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