此页面由 Cloud Translation API 翻译。

YouTube Player API Reference for iframe Embeds

借助 iFrame Player API，您可以在自己的网站上嵌入 YouTube 视频播放器，并使用 JavaScript 控制播放器。

使用 API 的 JavaScript 函数，您可以：将视频列入播放队列；播放、暂停或停止这些视频；调整播放器音量；或者检索正在播放的视频的相关信息。您还可以添加事件监听器，以响应特定播放器事件（例如播放器状态更改）而执行操作。

本指南介绍了如何使用 IFrame API。该文档介绍了该 API 可以发送的不同类型的事件，并说明了如何编写事件监听器来响应这些事件。此外，本指南还将详细说明您可以在控制视频播放器时调用的各种 JavaScript 函数，以及可用于进一步自定义播放器的播放器参数。

要求

用户的浏览器必须支持 HTML5 postMessage 功能。大多数现代浏览器都支持 postMessage。

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

使用 IFrame API 的所有网页都还必须实施以下 JavaScript 函数：

onYouTubeIframeAPIReady - 当网页下载完播放器 API 的 JavaScript 后，该 API 将调用此函数，以便您在网页上使用该 API。因此，此函数可创建您希望在网页加载时显示的播放器对象。

开始使用

下面的示例HTML网页可以创建一个执行以下操作的嵌入式播放器：加载视频，播放 6 秒钟，然后停止播放。示例下面的列表对 HTML 中带编号的注释进行了说明。

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

以下列表更加详细地介绍了上述示例：

此部分中的 <div> 标记用于标识 IFrame API 将在网页上的何处放置视频播放器。加载视频播放器部分介绍了播放器对象的构造函数，该构造函数会通过 id 标识 <div> 标记，以确保 API 将 <iframe> 放置在正确的位置。具体而言，IFrame API 会将 <div> 标记替换为 <iframe> 标记。

或者，您也可以直接在页面上放置 <iframe> 元素。加载视频播放器部分介绍了如何执行此操作。
此部分中的代码用于加载 IFrame Player API JavaScript 代码。此示例利用 DOM 修改来下载 API 代码，确保系统以异步方式检索代码。（如这篇 Stack Overflow 回答中所述，并非所有新型浏览器都支持 <script> 标记的 async 属性，该属性还支持异步下载。
在 Player API 代码下载后，onYouTubeIframeAPIReady 函数将立即执行。此部分代码定义了一个全局变量 player，该变量引用您要嵌入的视频播放器，然后该函数会构造视频播放器对象。
onPlayerReady 函数将在 onReady 事件触发时执行。在本示例中，该函数指示当视频播放器就绪时就应开始播放。
当播放器的状态发生变化时，该 API 会调用 onPlayerStateChange 函数，这可能表示播放器正在播放、暂停、已播放完毕等。该函数表示，当播放器状态为 1（播放）时，播放器应播放 6 秒钟，然后调用 stopVideo 函数停止视频。

加载视频播放器

该 API 的 JavaScript 代码加载后，该 API 将调用 onYouTubeIframeAPIReady 函数，此时您可以构造 YT.Player 对象以在网页上插入视频播放器。以下 HTML 摘录展示了上述示例中的 onYouTubeIframeAPIReady 函数：

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '390',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'playsinline': 1
    },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

视频播放器的构造函数指定了以下参数：

第一个参数指定 DOM 元素或 HTML 元素的 id，API 将在该元素中插入包含播放器的 <iframe> 标记。

IFrame API 会将指定元素替换为包含播放器的 <iframe> 元素。如果要替换的元素的显示样式与插入的 <iframe> 元素不同，这可能会影响网页的布局。默认情况下，<iframe> 显示为 inline-block 元素。
第二个参数是用于指定播放器选项的对象。该对象包含以下属性：
- width（数值）- 视频播放器的宽度。默认值为 640。
- height（数值）- 视频播放器的高度。默认值为 390。
- videoId（字符串）- YouTube 视频 ID，用于标识播放器将加载的视频。
- playerVars（对象）- 该对象的属性用于确定可用于自定义播放器的播放器参数。
- events（对象）- 该对象的属性用于标识 API 触发的事件以及 API 在这些事件发生时会调用的函数（事件监听器）。在该示例中，构造函数表明 onPlayerReady 函数将在 onReady 事件触发时执行，onPlayerStateChange 函数将在 onStateChange 事件触发时执行。

如开始使用部分中所述，您可以自行创建 <iframe> 标记，而不是在网页上编写一个空的 <div> 元素，然后由 Player API 的 JavaScript 代码将其替换为 <iframe> 元素。示例部分中的第一个示例展示了如何执行此操作。

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

请注意，如果您确实编写了 <iframe> 标记，那么在构建 YT.Player 对象时，您无需为 width 和 height（作为 <iframe> 标记的属性指定）或 videoId 和 player 参数（在 src 网址中指定）指定值。作为额外的安全措施，您还应向网址添加 origin 参数，并将网址架构（http:// 或 https://）和主机网页的完整网域指定为参数值。虽然 origin 是可选的，但添加它有助于防止恶意第三方 JavaScript 注入您的网页并盗用 YouTube 播放器的控制权。

如需了解构建视频播放器对象的其他示例，请参阅示例。

操作

要调用播放器 API 方法，您必须先引用要控制的播放器对象，如本文档的开始使用和加载视频播放器部分所述，您可以通过创建 YT.Player 对象来获取该引用。

函数

队列函数

队列函数可让您加载和播放视频、播放列表或其他视频列表。如果您使用下文所述的对象语法调用这些函数，则还可以将用户上传的视频列表加入队列或加载该列表。

该 API 支持两种不同的队列函数调用语法。

参数语法要求函数参数以规定的顺序列出。
对象语法可让您传递一个对象作为单个参数，还可以让您为设置的函数参数定义对象属性。此外，该 API 还可以支持参数语法所不支持的其他功能。

例如，可以通过以下任一方式调用 loadVideoById 函数。请注意，对象语法支持 endSeconds 属性，而实参语法不支持。

参数语法

loadVideoById("bHQqvYy5KYo", 5, "large")

对象语法

loadVideoById({'videoId': 'bHQqvYy5KYo',
               'startSeconds': 5,
               'endSeconds': 60});

视频队列函数

cueVideoById

参数语法

player.cueVideoById(videoId:String,
                    startSeconds:Number):Void

对象语法

player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number}):Void

此函数用于加载指定视频的缩略图，并准备用于播放视频的播放器。在调用 playVideo() 或 seekTo() 之前，播放器不会请求 FLV。

必需的 videoId 参数用于指定要播放的视频的 YouTube 视频 ID。在 YouTube Data API 中，video 资源的 id 属性指定了 ID。
可选的 startSeconds 参数接受浮点数/整数，用于指定在调用 playVideo() 时视频应从哪个时间开始播放。如果您指定 startSeconds 值，然后调用 seekTo()，则播放器将从 seekTo() 调用中指定的时间开始播放。当视频已就绪并准备播放时，播放器将广播 video cued 事件 (5)。
可选的 endSeconds 参数（仅在对象语法中受支持）接受浮点数/整数，用于指定在调用 playVideo() 时视频应停止播放的时间。如果您指定 endSeconds 值，然后调用 seekTo()，则 endSeconds 值将不再有效。

loadVideoById

参数语法

player.loadVideoById(videoId:String,
                     startSeconds:Number):Void

对象语法

player.loadVideoById({videoId:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

此函数用于加载并播放指定的视频。

必需的 videoId 参数用于指定要播放的视频的 YouTube 视频 ID。在 YouTube Data API 中，video 资源的 id 属性指定了 ID。
可选的 startSeconds 参数接受浮点数/整数。如果指定该可选参数，则视频会从距离指定时间最近的关键帧开始播放。
可选的 endSeconds 参数接受浮点数/整数。如果指定该可选参数，则视频会在指定的时间停止播放。

cueVideoByUrl

参数语法

player.cueVideoByUrl(mediaContentUrl:String,
                     startSeconds:Number):Void

对象语法

player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

此函数用于加载指定视频的缩略图，并准备用于播放视频的播放器。在调用 playVideo() 或 seekTo() 之前，播放器不会请求 FLV。

必需的 mediaContentUrl 参数指定了格式为 http://www.youtube.com/v/VIDEO_ID?version=3 的完全限定 YouTube 播放器网址。
可选的 startSeconds 参数接受浮点数/整数，用于指定在调用 playVideo() 时视频应从哪个时间开始播放。如果您指定 startSeconds 并调用 seekTo()，则播放器将从 seekTo() 调用中指定的时间开始播放。当视频已就绪并准备播放时，播放器将广播 video cued 事件 (5)。
可选的 endSeconds 参数（仅在对象语法中受支持）接受浮点数/整数，用于指定在调用 playVideo() 时视频应停止播放的时间。如果您指定 endSeconds 值，然后调用 seekTo()，则 endSeconds 值将不再有效。

loadVideoByUrl

参数语法

player.loadVideoByUrl(mediaContentUrl:String,
                      startSeconds:Number):Void

对象语法

player.loadVideoByUrl({mediaContentUrl:String,
                       startSeconds:Number,
                       endSeconds:Number}):Void

此函数用于加载并播放指定的视频。

必需的 mediaContentUrl 参数指定了格式为 http://www.youtube.com/v/VIDEO_ID?version=3 的完全限定 YouTube 播放器网址。
可选的 startSeconds 参数接受浮点数/整数，用于指定视频应从什么时间开始播放。如果指定了 startSeconds（数字可以是浮点数），则视频将从最接近指定时间的关键帧开始播放。
可选的 endSeconds 参数（仅在对象语法中受支持）接受浮点数/整数，用于指定视频应停止播放的时间。

列表队列函数

您可以使用 cuePlaylist 和 loadPlaylist 函数加载和播放播放列表。如果您使用对象语法调用这些函数，还可以将用户上传的视频列表加入队列（或加载）。

由于函数的具体工作方式取决于它们的调用方法（参数语法还是对象语法），因此我们在下文提供了这两种调用方法的说明。

cuePlaylist

参数语法
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
```
将指定的播放列表加入队列。当播放列表已就绪并准备播放时，播放器将广播 video cued 事件 (5)。
- 必需的 playlist 参数用于指定 YouTube 视频 ID 数组。在 YouTube Data API 中，video 资源的 id 属性用于标识相应视频的 ID。
- 可选的 index 参数用于指定播放列表中要播放的第一个视频的索引。该参数使用从 0 开始的索引，默认参数值为 0，因此默认行为是加载并播放播放列表中的第一个视频。
- 可选的 startSeconds 参数接受浮点数/整数，用于指定在调用 playVideo() 函数时播放列表中第一个视频的开始时间。如果您指定 startSeconds 值，然后调用 seekTo()，则播放器将从 seekTo() 调用中指定的时间开始播放。如果您提示播放列表，然后调用 playVideoAt() 函数，则播放器将从指定视频的开头开始播放。
对象语法
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
```
将指定的视频列表加入队列。列表可以是播放列表，也可以是用户上传的视频 Feed。将搜索结果列表加入队列的功能已弃用，自 2020 年 11 月 15 日起将不再受支持。
当列表已就绪并准备播放时，播放器将广播 video cued 事件 (5)。
- 可选的 listType 属性用于指定要检索的结果 Feed 的类型。有效值为 playlist 和 user_uploads。自 2020 年 11 月 15 日起，我们将不再支持已废弃的值 search。默认值为 playlist。
- 必需的 list 属性包含一个键，用于标识 YouTube 应返回的特定视频列表。
  - 如果 listType 属性值为 playlist，则 list 属性指定播放列表 ID 或视频 ID 数组。在 YouTube Data API 中，playlist 资源的 id 属性用于标识播放列表的 ID，video 资源的 id 属性用于指定视频 ID。
  - 如果 listType 属性值为 user_uploads，则 list 属性会标识将返回其上传视频的用户。
  - 如果 listType 属性值为 search，则 list 属性会指定搜索查询。注意：此功能已弃用，自 2020 年 11 月 15 日起将不再受支持。
- 可选的 index 属性用于指定列表中要播放的第一个视频的索引。该参数使用从 0 开始的索引，默认参数值为 0，因此默认行为是加载并播放列表中的第一个视频。
- 可选的 startSeconds 属性接受浮点数/整数，用于指定在调用 playVideo() 函数时列表中第一个视频应从什么时间开始播放。如果您指定 startSeconds 值，然后调用 seekTo()，则播放器将从 seekTo() 调用中指定的时间开始播放。如果您提示列表，然后调用 playVideoAt() 函数，则播放器将从指定视频的开头开始播放。

loadPlaylist

参数语法
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
```
此函数会加载指定的播放列表并播放该播放列表。
- 必需的 playlist 参数用于指定 YouTube 视频 ID 数组。在 YouTube Data API 中，video 资源的 id 属性用于指定视频 ID。
- 可选的 index 参数用于指定播放列表中要播放的第一个视频的索引。该参数使用从 0 开始的索引，默认参数值为 0，因此默认行为是加载并播放播放列表中的第一个视频。
- 可选的 startSeconds 参数接受浮点数/整数，用于指定播放列表中第一个视频应从什么时间开始播放。
对象语法
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
```
此函数会加载指定列表并播放该列表。列表可以是播放列表，也可以是用户上传的视频动态。加载搜索结果列表的功能已弃用，自 2020 年 11 月 15 日起将不再受支持。
- 可选的 listType 属性用于指定要检索的结果 Feed 的类型。有效值为 playlist 和 user_uploads。自 2020 年 11 月 15 日起，我们将不再支持已废弃的值 search。默认值为 playlist。
- 必需的 list 属性包含一个键，用于标识 YouTube 应返回的特定视频列表。
  - 如果 listType 属性值为 playlist，则 list 属性指定播放列表 ID 或视频 ID 数组。在 YouTube Data API 中，playlist 资源的 id 属性用于指定播放列表的 ID，video 资源的 id 属性用于指定视频 ID。
  - 如果 listType 属性值为 user_uploads，则 list 属性会标识将返回其上传视频的用户。
  - 如果 listType 属性值为 search，则 list 属性会指定搜索查询。注意：此功能已弃用，自 2020 年 11 月 15 日起将不再受支持。
- 可选的 index 属性用于指定列表中要播放的第一个视频的索引。该参数使用从 0 开始的索引，默认参数值为 0，因此默认行为是加载并播放列表中的第一个视频。
- 可选的 startSeconds 属性接受浮点数/整数，用于指定列表中第一个视频应从什么时间开始播放。

播放控制和播放器设置

播放视频

player.playVideo():Void: 播放当前已提示/加载的视频。此函数执行后的最终播放器状态将为 playing (1)。

注意：只有通过播放器中的原生播放按钮发起的播放才会计入视频的官方观看次数。

player.pauseVideo():Void: 暂停当前正在播放的视频。此函数执行后的最终玩家状态将为 paused (2)，除非在调用该函数时玩家处于 ended (0) 状态，在这种情况下，玩家状态将保持不变。

player.stopVideo():Void: 停止并取消加载当前视频。您应将此函数保留以用于极少数情况（例如，您知道用户不会观看播放器中的其他视频）。如果您的 intent 是暂停视频，您只需调用 pauseVideo 函数即可。如果您想更改播放器正在播放的视频，可以调用其中一个队列函数，而无需先调用 stopVideo。

重要提示：与 pauseVideo 函数（会将播放器保持在 paused [2] 状态）不同，stopVideo 函数可以将播放器置于任何非播放状态，包括 ended [0]、paused [2]、video cued [5] 或 unstarted [-1]。

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

跳转到视频中的指定时间。如果调用该函数时播放器已暂停，则播放器会保持暂停状态。如果从其他状态（playing、video cued 等）调用该函数，播放器将播放视频。

seconds 参数用于标识播放器应跳转到的时间。

除非播放器已下载用户要跳转到的视频片段，否则它会跳转到该时间点之前最近的关键帧。
如果 seconds 参数指定的时间超出了当前缓冲的视频数据，allowSeekAhead 参数将决定播放器是否会向服务器发出新请求。

我们建议您在用户沿视频进度条拖动鼠标时将此参数设置为 false，然后在用户松开鼠标时将其设置为 true。此方法可让用户滚动到视频的不同时间点，而无需在滚动过视频中未缓冲的时间点时请求新的视频流。当用户松开鼠标按钮后，播放器会快进到视频中的相应时间点，并在必要时请求新的视频流。

控制 360 度全景视频的播放

注意：移动设备对 360 度视频播放体验的支持有限。在不受支持的设备上，360 度视频会出现失真，并且完全没有任何受支持的方法可以更改观看视角，包括通过 API、使用方向传感器或响应设备屏幕上的触摸/拖动操作。

player.getSphericalProperties():Object

检索用于描述观看者当前观看视频的视角或视图的属性。此外：

此对象仅针对 360 度视频（也称为全景视频）进行填充。
如果当前视频不是 360 度视频，或者从不受支持的设备调用该函数，则该函数会返回一个空对象。
在受支持的移动设备上，如果 enableOrientationSensor 属性设置为 true，则此函数会返回一个对象，其中 fov 属性包含正确的值，其他属性设置为 0。

该对象包含以下属性：

属性
`yaw`	一个介于 [0, 360) 范围内的数字，表示视图的水平角度（以度为单位），反映了用户将视图向左或向右转动的程度。中性位置（在等角投影中朝向视频中心）表示 0°，随着观看者向左转动，此值会增加。
`pitch`	一个介于 [-90, 90] 范围内的数字，表示视图的垂直角度（以度为单位），反映了用户调整视图以向上或向下看的程度。中性位置（在等角投影中朝向视频中心）表示 0°，随着观看者向上看，此值会增加。
`roll`	一个介于 [-180, 180] 范围内的数字，表示视图的顺时针或逆时针旋转角度（以度为单位）。中性位置（等角投影中的水平轴与视图的水平轴平行）表示 0°。随着视图顺时针旋转，该值会增加；随着视图逆时针旋转，该值会减小。请注意，嵌入的播放器不会显示用于调整视图滚动的界面。您可以通过以下两种互斥方式调整滚动：使用移动浏览器中的方向传感器为视图提供滚动。如果方向传感器处于启用状态，则 `getSphericalProperties` 函数始终会将 `0` 作为 `roll` 属性的值返回。如果屏幕方向传感器已停用，请使用此 API 将滚动角设置为非零值。
`fov`	一个介于 [30, 120] 范围内的数字，表示视图的视野（以度为单位），沿视口的较长边测量。系统会自动调整较短边，使其与视图的宽高比成比例。默认值为 100 度。降低此值就像放大视频内容，而提高此值则就像缩小视频内容。当视频处于全屏模式时，您可以使用 API 或鼠标滚轮来调整此值。

player.setSphericalProperties(properties:Object):Void

设置 360 度视频的播放视频方向。（如果当前视频不是球形视频，则无论输入内容如何，此方法都不会执行任何操作。）

播放器视图会通过更新来响应对此方法的调用，以反映 properties 对象中的任何已知属性的值。该视图会保留该对象中未包含的任何其他已知属性的值。

此外：

如果对象包含未知和/或意外的属性，则播放器会忽略这些属性。
如本部分开头所述，并非所有移动设备都支持 360 度视频播放体验。
默认情况下，在受支持的移动设备上，此函数仅会设置 fov 属性，不会影响 360 度视频播放的 yaw、pitch 和 roll 属性。如需了解详情，请参阅下面的 enableOrientationSensor 属性。

传递给函数的 properties 对象包含以下属性：

属性
`yaw`	请参阅上文中的定义。
`pitch`	请参阅上文中的定义。
`roll`	请参阅上文中的定义。
`fov`	请参阅上文中的定义。
`enableOrientationSensor`	注意：此属性仅影响受支持设备上的 360 度观看体验。一个布尔值，用于指示 IFrame 嵌入内容是否应响应指示受支持设备屏幕方向变化的事件，例如移动浏览器的 `DeviceOrientationEvent`。默认参数值为 `true`。支持的移动设备当值为 `true` 时，嵌入式播放器仅依靠设备的移动来调整 360 度视频播放的 `yaw`、`pitch` 和 `roll` 属性。不过，您仍然可以通过 API 更改 `fov` 属性，事实上，API 是更改移动设备上的 `fov` 属性的唯一方式。这是默认行为。当值为 `false` 时，设备的移动不会影响 360 度观看体验，并且必须通过 API 设置 `yaw`、`pitch`、`roll` 和 `fov` 属性。不支持的移动设备 `enableOrientationSensor` 属性值对播放体验没有任何影响。

播放播放列表中的视频

player.nextVideo():Void

此函数会加载并播放播放列表中的下一个视频。

如果在观看播放列表中的最后一部视频时调用 player.nextVideo()，并且播放列表设置为连续播放 (loop)，则播放器将加载并播放列表中的第一个视频。
如果在观看播放列表中的最后一部视频时调用了 player.nextVideo()，并且播放列表未设置为连续播放，则播放将结束。

player.previousVideo():Void

此函数会加载并播放播放列表中的上一个视频。

如果在观看播放列表中第一个视频时调用 player.previousVideo()，并且播放列表已设置为连续播放 (loop)，则播放器将加载并播放列表中的最后一个视频。
如果在观看播放列表中第一个视频时调用了 player.previousVideo()，并且播放列表未设置为连续播放，则播放器将从头开始重播第一个播放列表视频。

player.playVideoAt(index:Number):Void

此函数会加载并播放播放列表中的指定视频。

必需的 index 参数用于指定您要在播放列表中播放的视频的索引。该参数使用从 0 开始的索引，因此值 0 表示列表中的第一个视频。如果您随机播放了播放列表，此函数将在随机播放的播放列表中指定位置播放视频。

更改播放器的音量

player.mute():Void: 将播放器静音。

player.unMute():Void: 取消静音。

player.isMuted():Boolean: 如果播放器处于静音状态，则返回 true；如果不是，则返回 false。

player.setVolume(volume:Number):Void: 设置音量。接受介于 0 和 100 之间的整数。

player.getVolume():Number: 返回播放器的当前音量，介于 0 和 100 之间的整数。请注意，即使播放器处于静音状态，getVolume() 也会返回音量。

设置播放器的大小

player.setSize(width:Number, height:Number):Object: 设置包含播放器的 <iframe> 的大小（以像素为单位）。

设置播放速率

player.getPlaybackRate():Number: 此函数用于检索当前正在播放的视频的播放速度。默认的播放速率为 1，表示视频以正常速度播放。播放速率可能包括 0.25、0.5、1、1.5 和 2 等值。

player.setPlaybackRate(suggestedRate:Number):Void: 此函数用于为当前视频设置建议的播放速率。如果播放速率改变，那么此函数将仅改变已插入或正在播放的视频的速率。如果您为已提示的视频设置了播放速率，那么在调用 playVideo 函数或用户直接通过播放器控件启动播放时，该速率仍会有效。此外，调用用于提示或加载视频或播放列表的函数（cueVideoById、loadVideoById 等）会将播放速率重置为 1。

调用此函数并不能保证播放速度会实际发生变化。不过，如果播放速率确实发生变化，系统会触发 onPlaybackRateChange 事件，您的代码应响应该事件，而不是响应它调用了 setPlaybackRate 函数。

getAvailablePlaybackRates 方法将返回当前正在播放的视频的可用播放速率。不过，如果您将 suggestedRate 参数设置为不受支持的整数或浮点值，则播放器会将该值向下舍入到最接近的受支持值（在 1 方向上）。

player.getAvailablePlaybackRates():Array: 此函数会返回当前视频支持的一组播放速率。默认值为 1，表示视频以正常速度播放。

此函数会返回一个数字数组，按播放速度从慢到快的顺序排列。即使播放器不支持可变播放速度，该数组也应始终包含至少一个值 (1)。

设置播放列表的播放行为

player.setLoop(loopPlaylists:Boolean):Void

此函数用于指明视频播放器应连续播放播放列表，还是应在播放列表中的最后一个视频结束之后停止播放。默认行为是播放列表不循环播放。

即使您加载或提示其他播放列表，此设置也会保留，这意味着，如果您加载一个播放列表，使用值为 true 调用 setLoop 函数，然后加载第二个播放列表，第二个播放列表也会循环播放。

必需的 loopPlaylists 参数用于标识循环行为。

如果参数值为 true，则视频播放器将连续播放播放列表。播放播放列表中的最后一个视频之后，视频播放器将回到播放列表开头，重新播放。
如果参数值为 false，则在视频播放器播放播放列表中的最后一部视频后，播放将结束。

player.setShuffle(shufflePlaylist:Boolean):Void

此函数用于指出播放列表中的视频是否应随机播放，以便使这些视频以不同于播放列表创建者指定的顺序播放。如果您在播放列表开始播放之后再将其设置为随机播放，则该列表将会重新排序，而正在播放的视频会继续播放。下一个要播放的视频会基于重新排序后的列表进行选择。

如果您加载或提示其他播放列表，此设置将不会保留，这意味着，如果您加载一个播放列表，调用 setShuffle 函数，然后加载第二个播放列表，系统不会对第二个播放列表进行随机播放。

必需的 shufflePlaylist 参数用于指示 YouTube 是否应随机播放播放列表。

如果参数值为 true，则 YouTube 会随机播放播放列表中的视频。如果您指示此函数随机播放某个已设置为随机播放的播放列表，则 YouTube 将会再次调整随机播放顺序。
如果参数值为 false，则 YouTube 会将播放列表顺序改回原始顺序。

播放状态

player.getVideoLoadedFraction():Float: 返回一个介于 0 和 1 之间的数字，用于指定播放器显示为已缓冲的视频所占的百分比。与现已废弃的 getVideoBytesLoaded 和 getVideoBytesTotal 方法相比，此方法返回的数字更可靠。

player.getPlayerState():Number

返回播放器的状态。可能的值包括：

-1 - 未启动
0 – 已结束
1 – 正在播放
2 – 已暂停
3 – 正在缓冲
5 – 已插入视频

player.getCurrentTime():Number: 返回视频开始播放后经过的秒数。

player.getVideoStartBytes():Number: 自 2012 年 10 月 31 日起已废弃。返回视频文件的加载点前已有的字节数（此方法现在始终返回 0 值。）示例场景：用户快进到尚未加载的某个点，然后播放器发出新请求来播放尚未加载的视频片段。

player.getVideoBytesLoaded():Number: 自 2012 年 7 月 18 日起已废弃。而是使用 getVideoLoadedFraction 方法确定视频缓冲的百分比。

此方法会返回一个介于 0 和 1000 之间的值，该值近似于已加载的视频量。您可以通过将 getVideoBytesLoaded 值除以 getVideoBytesTotal 值来计算已加载的视频的百分比。

player.getVideoBytesTotal():Number: 自 2012 年 7 月 18 日起已废弃。而是使用 getVideoLoadedFraction 方法确定视频缓冲的百分比。

返回当前加载/播放的视频的大小（以字节为单位），或视频大小的近似值。

此方法始终返回 1000 值。您可以通过将 getVideoBytesLoaded 值除以 getVideoBytesTotal 值来计算已加载的视频的百分比。

检索视频信息

player.getDuration():Number: 返回当前正在播放的视频的时长（以秒为单位）。请注意，在视频的元数据加载完毕之前，getDuration() 将返回 0，这通常会在视频开始播放后立即发生。

如果当前正在播放的视频是直播活动，getDuration() 函数将返回直播视频流开始以来经过的时间。具体而言，这是视频在未重置或中断的情况下直播的时长。此外，此时长通常比实际活动时间长，因为在活动开始时间之前就可能会开始直播。

player.getVideoUrl():String: 返回当前加载/播放的视频的 YouTube.com 网址。

player.getVideoEmbedCode():String: 返回当前加载/播放的视频的嵌入代码。

检索播放列表信息

player.getPlaylist():Array: 此函数会返回播放列表中视频 ID 的数组，并按当前的顺序排列。默认情况下，此函数将以播放列表所有者指定的顺序返回视频 ID。不过，如果您调用了 setShuffle 函数来随机播放播放列表的顺序，则 getPlaylist() 函数的返回值将反映随机播放的顺序。

player.getPlaylistIndex():Number

此函数会返回当前正在播放的播放列表视频的索引。

如果您尚未随机播放播放列表，则返回值将会标识播放列表创建者放置视频的位置。返回值使用从零开始的索引，因此值为0时标识播放列表中的第一个视频。
如果您已随机播放播放列表，则返回值将会确定随机播放的播放列表中视频的顺序。

添加或移除事件监听器

player.addEventListener(event:String, listener:String):Void: 为指定的 event 添加监听器函数。下文的事件部分介绍了玩家可能会触发的不同事件。监听器是一个字符串，用于指定触发指定事件时执行的函数。

player.removeEventListener(event:String, listener:String):Void: 移除指定 event 的监听器函数。listener 是一个字符串，用于标识在指定事件触发时不再执行的函数。

访问和修改 DOM 节点

player.getIframe():Object: 此方法会返回嵌入的 <iframe> 的 DOM 节点。

player.destroy():Void: 移除包含播放器的 <iframe>。

事件

API会触发事件来向您的应用通知嵌入式播放器发生的变化。如上一部分所述，您可以在构建 YT.Player 对象时添加事件监听器，以订阅事件，也可以使用 addEventListener 函数。

API会将事件对象作为单独的参数传递给每个函数。事件对象具有以下属性：

事件的 target 用于标识与事件对应的视频播放器。
事件的 data 用于指定与事件相关的值。请注意，onReady 和 onAutoplayBlocked 事件未指定 data 属性。

以下列表定义了API触发的事件：

onReady

每当玩家加载完毕并准备开始接收 API 调用时，此事件就会触发。如果您希望在播放器准备就绪后立即自动执行某些操作（例如播放视频或显示视频相关信息），则应在应用中实现此函数。

下面的示例展示了用于处理此事件的示例函数。API 传递给函数的事件对象具有 target 属性，用于标识播放器。该函数会检索当前加载的视频的嵌入代码，开始播放视频，并在 id 值为 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

每当播放器的状态发生变化时，此事件都会触发。 API 传递给事件监听器函数的事件对象的 data 属性将指定与新播放器状态对应的整数。可能的值包括：

-1（未启动）
0（已结束）
1（正在播放）
2（已暂停）
3（正在缓冲）
5（视频已插入）

当播放器首次加载视频时，它会广播 unstarted (-1) 事件。当视频已就绪并准备播放时，播放器将广播 video cued (5) 事件。在代码中，您可以指定整数值，也可以使用以下命名空间型变量之一：

YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED

onPlaybackQualityChange

每当视频播放画质发生变化时，都会触发此事件。这可能表示观看者的播放环境发生了变化。如需详细了解影响播放条件或可能会触发事件的因素，请访问 YouTube 帮助中心。

API 传递给事件监听器函数的事件对象的 data 属性值将是一个字符串，用于标识新的播放质量。可能的值包括：

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: 每当视频播放速度发生变化时，系统都会触发此事件。例如，如果您调用 setPlaybackRate(suggestedRate) 函数，当播放速率实际发生变化时，系统就会触发此事件。您的应用应响应该事件，而不要假定在调用 setPlaybackRate(suggestedRate) 函数时播放速率会自动更改。同样，您的代码不应假定视频播放速率只会因显式调用 setPlaybackRate 而发生变化。

API 传递给事件监听器函数的事件对象的 data 属性值将是一个数字，用于标识新的播放速率。 getAvailablePlaybackRates 方法会返回当前已提示或正在播放的视频的有效播放速率列表。

onError

如果播放器中发生错误，系统会触发此事件。该 API 会将 event 对象传递给事件监听器函数。该对象的 data 属性将指定一个整数，用于标识发生的错误类型。可能的值包括：

2 – 请求包含无效的参数值。例如，如果您指定的视频ID不足11个字符，或者如果视频ID包含无效字符（例如感叹号或星号），就会发生此错误。
5 – 请求的内容无法在HTML5播放器中播放，或者发生了与HTML5播放器有关的其他错误。
100 – 找不到所请求的视频。当视频已被移除（无论是何种原因）或者被标记为私有状态时，就会发生此错误。
101 – 所请求的视频的所有者不允许在嵌入式播放器中播放此视频。
150 – 此错误与101相同，这只是伪装成 101 错误的错误！

onApiChange

此事件会触发，以指示玩家已加载（或卸载）包含公开 API 方法的模块。您的应用可监听此事件，然后轮询播放器以确定为最近加载的模块指定的选项。然后，您的应用可以检索或更新这些选项的现有设置。

以下命令会检索可为其设置玩家选项的模块名称数组：

player.getOptions();

目前，您只能为 captions 模块设置选项，该模块用于处理播放器中的字幕。收到 onApiChange 事件后，您的应用可以使用以下命令确定可以为 captions 模块设置哪些选项：

player.getOptions('captions');

通过使用此命令轮询玩家，您可以确认您想要访问的选项确实可访问。以下命令用于检索和更新模块选项：

Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);

下表列出了该 API 支持的选项：

模块	选项	说明
字幕	fontSize	此选项用于调整播放器中显示字幕的字体大小。有效值为 `-1`、`0`、`1`、`2` 和 `3`。默认大小为 `0`，最小大小为 `-1`。将此选项设置为小于 `-1` 的整数将导致显示最小的字幕大小，而将此选项设置为大于 `3` 的整数将导致显示最大的字幕大小。
字幕	reload	此选项会为正在播放的视频重新加载字幕数据。如果您检索选项的值，则值将为 `null`。将值设置为 `true` 以重新加载字幕数据。

onAutoplayBlocked

每当浏览器屏蔽自动播放或脚本化视频播放功能（统称为“自动播放”）时，此事件都会触发。这包括尝试使用以下任一播放器 API 进行的播放：

autoplay 参数
loadPlaylist 函数
loadVideoById 函数
loadVideoByUrl 函数
playVideo 函数

大多数浏览器都有政策，可在桌面设备、移动设备和其他环境中根据特定条件阻止自动播放。此政策可能会在以下情况下触发：无需用户互动即可取消静音播放，或者未设置允许在跨源 iframe 中自动播放的权限政策。

如需了解完整详情，请参阅特定于浏览器的政策（Apple Safari / WebKit、Google Chrome、Mozilla Firefox）以及 Mozilla 的自动播放指南。

示例

创建 `YT.Player` 对象

示例 1：将 API 与现有 <iframe> 搭配使用

在此示例中，页面上的 <iframe> 元素已定义将用于该 API 的播放器。请注意，播放器的 src 网址必须将 enablejsapi 参数设置为 1，或者 <iframe> 元素的 enablejsapi 属性必须设置为 true。

当播放器准备就绪时，onPlayerReady 函数会将播放器周围边框的颜色更改为橙色。然后，onPlayerStateChange 函数会根据当前的播放器状态更改播放器周围边框的颜色。例如，播放器在播放时显示绿色，暂停时显示红色，缓冲时显示蓝色，依此类推。

此示例使用以下代码：

<iframe id="existing-iframe-example"
        width="640" height="360"
        src="https://www.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 = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player('existing-iframe-example', {
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
        }
    });
  }
  function onPlayerReady(event) {
    document.getElementById('existing-iframe-example').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('existing-iframe-example').style.borderColor = color;
    }
  }
  function onPlayerStateChange(event) {
    changeBorderColor(event.data);
  }
</script>

示例 2：音量过大

此示例将创建1280 x 720像素的视频播放器。然后，onReady 事件的事件监听器会调用 setVolume 函数，将音量调至最高设置。

function onYouTubeIframeAPIReady() {
  var player;
  player = 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();
}

示例 3 ：此示例设置了播放器参数，以便在视频加载时自动播放视频并隐藏视频播放器的控件。它还会为该 API 广播的多个事件添加事件监听器。

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

控制 360 度视频

此示例使用以下代码：

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

Android WebView Media Integrity API 集成

YouTube 扩展了 Android WebView Media Integrity API，以便嵌入式媒体播放器（包括 Android 应用中的 YouTube 播放器嵌入）验证嵌入应用的真实性。经过这项更改，嵌入的应用会自动向 YouTube 发送经过认证的应用 ID。通过使用此 API 收集的数据包括应用元数据（软件包名称、版本号和签名证书）以及 Google Play 服务生成的设备认证令牌。

这些数据用于验证应用和设备的完整性。这些数据会经过加密，不会与第三方分享，并会在固定保留期限过后删除。应用开发者可以在 WebView Media Integrity API 中配置其应用身份。该配置支持停用选项。

修订历史记录

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
- yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
- pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
- roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
- fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

April 28, 2014

This update contains the following changes:

The new removeEventListener function lets you remove a listener for a specified event.

March 25, 2014

This update contains the following changes:

The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a 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.

July 23, 2013

This update contains the following changes:

The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

October 31, 2012

This update contains the following changes:

The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)
When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.
The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.
The API supports several new functions and one new event that can be used to control the video playback speed:
- Functions
  - getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
  - getPlaybackRate – Retrieve the playback rate for the cued or playing video.
  - setPlaybackRate – Set the playback rate for the cued or playing video.
- Events
  - onPlaybackRateChange – This event fires when the video's playback rate changes.

July 19, 2012

This update contains the following changes:

The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.
The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.
The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.
The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

We have removed the experimental status from the IFrame Player API.
The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

The Requirements section has been updated to note the minimum player size.

YouTube Player API Reference for iframe Embeds 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

要求

开始使用

加载视频播放器

操作

函数

队列函数

视频队列函数

列表队列函数

播放控制和播放器设置

播放视频

控制 360 度全景视频的播放

播放播放列表中的视频

更改播放器的音量

设置播放器的大小

设置播放速率

设置播放列表的播放行为

播放状态

检索视频信息

检索播放列表信息

添加或移除事件监听器

访问和修改 DOM 节点

事件

示例

创建 YT.Player 对象

控制 360 度视频

Android WebView Media Integrity API 集成

修订历史记录

June 24, 2024

November 20, 2023

April 27, 2021

October 13, 2020

October 24, 2019

May 16, 2018

June 19, 2017

August 11, 2016

June 29, 2016

June 24, 2016

January 6, 2016

December 18, 2015

April 28, 2014

March 25, 2014

July 23, 2013

October 31, 2012

August 22, 2012

August 6, 2012

July 19, 2012

July 16, 2012

June 6, 2012

March 30, 2012

March 26, 2012

YouTube Player API Reference for iframe Embeds

创建 `YT.Player` 对象