開始事件錯誤外掛程式內容安全政策函數 currentTime dispose 持續時間 getIVSEvents getIVSPlayer 載入播放 playbackRate seekable

Amazon IVS 播放器 SDK：Video.js 整合

本文件說明 Amazon Interactive Video Service (IVS) Video.js 播放器中可用的最重要功能。

Video.js 播放程式整合的最新版本：1.24.0 (版本資訊)

開始

透過 Video.js 技術，實現 Amazon IVS 對 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.24.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.24.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 播放器開發套件：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 播放器開發套件：Web 參考。
`code`	錯誤代碼。
`source`	錯誤來源。
`message`	人類可讀的錯誤訊息。

外掛程式

我們提供了一個外掛程式，它为可用品質建立一個 UI 切換。要使用此外掛程式，如果您正在透過下面的 script 標記使用我們的技術，則必須透過包含 amazon-ivs-quality-plugin.min.js 檔案來載入它 (適用於 IVS 播放器的最新版本)：


<script src="https://player.live-video.net/1.24.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類型。外掛程式本質上是 mixins，所以這種類型的界面作為交集類型與 VideoJSIVSTech TypeScript 界面搭配使用。

內容安全政策

Amazon IVS Video.js API 設定為可在使用內容安全政策 (CSP) 的頁面上運作。請參閱 Amazon 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 技術後端。
`持續時間`	傳回影片的持續時間 (以秒為單位)。 Amazon IVS：對於即時串流，這會傳回 `Infinity`。
`載入`	開始載入 `src()` 資料。 Amazon IVS：這是無操作。
`播放`	播放透過 `src` 呼叫設定的串流。 Amazon IVS：如果暫停了即時串流，會從最新影格播放即時串流，而不是從暫停的位置繼續播放。
`playbackRate`	獲取或設定影片播放速率。1.0 表示正常速度；0.5 表示一半正常速度；2.0 表示兩倍正常速度；依此類推。 Amazon IVS：在即時串流中，get 會傳回 1，並忽略 set。
`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：我們不建議設定即時串流的目前時間。

簽章


currentTime
currentTime(time)

參數

參數	類型	描述
`time`	數字	如果 `time` 不存在，則會取得目前時間。如果 `time` 存在，會將影片播放設定為該時間。

傳回值

類型	描述
數字	目前的時間，以秒為單位從頭開始。

dispose

刪除播放器執行個體。

Amazon IVS：這也會刪除 Amazon IVS 技術後端。

簽章


dispose()

參數

無

傳回值

無

持續時間

傳回影片的持續時間 (以秒為單位)。

Amazon IVS：對於即時串流，這會傳回 Infinity。

簽章


duration()

參數

無

傳回值

類型	描述
數字	串流的持續時間 (以秒為單位)。對於即時串流，此值為 `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()

參數

無

傳回值

無

播放

播放透過 src 呼叫設定的串流。

Amazon IVS：如果暫停了即時串流，會從最新影格播放即時串流，而不是從暫停的位置繼續播放。

簽章


play()

參數

無

傳回值

無

playbackRate

獲取或設定影片播放速率。1.0 表示正常速度；0.5 表示一半正常速度；2.0 表示兩倍正常速度；依此類推。

Amazon IVS：在即時串流中，get 會傳回 1，並忽略 set。

簽章


playbackRate
playbackRate(rate)

參數

參數	類型	描述
`rate`	數字	播放速率。有效值：範圍為 [0.25, 2.0]。

傳回值

類型	描述
數字	播放速率。

seekable

傳回可搜尋的媒體的 TimeRanges。

Amazon IVS：對於即時串流，呼叫傳回值 (TimeRange) 上的 end(0) 會傳回無限。

簽章


seekable()

參數

無

傳回值

類型	描述
`TimeRange`	TimeRange 可供尋求的媒體。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

已知問題和解決方法

JW 播放器整合