Add TypeScript definitions

google-youtube.d.ts

@@ -0,0 +1,381 @@
+/**
+ * DO NOT EDIT
+ *
+ * This file was automatically generated by
+ *   https://github.com/Polymer/gen-typescript-declarations
+ *
+ * To modify these typings, edit the source file(s):
+ *   google-youtube.html
+ */
+
+/// <reference path="../polymer/types/polymer.d.ts" />
+/// <reference path="../iron-localstorage/iron-localstorage.d.ts" />
+/// <reference path="../google-apis/google-youtube-api.d.ts" />
+
+/**
+ * `google-youtube` encapsulates the YouTube player into a web component.
+ *
+ *     <google-youtube
+ *       video-id="..."
+ *       height="270px"
+ *       width="480px"
+ *       rel="0"
+ *       start="5"
+ *       autoplay="1">
+ *     </google-youtube>
+ *
+ * `google-youtube` supports all of the [embedded player parameters](https://developers.google.com/youtube/player_parameters). Each can be set as an attribute on `google-youtube`.
+ *
+ * The standard set of [YouTube player events](https://developers.google.com/youtube/iframe_api_reference#Events) are exposed, as well as methods for playing, pausing, seeking to a specific time, and loading a new video.
+ *
+ *
+ * Custom property | Description | Default
+ * ----------------|-------------|----------
+ * `--google-youtube-container`  | Mixin applied to the container div | `{}`
+ * `--google-youtube-thumbnail`  | Mixin for the video thumbnail      | `{}`
+ * `--google-youtube-iframe`     | Mixin for the embeded iframe       | `{}`
+ */
+interface GoogleYoutubeElement extends Polymer.Element {
+
+  /**
+   * Sets the id of the video to play. Changing this attribute will trigger a call
+   * to load a new video into the player (if `this.autoplay` is set to `1` and `playsupported` is true)
+   * or cue a new video otherwise.
+   *
+   * The underlying YouTube embed will not be added to the page unless
+   * `videoId` or `list` property is set.
+   *
+   * You can [search for videos programmatically](https://developers.google.com/youtube/v3/docs/search/list)
+   * using the YouTube Data API, or just hardcode known video ids to display on your page.
+   */
+  videoId: string|null|undefined;
+
+  /**
+   * The list parameter, in conjunction with the listType parameter, identifies the content that will load in the player.
+   * If the listType parameter value is search, then the list parameter value specifies the search query.
+   * If the listType parameter value is user_uploads, then the list parameter value identifies the YouTube channel whose uploaded videos will be loaded.
+   * If the listType parameter value is playlist, then the list parameter value specifies a YouTube playlist ID. In the parameter value, you need to prepend the playlist ID with the letters PL as shown in the example below.
+   *
+   * See https://developers.google.com/youtube/player_parameters#list
+   */
+  list: string|null|undefined;
+
+  /**
+   * See https://developers.google.com/youtube/player_parameters#listtype
+   */
+  listType: string|null|undefined;
+
+  /**
+   * Decides whether YouTube API should be loaded.
+   */
+  readonly shouldLoadApi: boolean|null|undefined;
+
+  /**
+   * Whether programmatic `<video>.play()` for initial playback is supported in the current browser.
+   *
+   * Most mobile browsers [do not support](https://developer.apple.com/library/safari/documentation/AudioVideo/Conceptual/Using_HTML5_Audio_Video/Device-SpecificConsiderations/Device-SpecificConsiderations.html#//apple_ref/doc/uid/TP40009523-CH5-SW1) autoplaying or scripted playback of videos.
+   * If you attempt to automatically initiate playback of a `<google-youtube>`, e.g. by calling the `play()` method before
+   * playback has initially begun, the YouTube Player will enter an unrecoverable "stuck" state.
+   * To protect against this, check the value of `playsupported` and don't call `play()` if it is set to `false`.
+   * (You can hide/disable your custom play button, etc.)
+   *
+   * The `playsupported` value is determined at runtime, by dynamically creating a `<video>` element with an
+   * inlined data source and calling `play()` on it. (Inspired by [Modernizr](https://github.com/Modernizr/Modernizr/blob/master/feature-detects/video/autoplay.js).)
+   *
+   * If you would rather not incur the minimal overhead involved in going through this process, you can explicitly set
+   * `playsupported` to `true` or `false` when initializing `<google-youtube>`. This is only recommended if you know that
+   * your web app will never (or only) be used on mobile browsers.
+   */
+  playsupported: boolean|null|undefined;
+
+  /**
+   * "1" if video should start automatically
+   */
+  autoplay: number|null|undefined;
+
+  /**
+   * Whether playback has started.
+   *
+   * This defaults to `false` and is set to `true` once the first 'playing' event is fired by
+   * the underlying YouTube Player API.
+   *
+   * Once set to `true`, it will remain that way indefinitely.
+   * Paused/buffering/ended events won't cause `playbackstarted` to reset to `false`.
+   * Nor will loading a new video into the player.
+   */
+  playbackstarted: boolean|null|undefined;
+
+  /**
+   * Sets the height of the player on the page.
+   * Accepts anything valid for a CSS measurement, e.g. '200px' or '50%'.
+   * If the unit of measurement is left off, 'px' is assumed.
+   */
+  height: string|null|undefined;
+
+  /**
+   * Sets the width of the player on the page.
+   * Accepts anything valid for a CSS measurement, e.g. '200px' or '50%'.
+   * If the unit of measurement is left off, 'px' is assumed.
+   */
+  width: string|null|undefined;
+
+  /**
+   * Exposes the current player state.
+   * Using this attribute is an alternative to listening to `google-youtube-state-change` events,
+   * and can simplify the logic in templates with conditional binding.
+   *
+   * The [possible values](https://developers.google.com/youtube/iframe_api_reference#onStateChange):
+   *   - -1 (unstarted)
+   *   - 0 (ended)
+   *   - 1 (playing)
+   *   - 2 (paused)
+   *   - 3 (buffering)
+   *   - 5 (video cued)
+   */
+  state: number|null|undefined;
+
+  /**
+   * Exposes the current playback time, in seconds.
+   *
+   * You can divide this value by the `duration` to determine the playback percentage.
+   */
+  currenttime: number|null|undefined;
+
+  /**
+   * Exposes the video duration, in seconds.
+   *
+   * You can divide the `currenttime` to determine the playback percentage.
+   */
+  duration: number|null|undefined;
+
+  /**
+   * Exposes the current playback time, formatted as a (HH:)MM:SS string.
+   */
+  currenttimeformatted: string|null|undefined;
+
+  /**
+   * Exposes the video duration, formatted as a (HH:)MM:SS string.
+   */
+  durationformatted: string|null|undefined;
+
+  /**
+   * The fraction of the bytes that have been loaded for the current video, in the range [0-1].
+   */
+  fractionloaded: number|null|undefined;
+
+  /**
+   * A shorthand to enable a set of player attributes that, used together, simulate a "chromeless" YouTube player.
+   *
+   * Equivalent to setting the following attributes:
+   * - `controls="0"`
+   * - `modestbranding="1"`
+   * - `showinfo="0"`
+   * - `iv_load_policy="3"`
+   * - `rel="0"`
+   *
+   * The "chromeless" player has minimal YouTube branding in cued state, and the native controls
+   * will be disabled during playback. Creating your own custom play/pause/etc. controls is recommended.
+   */
+  chromeless: boolean|null|undefined;
+
+  /**
+   * The URL of an image to use as a custom thumbnail.
+   *
+   * This is optional; if not provided, the standard YouTube embed (which uses the thumbnail associated
+   * with the video on YouTube) will be used.
+   *
+   * If `thumbnail` is set, than an `<img>` containing the thumbnail will be used in lieu of the actual
+   * YouTube embed. When the thumbnail is clicked, the `<img>` is swapped out for the actual YouTube embed,
+   * which will have [`autoplay=1`](https://developers.google.com/youtube/player_parameters#autoplay) set by default (in additional to any other player parameters specified on this element).
+   *
+   * Please note that `autoplay=1` won't actually autoplay videos on mobile browsers, so two taps will be required
+   * to play the video there. Also, on desktop browsers, setting `autoplay=1` will prevent the playback
+   * from [incrementing the view count](https://support.google.com/youtube/answer/1714329) for the video.
+   */
+  thumbnail: string|null|undefined;
+
+  /**
+   * If `fluid` is set, then the player will set its width to 100% to fill
+   * the parent container, while adding `padding-top` to preserve the
+   * aspect ratio provided by `width` and `height`. If `width` and `height`
+   * have not been set, the player will fall back to a 16:9 aspect ratio.
+   * This is useful for responsive designs where you don't want to
+   * introduce letterboxing on your video.
+   */
+  fluid: boolean|null|undefined;
+
+  /**
+   * Returns the player's current volume, an integer between 0 and 100.
+   * Note that `getVolume()` will return the volume even if the player is muted.
+   */
+  volume: number|null|undefined;
+
+  /**
+   * This function retrieves the playback rate of the currently playing video.
+   * The default playback rate is 1, which indicates that the video is playing at normal speed.
+   * Playback rates may include values like `0.25`, `0.5`, `1`, `1.5`, and `2`.
+   */
+  playbackrate: number|null|undefined;
+
+  /**
+   * This function retrieves the actual video quality of the current video.
+   * Possible return values are `highres`, `hd1080`, `hd720`, `large`, `medium` and `small`.
+   * It will also return `undefined` if there is no current video.
+   */
+  playbackquality: string|null|undefined;
+
+  /**
+   * Sets refresh interval in milliseconds for updating playback stats.
+   * YouTube API does not send events for video progress so we have to
+   * call getCurrentTime() manually. Smaller value makes updates smoother.
+   */
+  statsUpdateInterval: number|null|undefined;
+  _player: null;
+  _pendingVideoId: string;
+  _computeContainerStyle(width: any, height: any): any;
+  _computeShouldLoadApi(videoId: any, list: any): any;
+  _useExistingPlaySupportedValue(): void;
+
+  /**
+   * Detects whether programmatic <video>.play() is supported in the current browser.
+   *
+   * This is triggered via on-ironlocalstorage-load-empty. The logic is:
+   * - If playsupported is explicitly set to true or false on the element, use that.
+   * - Otherwise, if there's a cached value in localStorage, use that.
+   * - Otherwise, create a hidden <video> element and call play() on it:
+   *   - If playback starts, playsupported is true.
+   *   - If playback doesn't start (within 500ms), playsupported is false.
+   *   - Whatever happens, cache the result in localStorage.
+   */
+  _determinePlaySupported(): void;
+
+  /**
+   * Sets fluid width/height.
+   *
+   * If the fluid attribute is set, the aspect ratio of the video will
+   * be inferred (if set in pixels), or assumed to be 16:9. The element
+   * will give itself enough top padding to force the player to use the
+   * correct aspect ratio, even as the screen size changes.
+   */
+  ready(): void;
+
+  /**
+   * Clean up the underlying Player `<iframe>` when we're removed from the DOM.
+   */
+  detached(): void;
+
+  /**
+   * Plays the current video.
+   *
+   * Note that on certain mobile browsers, playback
+   * [can't be initiated programmatically](https://developers.google.com/youtube/iframe_api_reference#Mobile_considerations).
+   *
+   * If `this.playsupported` is not `true`, calling `play()` will have no effect.
+   */
+  play(): void;
+
+  /**
+   * Modifies the volume of the current video.
+   *
+   * Developers should take care not to break expected user experience by programmatically
+   * modifying the volume on mobile browsers.
+   * Note that the YouTube player, in addition, does not display volume controls in a
+   * mobile environment.
+   *
+   * @param volume The new volume, an integer between 0 (muted) and 100 (loudest).
+   */
+  setVolume(volume: number): void;
+
+  /**
+   * Mutes the current video.
+   *
+   * Developers should take care not to break expected user experience by programmatically
+   * modifying the volume on mobile browsers.
+   * Note that the YouTube player, in addition, does not display volume controls in a
+   * mobile environment.
+   */
+  mute(): void;
+
+  /**
+   * Unmutes the current video.
+   *
+   * Developers should take care not to break expected user experience by programmatically
+   * modifying the volume on mobile browsers.
+   * Note that the YouTube player, in addition, does not display volume controls in a
+   * mobile environment.
+   */
+  unMute(): void;
+
+  /**
+   * Pauses the current video.
+   */
+  pause(): void;
+
+  /**
+   * Skips ahead (or back) to the specified number of seconds.
+   *
+   * @param seconds Number of seconds to seek to.
+   */
+  seekTo(seconds: number): void;
+
+  /**
+   * This function sets the suggested playback rate for the current video.
+   * If the playback rate changes, it will only change for the video that is already cued or being played.
+   * If you set the playback rate for a cued video, that rate will still be in effect when the `playVideo` function is called or the user initiates playback directly through the player controls.
+   * In addition, calling functions to cue or load videos or playlists (`cueVideoById`, `loadVideoById`, etc.) will reset the playback rate to 1.
+   *
+   * Calling this function does not guarantee that the playback rate will actually change.
+   * However, if the playback rate does change, the `onPlaybackRateChange` event will fire, and your code should respond to the event rather than the fact that it called the `setPlaybackRate` function.
+   *
+   * The `getAvailablePlaybackRates` method will return the possible playback rates for the currently playing video.
+   * However, if you set the `suggestedRate` parameter to a non-supported integer or float value, the player will round that value down to the nearest supported value in the direction of 1.
+   *
+   * @param suggestedRate Playback rate for the current video.
+   */
+  setPlaybackRate(suggestedRate: number): void;
+
+  /**
+   * This function sets the suggested video quality for the current video.
+   * The function causes the video to reload at its current position in the new quality.
+   * If the playback quality does change, it will only change for the video being played.
+   * Calling this function does not guarantee that the playback quality will actually change.
+   * However, if the playback quality does change, the `onPlaybackQualityChange` event will fire, and your code should respond to the event rather than the fact that it called the `setPlaybackQuality` function.
+   *
+   * The `suggestedQuality` parameter value can be `small`, `medium`, `large`, `hd720`, `hd1080`, `highres` or `default`.
+   * We recommend that you set the parameter value to default, which instructs YouTube to select the most appropriate playback quality, which will vary for different users, videos, systems and other playback conditions.
+   *
+   * When you suggest a playback quality for a video, the suggested quality will only be in effect for that video.
+   * You should select a playback quality that corresponds to the size of your video player.
+   * For example, if your page displays a `1280px` by `720px` video player, a `hd720` quality video will actually look better than an `hd1080` quality video.
+   * We recommend calling the `getAvailableQualityLevels()` function to determine which quality levels are available for a video.
+   *
+   * The list below shows the playback quality levels that correspond to different standard player sizes.
+   * We recommend that you set the height of your video player to one of the values listed below and that you size your player to use 16:9 aspect ratio.
+   * As stated above, even if you choose a standard player size, we also recommend that you set the `suggestedQuality` parameter value to default to enable YouTube to select the most appropriate playback quality.
+   *
+   * - `small`: Player height is 240px, and player dimensions are at least 320px by 240px for 4:3 aspect ratio.
+   * - `medium`: 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).
+   * - `large`: 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).
+   * - `hd720`: 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).
+   * - `hd1080`: 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).
+   * - `highres`: Player height is greater than 1080px, which means that the player's aspect ratio is greater than 1920px by 1080px.
+   * - `default`: YouTube selects the appropriate playback quality. This setting effectively reverts the quality level to the default state and nullifies any previous efforts to set playback quality using the `cueVideoById`, `loadVideoById` or `setPlaybackQuality` functions.
+   *
+   * If you call the `setPlaybackQuality` function with a `suggestedQuality` level that is not available for the video, then the quality will be set to the next lowest level that is available.
+   * For example, if you request a quality level of large, and that is unavailable, then the playback quality will be set to medium (as long as that quality level is available).
+   *
+   * In addition, setting `suggestedQuality` to a value that is not a recognized quality level is equivalent to setting `suggestedQuality` to default.
+   *
+   * @param suggestedQuality Playback quality for the current video.
+   */
+  setPlaybackQuality(suggestedQuality: string): void;
+  _videoIdChanged(): void;
+  _apiLoad(): void;
+  _updatePlaybackStats(): void;
+  _toHHMMSS(totalSeconds: any): any;
+  _handleThumbnailTap(): void;
+}
+
+interface HTMLElementTagNameMap {
+  "google-youtube": GoogleYoutubeElement;
+}