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