开始使用事件错误插件内容安全策略函数 currentTime dispose duration getIVSEvents getIVSPlayer 负载 play playbackRate seekable

IVS 回放器 SDK：Video.js 集成

本文档介绍了 Amazon Interactive Video Service (IVS) Video.js 播放器中最重要的功能。

Video.js 播放器集成的最新版本：1.37.0（发布说明）

开始使用

Amazon IVS 对 Video.js 的支持是通过 Video.js 技术实现的。我们通过脚本标签以及 npm 模块提供支持。Amazon IVS 支持 Video.js 版本 7.6.6 以及更高的 7* 和 8* 版本。

请注意，在实例化播放器时，Video.js 源选项不受支持。相反，请正常实例化播放器并调用 Video.js src() 函数。如果启用了自动播放，则流将开始播放；否则，使用 play() 以开始播放。

演示

以下现场演示展示了如何使用 Video.js 集成与我们的内容分发网络中的脚本标签：Amazon IVS 播放器 Video.js 集成。

使用脚本标签进行设置

要使用 script 标签设置 Amazon IVS 技术，请执行以下操作：

包含以下标签（针对最新版本的播放器集成）。


<script src="https://player.live-video.net/1.37.0/amazon-ivs-videojs-tech.min.js"></script>

使用 registerIVSTech 函数注册技术：
```
registerIVSTech(videojs);
```
其中 videojs 是 Video.js 提供的对象。
创建播放器的实例时，添加 AmazonIVS 作为 techOrder 选项中的第一个技术。

当实例化播放器时，Video.js 源选项不受支持。相反，要设置源代码，请正常实例化播放器，然后调用 Video.js src() 函数。如果启用了自动播放，则流将开始播放；否则，使用 play() 以开始播放。

示例代码

在此示例中，PLAYBACK_URL 是要加载的源流。此示例使用最新版本的 Amazon IVS 播放器。


<!doctype html>
<html lang="en">
<head>
    <link href="https://cdnjs.cloudflare.com/ajax/libs/video.js/7.14.3/video-js.css" rel="stylesheet">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/video.js/7.14.3/video.min.js"></script>
    <script src="https://player.live-video.net/1.37.0/amazon-ivs-videojs-tech.min.js"></script>
</head>

<body>
    <div class="video-container">
        <video id="amazon-ivs-videojs" class="video-js vjs-4-3 vjs-big-play-centered" controls autoplay playsinline></video>
    </div>
    <style>
        body {
            margin: 0;
        }

        .video-container {
            width: 640px;
            height: 480px;
            margin: 15px;
        }
    </style>
    <script>
        (function play() {
            // Get playback URL from Amazon IVS API
            var PLAYBACK_URL = '';
            
            // Register Amazon IVS as playback technology for Video.js
            registerIVSTech(videojs);

            // Initialize player
            var player = videojs('amazon-ivs-videojs', {
               techOrder: ["AmazonIVS"]
            }, () => {
               console.log('Player is ready to use!');
               // Play stream
               player.src(PLAYBACK_URL);
            });
        })();
    </script>
</body>
</html>

使用 NPM 进行设置

要通过 npm 使用 Amazon IVS 播放器，请执行以下操作：

安装 video.js npm 软件包或确保您的项目具有对 Video.js 库的一些其他访问权限。
安装 amazon-ivs-player npm 软件包：
```
npm install amazon-ivs-player
```
准备好注册 Amazon IVS 技术时，请导入 registerIVSTech 函数：
```
import { registerIVSTech } from 'amazon-ivs-player';
```
使用 registerIVSTech 函数注册技术：
```
registerIVSTech(videojs, options);
```
其中：
- videojs 是 Video.js 提供的对象。
- options 是 Amazon IVS 技术层的选项。支持的选项为：
  - wasmWorker：托管 amazon-ivs-wasmworker.min.js 文件的 URL。
  - wasmBinary：托管 amazon-ivs-wasmworker.min.wasm 文件的 URL。
  工作线程文件位于 amazon-ivs-player/dist/ 下的 node_modules/ 文件夹中。您需要托管它们以使用 IVS 播放器。
创建播放器的实例时，添加 AmazonIVS 作为 techOrder 选项中的第一个技术：
```
const player = videojs('videojs-player', {
    techOrder: ["AmazonIVS"]
});
```

TypeScript

如果您使用的是 TypeScript，我们的 npm 软件包包含您可能需要导入和使用的以下类型。

VideoJSEvents，描述了从 getIVSEvents() 返回的结构。
VideoJSIVSTech，描述了使用 AmazonIVS 技术的播放器实例的接口。此值可以与 @types/video.js npm 软件包公开的 VideoJsPlayer 类型相交。
TechOptions，描述了定义您可以发送到 registerIVSTech() 的配置选项的接口。

有关这些类型的更多信息，请参阅 Amazon IVS 回放器 SDK：Web 参考。

事件

要侦听标准 Video.js 事件，请使用 Video.js 播放器的 on 函数。

要侦听特定于 Amazon IVS 的事件，请在 Amazon IVS Web 播放器上添加和删除事件侦听器：


player.getIVSPlayer().addEventListener(event, callback);
player.getIVSPlayer().removeEventListener(event, callback);

其中 callback 是您定义的回调，event 为以下值之一：PlayerEventType 或 PlayerState。有关事件的更多信息，请参阅 Amazon IVS 回放器 SDK：Web 参考。

错误

对于一般 Video.js 错误，请在播放器上侦听通用 error 事件：


player.on("error", callback);

对于特定于 Amazon IVS 的错误，请在 Amazon IVS 播放器上侦听其自身的错误：


let playerEvent = player.getIVSEvents().PlayerEventType;
player.getIVSPlayer().addEventListener(playerEvent.ERROR, callback);

回调将接收带有以下字段的对象：

字段	描述
`type`	错误类型。对应于 `ErrorType` 事件。有关更多信息，请参阅 Amazon IVS 回放器 SDK：Web 参考。
`code`	错误代码。
`source`	错误源。
`message`	人类可读的错误消息。

插件

我们提供了一个插件，可为可用质量创建 UI 切换。要使用此插件，如果您通过以下 script 标签使用我们的技术，则必须通过包含 amazon-ivs-quality-plugin.min.js 文件来加载该插件（对于最新版本的 IVS 播放器）：


<script src="https://player.live-video.net/1.37.0/amazon-ivs-quality-plugin.min.js"></script>

如果您使用的是 npm，请导入来自 amazon-ivs-player 模块的 registerIVSQualityPlugin：


import { registerIVSQualityPlugin } from 'amazon-ivs-player';

创建 Video.js 播放器的实例后，需要执行以下调用才能进行注册并启用：


registerIVSQualityPlugin(videojs); // where videojs is the video.js variable
player.enableIVSQualityPlugin(); // where player is the instance of the videojs player

这将创建一个 UI 菜单按钮，允许您选择流的质量。

插件和 TypeScript

如果您使用的是 TypeScript，我们的 npm 软件包包含您可能需要导入并与我们的插件一起使用的 VideoJSQualityPlugin 类型。插件本质上是 mixin，因此该类型接口被用作与 VideoJSIVSTech Typescript 接口的相交类型。

内容安全策略

Amazon IVS Video.js API 配置为在使用内容安全策略 (CSP) 的页面上工作。请参阅 IVS 播放器 SDK：Web 指南中的“使用内容安全策略”章节。

函数

播放

Amazon IVS Video.js API 支持 Video.js 框架内部使用的必要接口。客户端应用程序不太可能需要直接使用这些方法，因为 Video.js 进行了必要的集成并提供了一个标准接口。但是，如果需要，访问内部 Video.js 和 Amazon IVS 播放器方法的一种方式是使用 Video.js 播放器对象获取技术所需的对象句柄。

要访问 API，请像平常一样检索 Video.js 播放器的实例：


let player = videojs("videoTagId"); //replace videoTagId with your <video> tag’s id

然后，可以在该实例上调用函数。

以下是 Amazon IVS 技术层覆盖的 Video.js 函数的子集。有关 Video.js 函数的完整列表，请参阅 video.js API 文档。

函数	描述和 Amazon IVS 特定信息
`currentTime`	获取或设置时间（以秒为单位，从开始算起）。 Amazon IVS：我们不建议为实时流设置当前时间。
`dispose`	删除播放器实例 Amazon IVS：这也会删除 Amazon IVS 技术后端。
`duration`	返回视频的持续时长（以秒为单位）。 Amazon IVS：对于实时流，这将返回 `Infinity`。
`负载`	开始加载 `src()` 数据。 Amazon IVS：无操作。
`play`	播放通过 `src` 调用设置的流。 Amazon IVS：如果实时流已暂停，则播放最新帧的实时流，而不是从暂停的位置继续播放。
`playbackRate`	获取或设置视频播放速率。1.0 表示正常速度；0.5 表示正常速度的一半；2.0 表示正常速度的两倍；依此类推。 Amazon IVS：在实时流上，get 返回 1，并忽略一个集合。
`seekable`	返回可以搜索到的媒体的 `TimeRanges`。 Amazon IVS：对于实时流，对返回值 (`TimeRange`) 调用 `end(0)` 将返回无穷大。

Amazon IVS 特定

Amazon IVS Video.js 技术具有用于访问特定于 Amazon IVS 功能的行为的附加函数：

函数	描述
`getIVSPlayer`	返回底层 Amazon IVS 播放器实例。完整的 Amazon IVS 播放器 Web API 可通过此实例获得。我们建议尽可能使用基本的 Video.js 播放 API，并仅使用此函数访问 Amazon IVS 特定的功能。您可能需要在 Amazon IVS 播放器实例上访问的最常见函数是 `setQuality()` 和 `addEventListener()` / `removeEventListener()`。
`getIVSEvents`	返回一个包含 Amazon IVS 特定枚举的对象。这用于侦听 Amazon IVS 特定错误。有关更多信息，请参阅事件和错误。

currentTime

获取或设置时间（以秒为单位，从开始算起）。

Amazon IVS：我们不建议为实时流设置当前时间。

Signatures


currentTime
currentTime(time)

参数

参数	类型	描述
`time`	数字	如果 `time` 不存在，则获取当前时间。如果 `time` 存在，则将视频播放设置为该时间。

返回值

类型	描述
number	当前时间（以秒为单位，从开始算起）。

dispose

删除播放器实例。

Amazon IVS：这也会删除 Amazon IVS 技术后端。

签名


dispose()

参数

无

返回值

无

duration

返回视频的持续时长（以秒为单位）。

Amazon IVS：对于实时流，这将返回 Infinity。

签名


duration()

参数

无

返回值

类型	描述
number	流的持续时间，以秒为单位。对于实时流，此值为 `Infinity`。

getIVSEvents

返回一个包含 Amazon IVS 特定枚举的对象。这用于侦听 Amazon IVS 特定的错误和事件。有关更多信息，请参阅：

此文档中的事件和错误。
有关事件、错误类型和错误源的详细信息，请参阅 Amazon IVS 回放器 SDK：Web 参考。

签名


getIVSEvents()

参数

无

返回值

类型	描述
`object`	具有 `PlayerEventType`、`PlayerState` 和 `ErrorType` 键的对象，这些键映射到其关联的枚举。

getIVSPlayer

返回底层 Amazon IVS 播放器实例。完整的 Amazon IVS 播放器 Web API 可通过此实例获得。我们建议尽可能使用基本的 Video.js 播放 API，并仅使用此函数访问 Amazon IVS 特定的功能。您可能需要在 Amazon IVS 播放器实例上访问的最常见函数是 setQuality() 和 addEventListener() / removeEventListener()。

签名


getIVSPlayer()

参数

无

返回值

类型	描述
`MediaPlayer`	已创建的播放器实例。

负载

开始加载 src() 数据。

Amazon IVS：无操作。

签名


load()

参数

无

返回值

无

play

播放通过 src 调用设置的流。

Amazon IVS：如果实时流已暂停，则播放最新帧的实时流，而不是从暂停的位置继续播放。

签名


play()

参数

无

返回值

无

playbackRate

获取或设置视频播放速率。1.0 表示正常速度；0.5 表示正常速度的一半；2.0 表示正常速度的两倍；依此类推。

Amazon IVS：在实时流上，get 返回 1，并忽略一个集合。

Signatures


playbackRate
playbackRate(rate)

参数

参数	类型	描述
`rate`	number	播放速率。有效值：在 [0.25, 2.0] 范围内。

返回值

类型	描述
number	播放速率。

seekable

返回可以搜索到的媒体的 TimeRanges。

Amazon IVS：对于实时流，对返回值 (TimeRange) 调用 end(0) 将返回无穷大。

签名


seekable()

参数

无

返回值

类型	描述
`TimeRange`	可用于寻找的媒体的 TimeRange。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

已知问题和解决方法

JW 播放器集成