diff --git a/youtube/index.d.ts b/youtube/index.d.ts index ca5d99550a..a45ec6a8c8 100644 --- a/youtube/index.d.ts +++ b/youtube/index.d.ts @@ -1,166 +1,935 @@ // Type definitions for YouTube // Project: https://developers.google.com/youtube/ -// Definitions by: Daz Wilkin , Ian Obermiller +// Definitions by: Daz Wilkin , +// Ian Obermiller , +// Josh Goldberg // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.1 -declare namespace YT { - interface EventArgs { - target: Player; - data: any; - } - - interface EventHandler { - (event: EventArgs): void; - } - - export interface Events { - onReady?: EventHandler; - onPlayback?: EventHandler; - onStateChange?: EventHandler; - onError?: EventHandler; - } - - export enum ListType { - search, - user_uploads, - playlist, +/** + * @see https://developers.google.com/youtube/iframe_api_reference + * @see https://developers.google.com/YouTube/player_parameters + */ +declare namespace YT +{ + /** + * State of a video player. + */ + export enum PlayerState + { + UNSTARTED = -1, + ENDED = 0, + PLAYING = 1, + PAUSED = 2, + BUFFERING = 3, + CUED = 5 } - export interface PlayerVars { - autohide?: number; - autoplay?: number; - cc_load_policy?: any; - color?: string; - controls?: number; - disablekb?: number; - enablejsapi?: number; + /** + * Known causes for player errors. + */ + export const enum PlayerError + { + /** + * The request contained an invalid parameter value. + */ + InvalidParam = 2, + + /** + * The requested content cannot be played in an HTML5 player. + */ + Html5Error = 5, + + /** + * The video requested was not found. + */ + VideoNotFound = 100, + + /** + * The owner of the requested video does not allow it to be played in embedded players. + */ + EmbeddingNotAllowed = 101, + + /** + * This error is the same as 101. It's just a 101 error in disguise! + */ + EmbeddingNotAllowed2 = 150 + } + + /** + * Whether to auto-hide video controls. + */ + export const enum AutoHide + { + /** + * Controls are visible throughout the video + */ + AlwaysVisible = 0, + + /** + * Progress bar and player controls slide out of view after a couple of seconds. + */ + HideAllControls = 1, + + /** + * Progress bar fades out while the player controls remain visible. + */ + HideProgressBar = 2 + } + + /** + * Whether to autoplay the video. + */ + export const enum AutoPlay + { + /** + * Video does not autoplay. + */ + NoAutoPlay = 0, + + /** + * Video will autoplay when loaded. + */ + AutoPlay = 1 + } + + /** + * Whether to use user-preferred or forced caption loading. + */ + export const enum ClosedCaptionsLoadPolicy + { + /** + * Defaults to the user's preferences. + */ + UserDefault = 0, + + /** + * For closed captions to be shown. + */ + ForceOn = 1 + } + + /** + * Allowed progress bar colors. + */ + export type ProgressBarColor = "red" | "white"; + + /** + * How video controls are shown. + */ + export const enum Controls + { + /** + * Player controls do not display. + */ + Hide = 0, + + /** + * Player controls display. + */ + ShowLoadPlayer = 1, + + /** + * Player controls display after a delay. + */ + ShowDelayLoadPlayer = 2 + } + + /** + * Whether to allow keyboard controls. + */ + export const enum KeyboardControls + { + /** + * Keyboard controls are enabled. + */ + Enable = 0, + + /** + * Keyboard controls are disabled. + */ + Disable = 1 + } + + /** + * Whether the JavaScript API should be enabled. + */ + export const enum JsApi + { + /** + * JavaScript API will be disabled. + */ + Disable = 0, + + /** + * JavaScript API will be enabled. + */ + Enable = 1 + } + + /** + * Whether to display the full-screen button. + */ + export const enum FullscreenButton + { + /** + * The full screen button is hidden. + */ + Hide = 0, + + /** + * The full screen button is visible. + */ + Show = 1 + } + + /** + * Whether to show video annotations. + */ + export const enum IvLoadPolicy + { + /** + * Video annotations will be shown. + */ + Show = 1, + + /** + * Video annotations will not be shown. + */ + Hide = 3 + } + + /** + * Which type of content loads in the player. + */ + export type ListType = ListTypePlayer | ListTypeSearch | ListTypeUserUploads; + + /** + * The requested video should be shown in the player. + */ + export type ListTypePlayer = "player"; + + /** + * A search area should be shown in the player. + */ + export type ListTypeSearch = "search"; + + /** + * The user's uploads should load in the player. + */ + export type ListTypeUserUploads = "user_uploads"; + + /** + * Whether a single video should be looped. + */ + export const enum Loop + { + /** + * Video or playlist will be played only once. + */ + SinglePlay = 0, + + /** + * Video or playlist will be played over and over again. + */ + Loop = 1 + } + + /** + * Comma separated list of video IDs to play after the URL path's video. + */ + export const enum ModestBranding + { + /** + * Player will contain full YouTube branding. + */ + Full = 0, + + /** + * YouTube logo will not display in the control bar. + */ + Modest = 1 + } + + /** + * Whether to show related videos after the video finishes. + */ + export const enum RelatedVideos + { + /** + * Hide related videos after playback is complete. + */ + Hide = 0, + + /** + * Show related videos after playback is complete. + */ + Show = 1 + } + + /** + * Whether to show video information before playing. + */ + export const enum ShowInfo + { + /** + * Hide video title and uploader before video starts playing. + */ + Hide = 0, + + /** + * Show video title and uploader before video starts playing. + */ + Show = 1 + } + + /** + * Base interface for events triggered by a player. + */ + export interface PlayerEvent + { + /** + * Video player corresponding to the event. + */ + target: Player; + } + + /** + * Event for player state change. + */ + export interface OnStateChangeEvent extends PlayerEvent + { + /** + * New player state. + */ + data: PlayerState; + } + + /** + * Event for playback quality change. + */ + export interface OnPlaybackQualityChangeEvent extends PlayerEvent + { + /** + * New playback quality. + */ + data: string; + } + + /** + * Event for playback rate change. + */ + export interface OnPlaybackRateChangeEvent extends PlayerEvent + { + /** + * New playback rate. + */ + data: number; + } + + /** + * Event for a player error. + */ + export interface OnErrorEvent extends PlayerEvent + { + /** + * Which type of error occurred. + */ + data: PlayerError; + } + + /** + * Handles a player event. + * + * @param event The triggering event. + */ + export interface PlayerEventHandler + { + (event: TEvent): void; + } + + /** + * YouTube player options. + */ + export interface PlayerOptions + { + /** + * Player width. + */ + width?: number; + + /** + * Player height + */ + height?: number; + + /** + * ID of the video to load. + */ + videoId: string; + + /** + * Player parameters. + */ + playerVars?: PlayerVars; + + /** + * Handlers for events fired by the player. + */ + events?: Events; + } + + /** + * Allowed suggested player video qualities. + */ + export type SuggestedVideoQuality = ( + VideoQualityDefault + | VideoQualitySmall + | VideoQualityMedium + | VideoQualityLarge + | VideoQualityHD720 + | VideoQualityHD1080 + | VideoQualityHighRes); + + /** + * Default video quality chosen by YouTube. + */ + export type VideoQualityDefault = "default"; + + /** + * Player height is 240px, and player dimensions are at least 320px by 240px for 4:3 aspect ratio. + */ + export type VideoQualitySmall = "small"; + + /** + * Player height is 360px, and player dimensions are 640px by 360px (for 16:9 aspect ratio) or 480px by 360px (for 4:3 aspect ratio). + */ + export type VideoQualityMedium = "medium"; + + /** + * Player height is 480px, and player dimensions are 853px by 480px (for 16:9 aspect ratio) or 640px by 480px (for 4:3 aspect ratio). + */ + export type VideoQualityLarge = "large"; + + /** + * Player height is 720px, and player dimensions are 1280px by 720px (for 16:9 aspect ratio) or 960px by 720px (for 4:3 aspect ratio). + */ + export type VideoQualityHD720 = "hd720"; + + /** + * Player height is 1080px, and player dimensions are 1920px by 1080px (for 16:9 aspect ratio) or 1440px by 1080px (for 4:3 aspect ratio). + */ + export type VideoQualityHD1080 = "hd1080"; + + /** + * Player height is greater than 1080px, which means that the player's aspect ratio is greater than 1920px by 1080px. + */ + export type VideoQualityHighRes = "highres"; + + /** + * Player parameters. + */ + export interface PlayerVars + { + /** + * Whether to autohide video controls (by default, HideProgressBar). + */ + autohide?: AutoHide; + + /** + * Whether to autoplay the video (by default, NoAutoPlay). + */ + autoplay?: AutoPlay; + + /** + * Whether to use user-preferred or forced caption loading (by default, UserDefault). + */ + cc_load_policy?: ClosedCaptionsLoadPolicy; + + /** + * Player progress bar color + */ + color?: ProgressBarColor; + + /** + * How video controls are shown (by default, ShowLoadPlayer). + */ + controls?: Controls; + + /** + * Whether to allow keyboard controls (by default, Enable). + */ + disablekb?: KeyboardControls; + + /** + * Whether the JavaScript API should be enabled (by default, Disable). + */ + enablejsapi?: JsApi; + + /** + * Time, in seconds from the beginning of the video, when to stop playing. + */ end?: number; - fs?: number; - iv_load_policy?: number; + + /** + * Whether to display the full-screen button (by default, Show). + */ + fs?: FullscreenButton; + + /** + * Player language as an ISO 639-1 two-letter language code or fully-specified locale. + */ + hl?: string; + + /** + * Whether to show video annotations (by default, Show). + */ + iv_load_policy?: IvLoadPolicy; + + /** + * Identifies content that will load. + * If listType is search, this is the search query. + * If listType is user_uploads, this is the YouTube user. + * If listType is playlist, this is the playlist ID, prepended by 'PL'. + */ list?: string; + + /** + * Which type of content loads in the player. + */ listType?: ListType; - loop?: number; - modestbranding?: number; + + /** + * Whether a single video should be looped (by default, SinglePlay). + */ + loop?: Loop; + + /** + * Whether to hide some YouTube branding (by default, Full). + */ + modestbranding?: ModestBranding; + + /** + * Origin domain for additional security if using the JavaScript API. + */ origin?: string; - playerpiid?: string; - playlist?: string[]; - playsinline?: number; - rel?: number; - showinfo?: number; + + /** + * Comma separated list of video IDs to play after the URL path's video. + */ + playlist?: string; + + /** + * Whether to show related videos after the video finishes (by default, Show). + */ + rel?: RelatedVideos; + + /** + * Whether to show video information before playing (by default, Show). + */ + showinfo?: ShowInfo; + + /** + * Time, in seconds from the beginning of the video, when to start playing. + */ start?: number; - theme?: string; - } + } - export interface PlayerOptions { - width?: string | number; - height?: string | number; - videoId?: string; - playerVars?: PlayerVars; - events?: Events; - } + /** + * Handlers for events fired by the player. + */ + export interface Events + { + /** + * Event fired when a player has finished loading and is ready to begin receiving API calls. + */ + onReady?: PlayerEventHandler; - interface VideoByIdParams { - videoId: string; - startSeconds?: number; - endSeconds?: number; - suggestedQuality?: string; - } + /** + * Event fired when the player's state changes. + */ + onStateChange?: PlayerEventHandler; - interface VideoByUrlParams { - mediaContentUrl: string; - startSeconds?: number; - endSeconds?: number; - suggestedQuality?: string; - } + /** + * Event fired when the playback quality of the player changes. + */ + onPlaybackQualityChange?: PlayerEventHandler; - export interface VideoData - { - video_id: string; - author: string; - title: string; - } + /** + * Event fired when the playback rate of the player changes. + */ + onPlaybackRateChange?: PlayerEventHandler; - export class Player { - // Constructor - constructor(id: string, playerOptions: PlayerOptions); - constructor(element: HTMLElement, playerOptions: PlayerOptions); + /** + * Event fired when an error in the player occurs + */ + onError?: PlayerEventHandler; - // Queueing functions - loadVideoById(videoId: string, startSeconds?: number, suggestedQuality?: string): void; - loadVideoById(VideoByIdParams: Object): void; - cueVideoById(videoId: string, startSeconds?: number, suggestedQuality?: string): void; - cueVideoById(VideoByIdParams: Object): void; + /** + * Event fired to indicate thath the player has loaded, or unloaded, a module + * with exposed API methods. This currently only occurs for closed captioning. + */ + onApiChange?: PlayerEventHandler; + } - loadVideoByUrl(mediaContentUrl: string, startSeconds?: number, suggestedQuality?: string): void; - loadVideoByUrl(VideoByUrlParams: Object): void; - cueVideoByUrl(mediaContentUrl: string, startSeconds?: number, suggestedQuality?: string): void; - cueVideoByUrl(VideoByUrlParams: Object): void; + /** + * Settings to load, play, or queue a video or playlist. + */ + export interface VideoOrPlaylistSettings { + /** + * Time, in seconds from the beginning of the (first) video, when to start playing. + */ + startSeconds?: number; - // Properties - size: any; + /** + * Time, in seconds from the end of the (first) video, when to end playing. + */ + endSeconds?: number; - // Playing - playVideo(): void; - pauseVideo(): void; - stopVideo(): void; - seekTo(seconds:number, allowSeekAhead:boolean): void; - clearVideo(): void; + /** + * Suggested video player quality. + */ + suggestedQuality?: SuggestedVideoQuality + } - // Playlist - nextVideo(): void; - previousVideo(): void; - playVideoAt(index: number): void; + /** + * Settings to play or queue a video by ID. + */ + export interface VideoByIdSettings extends VideoOrPlaylistSettings { + /** + * Video ID. + */ + videoId: string; + } - // Volume - mute(): void; - unMute(): void; - isMuted(): boolean; - setVolume(volume: number): void; - getVolume(): number; + /** + * Settings to play or queue a video by media content URL. + */ + export interface VideoByMediaContentUrlSettings extends VideoOrPlaylistSettings { + /** + * Fully qualified player URL. + */ + mediaContentUrl: string; + } - // Sizing - setSize(width: number, height: number): any; + /** + * Settings to load or queue a playlist. + */ + export interface IPlaylistSettings extends VideoOrPlaylistSettings { + /** + * Identifier for the listType videos list. + */ + list: string; - // Playback - getPlaybackRate(): number; - setPlaybackRate(suggestedRate:number): void; - getAvailablePlaybackRates(): number[]; + /** + * Which type of content loads in the player. + */ + listType?: ListType; - // Behavior - setLoop(loopPlaylists: boolean): void; - setShuffle(shufflePlaylist: boolean): void; + /** + * Start index of the playlist, if not 0. + */ + index?: number; + } - // Status - getVideoLoadedFraction(): number; - getPlayerState(): number; - getCurrentTime(): number; - getVideoStartBytes(): number; - getVideoBytesLoaded(): number; - getVideoBytesTotal(): number; + /** + * Creates and controls a YouTube player in an