Source: externs/shaka/ads.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  8. /**
  9.  * @externs
  10.  */
  12. /**
  13.  * @typedef {{
  14.  *   loadTimes: !Array<number>,
  15.  *   averageLoadTime: number,
  16.  *   started: number,
  17.  *   playedCompletely: number,
  18.  *   skipped: number,
  19.  *   errors: number
  20.  * }}
  21.  *
  22.  * @description
  23.  * Contains statistics and information about the current state of the player.
  24.  *
  25.  * @property {number} loadTimes
  26.  *   The set of amounts of time it took to get the final manifest.
  27.  * @property {number} averageLoadTime
  28.  *   The average time it took to get the final manifest.
  29.  * @property {number} started
  30.  *   The number of ads started.
  31.  * @property {number} playedCompletely
  32.  *   The number of ads played completely.
  33.  * @property {number} skipped
  34.  *   The number of ads skipped.
  35.  * @property {number} errors
  36.  *   The number of ads with errors.
  37.  * @exportDoc
  38.  */
  39. shaka.extern.AdsStats;
  42. /**
  43.  * @typedef {{
  44.  *   start: number,
  45.  *   end: ?number
  46.  * }}
  47.  *
  48.  * @description
  49.  * Contains the times of a range of an Ad.
  50.  *
  51.  * @property {number} start
  52.  *   The start time of the range, in milliseconds.
  53.  * @property {number} end
  54.  *   The end time of the range, in milliseconds.
  55.  * @exportDoc
  56.  */
  57. shaka.extern.AdCuePoint;
  60. /**
  61.  * @typedef {{
  62.  *   id: ?string,
  63.  *   groupId: ?string,
  64.  *   startTime: number,
  65.  *   endTime: ?number,
  66.  *   uri: string,
  67.  *   mimeType: ?string,
  68.  *   isSkippable: boolean,
  69.  *   skipOffset: ?number,
  70.  *   skipFor: ?number,
  71.  *   canJump: boolean,
  72.  *   resumeOffset: ?number,
  73.  *   playoutLimit: ?number,
  74.  *   once: boolean,
  75.  *   pre: boolean,
  76.  *   post: boolean,
  77.  *   timelineRange: boolean,
  78.  *   loop: boolean,
  79.  *   overlay: ?shaka.extern.AdInterstitialOverlay
  80.  * }}
  81.  *
  82.  * @description
  83.  * Contains the ad interstitial info.
  84.  *
  85.  * @property {?string} id
  86.  *   The id of the interstitial.
  87.  * @property {?string} groupId
  88.  *   The group id of the interstitial.
  89.  * @property {number} startTime
  90.  *   The start time of the interstitial.
  91.  * @property {?number} endTime
  92.  *   The end time of the interstitial.
  93.  * @property {string} uri
  94.  *   The uri of the interstitial, can be any type that
  95.  *   ShakaPlayer supports (either in MSE or src=)
  96.  * @property {?string} mimeType
  97.  *   The mimeType of the interstitial if known.
  98.  * @property {boolean} isSkippable
  99.  *   Indicate if the interstitial is skippable.
  100.  * @property {?number} skipOffset
  101.  *   Time value that identifies when skip controls are made available to the
  102.  *   end user.
  103.  * @property {?number} skipFor
  104.  *   The amount of time in seconds a skip button should be displayed for.
  105.  *   Note that this value should be >= 0.
  106.  * @property {boolean} canJump
  107.  *   Indicate if the interstitial is jumpable.
  108.  * @property {?number} resumeOffset
  109.  *   Indicates where the primary playback will resume after the interstitial
  110.  *   plays. It is expressed as a time lag from when interstitial playback was
  111.  *   scheduled on the primary player's timeline. For live ad replacement it
  112.  *   must be null.
  113.  * @property {?number} playoutLimit
  114.  *   Indicate a limit for the playout time of the entire interstitial.
  115.  * @property {boolean} once
  116.  *   Indicates that the interstitial should only be played once.
  117.  * @property {boolean} pre
  118.  *   Indicates that an action is to be triggered before playback of the
  119.  *   primary asset begins, regardless of where playback begins in the primary
  120.  *   asset.
  121.  * @property {boolean} post
  122.  *   Indicates that an action is to be triggered after the primary asset has
  123.  *   been played to its end without error.
  124.  * @property {boolean} timelineRange
  125.  *   Indicates whether the  interstitial should be presented in a timeline UI
  126.  *   as a single point or as a range.
  127.  * @property {boolean} loop
  128.  *   Indicates that the interstitials should play in loop.
  129.  *   Only applies if the interstitials is an overlay.
  130.  *   Only supported when using multiple video elements for interstitials.
  131.  * @property {?shaka.extern.AdInterstitialOverlay} overlay
  132.  *   Indicates the characteristics of the overlay
  133.  *   Only supported when using multiple video elements for interstitials.
  134.  * @exportDoc
  135.  */
  136. shaka.extern.AdInterstitial;
  139. /**
  140.  * @typedef {{
  141.  *   viewport: {x: number, y: number},
  142.  *   topLeft: {x: number, y: number},
  143.  *   size: {x: number, y: number}
  144.  * }}
  145.  *
  146.  * @description
  147.  * Contains the ad interstitial overlay info.
  148.  *
  149.  * @property {{x: number, y: number}} viewport
  150.  *   The viewport in pixels.
  151.  * @property {{x: number, y: number}} topLeft
  152.  *   The topLeft in pixels.
  153.  * @property {{x: number, y: number}} size
  154.  *   The size in pixels.
  155.  * @exportDoc
  156.  */
  157. shaka.extern.AdInterstitialOverlay;
  160. /**
  161.  * An object that's responsible for all the ad-related logic
  162.  * in the player.
  163.  *
  164.  * @interface
  165.  * @exportDoc
  166.  */
  167. shaka.extern.IAdManager = class extends EventTarget {
  168.   /**
  169.    * @param {string} locale
  170.    */
  171.   setLocale(locale) {}
  173.   /**
  174.    * Called by the Player to provide an updated configuration any time it
  175.    * changes.
  176.    * Must be called at least once before init*().
  177.    *
  178.    * @param {shaka.extern.AdsConfiguration} config
  179.    */
  180.   configure(config) {}
  182.   release() {}
  184.   onAssetUnload() {}
  186.   /**
  187.    * @param {?HTMLElement} adContainer
  188.    * @param {!shaka.Player} basePlayer
  189.    * @param {!HTMLMediaElement} baseVideo
  190.    */
  191.   initInterstitial(adContainer, basePlayer, baseVideo) {}
  193.   /**
  194.    * @param {!HTMLElement} adContainer
  195.    * @param {!HTMLMediaElement} video
  196.    * @param {?google.ima.AdsRenderingSettings} adsRenderingSettings
  197.    */
  198.   initClientSide(adContainer, video, adsRenderingSettings) {}
  200.   /**
  201.    * @param {!google.ima.AdsRequest} imaRequest
  202.    */
  203.   requestClientSideAds(imaRequest) {}
  205.   /**
  206.    * @param {!google.ima.AdsRenderingSettings} adsRenderingSettings
  207.    */
  208.   updateClientSideAdsRenderingSettings(adsRenderingSettings) {}
  210.   /**
  211.    * @param {!HTMLElement} adContainer
  212.    * @param {!shaka.net.NetworkingEngine} networkingEngine
  213.    * @param {!HTMLMediaElement} video
  214.    */
  215.   initMediaTailor(adContainer, networkingEngine, video) {}
  217.   /**
  218.    * @param {string} url
  219.    * @param {Object} adsParams
  220.    * @param {string=} backupUrl
  221.    * @return {!Promise<string>}
  222.    */
  223.   requestMediaTailorStream(url, adsParams, backupUrl) {}
  225.   /**
  226.    * @param {string} url
  227.    */
  228.   addMediaTailorTrackingUrl(url) {}
  230.   /**
  231.    * @param {!HTMLElement} adContainer
  232.    * @param {!HTMLMediaElement} video
  233.    */
  234.   initServerSide(adContainer, video) {}
  236.   /**
  237.    * @param {!google.ima.dai.api.StreamRequest} imaRequest
  238.    * @param {string=} backupUrl
  239.    * @return {!Promise<string>}
  240.    */
  241.   requestServerSideStream(imaRequest, backupUrl) {}
  243.   /**
  244.    * @param {Object} adTagParameters
  245.    */
  246.   replaceServerSideAdTagParameters(adTagParameters) {}
  248.   /**
  249.    * @return {!Array<!shaka.extern.AdCuePoint>}
  250.    */
  251.   getServerSideCuePoints() {}
  253.   /**
  254.    * @return {!Array<!shaka.extern.AdCuePoint>}
  255.    */
  256.   getCuePoints() {}
  258.   /**
  259.    * Get statistics for the current playback session. If the player is not
  260.    * playing content, this will return an empty stats object.
  261.    */
  262.   getStats() {}
  264.   /**
  265.    * @param {shaka.extern.TimelineRegionInfo} region
  266.    */
  267.   onDashTimedMetadata(region) {}
  269.   /**
  270.    * Fired when the manifest is updated.
  271.    *
  272.    * @param {boolean} isLive
  273.    */
  274.   onManifestUpdated(isLive) {}
  276.   /**
  277.    * @param {shaka.extern.ID3Metadata} metadata
  278.    * @param {number} timestampOffset
  279.    */
  280.   onHlsTimedMetadata(metadata, timestampOffset) {}
  282.   /**
  283.    * @param {shaka.extern.MetadataFrame} value
  284.    */
  285.   onCueMetadataChange(value) {}
  287.   /**
  288.    * @param {!shaka.Player} basePlayer
  289.    * @param {!HTMLMediaElement} baseVideo
  290.    * @param {shaka.extern.HLSInterstitial} interstitial
  291.    */
  292.   onHLSInterstitialMetadata(basePlayer, baseVideo, interstitial) {}
  294.   /**
  295.    * @param {!shaka.Player} basePlayer
  296.    * @param {!HTMLMediaElement} baseVideo
  297.    * @param {shaka.extern.TimelineRegionInfo} region
  298.    */
  299.   onDASHInterstitialMetadata(basePlayer, baseVideo, region) {}
  301.   /**
  302.    * @param {shaka.extern.AdInterstitial} interstitial
  303.    */
  304.   addCustomInterstitial(interstitial) {}
  306.   /**
  307.    * @param {string} url
  308.    * @return {!Promise}
  309.    */
  310.   addAdUrlInterstitial(url) {}
  312.   /**
  313.    * @return {shaka.Player}
  314.    */
  315.   getInterstitialPlayer() {}
  316. };
  319. /**
  320.  * A factory for creating the ad manager.
  321.  *
  322.  * @typedef {function():!shaka.extern.IAdManager}
  323.  * @exportDoc
  324.  */
  325. shaka.extern.IAdManager.Factory;
  328. /**
  329.  * Interface for Ad objects.
  330.  *
  331.  * @extends {shaka.util.IReleasable}
  332.  * @interface
  333.  * @exportDoc
  334.  */
  335. shaka.extern.IAd = class {
  336.   /**
  337.    * @return {boolean}
  338.    */
  339.   needsSkipUI() {}
  341.   /**
  342.    * @return {boolean}
  343.    */
  344.   isClientRendering() {}
  346.   /**
  347.    * @return {boolean}
  348.    */
  349.   hasCustomClick() {}
  351.   /**
  352.    * @return {boolean}
  353.    */
  354.   isUsingAnotherMediaElement() {}
  356.   /**
  357.    * @return {number}
  358.    */
  359.   getDuration() {}
  361.   /**
  362.    * Gets the minimum suggested duration.  Defaults to being equivalent to
  363.    * getDuration() for server-side ads.
  364.    * @see http://bit.ly/3q3U6hI
  365.    * @return {number}
  366.    */
  367.   getMinSuggestedDuration() {}
  369.   /**
  370.    * @return {number}
  371.    */
  372.   getRemainingTime() {}
  374.   /**
  375.    * @return {number}
  376.    */
  377.   getTimeUntilSkippable() {}
  379.   /**
  380.    * @return {boolean}
  381.    */
  382.   isPaused() {}
  384.   /**
  385.    * @return {boolean}
  386.    */
  387.   isSkippable() {}
  389.   /**
  390.    * @return {boolean}
  391.    */
  392.   canSkipNow() {}
  394.   skip() {}
  396.   play() {}
  398.   pause() {}
  400.   /**
  401.    * @return {number}
  402.    */
  403.   getVolume() {}
  405.   /**
  406.    * @param {number} volume
  407.    */
  408.   setVolume(volume) {}
  410.   /**
  411.    * @return {boolean}
  412.    */
  413.   isMuted() {}
  415.   /**
  416.    * @param {boolean} muted
  417.    */
  418.   setMuted(muted) {}
  420.   /**
  421.    * @return {boolean}
  422.    */
  423.   isLinear() {}
  425.   /**
  426.    * @param {number} width
  427.    * @param {number} height
  428.    */
  429.   resize(width, height) {}
  431.   /**
  432.    * @return {number}
  433.    */
  434.   getSequenceLength() {}
  436.   /**
  437.    * @return {number}
  438.    */
  439.   getPositionInSequence() {}
  441.   /**
  442.    * @return {string}
  443.    */
  444.   getTitle() {}
  446.   /**
  447.    * @return {string}
  448.    */
  449.   getDescription() {}
  451.   /**
  452.    * @return {number}
  453.    */
  454.   getVastMediaBitrate() {}
  456.   /**
  457.    * @return {number}
  458.    */
  459.   getVastMediaHeight() {}
  461.   /**
  462.    * @return {number}
  463.    */
  464.   getVastMediaWidth() {}
  466.   /**
  467.    * @return {string}
  468.    */
  469.   getAdId() {}
  471.   /**
  472.    * @return {string}
  473.    */
  474.   getCreativeAdId() {}
  476.   /**
  477.    * @return {string}
  478.    */
  479.   getAdvertiserName() {}
  481.   /**
  482.    * @return {?string}
  483.    */
  484.   getMediaUrl() {}
  486.   /**
  487.    * @return {number}
  488.    */
  489.   getTimeOffset() {}
  491.   /**
  492.    * @return {number}
  493.    */
  494.   getPodIndex() {}
  495. };