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.  *   overlayAds: number,
  18.  *   playedCompletely: number,
  19.  *   skipped: number,
  20.  *   errors: number
  21.  * }}
  22.  *
  23.  * @description
  24.  * Contains statistics and information about the current state of the player.
  25.  *
  26.  * @property {number} loadTimes
  27.  *   The set of amounts of time it took to get the final manifest.
  28.  * @property {number} averageLoadTime
  29.  *   The average time it took to get the final manifest.
  30.  * @property {number} started
  31.  *   The number of ads started (linear and overlays ads).
  32.  * @property {number} overlayAds
  33.  *   The number of overlay ads started.
  34.  * @property {number} playedCompletely
  35.  *   The number of ads played completely.
  36.  * @property {number} skipped
  37.  *   The number of ads skipped.
  38.  * @property {number} errors
  39.  *   The number of ads with errors.
  40.  * @exportDoc
  41.  */
  42. shaka.extern.AdsStats;
  45. /**
  46.  * @typedef {{
  47.  *   start: number,
  48.  *   end: ?number
  49.  * }}
  50.  *
  51.  * @description
  52.  * Contains the times of a range of an Ad.
  53.  *
  54.  * @property {number} start
  55.  *   The start time of the range, in milliseconds.
  56.  * @property {number} end
  57.  *   The end time of the range, in milliseconds.
  58.  * @exportDoc
  59.  */
  60. shaka.extern.AdCuePoint;
  63. /**
  64.  * @typedef {{
  65.  *   id: ?string,
  66.  *   groupId: ?string,
  67.  *   startTime: number,
  68.  *   endTime: ?number,
  69.  *   uri: string,
  70.  *   mimeType: ?string,
  71.  *   isSkippable: boolean,
  72.  *   skipOffset: ?number,
  73.  *   skipFor: ?number,
  74.  *   canJump: boolean,
  75.  *   resumeOffset: ?number,
  76.  *   playoutLimit: ?number,
  77.  *   once: boolean,
  78.  *   pre: boolean,
  79.  *   post: boolean,
  80.  *   timelineRange: boolean,
  81.  *   loop: boolean,
  82.  *   overlay: ?shaka.extern.AdPositionInfo,
  83.  *   displayOnBackground: boolean,
  84.  *   currentVideo: ?shaka.extern.AdPositionInfo,
  85.  *   background: ?string
  86.  * }}
  87.  *
  88.  * @description
  89.  * Contains the ad interstitial info.
  90.  *
  91.  * @property {?string} id
  92.  *   The id of the interstitial.
  93.  * @property {?string} groupId
  94.  *   The group id of the interstitial.
  95.  * @property {number} startTime
  96.  *   The start time of the interstitial.
  97.  * @property {?number} endTime
  98.  *   The end time of the interstitial.
  99.  * @property {string} uri
  100.  *   The uri of the interstitial, can be any type that
  101.  *   ShakaPlayer supports (either in MSE or src=)
  102.  * @property {?string} mimeType
  103.  *   The mimeType of the interstitial if known.
  104.  * @property {boolean} isSkippable
  105.  *   Indicate if the interstitial is skippable.
  106.  * @property {?number} skipOffset
  107.  *   Time value that identifies when skip controls are made available to the
  108.  *   end user.
  109.  * @property {?number} skipFor
  110.  *   The amount of time in seconds a skip button should be displayed for.
  111.  *   Note that this value should be >= 0.
  112.  * @property {boolean} canJump
  113.  *   Indicate if the interstitial is jumpable.
  114.  * @property {?number} resumeOffset
  115.  *   Indicates where the primary playback will resume after the interstitial
  116.  *   plays. It is expressed as a time lag from when interstitial playback was
  117.  *   scheduled on the primary player's timeline. For live ad replacement it
  118.  *   must be null.
  119.  * @property {?number} playoutLimit
  120.  *   Indicate a limit for the playout time of the entire interstitial.
  121.  * @property {boolean} once
  122.  *   Indicates that the interstitial should only be played once.
  123.  * @property {boolean} pre
  124.  *   Indicates that an action is to be triggered before playback of the
  125.  *   primary asset begins, regardless of where playback begins in the primary
  126.  *   asset.
  127.  * @property {boolean} post
  128.  *   Indicates that an action is to be triggered after the primary asset has
  129.  *   been played to its end without error.
  130.  * @property {boolean} timelineRange
  131.  *   Indicates whether the  interstitial should be presented in a timeline UI
  132.  *   as a single point or as a range.
  133.  * @property {boolean} loop
  134.  *   Indicates that the interstitials should play in loop.
  135.  *   Only applies if the interstitials is an overlay.
  136.  *   Only supported when using multiple video elements for interstitials.
  137.  * @property {?shaka.extern.AdPositionInfo} overlay
  138.  *   Indicates the characteristics of the overlay
  139.  *   Only supported when using multiple video elements for interstitials.
  140.  * @property {boolean} displayOnBackground
  141.  *   Indicates if we should display on background, shrinking the current video.
  142.  * @property {?shaka.extern.AdPositionInfo} currentVideo
  143.  *   Indicates the characteristics of the current video.
  144.  *   Only set if any feature changes.
  145.  * @property {?string} background
  146.  *   Specifies the background, the value can be any value of the CSS background
  147.  *   property.
  148.  * @exportDoc
  149.  */
  150. shaka.extern.AdInterstitial;
  153. /**
  154.  * @typedef {{
  155.  *   viewport: {x: number, y: number},
  156.  *   topLeft: {x: number, y: number},
  157.  *   size: {x: number, y: number}
  158.  * }}
  159.  *
  160.  * @description
  161.  * Contains the coordinates of a position info
  162.  *
  163.  * @property {{x: number, y: number}} viewport
  164.  *   The viewport in pixels.
  165.  * @property {{x: number, y: number}} topLeft
  166.  *   The topLeft in pixels.
  167.  * @property {{x: number, y: number}} size
  168.  *   The size in pixels.
  169.  * @exportDoc
  170.  */
  171. shaka.extern.AdPositionInfo;
  174. /**
  175.  * An object that's responsible for all the ad-related logic
  176.  * in the player.
  177.  *
  178.  * @interface
  179.  * @exportDoc
  180.  */
  181. shaka.extern.IAdManager = class extends EventTarget {
  182.   /**
  183.    * @param {string} locale
  184.    */
  185.   setLocale(locale) {}
  187.   /**
  188.    * Called by the Player to provide an updated configuration any time it
  189.    * changes.
  190.    * Must be called at least once before init*().
  191.    *
  192.    * @param {shaka.extern.AdsConfiguration} config
  193.    */
  194.   configure(config) {}
  196.   release() {}
  198.   onAssetUnload() {}
  200.   /**
  201.    * @param {?HTMLElement} adContainer
  202.    * @param {!shaka.Player} basePlayer
  203.    * @param {!HTMLMediaElement} baseVideo
  204.    */
  205.   initInterstitial(adContainer, basePlayer, baseVideo) {}
  207.   /**
  208.    * @param {!HTMLElement} adContainer
  209.    * @param {!HTMLMediaElement} video
  210.    * @param {?google.ima.AdsRenderingSettings} adsRenderingSettings
  211.    */
  212.   initClientSide(adContainer, video, adsRenderingSettings) {}
  214.   /**
  215.    * @param {!google.ima.AdsRequest} imaRequest
  216.    */
  217.   requestClientSideAds(imaRequest) {}
  219.   /**
  220.    * @param {!google.ima.AdsRenderingSettings} adsRenderingSettings
  221.    */
  222.   updateClientSideAdsRenderingSettings(adsRenderingSettings) {}
  224.   /**
  225.    * @param {!HTMLElement} adContainer
  226.    * @param {!shaka.net.NetworkingEngine} networkingEngine
  227.    * @param {!HTMLMediaElement} video
  228.    */
  229.   initMediaTailor(adContainer, networkingEngine, video) {}
  231.   /**
  232.    * @param {string} url
  233.    * @param {Object} adsParams
  234.    * @param {string=} backupUrl
  235.    * @return {!Promise<string>}
  236.    */
  237.   requestMediaTailorStream(url, adsParams, backupUrl) {}
  239.   /**
  240.    * @param {string} url
  241.    */
  242.   addMediaTailorTrackingUrl(url) {}
  244.   /**
  245.    * @param {!HTMLElement} adContainer
  246.    * @param {!HTMLMediaElement} video
  247.    */
  248.   initServerSide(adContainer, video) {}
  250.   /**
  251.    * @param {!google.ima.dai.api.StreamRequest} imaRequest
  252.    * @param {string=} backupUrl
  253.    * @return {!Promise<string>}
  254.    */
  255.   requestServerSideStream(imaRequest, backupUrl) {}
  257.   /**
  258.    * @param {Object} adTagParameters
  259.    */
  260.   replaceServerSideAdTagParameters(adTagParameters) {}
  262.   /**
  263.    * @return {!Array<!shaka.extern.AdCuePoint>}
  264.    */
  265.   getServerSideCuePoints() {}
  267.   /**
  268.    * @return {!Array<!shaka.extern.AdCuePoint>}
  269.    */
  270.   getCuePoints() {}
  272.   /**
  273.    * Get statistics for the current playback session. If the player is not
  274.    * playing content, this will return an empty stats object.
  275.    */
  276.   getStats() {}
  278.   /**
  279.    * @param {shaka.extern.TimelineRegionInfo} region
  280.    */
  281.   onDashTimedMetadata(region) {}
  283.   /**
  284.    * Fired when the manifest is updated.
  285.    *
  286.    * @param {boolean} isLive
  287.    */
  288.   onManifestUpdated(isLive) {}
  290.   /**
  291.    * @param {shaka.extern.ID3Metadata} metadata
  292.    * @param {number} timestampOffset
  293.    */
  294.   onHlsTimedMetadata(metadata, timestampOffset) {}
  296.   /**
  297.    * @param {shaka.extern.MetadataFrame} value
  298.    */
  299.   onCueMetadataChange(value) {}
  301.   /**
  302.    * @param {!shaka.Player} basePlayer
  303.    * @param {!HTMLMediaElement} baseVideo
  304.    * @param {shaka.extern.HLSInterstitial} interstitial
  305.    */
  306.   onHLSInterstitialMetadata(basePlayer, baseVideo, interstitial) {}
  308.   /**
  309.    * @param {!shaka.Player} basePlayer
  310.    * @param {!HTMLMediaElement} baseVideo
  311.    * @param {shaka.extern.TimelineRegionInfo} region
  312.    */
  313.   onDASHInterstitialMetadata(basePlayer, baseVideo, region) {}
  315.   /**
  316.    * @param {shaka.extern.AdInterstitial} interstitial
  317.    */
  318.   addCustomInterstitial(interstitial) {}
  320.   /**
  321.    * @param {string} url
  322.    * @return {!Promise}
  323.    */
  324.   addAdUrlInterstitial(url) {}
  326.   /**
  327.    * @return {shaka.Player}
  328.    */
  329.   getInterstitialPlayer() {}
  330. };
  333. /**
  334.  * A factory for creating the ad manager.
  335.  *
  336.  * @typedef {function():!shaka.extern.IAdManager}
  337.  * @exportDoc
  338.  */
  339. shaka.extern.IAdManager.Factory;
  342. /**
  343.  * Interface for Ad objects.
  344.  *
  345.  * @extends {shaka.util.IReleasable}
  346.  * @interface
  347.  * @exportDoc
  348.  */
  349. shaka.extern.IAd = class {
  350.   /**
  351.    * @return {boolean}
  352.    */
  353.   needsSkipUI() {}
  355.   /**
  356.    * @return {boolean}
  357.    */
  358.   isClientRendering() {}
  360.   /**
  361.    * @return {boolean}
  362.    */
  363.   hasCustomClick() {}
  365.   /**
  366.    * @return {boolean}
  367.    */
  368.   isUsingAnotherMediaElement() {}
  370.   /**
  371.    * @return {number}
  372.    */
  373.   getDuration() {}
  375.   /**
  376.    * Gets the minimum suggested duration.  Defaults to being equivalent to
  377.    * getDuration() for server-side ads.
  378.    * @see http://bit.ly/3q3U6hI
  379.    * @return {number}
  380.    */
  381.   getMinSuggestedDuration() {}
  383.   /**
  384.    * @return {number}
  385.    */
  386.   getRemainingTime() {}
  388.   /**
  389.    * @return {number}
  390.    */
  391.   getTimeUntilSkippable() {}
  393.   /**
  394.    * @return {boolean}
  395.    */
  396.   isPaused() {}
  398.   /**
  399.    * @return {boolean}
  400.    */
  401.   isSkippable() {}
  403.   /**
  404.    * @return {boolean}
  405.    */
  406.   canSkipNow() {}
  408.   skip() {}
  410.   play() {}
  412.   pause() {}
  414.   /**
  415.    * @return {number}
  416.    */
  417.   getVolume() {}
  419.   /**
  420.    * @param {number} volume
  421.    */
  422.   setVolume(volume) {}
  424.   /**
  425.    * @return {boolean}
  426.    */
  427.   isMuted() {}
  429.   /**
  430.    * @param {boolean} muted
  431.    */
  432.   setMuted(muted) {}
  434.   /**
  435.    * @return {boolean}
  436.    */
  437.   isLinear() {}
  439.   /**
  440.    * @param {number} width
  441.    * @param {number} height
  442.    */
  443.   resize(width, height) {}
  445.   /**
  446.    * @return {number}
  447.    */
  448.   getSequenceLength() {}
  450.   /**
  451.    * @return {number}
  452.    */
  453.   getPositionInSequence() {}
  455.   /**
  456.    * @return {string}
  457.    */
  458.   getTitle() {}
  460.   /**
  461.    * @return {string}
  462.    */
  463.   getDescription() {}
  465.   /**
  466.    * @return {number}
  467.    */
  468.   getVastMediaBitrate() {}
  470.   /**
  471.    * @return {number}
  472.    */
  473.   getVastMediaHeight() {}
  475.   /**
  476.    * @return {number}
  477.    */
  478.   getVastMediaWidth() {}
  480.   /**
  481.    * @return {string}
  482.    */
  483.   getAdId() {}
  485.   /**
  486.    * @return {string}
  487.    */
  488.   getCreativeAdId() {}
  490.   /**
  491.    * @return {string}
  492.    */
  493.   getAdvertiserName() {}
  495.   /**
  496.    * @return {?string}
  497.    */
  498.   getMediaUrl() {}
  500.   /**
  501.    * @return {number}
  502.    */
  503.   getTimeOffset() {}
  505.   /**
  506.    * @return {number}
  507.    */
  508.   getPodIndex() {}
  509. };