Source: ui/externs/ui.js

  1. /*! @license
  2. * Shaka Player
  3. * Copyright 2016 Google LLC
  4. * SPDX-License-Identifier: Apache-2.0
  5. */
  6. /**
  7. * @externs
  8. * @suppress {duplicate} To prevent compiler errors with the namespace
  9. * being declared both here and by goog.provide in the library.
  10. */
  11. /** @namespace */
  12. var shaka = {};
  13. /** @namespace */
  14. shaka.extern = {};
  15. /**
  16. * @typedef {{
  17. * base: string,
  18. * buffered: string,
  19. * played: string,
  20. * adBreaks: string
  21. * }}
  22. *
  23. * @property {string} base
  24. * The CSS background color applied to the base of the seek bar, on top of
  25. * which the buffer level and playback position are shown.
  26. * @property {string} buffered
  27. * The CSS background color applied to the portion of the seek bar showing
  28. * what has been buffered ahead of the playback position.
  29. * @property {string} played
  30. * The CSS background color applied to the portion of the seek bar showing
  31. * what has been played already.
  32. * @property {string} adBreaks
  33. * The CSS background color applied to the portion of the seek bar showing
  34. * when the ad breaks are scheduled to occur on the timeline.
  35. * @exportDoc
  36. */
  37. shaka.extern.UISeekBarColors;
  38. /**
  39. * @typedef {{
  40. * base: string,
  41. * level: string
  42. * }}
  43. *
  44. * @property {string} base
  45. * The CSS background color applied to the base of the volume bar, on top of
  46. * which the volume level is shown.
  47. * @property {string} level
  48. * The CSS background color applied to the portion of the volume bar showing
  49. * the volume level.
  50. * @exportDoc
  51. */
  52. shaka.extern.UIVolumeBarColors;
  53. /**
  54. * @typedef {{
  55. * 720: string,
  56. * 1080: string,
  57. * 1440: string,
  58. * 2160: string,
  59. * 4320: string
  60. * }}
  61. *
  62. * @property {string} 720
  63. * The mark that will be displayed when the quality is 720p.
  64. * <br>
  65. * Defaults to ''.
  66. * @property {string} 1080
  67. * The mark that will be displayed when the quality is 1080p.
  68. * <br>
  69. * Defaults to 'HD'.
  70. * @property {string} 1440
  71. * The mark that will be displayed when the quality is 1440p.
  72. * <br>
  73. * Defaults to '2K'.
  74. * @property {string} 2160
  75. * The mark that will be displayed when the quality is 2160p.
  76. * <br>
  77. * Defaults to '4K'.
  78. * @property {string} 4320
  79. * The mark that will be displayed when the quality is 4320p.
  80. * <br>
  81. * Defaults to '8K'.
  82. * @exportDoc
  83. */
  84. shaka.extern.UIQualityMarks;
  85. /**
  86. * @description
  87. * The UI's configuration options.
  88. *
  89. * @typedef {{
  90. * controlPanelElements: !Array<string>,
  91. * overflowMenuButtons: !Array<string>,
  92. * contextMenuElements: !Array<string>,
  93. * statisticsList: !Array<string>,
  94. * adStatisticsList: !Array<string>,
  95. * playbackRates: !Array<number>,
  96. * fastForwardRates: !Array<number>,
  97. * rewindRates: !Array<number>,
  98. * addSeekBar: boolean,
  99. * addBigPlayButton: boolean,
  100. * customContextMenu: boolean,
  101. * castReceiverAppId: string,
  102. * castAndroidReceiverCompatible: boolean,
  103. * clearBufferOnQualityChange: boolean,
  104. * showUnbufferedStart: boolean,
  105. * seekBarColors: shaka.extern.UISeekBarColors,
  106. * volumeBarColors: shaka.extern.UIVolumeBarColors,
  107. * qualityMarks: shaka.extern.UIQualityMarks,
  108. * trackLabelFormat: shaka.ui.Overlay.TrackLabelFormat,
  109. * textTrackLabelFormat: shaka.ui.Overlay.TrackLabelFormat,
  110. * fadeDelay: number,
  111. * closeMenusDelay: number,
  112. * doubleClickForFullscreen: boolean,
  113. * singleClickForPlayAndPause: boolean,
  114. * enableKeyboardPlaybackControls: boolean,
  115. * enableFullscreenOnRotation: boolean,
  116. * forceLandscapeOnFullscreen: boolean,
  117. * enableTooltips: boolean,
  118. * keyboardSeekDistance: number,
  119. * keyboardLargeSeekDistance: number,
  120. * fullScreenElement: HTMLElement,
  121. * preferDocumentPictureInPicture: boolean,
  122. * showAudioChannelCountVariants: boolean,
  123. * seekOnTaps: boolean,
  124. * tapSeekDistance: number,
  125. * refreshTickInSeconds: number,
  126. * displayInVrMode: boolean,
  127. * defaultVrProjectionMode: string,
  128. * setupMediaSession: boolean,
  129. * preferVideoFullScreenInVisionOS: boolean,
  130. * showAudioCodec: boolean,
  131. * showVideoCodec: boolean,
  132. * castSenderUrl: string
  133. * }}
  134. *
  135. * @property {!Array<string>} controlPanelElements
  136. * The ordered list of control panel elements of the UI.
  137. * @property {!Array<string>} overflowMenuButtons
  138. * The ordered list of the overflow menu buttons.
  139. * @property {!Array<string>} contextMenuElements
  140. * The ordered list of buttons in the context menu.
  141. * @property {!Array<string>} statisticsList
  142. * The ordered list of statistics present in the statistics container.
  143. * @property {!Array<string>} adStatisticsList
  144. * The ordered list of ad statistics present in the ad statistics container.
  145. * @property {!Array<number>} playbackRates
  146. * The ordered list of rates for playback selection.
  147. * <br>
  148. * Defaults to <code>[0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]</code>.
  149. * @property {!Array<number>} fastForwardRates
  150. * The ordered list of rates for fast forward selection.
  151. * <br>
  152. * Defaults to <code>[2, 4, 8, 1]</code>.
  153. * @property {!Array<number>} rewindRates
  154. * The ordered list of rates for rewind selection.
  155. * <br>
  156. * Defaults to <code>[-1, -2, -4, -8]</code>.
  157. * @property {boolean} addSeekBar
  158. * Whether or not a seek bar should be part of the UI.
  159. * <br>
  160. * Defaults to <code>true</code>.
  161. * @property {boolean} addBigPlayButton
  162. * Whether or not a big play button in the center of the video
  163. * should be part of the UI.
  164. * <br>
  165. * Defaults to <code>false</code> except on mobile where the default value
  166. * is <code>true</code>
  167. * @property {boolean} customContextMenu
  168. * Whether or not a custom context menu replaces the default.
  169. * <br>
  170. * Defaults to <code>false</code>.
  171. * @property {string} castReceiverAppId
  172. * Receiver app id to use for the Chromecast support.
  173. * <br>
  174. * Defaults to <code>''</code>.
  175. * @property {boolean} castAndroidReceiverCompatible
  176. * Indicates if the app is compatible with an Android Cast Receiver.
  177. * <br>
  178. * Defaults to <code>false</code>.
  179. * @property {boolean} clearBufferOnQualityChange
  180. * Only applicable if the resolution selection is part of the UI.
  181. * Whether buffer should be cleared when changing resolution
  182. * via UI. Clearing buffer would result in immediate change of quality,
  183. * but playback may flicker/stall for a sec as the content in new
  184. * resolution is being buffered. Not clearing the buffer will mean
  185. * we play the content in the previously selected resolution that we
  186. * already have buffered before switching to the new resolution.
  187. * <br>
  188. * Defaults to <code>true</code>.
  189. * @property {boolean} showUnbufferedStart
  190. * If true, color any unbuffered region at the start of the seek bar as
  191. * unbuffered (using the "base" color). If false, color any unbuffered region
  192. * at the start of the seek bar as played (using the "played" color).
  193. * <br>
  194. * A value of false matches the default behavior of Chrome's native controls
  195. * and Shaka Player v3.0+.
  196. * <br>
  197. * A value of true matches the default behavior of Shaka Player v2.5.
  198. * <br>
  199. * Defaults to <code>false</code>.
  200. * @property {shaka.extern.UISeekBarColors} seekBarColors
  201. * The CSS colors applied to the seek bar. This allows you to override the
  202. * colors used in the linear gradient constructed in JavaScript, since you
  203. * cannot easily do this in pure CSS.
  204. * @property {shaka.extern.UIVolumeBarColors} volumeBarColors
  205. * The CSS colors applied to the volume bar. This allows you to override the
  206. * colors used in the linear gradient constructed in JavaScript, since you
  207. * cannot do this in pure CSS.
  208. * @property {shaka.extern.UIQualityMarks} qualityMarks
  209. * The name of the quality marks.
  210. * @property {shaka.ui.Overlay.TrackLabelFormat} trackLabelFormat
  211. * An enum that determines what is shown in the labels for audio variant
  212. * selection.
  213. * LANGUAGE means that only the language of the item is shown.
  214. * ROLE means that only the role of the item is shown.
  215. * LANGUAGE_ROLE means both language and role are shown, or just language if
  216. * there is no role.
  217. * LABEL means the non-standard DASH "label" attribute or the standard DASH
  218. * "Label" element or the HLS "NAME" attribute are shown.
  219. * <br>
  220. * Defaults to <code>LANGUAGE</code>.
  221. * @property {shaka.ui.Overlay.TrackLabelFormat} textTrackLabelFormat
  222. * An enum that determines what is shown in the labels for text track
  223. * selection.
  224. * LANGUAGE means that only the language of the item is shown.
  225. * ROLE means that only the role of the item is shown.
  226. * LANGUAGE_ROLE means both language and role are shown, or just language if
  227. * there is no role.
  228. * LABEL means the non-standard DASH "label" attribute or the standard DASH
  229. * "Label" element or the HLS "NAME" attribute are shown.
  230. * <br>
  231. * Defaults to <code>LANGUAGE</code>.
  232. * @property {number} fadeDelay
  233. * The delay (in seconds) before fading out the controls once the user stops
  234. * interacting with them. We recommend setting this to 3 on your cast
  235. * receiver UI.
  236. * <br>
  237. * Defaults to <code>0</code>.
  238. * @property {number} closeMenusDelay
  239. * The delay (in seconds) before close the opened menus when the UI is hidden.
  240. * <br>
  241. * Defaults to <code>2</code>.
  242. * @property {boolean} doubleClickForFullscreen
  243. * Whether or not double-clicking on the UI should cause it to enter
  244. * fullscreen.
  245. * <br>
  246. * Defaults to <code>true</code> except on mobile and smart TV whose default
  247. * value is <code>false</code>.
  248. * @property {boolean} singleClickForPlayAndPause
  249. * Whether or not clicking on the video should cause it to play or pause.
  250. * It does not work in VR mode.
  251. * <br>
  252. * Defaults to <code>true</code> except on mobile and smart TV whose default
  253. * value is <code>false</code>.
  254. * @property {boolean} enableKeyboardPlaybackControls
  255. * Whether or not playback controls via keyboard is enabled, such as seek
  256. * forward, seek backward, jump to the beginning/end of the video.
  257. * <br>
  258. * Defaults to <code>true</code>.
  259. * @property {boolean} enableFullscreenOnRotation
  260. * Whether or not to enter/exit fullscreen mode when the screen is rotated.
  261. * <br>
  262. * Defaults to <code>false</code> except on mobile where the default value
  263. * is <code>true</code>
  264. * @property {boolean} forceLandscapeOnFullscreen
  265. * Whether or not the device should rotate to landscape mode when the video
  266. * enters fullscreen. Note that this behavior is based on an experimental
  267. * browser API, and may not work on all platforms.
  268. * <br>
  269. * Defaults to <code>false</code> except on mobile where the default value
  270. * is <code>true</code>
  271. * @property {boolean} enableTooltips
  272. * Whether or not buttons in the control panel display tooltips that contain
  273. * information about their function.
  274. * <br>
  275. * Defaults to <code>true</code> except on mobile and smart TV whose default
  276. * value is <code>false</code>.
  277. * @property {number} keyboardSeekDistance
  278. * The time interval, in seconds, to seek when the user presses the left or
  279. * right keyboard keys when the video is selected. If less than or equal to 0,
  280. * no seeking will occur.
  281. * <br>
  282. * Defaults to <code>5</code>.
  283. * @property {number} keyboardLargeSeekDistance
  284. * The time interval, in seconds, to seek when the user presses the page up or
  285. * page down keyboard keys when the video is selected. If less than or equal
  286. * to 0, no seeking will occur.
  287. * <br>
  288. * Defaults to <code>60</code>.
  289. * @property {HTMLElement} fullScreenElement
  290. * DOM element on which fullscreen will be done.
  291. * <br>
  292. * Defaults to <code>Shaka Player Container</code>.
  293. * @property {boolean} preferDocumentPictureInPicture
  294. * Indicates whether the Document Picture in Picture API is preferred or the
  295. * Video Element Picture in Picture API is preferred.
  296. * Changing this property in mid-playback may produce undesired behavior if
  297. * you are already in PiP.
  298. * <br>
  299. * Defaults to <code>true</code>.
  300. * @property {boolean} showAudioChannelCountVariants
  301. * Indicates whether the combination of language and channel count should be
  302. * displayed or if, on the contrary, only the language should be displayed
  303. * regardless of the channel count.
  304. * <br>
  305. * Defaults to <code>true</code>.
  306. * @property {boolean} seekOnTaps
  307. * Indicates whether or not a fast-forward and rewind tap button that seeks
  308. * video some seconds.
  309. * <br>
  310. * Defaults to <code>false</code> except on mobile where the default value
  311. * is <code>true</code>
  312. * @property {number} tapSeekDistance
  313. * The time interval, in seconds, to seek when the user presses the left or
  314. * right part of the video. If less than or equal to 0,
  315. * no seeking will occur.
  316. * <br>
  317. * Defaults to <code>10</code>.
  318. * @property {number} refreshTickInSeconds
  319. * The time interval, in seconds, to update the seek bar.
  320. * <br>
  321. * Defaults to <code>0.125</code>.
  322. * @property {boolean} displayInVrMode
  323. * If true, the content will be treated as VR.
  324. * If false, it will only be treated as VR if we automatically detect it as
  325. * such. (See the Enabling VR section in docs/tutorials/ui.md)
  326. * <br>
  327. * Defaults to <code>false</code>.
  328. * @property {string} defaultVrProjectionMode
  329. * Indicate the default VR projection mode.
  330. * Possible values: <code>'equirectangular'</code> or
  331. * <code>'halfequirectangular'</code> or <code>'cubemap'</code>.
  332. * <br>
  333. * Defaults to <code>'equirectangular'</code>.
  334. * @property {boolean} setupMediaSession
  335. * If true, MediaSession controls will be managed by the UI. It will also use
  336. * the ID3 APIC and TIT2 as image and title in Media Session, and ID3 APIC
  337. * will also be used to change video poster.
  338. * <br>
  339. * Defaults to <code>true</code>.
  340. * @property {boolean} preferVideoFullScreenInVisionOS
  341. * If true, we will use the fullscreen API of the video element itself if it
  342. * is available in Vision OS. This is useful to be able to access 3D
  343. * experiences that are only allowed with the fullscreen of the video element
  344. * itself.
  345. * <br>
  346. * Defaults to <code>false</code>.
  347. * @property {boolean} showAudioCodec
  348. * Show the audio codec if the language has more than one audio codec.
  349. * <br>
  350. * Defaults to <code>true</code>.
  351. * @property {boolean} showVideoCodec
  352. * Show the video codec if the resolution has more than one video codec.
  353. * <br>
  354. * Defaults to <code>true</code>.
  355. * @property {string} castSenderUrl
  356. * URL to load the cast sender if your platform supports it. This URL does not
  357. * apply to Smart TVs.
  358. * Note: This URL is only used if the cast sender is not previously loaded.
  359. * <br>
  360. * Defaults to
  361. * <code>'https://www.gstatic.com/cv/js/sender/v1/cast_sender.js'</code>.
  362. * @exportDoc
  363. */
  364. shaka.extern.UIConfiguration;
  365. /**
  366. * Interface for UI elements. UI elements should inherit from the concrete base
  367. * class shaka.ui.Element. The members defined in this extern's constructor are
  368. * all available from the base class, and are defined here to keep the compiler
  369. * from renaming them.
  370. *
  371. * @extends {shaka.util.IReleasable}
  372. * @interface
  373. * @exportDoc
  374. */
  375. shaka.extern.IUIElement = class {
  376. /**
  377. * @param {!HTMLElement} parent
  378. * @param {!shaka.ui.Controls} controls
  379. */
  380. constructor(parent, controls) {
  381. /**
  382. * @protected {HTMLElement}
  383. * @exportDoc
  384. */
  385. this.parent;
  386. /**
  387. * @protected {shaka.ui.Controls}
  388. * @exportDoc
  389. */
  390. this.controls;
  391. /**
  392. * @protected {shaka.util.EventManager}
  393. * @exportDoc
  394. */
  395. this.eventManager;
  396. /**
  397. * @protected {shaka.ui.Localization}
  398. * @exportDoc
  399. */
  400. this.localization;
  401. /**
  402. * @protected {shaka.Player}
  403. * @exportDoc
  404. */
  405. this.player;
  406. /**
  407. * @protected {HTMLMediaElement}
  408. * @exportDoc
  409. */
  410. this.video;
  411. /**
  412. * @protected {shaka.extern.IAdManager}
  413. * @exportDoc
  414. */
  415. this.adManager;
  416. /**
  417. * @protected {shaka.extern.IAd}
  418. * @exportDoc
  419. */
  420. this.ad;
  421. }
  422. /**
  423. * @override
  424. */
  425. release() {}
  426. };
  427. /**
  428. * A factory for creating a UI element.
  429. *
  430. * @interface
  431. * @exportDoc
  432. */
  433. shaka.extern.IUIElement.Factory = class {
  434. /**
  435. * @param {!HTMLElement} rootElement
  436. * @param {!shaka.ui.Controls} controls
  437. * @return {!shaka.extern.IUIElement}
  438. */
  439. create(rootElement, controls) {}
  440. };
  441. /**
  442. * Interface for UI range elements. UI range elements should inherit from the
  443. * concrete base class shaka.ui.RangeElement. The members defined in this
  444. * extern's constructor are all available from the base class, and are defined
  445. * here to keep the compiler from renaming them.
  446. *
  447. * @extends {shaka.extern.IUIElement}
  448. * @interface
  449. * @exportDoc
  450. */
  451. shaka.extern.IUIRangeElement = class {
  452. /**
  453. * @param {!HTMLElement} parent
  454. * @param {!shaka.ui.Controls} controls
  455. * @param {!Array<string>} containerClassNames
  456. * @param {!Array<string>} barClassNames
  457. */
  458. constructor(parent, controls, containerClassNames, barClassNames) {
  459. /**
  460. * @protected {!HTMLElement}
  461. * @exportDoc
  462. */
  463. this.container;
  464. /**
  465. * @protected {!HTMLInputElement}
  466. * @exportDoc
  467. */
  468. this.bar;
  469. }
  470. /**
  471. * @param {number} min
  472. * @param {number} max
  473. */
  474. setRange(min, max) {}
  475. /**
  476. * Called when user interaction begins.
  477. * To be overridden by subclasses.
  478. */
  479. onChangeStart() {}
  480. /**
  481. * Called when a new value is set by user interaction.
  482. * To be overridden by subclasses.
  483. */
  484. onChange() {}
  485. /**
  486. * Called when user interaction ends.
  487. * To be overridden by subclasses.
  488. */
  489. onChangeEnd() {}
  490. /** @return {number} */
  491. getValue() {}
  492. /** @param {number} value */
  493. setValue(value) {}
  494. /** @param {number} value */
  495. changeTo(value) {}
  496. };
  497. /**
  498. * Interface for UI settings menus. UI settings menus should inherit from the
  499. * concrete base class shaka.ui.SettingsMenu. The members defined in this
  500. * extern's constructor are all available from the base class, and are defined
  501. * here to keep the compiler from renaming them.
  502. *
  503. * @extends {shaka.extern.IUIElement}
  504. * @interface
  505. * @exportDoc
  506. */
  507. shaka.extern.IUISettingsMenu = class {
  508. /**
  509. * @param {!HTMLElement} parent
  510. * @param {!shaka.ui.Controls} controls
  511. * @param {string} iconText
  512. */
  513. constructor(parent, controls, iconText) {
  514. /**
  515. * @protected {!HTMLButtonElement}
  516. * @exportDoc
  517. */
  518. this.button;
  519. /**
  520. * @protected {!HTMLElement}
  521. * @exportDoc
  522. */
  523. this.icon;
  524. /**
  525. * @protected {!HTMLElement}
  526. * @exportDoc
  527. */
  528. this.nameSpan;
  529. /**
  530. * @protected {!HTMLElement}
  531. * @exportDoc
  532. */
  533. this.currentSelection;
  534. /**
  535. * @protected {!HTMLElement}
  536. * @exportDoc
  537. */
  538. this.menu;
  539. /**
  540. * @protected {!HTMLButtonElement}
  541. * @exportDoc
  542. */
  543. this.backButton;
  544. /**
  545. * @protected {!HTMLElement}
  546. * @exportDoc
  547. */
  548. this.backSpan;
  549. }
  550. };
  551. /**
  552. * Interface for SeekBars. SeekBars should inherit from the concrete base
  553. * class shaka.ui.Element. If you do not need to totally rebuild the
  554. * SeekBar, you should consider using shaka.ui.RangeElement or
  555. * shaka.ui.SeekBar as your base class.
  556. *
  557. * @extends {shaka.extern.IUIRangeElement}
  558. * @interface
  559. * @exportDoc
  560. */
  561. shaka.extern.IUISeekBar = class {
  562. /** @return {number} */
  563. getValue() {}
  564. /** @param {number} value */
  565. setValue(value) {}
  566. /**
  567. * Called by Controls on a timer to update the state of the seek bar.
  568. * Also called internally when the user interacts with the input element.
  569. */
  570. update() {}
  571. /** @return {boolean} */
  572. isShowing() {}
  573. };
  574. /**
  575. * A factory for creating a SeekBar element.
  576. *
  577. * @interface
  578. * @exportDoc
  579. */
  580. shaka.extern.IUISeekBar.Factory = class {
  581. /**
  582. * @param {!HTMLElement} rootElement
  583. * @param {!shaka.ui.Controls} controls
  584. * @return {!shaka.extern.IUISeekBar}
  585. */
  586. create(rootElement, controls) {}
  587. };
  588. /**
  589. * @interface
  590. * @exportDoc
  591. */
  592. shaka.extern.IUIPlayButton = class {
  593. /**
  594. * @param {!HTMLElement} parent
  595. * @param {!shaka.ui.Controls} controls
  596. */
  597. constructor(parent, controls) {
  598. /**
  599. * @protected {!HTMLButtonElement}
  600. * @exportDoc
  601. */
  602. this.button;
  603. }
  604. /** @return {boolean} */
  605. isPaused() {}
  606. /** @return {boolean} */
  607. isEnded() {}
  608. };