Source: lib/util/player_configuration.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.util.PlayerConfiguration');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.abr.SimpleAbrManager');
  11. goog.require('shaka.log');
  12. goog.require('shaka.net.NetworkingEngine');
  13. goog.require('shaka.util.ConfigUtils');
  14. goog.require('shaka.util.LanguageUtils');
  15. goog.require('shaka.util.ManifestParserUtils');
  16. goog.require('shaka.util.Platform');
  19. /**
  20.  * @final
  21.  * @export
  22.  */
  23. shaka.util.PlayerConfiguration = class {
  24.   /**
  25.    * @return {shaka.extern.PlayerConfiguration}
  26.    * @export
  27.    */
  28.   static createDefault() {
  29.     // This is a relatively safe default in the absence of clues from the
  30.     // browser.  For slower connections, the default estimate may be too high.
  31.     const bandwidthEstimate = 1e6; // 1Mbps
  33.     let abrMaxHeight = Infinity;
  35.     // Some browsers implement the Network Information API, which allows
  36.     // retrieving information about a user's network connection.
  37.     if (navigator.connection) {
  38.       // If the user has checked a box in the browser to ask it to use less
  39.       // data, the browser will expose this intent via connection.saveData.
  40.       // When that is true, we will default the max ABR height to 360p. Apps
  41.       // can override this if they wish.
  42.       //
  43.       // The decision to use 360p was somewhat arbitrary. We needed a default
  44.       // limit, and rather than restrict to a certain bandwidth, we decided to
  45.       // restrict resolution. This will implicitly restrict bandwidth and
  46.       // therefore save data. We (Shaka+Chrome) judged that:
  47.       //   - HD would be inappropriate
  48.       //   - If a user is asking their browser to save data, 360p it reasonable
  49.       //   - 360p would not look terrible on small mobile device screen
  50.       // We also found that:
  51.       //   - YouTube's website on mobile defaults to 360p (as of 2018)
  52.       //   - iPhone 6, in portrait mode, has a physical resolution big enough
  53.       //     for 360p widescreen, but a little smaller than 480p widescreen
  54.       //     (https://apple.co/2yze4es)
  55.       // If the content's lowest resolution is above 360p, AbrManager will use
  56.       // the lowest resolution.
  57.       if (navigator.connection.saveData) {
  58.         abrMaxHeight = 360;
  59.       }
  60.     }
  62.     const drm = {
  63.       retryParameters: shaka.net.NetworkingEngine.defaultRetryParameters(),
  64.       // These will all be verified by special cases in mergeConfigObjects_():
  65.       servers: {},    // key is arbitrary key system ID, value must be string
  66.       clearKeys: {},  // key is arbitrary key system ID, value must be string
  67.       advanced: {},    // key is arbitrary key system ID, value is a record type
  68.       delayLicenseRequestUntilPlayed: false,
  69.       initDataTransform: (initData, initDataType, drmInfo) => {
  70.         return shaka.util.ConfigUtils.referenceParametersAndReturn(
  71.             [initData, initDataType, drmInfo],
  72.             initData);
  73.       },
  74.       logLicenseExchange: false,
  75.       updateExpirationTime: 1,
  76.       preferredKeySystems: [],
  77.     };
  79.     const manifest = {
  80.       retryParameters: shaka.net.NetworkingEngine.defaultRetryParameters(),
  81.       availabilityWindowOverride: NaN,
  82.       disableAudio: false,
  83.       disableVideo: false,
  84.       disableText: false,
  85.       disableThumbnails: false,
  86.       defaultPresentationDelay: 0,
  87.       segmentRelativeVttTiming: false,
  88.       dash: {
  89.         clockSyncUri: '',
  90.         ignoreDrmInfo: false,
  91.         disableXlinkProcessing: false,
  92.         xlinkFailGracefully: false,
  93.         ignoreMinBufferTime: false,
  94.         autoCorrectDrift: true,
  95.         initialSegmentLimit: 1000,
  96.         ignoreSuggestedPresentationDelay: false,
  97.         ignoreEmptyAdaptationSet: false,
  98.         ignoreMaxSegmentDuration: false,
  99.         keySystemsByURI: {
  100.           'urn:uuid:1077efec-c0b2-4d02-ace3-3c1e52e2fb4b':
  101.             'org.w3.clearkey',
  102.           'urn:uuid:e2719d58-a985-b3c9-781a-b030af78d30e':
  103.             'org.w3.clearkey',
  104.           'urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed':
  105.             'com.widevine.alpha',
  106.           'urn:uuid:9a04f079-9840-4286-ab92-e65be0885f95':
  107.             'com.microsoft.playready',
  108.           'urn:uuid:79f0049a-4098-8642-ab92-e65be0885f95':
  109.             'com.microsoft.playready',
  110.           'urn:uuid:f239e769-efa3-4850-9c16-a903c6932efb':
  111.             'com.adobe.primetime',
  112.         },
  113.         manifestPreprocessor: (element) => {
  114.           return shaka.util.ConfigUtils.referenceParametersAndReturn(
  115.               [element],
  116.               element);
  117.         },
  118.       },
  119.       hls: {
  120.         ignoreTextStreamFailures: false,
  121.         ignoreImageStreamFailures: false,
  122.         defaultAudioCodec: 'mp4a.40.2',
  123.         defaultVideoCodec: 'avc1.42E01E',
  124.         ignoreManifestProgramDateTime: false,
  125.         mediaPlaylistFullMimeType:
  126.             'video/mp2t; codecs="avc1.42E01E, mp4a.40.2"',
  127.       },
  128.     };
  130.     const liveCatchUp = {
  131.       enabled: false,
  132.       playbackRateMaxOverride: 0,
  133.       playbackRateMinOverride: 0,
  134.       targetLiveLatencyOverride: 0,
  135.     };
  137.     const streaming = {
  138.       retryParameters: shaka.net.NetworkingEngine.defaultRetryParameters(),
  139.       // Need some operation in the callback or else closure may remove calls
  140.       // to the function as it would be a no-op.  The operation can't just be a
  141.       // log message, because those are stripped in the compiled build.
  142.       failureCallback: (error) => {
  143.         shaka.log.error('Unhandled streaming error', error);
  144.         return shaka.util.ConfigUtils.referenceParametersAndReturn(
  145.             [error],
  146.             undefined);
  147.       },
  148.       // When low latency streaming is enabled, rebufferingGoal will default to
  149.       // 0.01 if not specified.
  150.       rebufferingGoal: 2,
  151.       bufferingGoal: 10,
  152.       bufferBehind: 30,
  153.       ignoreTextStreamFailures: false,
  154.       alwaysStreamText: false,
  155.       startAtSegmentBoundary: false,
  156.       gapDetectionThreshold: 0.1,
  157.       durationBackoff: 1,
  158.       forceTransmuxTS: false,
  159.       // Offset by 5 seconds since Chromecast takes a few seconds to start
  160.       // playing after a seek, even when buffered.
  161.       safeSeekOffset: 5,
  162.       stallEnabled: true,
  163.       stallThreshold: 1 /* seconds */,
  164.       stallSkip: 0.1 /* seconds */,
  165.       useNativeHlsOnSafari: true,
  166.       // If we are within 2 seconds of the start of a live segment, fetch the
  167.       // previous one.  This allows for segment drift, but won't download an
  168.       // extra segment if we aren't close to the start.
  169.       // When low latency streaming is enabled,  inaccurateManifestTolerance
  170.       // will default to 0 if not specified.
  171.       inaccurateManifestTolerance: 2,
  172.       lowLatencyMode: false,
  173.       autoLowLatencyMode: false,
  174.       liveCatchUp: liveCatchUp,
  175.       forceHTTPS: false,
  176.       preferNativeHls: false,
  177.       updateIntervalSeconds: 1,
  178.       dispatchAllEmsgBoxes: false,
  179.       observeQualityChanges: false,
  180.       maxDisabledTime: 30,
  181.     };
  183.     // Some browsers will stop earlier than others before a gap (e.g., Edge
  184.     // stops 0.5 seconds before a gap). So for some browsers we need to use a
  185.     // larger threshold. See: https://bit.ly/2K5xmJO
  186.     if (shaka.util.Platform.isLegacyEdge() ||
  187.         shaka.util.Platform.isTizen() ||
  188.         shaka.util.Platform.isChromecast()) {
  189.       streaming.gapDetectionThreshold = 0.5;
  190.     }
  192.     // WebOS, Tizen, and Chromecast have long hardware pipelines that respond
  193.     // slowly to seeking.  Therefore we should not seek when we detect a stall
  194.     // on one of these platforms.  Instead, default stallSkip to 0 to force the
  195.     // stall detector to pause and play instead.
  196.     if (shaka.util.Platform.isWebOS() ||
  197.         shaka.util.Platform.isTizen() ||
  198.         shaka.util.Platform.isChromecast()) {
  199.       streaming.stallSkip = 0;
  200.     }
  202.     const offline = {
  203.       // We need to set this to a throw-away implementation for now as our
  204.       // default implementation will need to reference other fields in the
  205.       // config. We will set it to our intended implementation after we have
  206.       // the top-level object created.
  207.       // eslint-disable-next-line require-await
  208.       trackSelectionCallback: async (tracks) => tracks,
  210.       downloadSizeCallback: async (sizeEstimate) => {
  211.         if (navigator.storage && navigator.storage.estimate) {
  212.           const estimate = await navigator.storage.estimate();
  213.           // Limit to 95% of quota.
  214.           return estimate.usage + sizeEstimate < estimate.quota * 0.95;
  215.         } else {
  216.           return true;
  217.         }
  218.       },
  220.       // Need some operation in the callback or else closure may remove calls
  221.       // to the function as it would be a no-op.  The operation can't just be a
  222.       // log message, because those are stripped in the compiled build.
  223.       progressCallback: (content, progress) => {
  224.         return shaka.util.ConfigUtils.referenceParametersAndReturn(
  225.             [content, progress],
  226.             undefined);
  227.       },
  229.       // By default we use persistent licenses as forces errors to surface if
  230.       // a platform does not support offline licenses rather than causing
  231.       // unexpected behaviours when someone tries to plays downloaded content
  232.       // without a persistent license.
  233.       usePersistentLicense: true,
  235.       numberOfParallelDownloads: 5,
  236.     };
  238.     const abr = {
  239.       enabled: true,
  240.       useNetworkInformation: true,
  241.       defaultBandwidthEstimate: bandwidthEstimate,
  242.       switchInterval: 8,
  243.       bandwidthUpgradeTarget: 0.85,
  244.       bandwidthDowngradeTarget: 0.95,
  245.       stallCountToDowngrade: 3,
  246.       restrictions: {
  247.         minWidth: 0,
  248.         maxWidth: Infinity,
  249.         minHeight: 0,
  250.         maxHeight: abrMaxHeight,
  251.         minPixels: 0,
  252.         maxPixels: Infinity,
  253.         minFrameRate: 0,
  254.         maxFrameRate: Infinity,
  255.         minBandwidth: 0,
  256.         maxBandwidth: Infinity,
  257.       },
  258.       advanced: {
  259.         minTotalBytes: 128e3,
  260.         minBytes: 16e3,
  261.         fastHalfLife: 2,
  262.         slowHalfLife: 5,
  263.       },
  264.     };
  266.     const cmcd = {
  267.       enabled: false,
  268.       sessionId: '',
  269.       contentId: '',
  270.       useHeaders: false,
  271.     };
  273.     /** @type {shaka.extern.PlayerConfiguration} */
  274.     const config = {
  275.       drm: drm,
  276.       manifest: manifest,
  277.       streaming: streaming,
  278.       offline: offline,
  279.       abrFactory: () => new shaka.abr.SimpleAbrManager(),
  280.       abr: abr,
  281.       preferredAudioLanguage: '',
  282.       preferredTextLanguage: '',
  283.       preferredVariantRole: '',
  284.       preferredTextRole: '',
  285.       preferredAudioChannelCount: 2,
  286.       preferredVideoCodecs: [],
  287.       preferredAudioCodecs: [],
  288.       preferForcedSubs: false,
  289.       preferredDecodingAttributes: [],
  290.       restrictions: {
  291.         minWidth: 0,
  292.         maxWidth: Infinity,
  293.         minHeight: 0,
  294.         maxHeight: Infinity,
  295.         minPixels: 0,
  296.         maxPixels: Infinity,
  297.         minFrameRate: 0,
  298.         maxFrameRate: Infinity,
  299.         minBandwidth: 0,
  300.         maxBandwidth: Infinity,
  301.       },
  302.       playRangeStart: 0,
  303.       playRangeEnd: Infinity,
  304.       textDisplayFactory: () => null,
  305.       cmcd: cmcd,
  306.     };
  308.     // Add this callback so that we can reference the preferred audio language
  309.     // through the config object so that if it gets updated, we have the
  310.     // updated value.
  311.     // eslint-disable-next-line require-await
  312.     offline.trackSelectionCallback = async (tracks) => {
  313.       return shaka.util.PlayerConfiguration.defaultTrackSelect(
  314.           tracks, config.preferredAudioLanguage);
  315.     };
  317.     return config;
  318.   }
  320.   /**
  321.    * Merges the given configuration changes into the given destination.  This
  322.    * uses the default Player configurations as the template.
  323.    *
  324.    * @param {shaka.extern.PlayerConfiguration} destination
  325.    * @param {!Object} updates
  326.    * @param {shaka.extern.PlayerConfiguration=} template
  327.    * @return {boolean}
  328.    * @export
  329.    */
  330.   static mergeConfigObjects(destination, updates, template) {
  331.     const overrides = {
  332.       '.drm.servers': '',
  333.       '.drm.clearKeys': '',
  334.       '.drm.advanced': {
  335.         distinctiveIdentifierRequired: false,
  336.         persistentStateRequired: false,
  337.         videoRobustness: '',
  338.         audioRobustness: '',
  339.         sessionType: '',
  340.         serverCertificate: new Uint8Array(0),
  341.         serverCertificateUri: '',
  342.         individualizationServer: '',
  343.       },
  344.     };
  345.     return shaka.util.ConfigUtils.mergeConfigObjects(
  346.         destination, updates,
  347.         template || shaka.util.PlayerConfiguration.createDefault(), overrides,
  348.         '');
  349.   }
  351.   /**
  352.    * @param {!Array.<shaka.extern.Track>} tracks
  353.    * @param {string} preferredAudioLanguage
  354.    * @return {!Array.<shaka.extern.Track>}
  355.    */
  356.   static defaultTrackSelect(tracks, preferredAudioLanguage) {
  357.     const ContentType = shaka.util.ManifestParserUtils.ContentType;
  358.     const LanguageUtils = shaka.util.LanguageUtils;
  360.     /** @type {!Array.<shaka.extern.Track>} */
  361.     const allVariants = tracks.filter((track) => track.type == 'variant');
  363.     /** @type {!Array.<shaka.extern.Track>} */
  364.     let selectedVariants = [];
  366.     // Find the locale that best matches our preferred audio locale.
  367.     const closestLocale = LanguageUtils.findClosestLocale(
  368.         preferredAudioLanguage,
  369.         allVariants.map((variant) => variant.language));
  370.     // If we found a locale that was close to our preference, then only use
  371.     // variants that use that locale.
  372.     if (closestLocale) {
  373.       selectedVariants = allVariants.filter((variant) => {
  374.         const locale = LanguageUtils.normalize(variant.language);
  375.         return locale == closestLocale;
  376.       });
  377.     }
  379.     // If we failed to get a language match, go with primary.
  380.     if (selectedVariants.length == 0) {
  381.       selectedVariants = allVariants.filter((variant) => {
  382.         return variant.primary;
  383.       });
  384.     }
  386.     // Otherwise, there is no good way to choose the language, so we don't
  387.     // choose a language at all.
  388.     if (selectedVariants.length == 0) {
  389.       // Issue a warning, but only if the content has multiple languages.
  390.       // Otherwise, this warning would just be noise.
  391.       const languages = new Set(allVariants.map((track) => {
  392.         return track.language;
  393.       }));
  395.       if (languages.size > 1) {
  396.         shaka.log.warning('Could not choose a good audio track based on ' +
  397.                           'language preferences or primary tracks.  An ' +
  398.                           'arbitrary language will be stored!');
  399.       }
  401.       // Default back to all variants.
  402.       selectedVariants = allVariants;
  403.     }
  405.     // From previously selected variants, choose the SD ones (height <= 480).
  406.     const tracksByHeight = selectedVariants.filter((track) => {
  407.       return track.height && track.height <= 480;
  408.     });
  410.     // If variants don't have video or no video with height <= 480 was
  411.     // found, proceed with the previously selected tracks.
  412.     if (tracksByHeight.length) {
  413.       // Sort by resolution, then select all variants which match the height
  414.       // of the highest SD res.  There may be multiple audio bitrates for the
  415.       // same video resolution.
  416.       tracksByHeight.sort((a, b) => {
  417.         // The items in this list have already been screened for height, but the
  418.         // compiler doesn't know that.
  419.         goog.asserts.assert(a.height != null, 'Null height');
  420.         goog.asserts.assert(b.height != null, 'Null height');
  422.         return b.height - a.height;
  423.       });
  424.       selectedVariants = tracksByHeight.filter((track) => {
  425.         return track.height == tracksByHeight[0].height;
  426.       });
  427.     }
  429.     /** @type {!Array.<shaka.extern.Track>} */
  430.     const selectedTracks = [];
  432.     // If there are multiple matches at different audio bitrates, select the
  433.     // middle bandwidth one.
  434.     if (selectedVariants.length) {
  435.       const middleIndex = Math.floor(selectedVariants.length / 2);
  436.       selectedVariants.sort((a, b) => a.bandwidth - b.bandwidth);
  437.       selectedTracks.push(selectedVariants[middleIndex]);
  438.     }
  440.     // Since this default callback is used primarily by our own demo app and by
  441.     // app developers who haven't thought about which tracks they want, we
  442.     // should select all image/text tracks, regardless of language.  This makes
  443.     // for a better demo for us, and does not rely on user preferences for the
  444.     // unconfigured app.
  445.     for (const track of tracks) {
  446.       if (track.type == ContentType.TEXT || track.type == ContentType.IMAGE) {
  447.         selectedTracks.push(track);
  448.       }
  449.     }
  451.     return selectedTracks;
  452.   }
  453. };