Jekyll One

QuickSearch

The YouTube Embedded Player API explains how to embed a YouTube player in your application and also defines the parameters that are available in the YouTube embedded player.

The YouTube iFrame API is used the underlying Provider API for VideoJS players (over YouTube). VideoJS players are the default video player for all video sources supported by J1 Template.

30-60 Minutes to read

VideoJS Player Example

VideoJS provides a flexible and customizable platform for displaying and controlling video content on websites and web applications. The J1 Template system utilizes online videos from the YouTube platform. The player plugin VideoJS YT Tech is used to provide custom players, offering the default look and feel for all J1 video players.

VideoJS Player · YouTube Video over VideoJS YT Tech

Overview

By appending parameters to the IFrame URL, you can customize the playback experience in your application. For example, you can automatically play videos using the autoplay parameter or cause a video to play repeatedly using the loop parameter. You can also use the enablejsapi parameter to enable the player to be controlled via the IFrame Player API.

This page currently defines all parameters supported in any YouTube-embedded player. Each parameter definition identifies the players that support the corresponding parameter.

Embedded players must have a viewport that is at least 200px by 200px. If the player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

Embed a Player

Define an <iframe> tag in your application in which the src URL specifies the content that the player will load as well as any other player parameters you want to set. The <iframe> tag’s height and width parameters specify the dimensions of the player.

If you create the <iframe> element yourself (rather than using the IFrame Player API to create it), you can append player parameters directly to the end of the URL. The URL has the following format:

https://www.youtube.com/embed/<VIDEO_ID>

The <iframe> tag below would load a 640x360px player that would play the YouTube video M7lc1UVf-VE. Since the URL sets the autoplay parameter to 1, the video would play automatically once the player has loaded.

<iframe
  id="ytplayer"
  type="text/html"
  width="640" height="360"
  src="https://www.youtube.com/embed/M7lc1UVf-VE?autoplay=1&origin=http://example.com"
  frameborder="0">
</iframe>

Follow the IFrame Player API instructions to insert a video player in your web page or application after the Player API’s Javascript code has loaded. The second parameter in the constructor for the video player is an object that specifies player options. Within that object, the playerVars property identifies player parameters.

The HTML and Javascript code below shows a simple example that inserts a YouTube player into the page element that has an id value of ytplayer. The onYouTubePlayerAPIReady() method specified here is called automatically when the IFrame Player API code has loaded. This code does not define any player parameters and also does not define other event handlers.

<div id="ytplayer"></div>
<script>
  // Load the IFrame Player API code asynchronously.
  var tag = document.createElement('script');
  tag.src = "https://www.youtube.com/player_api";
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
  // Replace the 'ytplayer' element with an <iframe> and
  // YouTube player after the API code downloads.
  var player;
  function onYouTubePlayerAPIReady() {
    player = new YT.Player('ytplayer', {
      height: '360',
      width: '640',
      videoId: 'M7lc1UVf-VE'
    });
  }
</script>

Select content to play

You can configure your embedded player to load a video, a playlist, or a user’s uploaded videos.

The following list explains these options for loading a video. For an IFrame embed, the YouTube video ID for the video that you want to load is specified in the IFrame’s src URL.

https://www.youtube.com/embed/<VIDEO_ID>

If you are using the YouTube Data API (v3), you can programmatically construct these URLs by retrieving video IDs from search results, playlist item resources, video resources, or other resources. After obtaining a video ID, replace the VIDEO_ID text in the URLs above with that value to create the player URL.

For loading a playlist, set the listType player parameter to playlist. In addition, set the list player parameter to the YouTube playlist ID that you want to load.

https://www.youtube.com/embed?listType=playlist&list=PLAYLIST_ID

Note that you need to prepend the playlist ID with the letters PL as shown in the following example:

https://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6

If you are using the YouTube Data API (v3), you can programmatically construct these URLs by retrieving playlist IDs from search results, channel resources, or activity resources. After obtaining a playlist ID, replace the PLAYLIST_ID text in the URL above with that value.

For Loading a user’s uploaded videos, set the listType player parameter to user_uploads. In addition, set the list player parameter to the YouTube username whose uploaded videos you want to load.

https://www.youtube.com/embed?listType=user_uploads&list=USERNAME

Supported players parameters

All of the following parameters are optional.

autoplay

This parameter specifies whether the initial video will automatically start to play when the player loads. Supported values are 0 or 1. The default value is 0.

If you enable Autoplay, playback will occur without any user interaction with the player; playback data collection and sharing will therefore occur upon page load.

Type Default

0|1

0

cc_lang_pref

This parameter specifies the default language that the player will use to display captions. Set the parameter’s value to an ISO 639-1 two-letter language code.

If you use this parameter and also set the cc_load_policy parameter to 1, then the player will show captions in the specified language when the player loads. If you do not also set the cc_load_policy parameter, then captions will not display by default, but will display in the specified language if the user opts to turn captions on.

Type Default

string

no defaults

cc_load_policy

Setting the parameter’s value to 1 causes closed captions to be shown by default, even if the user has turned captions off. The default behavior is based on user preference.

Type Default

0|1

no defaults

color

This parameter specifies the color that will be used in the player’s video progress bar to highlight the amount of the video that the viewer has already seen. Valid parameter values are red and white, and, by default, the player uses the color red in the video progress bar.

Type Default

red|white

red

controls

This parameter indicates whether the video player controls are displayed:

  • controls=0, Player controls do not display in the player.

  • controls=1, Player controls display in the player (default).

Type Default

0|1

1

disablekb

Setting the parameter’s value to 1 causes the player to not respond to keyboard controls. The default value is 0, which means that keyboard controls are enabled. Currently supported keyboard controls are:

  • Spacebar or [k]: Play / Pause

  • Arrow Left: Jump back 5 seconds in the current video

  • Arrow Right: Jump ahead 5 seconds in the current video

  • Arrow Up: Volume up

  • Arrow Down: Volume Down

  • [f]: Toggle full-screen display

  • [j]: Jump back 10 seconds in the current video

  • [l]: Jump ahead 10 seconds in the current video

  • [m]: Mute or unmute the video

  • [0-9]: Jump to a point in the video. 0 jumps to the beginning of the video, 1 jumps to the point 10% into the video, 2 jumps to the point 20% into the video, and so forth.

Type Default

0|1

0

enablejsapi

Setting the parameter’s value to 1 enables the player to be controlled via IFrame Player API calls. The default value is 0, which means that the player cannot be controlled using that API.

For more information on the IFrame API and how to use it, see the IFrame API documentation.

Type Default

0|1

0

end

This parameter specifies the time, measured in seconds from the start of the video, when the player should stop playing the video. The parameter value is a positive integer.

Note that the time is measured from the beginning of the video and not from either the value of the start player parameter or the startSeconds parameter, which is used in YouTube Player API methods for loading or queueing a video.

Type Default

integer

no defaults

fs

Setting this parameter to 0 prevents the fullscreen button from displaying in the player. The default value is 1, which causes the fullscreen button to display.

Type Default

0|1

1

hl

Sets the player’s interface language. The parameter value is an ISO 639-1 two-letter language code or a fully specified locale. For example, fr and fr-ca are both valid values. Other language input codes, such as IETF language tags (BCP 47) might also be handled properly.

The interface language is used for tooltips in the player and also affects the default caption track. Note that YouTube might select a different caption track language for a particular user based on the user’s individual language preferences and the availability of caption tracks.

Type Default

string

no defaults

iv_load_policy

Setting the parameter’s value to 1 causes video annotations to be shown by default, whereas setting to 3 causes video annotations to not be shown by default. The default value is 1.

Type Default

1|3

1

list

The list parameter, in conjunction with the listType parameter, identifies the content that will load in the player.

  • 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.

https://www.youtube.com/embed?listType=playlist &list=PLC77007E23FF423C6

  • If the listType parameter value is search, then the list parameter value specifies the search query.

This functionality is deprecated and will no longer be supported as of 15 November 2020.

If you specify values for the list and listType parameters, the IFrame embed URL does not need to specify a video ID.

listType

The listType parameter, in conjunction with the list parameter, identifies the content that will load in the player. Valid parameter values are playlist and user_uploads.

If you specify values for the list and listType parameters, the IFrame embed URL does not need to specify a video ID.

A third value, search, has been deprecated and will no longer be supported as of 15 November 2020.
Type Default

user_uploads|playlist

no defaults

loop

In the case of a single video player, a setting of 1 causes the player to play the initial video again and again. In the case of a playlist player (or custom player), the player plays the entire playlist and then starts again at the first video.

Supported values are 0 and 1, and the default value is 0.

This parameter has limited support in IFrame embeds. To loop a single video, set the loop parameter value to 1 and set the playlist parameter value to the same video ID already specified in the Player API URL:

 
https://www.youtube.com/embed/VIDEO_ID?playlist=VIDEO_ID&loop=1
Type Default

0|1

0

modestbranding

This parameter allows you to use a YouTube player that does not display the YouTube logo. Set the parameter value to 1 to prevent the YouTube logo from being displayed in the control bar. However, a small YouTube text label will appear in the top right corner of a paused video when the user hovers over the player.

This parameter is deprecated and has no effect. See the deprecation announcement for more information.

origin

This parameter provides an extra security measure for the IFrame API and is only supported for IFrame embeds. If you are using the IFrame API, which means you are setting the enablejsapi parameter value to 1, you should always specify your domain as the origin parameter value.

To ensure secure communication between your website and the YouTube Player API, you need to specify the domain of your website as an origin parameter in the iframe embed URL.

Determine the exact domain (including the protocol, http:// or https://) where your YouTube player will be embedded. For example: https://yourwebsite.com.

Why is this important?

  • Security: By specifying the origin parameter, you prevent unauthorized access to your website’s resources and protect user data.

  • API Functionality: It ensures that the YouTube Player API can communicate with your website’s JavaScript code, enabling features like custom controls, interactive elements, and more.

Type Default

string

no defaults

playlist

This parameter specifies a comma-separated list of video IDs to play. If you specify a value, the first video that plays will be the VIDEO_ID specified in the URL path, and the videos specified in the playlist parameter will play thereafter.

Type Default

array

no defaults

playsinline

This parameter controls whether videos play inline or fullscreen on iOS. Valid values are:

  • 0, Results in fullscreen playback. This is currently the default value, though the default is subject to change.

  • 1, Results in inline playback for mobile browsers and for WebViews created with the allowsInlineMediaPlayback property set to YES.

Type Default

0|1

0

rel

Prior to the change, this parameter indicates whether the player should show related videos when playback of the initial video ends.

  • If the parameter’s value is set to 1, which is the default value, then the player does show related videos.

  • If the parameter’s value is set to 0, then the player does not show related videos.

After the change, you will not be able to disable related videos. Instead, if the rel parameter is set to 0, related videos will come from the same channel as the video that was just played.

Type Default

0|1

1

showinfo

If you set the parameter value to 0, information such as the video title or the name of the uploader will not be displayed in the player before the video starts playing.

If the player loads a playlist and you have explicitly set the parameter value to 1, the player will also display thumbnails for the videos in the respective playlist after loading.

This feature is only supported for the AS3 player, as this is the only player that can load a playlist.
Type Default

0|1

1

start

This parameter causes the player to begin playing the video at the given number of seconds from the start of the video. The parameter value is a positive integer. Note that similar to the seekTo method, the player will look for the closest keyframe to the time you specify. This means that sometimes the play head may seek to just before the requested time, usually no more than around two seconds.

Type Default

integer

no defaults

widget_referrer

This parameter identifies the URL where the player is embedded. This value is used in YouTube Analytics reporting when the YouTube player is embedded in a widget, and that widget is then embedded in a web page or application. In that scenario, the origin parameter identifies the widget provider’s domain, but YouTube Analytics should not identify the widget provider as the actual traffic source. Instead, YouTube Analytics uses the widget_referrer parameter value to identify the domain associated with the traffic source.

Type Default

string

no defaults

Methods

Natus quibusdam architecto aut non cum non. Quo fugit optio ut tenetur ipsa quis. Dolorum laudantium facere molestiae in illo vero corrupti architecto quos illum natus dicta harum. Minima et molestias tempora voluptatum non ut odio non iusto et maxime ea. Temporibus ea quia tenetur sapiente dolor a sint a id.

player.playVideo

Plays the currently cued/loaded video. The final player state after this method executes will be playing (1).

A playback only counts toward a video’s official view count if it is initiated via a native play button in the player.

player.pauseVideo

Pauses the currently playing video. The final player state after this method executes will be paused (2) unless the player is in the ended (0) state when the method is called, in which case the player state will not change.

player.stopVideo

Stops and cancels loading of the current video. This method should be reserved for rare situations when you know that the user will not be watching additional video in the player. If your intent is to pause the video, you should just call the pauseVideo method. If you want to change the video that the player is playing, you can call one of the queueing methods without calling stopVideo first.

Unlike the pauseVideo method, which leaves the player in the paused (2) state, the stopVideo method could put the player into any not-playing state, including ended (0), paused (2), video cued (5) or not started (-1).

player.seekTo(seconds:Number, allowSeekAhead:Boolean)

Seeks to a specified time in the video. If the player is paused when the method is called, it will remain paused. If the method is called from another state (playing, video cued, etc.), the player will play the video.

  • The seconds parameter identifies the time to which the player should advance.

The player will advance to the closest keyframe before that time unless the player has already downloaded the portion of the video to which the user is seeking. * The allowSeekAhead parameter determines whether the player will make a new request to the server if the seconds parameter specifies a time outside of the currently buffered video data.

It is recommendend that you set this parameter to false while the user drags the mouse along a video progress bar and then set it to true when the user releases the mouse. This approach lets a user scroll to different points of a video without requesting new video streams by scrolling past unbuffered points in the video. When the user releases the mouse button, the player advances to the desired point in the video and requests a new video stream if necessary.

Changing the playback quality

The getPlaybackQuality(), setPlaybackQuality(), and getAvailableQualityLevels() methods are no longer supported (October 24, 2019). In particular, calls to setPlaybackQuality() will be no-op functions, meaning they will not actually have any impact on the viewer’s playback experience.

player.getPlaybackQuality()

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.

player.setPlaybackQuality(suggestedQuality:String)

This function sets the recommended video quality for the current video. It causes the video to reload at the current position with the new quality. If the playback quality changes, it only changes for the video that is currently playing. Calling this function does not guarantee that the playback quality will actually change.

If the playback quality does change, however, the onPlaybackQualityChange() event will be fired and your code should respond to the event, not to the fact that the setPlaybackQuality() method was called.

The suggestedQuality parameter value can be small, medium, large, hd720, hd1080, highres, or default. We recommend that you set the parameter value to default. This tells YouTube to choose the most appropriate playback quality based on the user, video, system, and other playback conditions.

If you suggest a playback quality for a video, the suggested quality will only be enabled for that video. You should select a playback quality that matches the size of your video player.

For example, if your page displays a video player that is 1280 x 720 pixels in size, a video with a quality of hd720 will look better than a video with a quality of hd1080.

We recommend calling the getAvailableQualityLevels() method to determine which levels are available for a video.

The list below shows the playback quality levels that relate to various standard player sizes. We recommend that you set the player height to one of the values ​​listed below and size your player to use a 16:9 aspect ratio.

As mentioned above, if you select a standard player size, we recommend that you set the suggestedQuality parameter value to default so that YouTube can select the most appropriate playback quality.

Table 1. Available Video quality levels
Type Description

small

The player height is 240 pixels and the dimensions are at least 320 x 240 pixels for an aspect ratio of 4:3.

medium

The player height is 360 pixels and the dimensions are 640 x 360 pixels for an aspect ratio of 16:9 and 480 x 360 pixels for an aspect ratio of 4:3.

large

The player height is 480 pixels and the dimensions are 853 x 480 pixels for an aspect ratio of 16:9 and 640 x 480 pixels for an aspect ratio of 4:3.

'hd720'

The player height is 720 pixels and the dimensions are 1280 x 720 pixels for an aspect ratio of 16:9 and 960 x 720 pixels for an aspect ratio of 4:3.

hd1080

The player height is 1080 pixels and the dimensions are 1920 x 1080 pixels for a 16:9 aspect ratio and 1440 x 1080 pixels for a 4:3 aspect ratio.

highres

The player height is greater than 1080 pixels. This means that the player aspect ratio is greater than 1920 x 1080 pixels.

default

YouTube will choose the appropriate playback quality. This setting will reset the quality level to the default value, undoing any previous attempts to set the playback quality using the methods cueVideoById(), loadVideoById(), or setPlaybackQuality().

If you call the method setPlaybackQuality() with a suggestedQuality level that is not available for the video, the quality will be set to the next lowest available level. For example, if you request the quality level large and it is not available, the playback quality will be set to medium if that level is available.

Additionally, setting suggestedQuality to a value that is not recognized as a quality level is equivalent to setting suggestedQuality to default.

player.getAvailableQualityLevels()

This function returns the quality formats in which the current video is available. You could use this function to determine whether the video is available in a higher quality than the one the user is currently using to play it.

Your player could display a button or other element to allow the user to adjust the quality accordingly. The function returns several strings sorted in decreasing order of quality. Possible array element values ​​are highres, hd1080, hd720, large, medium, and small.

This function returns an empty array if there is no current video. Your client should not automatically switch to the highest or lowest video quality or to an unknown format name.

YouTube could expand the list of quality levels to include formats that may not be appropriate for your player context. Likewise, YouTube could remove options, potentially compromising the quality provided to the user. If your client only switches to known available formats, client performance will not be affected by introducing new quality levels or by removing quality levels that are not appropriate for your player context.

Changing the player volume

Temporibus consectetur velit non atque cum eveniet est quo. Consectetur omnis quasi quibusdam qui architecto a dolorem voluptatum. Hic unde tenetur provident voluptas labore quis fugiat voluptas pariatur id quam. Labore nihil reprehenderit nostrum aut qui mollitia tenetur illo eveniet maxime. Commodi ea vero placeat inventore.

player.mute()

Mutes the player.

player.unMute()

Unmutes the player.

player.isMuted()

Returns true if the player is muted, false if not.

player.setVolume(volume:Number)

Sets the volume. Accepts an integer between 0 and 100.

player.getVolume(volume:Number)

Returns the player’s current volume, an integer between 0 and 100.

The method getVolume() will return the volume even if the player is muted.

Setting the player size

Voluptatem pariatur reprehenderit provident esse rem odio sit non pariatur voluptatem est. Ipsa explicabo et aut et eius nisi numquam fuga vero facilis culpa quis voluptate ipsum. Quam at ipsa tenetur nihil animi adipisci tempore ipsam eum quia. Harum dolorem velit est iusto doloremque praesentium ea non quasi voluptate. Eaque quaerat in praesentium est sed ut temporibus libero ut a consectetur porro.

player.setSize(width:Number, height:Number)

Sets the size in pixels of the <iframe> that contains the player.

Setting the playback rate

Asperiores molestias est sapiente voluptatibus dicta sed occaecati. Qui consequuntur voluptas beatae nobis quidem pariatur ut officiis id a eum rerum. Natus accusantium aut aut suscipit doloribus ea deserunt distinctio pariatur sequi repellat optio in fuga. Earum est qui nesciunt aut beatae voluptatum aut suscipit in occaecati. Totam et cumque neque asperiores praesentium atque et voluptas ut ea necessitatibus exercitationem.

player.getPlaybackRate()

This method 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.

player.setPlaybackRate(suggestedRate:Number)

This method 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 method is called or the user initiates playback directly through the player controls. In addition, calling methods to cue or load videos or playlists (cueVideoById, loadVideoById, etc.) will reset the playback rate to 1.

Calling this method 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 method.

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.

player.getAvailablePlaybackRates()

This method returns the set of playback rates (as an array) in which the current video is available. The default value is 1, which indicates that the video is playing at normal speed.

The method returns an array of numbers ordered from slowest to fastest playback speed. Even if the player does not support variable playback speeds, the array should always contain at least one value (1).

Setting playback behavior for playlists

Et fugit nisi minima incidunt est. Optio possimus et qui. Sunt ullam dolor error voluptates qui debitis eos qui animi aliquam culpa. Nisi illo et blanditiis magnam perspiciatis numquam cum velit quibusdam. Et recusandae incidunt est ullam officiis eum doloremque aperiam fugit qui consectetur incidunt quis esse.

player.setLoop(loopPlaylists:Boolean)

This method indicates whether the video player should continuously play a playlist or if it should stop playing after the last video in the playlist ends. The default behavior is that playlists do not loop.

This setting will persist even if you load or cue a different playlist, which means that if you load a playlist, call the setLoop method with a value of true, and then load a second playlist, the second playlist will also loop.

The required loopPlaylists parameter identifies the looping behavior.

  • If the parameter value is true, then the video player will continuously play playlists. After playing the last video in a playlist, the video player will go back to the beginning of the playlist and play it again.

  • If the parameter value is false, then playbacks will end after the video player plays the last video in a playlist.

player.setShuffle(shufflePlaylist:Boolean)

This method indicates whether a playlist’s videos should be shuffled so that they play back in an order different from the one that the playlist creator designated. If you shuffle a playlist after it has already started playing, the list will be reordered while the video that is playing continues to play. The next video that plays will then be selected based on the reordered list.

This setting will not persist if you load or cue a different playlist, which means that if you load a playlist, call the setShuffle method, and then load a second playlist, the second playlist will not be shuffled.

The required shufflePlaylist parameter indicates whether YouTube should shuffle the playlist.

  • If the parameter value is true, then YouTube will shuffle the playlist order. If you instruct the method to shuffle a playlist that has already been shuffled, YouTube will shuffle the order again.

  • If the parameter value is false, then YouTube will change the playlist order back to its original order.

Playback status

Modi rerum sit et qui. Corrupti at cupiditate dicta a similique ipsa tempora quo. Eveniet modi omnis quo. Consectetur maiores ipsum dolorem. Dolorem non animi provident.

player.getVideoLoadedFraction

Returns a (float) number between 0 and 1 that specifies the percentage of the video that the player shows as buffered. This method returns a more reliable number than the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods.

player.etPlayerState()

Returns the state of the player. Possible values are:

  • -1, not started

  • 0, ended

  • 1, playing

  • 2, paused

  • 3, buffering

  • 5, video cued

player.getCurrentTime()

Returns the elapsed time in seconds since the video started playing.

player.getVideoStartBytes()

Deprecated as of October 31, 2012. Returns the number of bytes the video file started loading from. (This method now always returns a value of 0.) Example scenario: the user seeks ahead to a point that hasn’t loaded yet, and the player makes a new request to play a segment of the video that hasn’t loaded yet.

player.getVideoBytesLoaded()

Deprecated as of July 18, 2012. Instead, use the getVideoLoadedFraction method to determine the percentage of the video that has buffered.

This method returns a value between 0 and 1000 that approximates the amount of the video that has been loaded. You could calculate the fraction of the video that has been loaded by dividing the getVideoBytesLoaded value by the getVideoBytesTotal value.

player.getVideoBytesTotal()

Deprecated as of July 18, 2012. Instead, use the getVideoLoadedFraction method to determine the percentage of the video that has buffered.

Returns the size in bytes of the currently loaded/playing video or an approximation of the video’s size.

This method always returns a value of 1000. You could calculate the fraction of the video that has been loaded by dividing the getVideoBytesLoaded value by the getVideoBytesTotal value.

Retrieving video information

Nesciunt nulla aliquam eveniet. Ut consequatur magnam quis magnam est. Saepe voluptates omnis quis quos sunt aut est quam magni necessitatibus est. Maiores velit omnis et atque reprehenderit et doloremque sint ab blanditiis consequatur adipisci voluptas velit. Et laborum aut aliquid eos.

player.getDuration()

Returns the duration in seconds of the currently playing video. Note that getDuration() method will return 0 until the video’s metadata is loaded, which normally happens just after the video starts playing.

If the currently playing video is a live event, the getDuration() method will return the elapsed time since the live video stream began. Specifically, this is the amount of time that the video has streamed without being reset or interrupted. In addition, this duration is commonly longer than the actual event time since streaming may begin before the event’s start time.

player.getVideoUrl()

Returns the YouTube.com URL for the currently loaded/playing video.

player.getVideoEmbedCode()

Returns the embed code for the currently loaded/playing video.

Retrieving playlist information

Sequi et voluptas repellat enim ut aut doloribus suscipit neque id laborum aspernatur rerum. Praesentium et ut rem similique nihil ea mollitia necessitatibus laboriosam nihil cupiditate mollitia consectetur quia. Laborum quia molestiae esse deserunt deserunt molestiae doloribus. Consequatur id saepe corporis dolorum assumenda. In iure quia quasi sunt molestiae itaque qui officiis.

player.getPlaylist()

This method returns an array of the video IDs in the playlist as they are currently ordered. By default, this method will return video IDs in the order designated by the playlist owner. However, if you have called the setShuffle method to shuffle the playlist order, then the getPlaylist() method’s return value will reflect the shuffled order.

player.getPlaylistIndex()

This method returns the index of the playlist video that is currently playing.

  • If you have not shuffled the playlist, the return value will identify the position where the playlist creator placed the video. The return value uses a zero-based index, so a value of 0 identifies the first video in the playlist.

  • If you have shuffled the playlist, the return value will identify the video’s order within the shuffled playlist.

Adding or removing an event listener

Est veniam labore atque. Non eos accusamus doloremque atque a quasi ea. Alias quam ipsum at cum aut ut et et aut. Omnis voluptatum quia vero possimus qui dolor mollitia ut unde velit. Ut praesentium sunt et reprehenderit architecto aut omnis mollitia accusantium accusantium voluptas.

player.addEventListener(event:String, listener:String)

Adds a listener method for the specified event. The Events section below identifies the different events that the player might fire. The listener is a string that specifies the method that will execute when the specified event fires.

player.removeEventListener+(event:String, listener:String)

Removes a listener method for the specified event. The listener is a string that identifies the method that will no longer execute when the specified event fires.

Accessing and modifying DOM nodes

Placeat laborum expedita ex delectus aut est sint quis. Labore ipsum sint qui cumque doloremque et omnis temporibus optio sit eius aut. Iste hic omnis voluptatum sapiente sint pariatur aut est. Adipisci doloribus possimus soluta a ea tenetur soluta. Officia sunt omnis illum.

player.getIframe()

This method returns the DOM node for the embedded <iframe>.

player.destroy()

Removes the <iframe> containing the player.

Events

The API fires events to notify your application of changes to the embedded player. As noted in the previous section, you can subscribe to events by adding an event listener when constructing the YT.Player object, and you can also use the addEventListener method.

The API will pass an event object as the sole argument to each of those methods. The event object has the following properties:

  • The event’s target identifies the video player that corresponds to the event.

  • The event’s data specifies a value relevant to the event. Note that the onReady and onAutoplayBlocked events do not specify a data property.

onReady

This event fires whenever a player has finished loading and is ready to begin receiving API calls. Your application should implement this method if you want to automatically execute certain operations, such as playing the video or displaying information about the video, as soon as the player is ready.

The example below shows a sample method for handling this event. The event object that the API passes to the method has a target property, which identifies the player. The method retrieves the embed code for the currently loaded video, starts to play the video, and displays the embed code in the page element that has an id value of embed-code.

function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}

onStateChange

This event fires whenever the player’s state changes. The data property of the event object that the API passes to your event listener method will specify an integer that corresponds to the new player state. Possible values are:

  • -1, not started

  • 0, ended

  • 1, playing

  • 2, paused

  • 3, buffering

  • 5, video cued

When the player first loads a video, it will broadcast an unstarted (-1) event. When a video is cued and ready to play, the player will broadcast a video cued (5) event. In your code, you can specify the integer values or you can use one of the following namespaced variables:

  • YT.PlayerState.ENDED

  • YT.PlayerState.PLAYING

  • YT.PlayerState.PAUSED

  • YT.PlayerState.BUFFERING

  • YT.PlayerState.CUED

onPlaybackQualityChange

This event fires whenever the video playback quality changes. It might signal a change in the viewer’s playback environment. See the YouTube Help Center for more information about factors that affect playback conditions or that might cause the event to fire.

The data property value of the event object that the API passes to the event listener method will be a string that identifies the new playback quality. Possible values are:

  • small

  • medium

  • large

  • hd720

  • hd1080

  • highres

onPlaybackRateChange

This event fires whenever the video playback rate changes. For example, if you call the setPlaybackRate(suggestedRate) method, this event will fire if the playback rate actually changes. Your application should respond to the event and should not assume that the playback rate will automatically change when the setPlaybackRate(suggestedRate) method is called. Similarly, your code should not assume that the video playback rate will only change as a result of an explicit call to setPlaybackRate.

The data property value of the event object that the API passes to the event listener method will be a number that identifies the new playback rate. The getAvailablePlaybackRates method returns a list of the valid playback rates for the currently cued or playing video.

onError

This event fires if an error occurs in the player. The API will pass an event object to the event listener method. That object’s data property will specify an integer that identifies the type of error that occurred.

Possible values are:

  • 2, The request contains an invalid parameter value. For example, this error occurs if you specify a video ID that does not have 11 characters, or if the video ID contains invalid characters, such as exclamation points or asterisks.

  • 5, The requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.

  • 100, The video requested was not found. This error occurs when a video has been removed (for any reason) or has been marked as private.

  • 101, The owner of the requested video does not allow it to be played in embedded players.

  • 150, This error is the same as 101. It’s just a 101 error in disguise.

onApiChange

This event is fired to indicate that the player has loaded (or unloaded) a module with exposed API methods. Your application can listen for this event and then poll the player to determine which options are exposed for the recently loaded module. Your application can then retrieve or update the existing settings for those options.

The following command retrieves an array of module names for which you can set player options:

player.getOptions();

Currently, the only module that you can set options for is the captions module, which handles closed captioning in the player. Upon receiving an onApiChange event, your application can use the following command to determine which options can be set for the captions module:

player.getOptions('captions');

By polling the player with this command, you can confirm that the options you want to access are, indeed, accessible. The following commands retrieve and update module options:

// Retrieving an option:
player.getOption(module, option);
//Setting an option
player.setOption(module, option, value);

The table below lists the options that the API supports:

Module Option Description

captions

fontSize

This option adjusts the font size of the captions displayed in the player.

Valid values are -1, 0, 1, 2, and 3. The default size is 0, and the smallest size is -1. Setting this option to an integer below -1 will cause the smallest caption size to display, while setting this option to an integer above 3 will cause the largest caption size to display.

captions

reload

This option reloads the closed caption data for the video that is playing. The value will be null if you retrieve the option’s value. Set the value to true to reload the closed caption data.

onAutoplayBlocked

This event fires any time the browser blocks autoplay or scripted video playback features, collectively referred to as "autoplay". This includes playback attempted with any of the following player APIs:

  • autoplay parameter

  • loadPlaylist method

  • loadVideoById method

  • loadVideoByUrl method

  • playVideo method

Most browsers have policies that can block autoplay in desktop, mobile, and other environments if certain conditions are true. Instances where this policy may be triggered include unmuted playback without user interaction, or when a Permissions Policy to permit autoplay on a cross-origin iframe has not been set.

For complete details, refer to browser-specific policies (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) and Mozilla’s autoplay guide.

Examples

Find below examples how to use the YouTube iFrame API on webpages for native players. Based on the example, you can manually implement YouTube players on a page.

The J1 Template system automates the process using the iFrame API and transforms native players into custom players using VideoJS. This transformation enhances the user experience, as all players utilize the same look and feel, including the controls (progress bar or play and skip buttons). Using the VideoJS YT Tech plugin, disturbing commercial advertising gets suppressed, allowing users to watch videos uninterrupted.

Example 1

Use API with existing <iframe>. In this example, an <iframe> element on the page already defines the player with which the API will be used. Note that either the player’s src URL must set the enablejsapi parameter to 1 or the <iframe> element’s enablejsapi attribute must be set to true.

The onPlayerReady method changes the color of the border around the player to orange when the player is ready. The `onPlayerStateChange+ method then changes the color of the border around the player based on the current player status. For example, the color is green when the player is playing, red when paused, blue when buffering, and so forth.

This example uses the following code:

<iframe id="iframe-example-01"
  width="640" height="360"
  src="//youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
  frameborder="0"
  style="border: solid 4px #37474F"
></iframe>
<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = '//youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
  var player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player('iframe-example-01', {
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
        }
    });
  }
  function onPlayerReady(event) {
    document.getElementById('iframe-example-01').style.borderColor = '#FF6D00';
  }
  function changeBorderColor(playerStatus) {
    var color;
    if (playerStatus == -1) {
      color = "#37474F"; // unstarted = gray
    } else if (playerStatus == 0) {
      color = "#FFFF00"; // ended = yellow
    } else if (playerStatus == 1) {
      color = "#33691E"; // playing = green
    } else if (playerStatus == 2) {
      color = "#DD2C00"; // paused = red
    } else if (playerStatus == 3) {
      color = "#AA00FF"; // buffering = purple
    } else if (playerStatus == 5) {
      color = "#FF6DOO"; // video cued = orange
    }
    if (color) {
      document.getElementById('iframe-example-01').style.borderColor = color;
    }
  }
  function onPlayerStateChange(event) {
    changeBorderColor(event.data);
  }
</script>

Example 2

Playback video (loud) at volume set to 100%. This example creates a video player of size 1280px by 720px. The event listener for the onReady event then calls the setVolume method to adjust the volume to the highest setting.

This example uses the following code:

function onYouTubeIframeAPIReady() {
  var player_example_02;
  player_example_02 = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}
function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

Example 3

This example sets player parameters to automatically play the video when it loads and hide the video player’s controls. It also adds event listeners for several events that the API broadcasts.

This example uses the following code:

function onYouTubeIframeAPIReady() {
  var player_example_03;
  player_example_03 = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'autoplay': 1,
      'controls': 0
      },
    events: {
      'onReady':        onPlayerReady,
      'onStateChange':  onPlayerStateChange,
      'onError':        onPlayerError
    }
  });
}