播放器参数

概述

本文档介绍了如何在应用中嵌入YouTube播放器,并定义了YouTube嵌入式播放器可以使用的参数。

通过将参数附加到iframe网址,您可以自行设置应用中的播放体验。例如,您可以使用autoplay参数自动播放视频,也可以使用loop参数重复播放某个视频。您还可以使用enablejsapi参数为播放器启用JavaScript API

目前,本页面定义了所有YouTube嵌入式播放器支持的全部参数。每个参数定义均会确定支持相应参数的播放器。

注意:嵌入式播放器必须具有一个尺寸至少为200x200像素的视口。如果播放器显示控件,>那么它必须足够大,可以在无需将视口缩小到最小尺寸以下的情况下完整显示控件。我们建议16:9播放器的宽至少为480像素、高至少为270像素。

嵌入YouTube播放器

您可以使用以下任意一种方法在应用中嵌入YouTube播放器并指定播放器参数。请注意,以下说明将介绍如何嵌入会加载单个视频的播放器。接下来的部分将说明如何配置您的播放器,以便加载其他类型的内容(例如播放列表和搜索结果)。

iframe嵌入:使用<iframe>代码

在您的应用中定义一个<iframe>代码,其中src网址会指定播放器将要加载的内容以及您想设置的其他任何播放器参数。<iframe>代码的heightwidth参数会指定播放器的尺寸。

如果您正自行创建<iframe>元素(而不是使用iframe Player API创建),则可以直接将播放器参数附加到网址末尾。网址格式如下:

http://www.youtube.com/embed/VIDEO_ID

以下<iframe>代码将会加载一个可用来播放YouTube视频M7lc1UVf-VE的640x360像素的播放器。由于网址会将autoplay参数设为1,因此视频会在播放器加载完后自动播放。

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

iframe嵌入:使用iframe Player API

加载Player API的JavaScript代码之后,请按照iframe Player API说明在网页或应用中插入视频播放器。视频播放器构造函数中的第二个参数是指定播放器选项的对象。在此对象中,playerVars属性会确定播放器参数。

以下HTML和JavaScript代码展示了一个简单示例,即将YouTube播放器插入id值为ytplayer的页面元素。系统会在iframe Player API代码加载完成后自动调用此处指定的onYouTubePlayerAPIReady()函数。此代码不会定义任何播放器参数,也不会定义其他事件处理脚本。

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

选择播放内容

您可以配置已嵌入的播放器,以加载视频、播放列表、用户上传的视频或针对特定查询的搜索结果。

以下列表介绍了这些选项:

  • 加载视频

    对于iframe嵌入,系统会在iframe的src网址中指定您想加载的视频的YouTube视频ID。

    http://www.youtube.com/embed/VIDEO_ID

    如果您使用的是YouTube Data API (v3),则可以从搜索结果播放列表项目资源视频资源或其他资源中检索视频ID,以编程方式构建这些网址。获得视频ID之后,请使用该值替换上述网址中的VIDEO_ID文字,来创建播放器网址。

  • 加载播放列表

    listType播放器参数设为playlist。此外,将list播放器参数设为您想加载的YouTube播放列表ID。

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

    请注意,播放列表ID需要以字母PL作为前缀,如下例所示:

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

    如果您使用的是YouTube Data API (v3),则可以从搜索结果频道资源活动资源中检索播放列表ID,以编程方式构建这些网址。获得播放列表ID之后,请使用该值替换上述网址中的PLAYLIST_ID文字。

  • 加载用户上传的视频

    listType播放器参数设为user_uploads,然后将list播放器参数设为YouTube用户名,加载自己喜欢的对象所上传的视频。

    http://www.youtube.com/embed?listType=user_uploads&list=USERNAME
  • 加载指定查询的搜索结果

    listType播放器参数设为search,然后将list播放器参数设为您希望的查询字词,让播放器加载相应的搜索结果。

    http://www.youtube.com/embed?listType=search&list=QUERY

参数

以下所有参数均为可选参数。

Parameters

autoplay

值:01。默认值为0。用于设置初始视频是否在加载播放器时自动播放。

cc_load_policy

值:1。默认值是根据用户偏好设置确定的。将此值设为1会使系统在默认情况下显示字幕,即使在用户关闭字幕的情况下也是如此。

color

此参数会指定将在播放器的视频进度条中使用,用来突出显示观看者已经看过的视频量的颜色。有效的参数值包括redwhite,而且在默认情况下,播放器将在视频进度条中使用红色。有关颜色选项的详情,请参见YouTube API博客

注意:将color参数设为white将会停用modestbranding选项。

controls

值:012。默认值为1。此参数会指明视频播放器控件是否会显示。对于加载Flash播放器的iframe嵌入,此参数还会定义控件何时在播放器中显示,以及播放器加载时间:

  • controls=0 - 播放器控件不会在播放器中显示。对于iframe嵌入,Flash播放器会立即加载。
  • controls=1 - 播放器控件会在播放器中显示。对于iframe嵌入,控件会立即显示,而且Flash播放器也会立即加载。
  • controls=2 - 播放器控件会在播放器中显示。对于iframe嵌入,控件会显示,而且Flash播放器会在用户启动视频播放时加载。

注意:参数值12用于提供一致的用户体验,但是,对于iframe嵌入而言,controls=2提供的性能较之controls=1已得到改进。目前,这两个参数值仍会在播放器中产生一些视觉方面的差异(例如,视频标题的字体大小)。但是,当两个参数值之间的差异对用户而言变得完全透明时,默认参数值可能会从1更改为2

disablekb

值:01。默认值为0。将此值设为1将会停用播放器键盘控件。键盘控件如下:

  • 空格键:播放/暂停
  • 向左箭头:当前视频后退10%
  • 向右箭头:当前视频前进10%
  • 向上箭头:调高音量
  • 向下箭头:降低音量

enablejsapi

值:01。默认值为0。将此值设为1将会停用Javascript API。有关Javascript API及其使用方法的详情,请参见JavaScript API文档

end

值:正整数。此参数会指定时间,自视频开始时起以秒计量,直到播放器应该停止播放视频时止。请注意,时间是从视频开始处而不是从start播放器参数或startSeconds参数开始计量的,该时间在YouTube Player API中用于加载或将视频加入播放队列。

fs

值:01。默认值为1,该值会使全屏按钮显示。将此参数设为0会阻止全屏按钮显示。

hl

设置播放器的界面语言。此参数值为两个字母的ISO 639-1语言代码,即使是其他语言输入代码(例如IETF语言代码(BCP 47))也可得到恰当处理。

界面语言用于播放器中的工具提示,而且还会影响默认的字幕轨道。请注意,YouTube可能会根据特定用户的个人语言偏好设置和提供的字幕轨道,为该用户选择其他字幕轨道语言。

iv_load_policy

值:13。默认值为1。将此值设为1会在默认情况下显示视频注释,而将其设为3则默认不显示。

list

list参数与listType参数结合可确定播放器中将要加载的内容。

  • 如果listType参数的值为search,则list参数值会指定搜索查询。
  • 如果listType参数的值为user_uploads,则list参数值会确定将要加载的已上传视频所在的YouTube频道。
  • 如果listType参数的值为playlist,则list参数值会指定YouTube播放列表ID。在参数值中,您需要使用字母PL为播放列表ID添加前缀,如下例所示。
    http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6

注意:如果您指定listlistType参数的值,则iframe嵌入网址就无需指定视频ID。

listType

listType参数与list参数结合可确定播放器中将要加载的内容。有效的参数值包括playlistsearchuser_uploads

如果您指定listlistType参数的值,则iframe嵌入网址就无需指定视频ID。

loop

值:01。默认值为0。如果播放器是单视频播放器,则将此值设为1会使播放器反复播放初始视频。如果播放器是播放列表播放器(或自定义播放器),则会播放播放列表中的所有视频,然后再从第一个视频开始从头播放。

注意:此参数在AS3播放器和iframe嵌入(可能会加载AS3或HTML5播放器)中得到的支持会受到限制。目前,仅在与playlist参数结合使用时,loop参数才能在AS3播放器中起作用。要循环播放单个视频,请将loop参数值设为1,并将playlist参数值设为与Player API网址中已指定的视频ID相同的值:
http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID

modestbranding

此参数可让您使用不显示YouTube徽标的YouTube播放器。将参数值设为1可以阻止YouTube徽标显示在控件栏中。请注意,当用户的鼠标指针悬停在播放器上方时,小的YouTube文字标签仍将显示在已暂停的视频的右上角。

origin

此参数为iframe API提供额外的安全保护,而且仅受iframe嵌入支持。如果您使用的是iframe API,这意味着您即将把enablejsapi参数的值设为1,您应始终将网域的参数值指定为origin

playlist

值是要播放的视频对应的视频ID列表(以逗号分隔)。如果您指定一个值,则播放的第一个视频将是网址路径中指定的VIDEO_ID,而在playlist参数中指定的视频将在随后播放。

playsinline

此参数会控制视频在iOS设备上的HTML5播放器中播放时,以内嵌方式播放还是以全屏形式播放。有效值如下:

  • 0:如果使用该值,视频将在全屏模式下播放。目前,这是默认值,但默认值可能会发生变化。
  • 1:如果使用该值,系统会将使用allowsInlineMediaPlayback属性创建的UIWebViews的内嵌播放值设为TRUE

rel

值:01。默认值为1。此参数将表明初始视频播放结束时,播放器是否应显示相关视频。

showinfo

值:01。此参数的默认值为1。如果您将此参数的值设为0,则在视频开始播放之前,播放器不会显示视频标题和上传者等信息。

如果播放器正在加载播放列表,而且您已明确将此参数的值设为1,那么播放列表加载时,播放器还将显示播放列表中视频的缩略图。请注意,只有AS3播放器支持此功能,因为只有AS3播放器可以加载播放列表。

start

值:正整数。此参数可让播放器从视频中的指定位置开始播放视频,具体位置以距视频开头的秒数表示。请注意,与seekTo函数类似,播放器会查找与指定时间最接近的关键帧。这就意味着,播放指针有时可能会尽量停在请求时间之前几秒,通常与请求时间相差不超过2秒。

修订历史记录

October 14, 2014

July 18, 2014

  • The new hl parameter can be used to set the player's interface language. The interface language is used for tooltips in the player and also affects the default caption track. The selected caption track may also depend on the availability of caption tracks and user's individual language preferences.

    The parameter's value is an ISO 639-1 two-letter language code, though other language input codes, such as IETF language tags (BCP 47) may also be handled properly.

  • The definition of the playsinline parameter, which only affects HTML5 players on iOS, has been modified slightly. The definition now notes that setting the parameter value to 1 causes inline playback only for UIWebViews created with the allowsInlineMediaPlayback property set to TRUE.

January 28, 2014

  • The playsinline parameter controls whether videos play inline or fullscreen in an HTML5 player on iOS. Setting the value to 1 causes inline playback.

  • The Selecting content to play section has been updated to explain how to find YouTube video IDs and playlist IDs using the YouTube Data API (v3) rather than the older API version.

  • The controls parameter's definition has been updated to reflect the fact that the parameter value only affects the time that the Flash player actually loads in IFrame embeds. In addition, for IFrame embeds, the parameter value also determines when the controls display in the player. If you set the parameter's value to 2, then the controls display and the Flash player loads after the user initiates the video playback.

May 10, 2013

This update contains the following changes:

July 20, 2012

This update contains the following changes:

  • The definition of the controls parameter has been updated to reflect support for a parameter value of 2 and to explain that, for AS3 players, the parameter value determines the time when the Flash player actually loads. If the controls parameter is set to 0 or 1, the Flash player loads immediately. If the parameter value is 2, the Flash player does not load until the video playback is initiated.

June 5, 2012

This update contains the following changes:

  • The HTML5 player now supports the color, modestbranding, and rel parameters, and the definitions for these parameters have been updated accordingly.

  • The definition of the showinfo parameter has been updated to explain how that if the player is loading a playlist, and you explicitly set the parameter value to 1, then, upon loading, the player will also display thumbnail images for the videos in the playlist. Note that this functionality is only supported for the AS3 player since that is the only player that can load a playlist.

May 4, 2012

This update contains the following changes:

  • The showinfo parameter's definition has been updated to reflect the fact that the HTML5 player supports this parameter.

May 3, 2012

This update contains the following changes:

  • The new end parameter specifies the time, measured in seconds from the start of the video, when the player should stop playing a video. Note that the time when playback is stopped is measured from the beginning of the video and not from the value of either the start player parameter or the startSeconds parameter, which is used in YouTube Player API functions for loading or queueing a video.

March 29, 2012

This update contains the following changes:

  • The new Embedding a YouTube player section explains different ways to embed a YouTube player in your application. This section covers manual IFrame embeds, IFrame embeds that use the IFrame Player API, and AS3 and AS2 object embeds. This section incorporates information from the old Example usage section, which has been removed.

  • The new Selecting content to play section explains how to configure the player to load a video, a playlist, search results for a specified query, or uploaded videos for a specified user.

  • The new list and listType parameters let you specify the content that the player should load. You can specify a playlist, a search query, or a particular user's uploaded videos.

  • The definitions of the fs and rel parameters have been updated to more clearly explain the default parameter values for the AS3 player.

  • The border, color1, egm, hd, and showsearch parameters, which are all only supported for the deprecated AS2 Player API, have been moved to a new section named deprecated parameters only used in the AS2 Player API.

  • The document no longer provides a way to filter the parameter list to only display parameters supported in either the AS3, AS2, or HTML5 player. Instead, each parameter definition has been updated to identify the players that support that parameter.

August 11, 2011

This update contains the following changes:

  • The new theme and color parameters let you customize the appearance of the embedded player's player controls. See the YouTube API blog for more information.

June 8, 2011

This update contains the following changes:

  • The new modestbranding parameter lets you use a YouTube player that does not show a YouTube logo. As of this release, the parameter was only supported for the AS3 embedded player and for IFrame embeds that loaded the AS3 player. As of June 5, 2012, the HTML5 player also supported this parameter.

February 14, 2011

This update contains the following changes:

  • The documentation has been updated to note that the AS2 Player API has been deprecated. The deprecation of the AS2 Player API was actually announced on October 14, 2009.

February 3, 2011

This update contains the following changes:

  • The documentation has been updated to identify parameters supported in the HTML5 (IFrame) embedded player.

  • The document now displays all of the parameters supported in any of YouTube's embedded players (HTML5, AS3, AS2).

  • The following parameters are supported in the AS2 player but have been deprecated for the newer AS3 and HTML5 players: border, color1, color2, egm, hd, and showsearch.

    In addition, the loop parameter has limited support in the AS3 player and in IFrame embeds, which could load either an AS3 or HTML player. Currently, the loop parameter only works in the AS3 player when used in conjunction with the playlist parameter. To loop a single video, set the loop parameter to 1 and set the playlist parameter value to the same video ID already specified in the Player API URL:

    http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID

    Similarly, the controls and playlist parameters are supported in the AS3 and HTML5 players but are not and will not be supported in the AS2 player.

    As noted above, IFrame embeds can load either an AS3 or HTML5 player. Though some parameters are not supported in both players, an IFrame embed that loads the AS3 player will support all parameters that work with that player and ignore all other parameters. Similarly, an IFrame embed that loads the HTML5 player will support all parameters that work with that player while ignoring all other parameters.

  • The parameter list has been updated to include the autohide parameter, which indicates whether the player's video controls will automatically hide after a video begins playing.

  • The parameter list has been updated to include the controls parameter, which indicates whether the player's video controls will display at all. (Player controls do display by default.)

  • The parameter list has been updated to include the playlist parameter, which specifies a comma-separated list of video IDs to play.

  • The definition of the fs has been updated to note that the fullscreen option will not work if you load the YouTube player into another SWF.

  • The example at the end of the document has been updated to use the embedded AS3 player instead of the embedded AS2 player. The parameters used in the example have also been updated to only include parameters that the AS3 player supports.

    In addition, the instructions for constructing the URLs that contain player parameters have been updated to reflect the URL formats used by the AS3 and AS2 embedded and chromeless players as well as by the HTML5 player.