# 開始使用 IVS Web 廣播 SDK \| 低延遲串流
<a name="broadcast-web-getting-started"></a>

本文件將帶您了解開始使用 Amazon IVS 低延遲串流功能 Web 廣播 SDK 的相關步驟。

## 安裝程式庫
<a name="broadcast-web-install"></a>

請注意，IVSBroadcastClient 使用的是 [reflect-metadata](https://www.npmjs.com/package/reflect-metadata)，這會擴充全域 Reflect 物件。雖然這不應該造成任何衝突，但在極少數的情況下，這可能會導致不需要的行為。

### 使用指令碼標籤
<a name="broadcast-web-how-to-install-script"></a>

Web 廣播開發套件以 JavaScript 程式庫的形式發佈，可以在 [https://web-broadcast.live-video.net/1.34.0/amazon-ivs-web-broadcast.js](https://web-broadcast.live-video.net/1.34.0/amazon-ivs-web-broadcast.js) 上擷取。

透過 `<script>` 標籤載入時，程式庫會在名為 `IVSBroadcastClient` 的視窗範圍中公開全域變數。

### 使用 NPM
<a name="broadcast-web-how-to-install-npm"></a>

若要安裝 `npm` 套件：

```
npm install amazon-ivs-web-broadcast
```

您現在可以存取 `IVSBroadcastClient` 物件並提取其他模組和常數，例如 `Errors`、`BASIC_LANDSCAPE`：

```
import IVSBroadcastClient, {
   Errors,
   BASIC_LANDSCAPE
} from 'amazon-ivs-web-broadcast';
```

## 範例
<a name="broadcast-web-samples"></a>

若要快速開始，請參閱下列範例：
+ [單一廣播到 IVS 頻道 (HTML 和 JavaScript)](https://codepen.io/amazon-ivs/pen/poLRoPp)
+ [帶螢幕共用單一廣播到 IVS 頻道](https://stream.ivs.rocks/) ([React 原始碼](https://github.com/aws-samples/amazon-ivs-broadcast-web-demo))

## 建立 AmazonIVSBroadcastClient 執行個體
<a name="broadcast-web-instance"></a>

若要使用程式庫，則必須建立用戶端的執行個體。使用 `streamConfig` 參數在 `IVSBroadcastClient` 上呼叫 `create` 方法 (指定廣播的限制條件，例如解析度和影格速率)，您便可以實現此目的。您可以在建立用戶端時指定擷取端點，也可以在開始串流時進行設定。

可以在 AWS Console 中找到擷取端點，也可以由 CreateChannel 操作傳回此擷取端點 (例如，UNIQUE\_ID.global-contribute.live-video.net)。

```
const client = IVSBroadcastClient.create({
   // Enter the desired stream configuration
   streamConfig: IVSBroadcastClient.BASIC_LANDSCAPE,
   // Enter the ingest endpoint from the AWS console or CreateChannel API
   ingestEndpoint: 'UNIQUE_ID.global-contribute.live-video.net',
});
```

這些是常見的支援串流組態。預設集為高達 480p 和 1.5 Mbps 位元速率的 `BASIC`，高達 1080p 和 3.5 Mbps 位元速率的 BASIC Full HD，以及高達 1080p 和 8.5 Mbps 位元速率的 `STANDARD` (或 `ADVANCED`)。如果需要，您可以自訂位元速率、影格速率和解析度。如需詳細資訊，請參閱 [BroadcastClientConfig](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/BroadcastClientConfig)。

```
IVSBroadcastClient.BASIC_LANDSCAPE;
IVSBroadcastClient.BASIC_FULL_HD_LANDSCAPE;
IVSBroadcastClient.STANDARD_LANDSCAPE;
IVSBroadcastClient.BASIC_PORTRAIT;
IVSBroadcastClient.BASIC_FULL_HD_PORTRAIT;
IVSBroadcastClient.STANDARD_PORTRAIT;
```

如果使用 `npm` 套件，您可以個別匯入這些項目。

注意：請確保用戶端組態與後端頻道類型一致。例如，如果頻道類型為 `STANDARD`，則應將 `streamConfig` 設為其中一個 `IVSBroadcastClient.STANDARD_*` 值。如果頻道類型為 `ADVANCED`，則需要手動設定組態，如下所示 (以 `ADVANCED_HD` 為例)：

```
const client = IVSBroadcastClient.create({
   // Enter the custom stream configuration
   streamConfig: {
      maxResolution: {
         width: 1080,
         height: 1920,
     },
     maxFramerate: 30,
     /**
      * maxBitrate is measured in kbps
      */
     maxBitrate: 3500,
   },
   // Other configuration . . .
});
```

## 請求權限
<a name="broadcast-web-request-permissions"></a>

您的應用程式必須請求許可，才能存取使用者的攝影機和麥克風，而您必須使用 HTTPS 為其提供服務。(這不限於 Amazon IVS；任何需要存取攝影機和麥克風的網站都必須如此。)

以下範例函數顯示如何請求和擷取音訊及影片裝置的許可：

```
async function handlePermissions() {
   let permissions = {
       audio: false,
       video: false,
   };
   try {
       const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
       for (const track of stream.getTracks()) {
           track.stop();
       }
       permissions = { video: true, audio: true };
   } catch (err) {
       permissions = { video: false, audio: false };
       console.error(err.message);
   }
   // If we still don't have permissions after requesting them display the error message
   if (!permissions.video) {
       console.error('Failed to get video permissions.');
   } else if (!permissions.audio) {
       console.error('Failed to get audio permissions.');
   }
}
```

如需詳細資訊，請參閱[許可 API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) 和 [MediaDevices.getUserMedia()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)。

## 設定串流預覽
<a name="broadcast-web-request-set-up-stream"></a>

若要預覽即將廣播的內容，請為 SDK 提供 `<canvas>` 元素。

```
// where #preview is an existing <canvas> DOM element on your page
const previewEl = document.getElementById('preview');
client.attachPreview(previewEl);
```

## 列出可用裝置
<a name="broadcast-web-request-list-devices"></a>

若要查看可以擷取的裝置，請查詢瀏覽器的 [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices) 方法：

```
const devices = await navigator.mediaDevices.enumerateDevices();
window.videoDevices = devices.filter((d) => d.kind === 'videoinput');
window.audioDevices = devices.filter((d) => d.kind === 'audioinput');
```

## 從裝置擷取 MediaStream
<a name="broadcast-web-retrieve-mediastream"></a>

取得可用裝置清單後，您就可以從任意數量的裝置中擷取串流。例如，您可以使用 `getUserMedia()` 方法來擷取攝影機的串流。

如果想指定要從哪個裝置擷取串流，您可以在媒體限制條件的 `audio` 或 `video` 區段中明確設定 `deviceId`。或者，您可以省略 `deviceId` 並讓使用者從瀏覽器提示中選取其裝置。

您也可以使用 `width` 和 `height` 限制條件指定理想的攝影機解析度。(在[此處](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#properties_of_video_tracks)閱讀有關這些限制條件的更多資訊。) SDK 會自動套用與您最大廣播解析度相對應的最大寬度和高度限制條件；不過，最好還是自行套用這些限制條件，以確保在將來源新增至 SDK 之後，來源長寬比不會遭到變更。

```
const streamConfig = IVSBroadcastClient.BASIC_LANDSCAPE;
...
window.cameraStream = await navigator.mediaDevices.getUserMedia({
   video: {
       deviceId: window.videoDevices[0].deviceId,
       width: {
           ideal: streamConfig.maxResolution.width,
       },
       height: {
           ideal: streamConfig.maxResolution.height,
       },
   },
});
window.microphoneStream = await navigator.mediaDevices.getUserMedia({
   audio: { deviceId: window.audioDevices[0].deviceId },
});
```

## 將裝置新增至串流
<a name="broadcast-web-add-device"></a>

取得串流後，您可以透過指定唯一的名稱 (即下文的 `camera1`) 和組成位置 (用於影片)，將裝置新增至版面配置。例如，透過指定網路攝影機裝置，您就可以將網路攝影機影片來源新增至廣播串流。

指定影片輸入裝置時，您必須指定索引，該索引代表要在其上進行廣播的「圖層」。這是圖像編輯或 CSS 的同義詞，其中 z-index 代表要呈現的圖層順序。或者，您可以提供位置，其會定義串流來源的 x/y 座標 (以及大小)。

如需參數的詳細資訊，請參閱 [VideoComposition](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/VideoComposition)。

```
client.addVideoInputDevice(window.cameraStream, 'camera1', { index: 0 }); // only 'index' is required for the position parameter
client.addAudioInputDevice(window.microphoneStream, 'mic1');
```

## 開始廣播
<a name="broadcast-web-start-broadcast"></a>

若要開始廣播，請為 Amazon IVS 頻道提供串流金鑰：

```
client
   .startBroadcast(streamKey)
   .then((result) => {
       console.log('I am successfully broadcasting!');
   })
   .catch((error) => {
       console.error('Something drastically failed while broadcasting!', error);
   });
```

## 停止廣播
<a name="broadcast-web-stop-broadcast"></a>

```
client.stopBroadcast();
```

## 交換影片位置
<a name="broadcast-web-swap-video-positions"></a>

用戶端支援交換影片裝置的組成位置：

```
client.exchangeVideoDevicePositions('camera1', 'camera2');
```

## 關閉音訊
<a name="broadcast-web-muting-audio"></a>

若要將音訊靜音，請使用 `removeAudioInputDevice` 移除音訊裝置，或在音軌上設定 `enabled` 屬性：

```
let audioStream = client.getAudioInputDevice(AUDIO_DEVICE_NAME);
audioStream.getAudioTracks()[0].enabled = false;
```

其中，`AUDIO_DEVICE_NAME` 是在 `addAudioInputDevice()` 呼叫期間提供給原始音訊裝置的名稱。

若要取消靜音：

```
let audioStream = client.getAudioInputDevice(AUDIO_DEVICE_NAME);
audioStream.getAudioTracks()[0].enabled = true;
```

## 隱藏影片
<a name="broadcast-web-hiding-video"></a>

若要隱藏影片，請使用 `removeVideoInputDevice` 移除影片裝置，或在影片播放軌上設定 `enabled` 屬性：

```
let videoStream = client.getVideoInputDevice(VIDEO_DEVICE_NAME).source;
videoStream.getVideoTracks()[0].enabled = false;
```

其中，`VIDEO_DEVICE_NAME` 是在原本呼叫 `addVideoInputDevice()` 時為影片裝置命名的名稱。

若要取消隱藏：

```
let videoStream = client.getVideoInputDevice(VIDEO_DEVICE_NAME).source;
videoStream.getVideoTracks()[0].enabled = true;
```