Source: lib/media/segment_reference.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.media.InitSegmentReference');
  8. goog.provide('shaka.media.SegmentReference');
  10. goog.require('goog.asserts');
  11. goog.require('shaka.log');
  12. goog.require('shaka.util.ArrayUtils');
  13. goog.require('shaka.util.BufferUtils');
  16. /**
  17.  * Creates an InitSegmentReference, which provides the location to an
  18.  * initialization segment.
  19.  *
  20.  * @export
  21.  */
  22. shaka.media.InitSegmentReference = class {
  23.   /**
  24.    * @param {function(): !Array<string>} uris A function that creates the URIs
  25.    *   of the resource containing the segment.
  26.    * @param {number} startByte The offset from the start of the resource to the
  27.    *   start of the segment.
  28.    * @param {?number} endByte The offset from the start of the resource
  29.    *   to the end of the segment, inclusive.  A value of null indicates that the
  30.    *   segment extends to the end of the resource.
  31.    * @param {null|shaka.extern.MediaQualityInfo=} mediaQuality Information about
  32.    *   the quality of the media associated with this init segment.
  33.    * @param {(null|number)=} timescale
  34.    * @param {(null|BufferSource)=} segmentData
  35.    * @param {?shaka.extern.aesKey=} aesKey
  36.    *  The segment's AES-128-CBC full segment encryption key and iv.
  37.    * @param {boolean=} encrypted
  38.    */
  39.   constructor(uris, startByte, endByte, mediaQuality = null, timescale = null,
  40.       segmentData = null, aesKey = null, encrypted = false) {
  41.     /** @type {function(): !Array<string>} */
  42.     this.getUris = uris;
  44.     /** @const {number} */
  45.     this.startByte = startByte;
  47.     /** @const {?number} */
  48.     this.endByte = endByte;
  50.     /** @type {shaka.extern.MediaQualityInfo|null} */
  51.     this.mediaQuality = mediaQuality;
  53.     /** @type {number|null} */
  54.     this.timescale = timescale;
  56.     /** @type {BufferSource|null} */
  57.     this.segmentData = segmentData;
  59.     /** @type {?shaka.extern.aesKey} */
  60.     this.aesKey = aesKey;
  62.     /** @type {?string} */
  63.     this.codecs = null;
  65.     /** @type {?string} */
  66.     this.mimeType = null;
  68.     /** @type {?number} */
  69.     this.boundaryEnd = null;
  71.     /** @const {boolean} */
  72.     this.encrypted = encrypted;
  73.   }
  75.   /**
  76.    * Returns the offset from the start of the resource to the
  77.    * start of the segment.
  78.    *
  79.    * @return {number}
  80.    * @export
  81.    */
  82.   getStartByte() {
  83.     return this.startByte;
  84.   }
  86.   /**
  87.    * Returns the offset from the start of the resource to the end of the
  88.    * segment, inclusive.  A value of null indicates that the segment extends
  89.    * to the end of the resource.
  90.    *
  91.    * @return {?number}
  92.    * @export
  93.    */
  94.   getEndByte() {
  95.     return this.endByte;
  96.   }
  98.   /**
  99.    * Returns the size of the init segment.
  100.    * @return {?number}
  101.    */
  102.   getSize() {
  103.     if (this.endByte) {
  104.       return this.endByte - this.startByte;
  105.     } else {
  106.       return null;
  107.     }
  108.   }
  110.   /**
  111.    * Returns media quality information for the segments associated with
  112.    * this init segment.
  113.    *
  114.    * @return {?shaka.extern.MediaQualityInfo}
  115.    */
  116.   getMediaQuality() {
  117.     return this.mediaQuality;
  118.   }
  120.   /**
  121.    * Set the segment data.
  122.    *
  123.    * @param {!BufferSource} segmentData
  124.    */
  125.   setSegmentData(segmentData) {
  126.     this.segmentData = segmentData;
  127.   }
  129.   /**
  130.    * Return the segment data.
  131.    *
  132.    * @return {?BufferSource}
  133.    */
  134.   getSegmentData() {
  135.     return this.segmentData;
  136.   }
  139.   /**
  140.    * Check if two initSegmentReference have all the same values.
  141.    * @param {?shaka.media.InitSegmentReference} reference1
  142.    * @param {?shaka.media.InitSegmentReference} reference2
  143.    * @return {boolean}
  144.    */
  145.   static equal(reference1, reference2) {
  146.     const ArrayUtils = shaka.util.ArrayUtils;
  147.     const BufferUtils = shaka.util.BufferUtils;
  149.     if (reference1 === reference2) {
  150.       return true;
  151.     } else if (!reference1 || !reference2) {
  152.       return reference1 == reference2;
  153.     } else {
  154.       return reference1.getStartByte() == reference2.getStartByte() &&
  155.           reference1.getEndByte() == reference2.getEndByte() &&
  156.           ArrayUtils.equal(
  157.               reference1.getUris().sort(), reference2.getUris().sort()) &&
  158.           BufferUtils.equal(reference1.getSegmentData(),
  159.               reference2.getSegmentData());
  160.     }
  161.   }
  162. };
  165. /**
  166.  * SegmentReference provides the start time, end time, and location to a media
  167.  * segment.
  168.  *
  169.  * @export
  170.  */
  171. shaka.media.SegmentReference = class {
  172.   /**
  173.    * @param {number} startTime The segment's start time in seconds.
  174.    * @param {number} endTime The segment's end time in seconds.  The segment
  175.    *   ends the instant before this time, so |endTime| must be strictly greater
  176.    *   than |startTime|.
  177.    * @param {function(): !Array<string>} uris
  178.    *   A function that creates the URIs of the resource containing the segment.
  179.    * @param {number} startByte The offset from the start of the resource to the
  180.    *   start of the segment.
  181.    * @param {?number} endByte The offset from the start of the resource to the
  182.    *   end of the segment, inclusive.  A value of null indicates that the
  183.    *   segment extends to the end of the resource.
  184.    * @param {shaka.media.InitSegmentReference} initSegmentReference
  185.    *   The segment's initialization segment metadata, or null if the segments
  186.    *   are self-initializing.
  187.    * @param {number} timestampOffset
  188.    *   The amount of time, in seconds, that must be added to the segment's
  189.    *   internal timestamps to align it to the presentation timeline.
  190.    *   <br>
  191.    *   For DASH, this value should equal the Period start time minus the first
  192.    *   presentation timestamp of the first frame/sample in the Period.  For
  193.    *   example, for MP4 based streams, this value should equal Period start
  194.    *   minus the first segment's tfdt box's 'baseMediaDecodeTime' field (after
  195.    *   it has been converted to seconds).
  196.    *   <br>
  197.    *   For HLS, this value should be the start time of the most recent
  198.    *   discontinuity, or 0 if there is no preceding discontinuity. Only used
  199.    *   in segments mode.
  200.    * @param {number} appendWindowStart
  201.    *   The start of the append window for this reference, relative to the
  202.    *   presentation.  Any content from before this time will be removed by
  203.    *   MediaSource.
  204.    * @param {number} appendWindowEnd
  205.    *   The end of the append window for this reference, relative to the
  206.    *   presentation.  Any content from after this time will be removed by
  207.    *   MediaSource.
  208.    * @param {!Array<!shaka.media.SegmentReference>=} partialReferences
  209.    *   A list of SegmentReferences for the partial segments.
  210.    * @param {?string=} tilesLayout
  211.    *   The value is a grid-item-dimension consisting of two positive decimal
  212.    *   integers in the format: column-x-row ('4x3'). It describes the
  213.    *   arrangement of Images in a Grid. The minimum valid LAYOUT is '1x1'.
  214.    * @param {?number=} tileDuration
  215.    *  The explicit duration of an individual tile within the tiles grid.
  216.    *  If not provided, the duration should be automatically calculated based on
  217.    *  the duration of the reference.
  218.    * @param {?number=} syncTime
  219.    *  A time value, expressed in seconds since 1970, which is used to
  220.    *  synchronize between streams.  Both produced and consumed by the HLS
  221.    *  parser.  Other components should not need this value.
  222.    * @param {shaka.media.SegmentReference.Status=} status
  223.    *  The segment status is used to indicate that a segment does not exist or is
  224.    *  not available.
  225.    * @param {?shaka.extern.aesKey=} aesKey
  226.    *  The segment's AES-128-CBC full segment encryption key and iv.
  227.    * @param {boolean=} allPartialSegments
  228.    *  Indicate if the segment has all partial segments
  229.    */
  230.   constructor(
  231.       startTime, endTime, uris, startByte, endByte, initSegmentReference,
  232.       timestampOffset, appendWindowStart, appendWindowEnd,
  233.       partialReferences = [], tilesLayout = '', tileDuration = null,
  234.       syncTime = null, status = shaka.media.SegmentReference.Status.AVAILABLE,
  235.       aesKey = null, allPartialSegments = false) {
  236.     // A preload hinted Partial Segment has the same startTime and endTime.
  237.     goog.asserts.assert(startTime <= endTime,
  238.         'startTime must be less than or equal to endTime');
  239.     goog.asserts.assert((endByte == null) || (startByte < endByte),
  240.         'startByte must be < endByte');
  242.     /** @type {number} */
  243.     this.startTime = startTime;
  245.     /** @type {number} */
  246.     this.endTime = endTime;
  248.     /**
  249.      * The "true" end time of the segment, without considering the period end
  250.      * time.  This is necessary for thumbnail segments, where timing requires us
  251.      * to know the original segment duration as described in the manifest.
  252.      * @type {number}
  253.      */
  254.     this.trueEndTime = endTime;
  256.     /** @type {function(): !Array<string>} */
  257.     this.getUrisInner = uris;
  259.     /** @const {number} */
  260.     this.startByte = startByte;
  262.     /** @const {?number} */
  263.     this.endByte = endByte;
  265.     /** @type {shaka.media.InitSegmentReference} */
  266.     this.initSegmentReference = initSegmentReference;
  268.     /** @type {number} */
  269.     this.timestampOffset = timestampOffset;
  271.     /** @type {number} */
  272.     this.appendWindowStart = appendWindowStart;
  274.     /** @type {number} */
  275.     this.appendWindowEnd = appendWindowEnd;
  277.     /** @type {!Array<!shaka.media.SegmentReference>} */
  278.     this.partialReferences = partialReferences;
  280.     /** @type {?string} */
  281.     this.tilesLayout = tilesLayout;
  283.     /** @type {?number} */
  284.     this.tileDuration = tileDuration;
  286.     /**
  287.      * A time value, expressed in seconds since 1970, which is used to
  288.      * synchronize between streams.  Both produced and consumed by the HLS
  289.      * parser.  Other components should not need this value.
  290.      *
  291.      * @type {?number}
  292.      */
  293.     this.syncTime = syncTime;
  295.     /** @type {shaka.media.SegmentReference.Status} */
  296.     this.status = status;
  298.     /** @type {boolean} */
  299.     this.preload = false;
  301.     /** @type {boolean} */
  302.     this.independent = true;
  304.     /** @type {boolean} */
  305.     this.byterangeOptimization = false;
  307.     /** @type {?shaka.extern.aesKey} */
  308.     this.aesKey = aesKey;
  310.     /** @type {?shaka.extern.ThumbnailSprite} */
  311.     this.thumbnailSprite = null;
  313.     /** @type {number} */
  314.     this.discontinuitySequence = -1;
  316.     /** @type {boolean} */
  317.     this.allPartialSegments = allPartialSegments;
  319.     /** @type {boolean} */
  320.     this.partial = false;
  322.     /** @type {boolean} */
  323.     this.lastPartial = false;
  325.     for (const partial of this.partialReferences) {
  326.       partial.markAsPartial();
  327.     }
  328.     if (this.allPartialSegments && this.partialReferences.length) {
  329.       const lastPartial =
  330.           this.partialReferences[this.partialReferences.length - 1];
  331.       lastPartial.markAsLastPartial();
  332.     }
  334.     /** @type {?string} */
  335.     this.codecs = null;
  337.     /** @type {?string} */
  338.     this.mimeType = null;
  340.     /** @type {?number} */
  341.     this.bandwidth = null;
  343.     /** @type {BufferSource|null} */
  344.     this.segmentData = null;
  346.     /** @type {boolean} */
  347.     this.removeSegmentDataOnGet = false;
  348.   }
  350.   /**
  351.    * Creates and returns the URIs of the resource containing the segment.
  352.    *
  353.    * @return {!Array<string>}
  354.    * @export
  355.    */
  356.   getUris() {
  357.     return this.getUrisInner();
  358.   }
  360.   /**
  361.    * Returns the segment's start time in seconds.
  362.    *
  363.    * @return {number}
  364.    * @export
  365.    */
  366.   getStartTime() {
  367.     return this.startTime;
  368.   }
  370.   /**
  371.    * Returns the segment's end time in seconds.
  372.    *
  373.    * @return {number}
  374.    * @export
  375.    */
  376.   getEndTime() {
  377.     return this.endTime;
  378.   }
  380.   /**
  381.    * Returns the offset from the start of the resource to the
  382.    * start of the segment.
  383.    *
  384.    * @return {number}
  385.    * @export
  386.    */
  387.   getStartByte() {
  388.     return this.startByte;
  389.   }
  391.   /**
  392.    * Returns the offset from the start of the resource to the end of the
  393.    * segment, inclusive.  A value of null indicates that the segment extends to
  394.    * the end of the resource.
  395.    *
  396.    * @return {?number}
  397.    * @export
  398.    */
  399.   getEndByte() {
  400.     return this.endByte;
  401.   }
  403.   /**
  404.    * Returns the size of the segment.
  405.    * @return {?number}
  406.    */
  407.   getSize() {
  408.     if (this.endByte) {
  409.       return this.endByte - this.startByte;
  410.     } else {
  411.       return null;
  412.     }
  413.   }
  415.   /**
  416.    * Returns true if it contains partial SegmentReferences.
  417.    * @return {boolean}
  418.    */
  419.   hasPartialSegments() {
  420.     return this.partialReferences.length > 0;
  421.   }
  423.   /**
  424.    * Returns true if it contains all partial SegmentReferences.
  425.    * @return {boolean}
  426.    */
  427.   hasAllPartialSegments() {
  428.     return this.allPartialSegments;
  429.   }
  431.   /**
  432.    * Returns the segment's tiles layout. Only defined in image segments.
  433.    *
  434.    * @return {?string}
  435.    * @export
  436.    */
  437.   getTilesLayout() {
  438.     return this.tilesLayout;
  439.   }
  441.   /**
  442.    * Returns the segment's explicit tile duration.
  443.    * Only defined in image segments.
  444.    *
  445.    * @return {?number}
  446.    * @export
  447.    */
  448.   getTileDuration() {
  449.     return this.tileDuration;
  450.   }
  452.   /**
  453.    * Returns the segment's status.
  454.    *
  455.    * @return {shaka.media.SegmentReference.Status}
  456.    * @export
  457.    */
  458.   getStatus() {
  459.     return this.status;
  460.   }
  462.   /**
  463.    * Mark the reference as unavailable.
  464.    *
  465.    * @export
  466.    */
  467.   markAsUnavailable() {
  468.     this.status = shaka.media.SegmentReference.Status.UNAVAILABLE;
  469.   }
  471.   /**
  472.    * Mark the reference as preload.
  473.    *
  474.    * @export
  475.    */
  476.   markAsPreload() {
  477.     this.preload = true;
  478.   }
  480.   /**
  481.    * Returns true if the segment is preloaded.
  482.    *
  483.    * @return {boolean}
  484.    * @export
  485.    */
  486.   isPreload() {
  487.     return this.preload;
  488.   }
  490.   /**
  491.    * Mark the reference as non-independent.
  492.    *
  493.    * @export
  494.    */
  495.   markAsNonIndependent() {
  496.     this.independent = false;
  497.   }
  499.   /**
  500.    * Returns true if the segment is independent.
  501.    *
  502.    * @return {boolean}
  503.    * @export
  504.    */
  505.   isIndependent() {
  506.     return this.independent;
  507.   }
  509.   /**
  510.    * Mark the reference as partial.
  511.    *
  512.    * @export
  513.    */
  514.   markAsPartial() {
  515.     this.partial = true;
  516.   }
  518.   /**
  519.    * Returns true if the segment is partial.
  520.    *
  521.    * @return {boolean}
  522.    * @export
  523.    */
  524.   isPartial() {
  525.     return this.partial;
  526.   }
  528.   /**
  529.    * Mark the reference as being the last part of the full segment
  530.    *
  531.    * @export
  532.    */
  533.   markAsLastPartial() {
  534.     this.lastPartial = true;
  535.   }
  537.   /**
  538.    * Returns true if reference as being the last part of the full segment.
  539.    *
  540.    * @return {boolean}
  541.    * @export
  542.    */
  543.   isLastPartial() {
  544.     return this.lastPartial;
  545.   }
  547.   /**
  548.    * Mark the reference as byterange optimization.
  549.    *
  550.    * The "byterange optimization" means that it is playable using MP4 low
  551.    * latency streaming with chunked data.
  552.    *
  553.    * @export
  554.    */
  555.   markAsByterangeOptimization() {
  556.     this.byterangeOptimization = true;
  557.   }
  559.   /**
  560.    * Returns true if the segment has a byterange optimization.
  561.    *
  562.    * @return {boolean}
  563.    * @export
  564.    */
  565.   hasByterangeOptimization() {
  566.     return this.byterangeOptimization;
  567.   }
  569.   /**
  570.    * Set the segment's thumbnail sprite.
  571.    *
  572.    * @param {shaka.extern.ThumbnailSprite} thumbnailSprite
  573.    * @export
  574.    */
  575.   setThumbnailSprite(thumbnailSprite) {
  576.     this.thumbnailSprite = thumbnailSprite;
  577.   }
  579.   /**
  580.    * Returns the segment's thumbnail sprite.
  581.    *
  582.    * @return {?shaka.extern.ThumbnailSprite}
  583.    * @export
  584.    */
  585.   getThumbnailSprite() {
  586.     return this.thumbnailSprite;
  587.   }
  589.   /**
  590.    * Offset the segment reference by a fixed amount.
  591.    *
  592.    * @param {number} offset The amount to add to the segment's start and end
  593.    *   times.
  594.    * @export
  595.    */
  596.   offset(offset) {
  597.     this.startTime += offset;
  598.     this.endTime += offset;
  599.     this.trueEndTime += offset;
  601.     for (const partial of this.partialReferences) {
  602.       partial.startTime += offset;
  603.       partial.endTime += offset;
  604.       partial.trueEndTime += offset;
  605.     }
  606.   }
  608.   /**
  609.    * Sync this segment against a particular sync time that will serve as "0" in
  610.    * the presentation timeline.
  611.    *
  612.    * @param {number} lowestSyncTime
  613.    * @export
  614.    */
  615.   syncAgainst(lowestSyncTime) {
  616.     if (this.syncTime == null) {
  617.       shaka.log.alwaysError('Sync attempted without sync time!');
  618.       return;
  619.     }
  620.     const desiredStart = this.syncTime - lowestSyncTime;
  621.     const offset = desiredStart - this.startTime;
  622.     if (Math.abs(offset) >= 0.001) {
  623.       this.offset(offset);
  624.     }
  625.   }
  627.   /**
  628.    * Set the segment data.
  629.    *
  630.    * @param {!BufferSource} segmentData
  631.    * @param {boolean=} singleUse
  632.    * @export
  633.    */
  634.   setSegmentData(segmentData, singleUse = false) {
  635.     this.segmentData = segmentData;
  636.     this.removeSegmentDataOnGet = singleUse;
  637.   }
  639.   /**
  640.    * Return the segment data.
  641.    *
  642.    * @param {boolean=} allowDeleteOnSingleUse
  643.    * @return {?BufferSource}
  644.    * @export
  645.    */
  646.   getSegmentData(allowDeleteOnSingleUse = true) {
  647.     const ret = this.segmentData;
  648.     if (allowDeleteOnSingleUse && this.removeSegmentDataOnGet) {
  649.       this.segmentData = null;
  650.     }
  651.     return ret;
  652.   }
  654.   /**
  655.    * Updates the init segment reference and propagates the update to all partial
  656.    * references.
  657.    * @param {shaka.media.InitSegmentReference} initSegmentReference
  658.    */
  659.   updateInitSegmentReference(initSegmentReference) {
  660.     this.initSegmentReference = initSegmentReference;
  661.     for (const partialReference of this.partialReferences) {
  662.       partialReference.updateInitSegmentReference(initSegmentReference);
  663.     }
  664.   }
  665. };
  668. /**
  669.  * Rather than using booleans to communicate what the state of the reference,
  670.  * we have this enum.
  671.  *
  672.  * @enum {number}
  673.  * @export
  674.  */
  675. shaka.media.SegmentReference.Status = {
  676.   AVAILABLE: 0,
  677.   UNAVAILABLE: 1,
  678.   MISSING: 2,
  679. };
  682. /**
  683.  * A convenient typedef for when either type of reference is acceptable.
  684.  *
  685.  * @typedef {shaka.media.InitSegmentReference|shaka.media.SegmentReference}
  686.  */
  687. shaka.media.AnySegmentReference;
  690. /**
  691.  * @typedef {{
  692.  *   height: number,
  693.  *   positionX: number,
  694.  *   positionY: number,
  695.  *   width: number
  696.  * }}
  697.  *
  698.  * @property {number} height
  699.  *    The thumbnail height in px.
  700.  * @property {number} positionX
  701.  *    The thumbnail left position in px.
  702.  * @property {number} positionY
  703.  *    The thumbnail top position in px.
  704.  * @property {number} width
  705.  *    The thumbnail width in px.
  706.  * @export
  707.  */
  708. shaka.media.SegmentReference.ThumbnailSprite;