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