IVS 個別參與者錄製 | 即時串流 - Amazon IVS

IVS 個別參與者錄製 | 即時串流

本文件說明如何搭配 IVS 即時串流使用個別參與者錄製功能。

會收取標準 S3 儲存空間和請求的成本。縮圖不會產生額外的 IVS 費用。如需詳細資訊，請參閱 Amazon IVS 定價。

簡介

個別參與者錄製允許 IVS 即時串流客戶，將 IVS 舞台發布者個別錄製到 S3 儲存貯體。啟用舞台的個別參與者錄製後，發布者開始向舞台發布內容後，就會錄製發布者內容。

注意：如果您要將所有舞台參與者混入一段影片中，則複合錄製功能會更為合適。如需錄製 IVS 即時串流內容的摘要，請參閱錄製。

工作流程

1. 建立 S3 儲存貯體

您需要 S3 儲存貯體來寫入 VOD。如需詳細資訊，請參閱 S3 文件：如何建立儲存貯體。請注意，對於個別參與者錄製，必須在與 IVS 舞台相同的 AWS 區域中建立 S3 儲存貯體。

重要事項：如果您使用現有的 S3 儲存貯體，則物件擁有權設定必須是強制執行的儲存貯體擁有者，或是偏好的儲存貯體擁有者。如需詳細資訊，請參閱 S3 文件：控制物件擁有權。

2. 建立 StorageConfiguration 物件

建立儲存貯體後呼叫 IVS 即時串流 API，以建立 StorageConfiguration 物件。成功建立儲存體組態後，IVS 將獲得許可，可寫入所提供 S3 儲存貯體。您可以將此 StorageConfiguration 物件重複用於多個舞台。

3. 建立具有參與者權杖的舞台

現在，您需要建立 IVS 舞台，並為舞台啟用個別參與者錄製 (方式是設定 AutoParticipantRecordingConfiguration 物件)，同時為每個發布者建立參與者權杖。

以下請求會建立一個具有兩個參與者權杖並啟用個別參與者錄製的舞台。



POST /CreateStage HTTP/1.1
Content-type: application/json

{
   "autoParticipantRecordingConfiguration": { 
      "mediaTypes": ["AUDIO_VIDEO"],
      "storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/AbCdef1G2hij",
      "thumbnailConfiguration": {
         "recordingMode": "INTERVAL",
         "storage": ["LATEST", "SEQUENTIAL"],
         "targetIntervalSeconds": 60
      }
   },
   "name": "TestStage",
   "participantTokenConfigurations": [ 
      { 
         "capabilities": ["PUBLISH", "SUBSCRIBE"],
         "duration": 20160,
         "userId": "1"
      },
      { 
         "capabilities": ["PUBLISH", "SUBSCRIBE"],
         "duration": 20160,
         "userId": "2"
      }
   ]
}

4. 以作用中發布者身分加入此舞台

將參與者權杖分發給發布者，讓他們加入此舞台並開始向舞台發布內容。

發布者加入此舞台並開始使用其中一個 IVS 即時串流廣播 SDK 向舞台發布內容時，參與者錄製程序會自動開始，並向您傳送 EventBridge 事件，指出錄製已開始。(此事件為「IVS 參與者錄製狀態變更 – 錄製開始」。) 同時，參與者錄製程序會開始將 VOD 和中繼資料檔案寫入設定的 S3 儲存貯體。注意：不保證會將連線持續時間極短 (少於 5 秒) 的參與者錄製下來。

有兩種方式可以取得每個錄製的 S3 字首：

接聽 EventBridge 事件：


{
   "version": "0",
   "id": "12345678-1a23-4567-a1bc-1a2b34567890",
   "detail-type": "IVS Participant Recording State Change",
   "source": "aws.ivs",
   "account": "123456789012",
   "time": "2024-03-13T22:19:04Z",
   "region": "us-east-1",
   "resources": ["arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij"],
   "detail": {
      "session_id": "st-ZyXwvu1T2s",
      "event_name": "Recording Start",
      "participant_id": "xYz1c2d3e4f",
      "recording_s3_bucket_name": "ivs-recordings",
      "recording_s3_key_prefix": "<stage_id>/<session_id>/<participant_id>/2024-01-01T12-00-55Z"
   }
}

使用 GetParticipant API 操作：此回應包含指向參與者錄製檔案位置的 S3 儲存貯體和字首。以下是請求內容：


POST /GetParticipant HTTP/1.1
Content-type: application/json
{
   "participantID": "xYz1c2d3e4f",
   "sessionId": "st-ZyXwvu1T2s",
   "stageArn": "arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij"
}

以下是回應內容：


Content-type: application/json
{
   "participant": {
      ...
      "recordingS3BucketName": "ivs-recordings",
      "recordingS3Prefix": "<stage_id>/<session_id>/<participant_id>",
      "recordingState": "ACTIVE",
      ...
   }
}

5. 播放 VOD

錄製結束後，您可以使用 IVS 播放器觀看內容。如需有關如何設定 CloudFront 分佈以進行 VOD 播放的說明，請參閱從私有儲存貯體播放錄製的內容。

純音訊錄製

設定個別參與者錄製時，可以選擇將純音訊 HLS 區段寫入 S3 儲存貯體。若要使用此功能，請在建立舞台時選擇 AUDIO_ONLY mediaType：


POST /CreateStage HTTP/1.1
Content-type: application/json

{
   "autoParticipantRecordingConfiguration": { 
      "storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/AbCdef1G2hij",
      "mediaTypes": ["AUDIO_ONLY"],
      "thumbnailConfiguration": {
         "recordingMode": "DISABLED"
      }
   },
   "name": "TestStage",
   "participantTokenConfigurations": [ 
      { 
         "capabilities": ["PUBLISH", "SUBSCRIBE"],
         "duration": 20160,
         "userId": "1"
      },
      { 
         "capabilities": ["PUBLISH", "SUBSCRIBE"],
         "duration": 20160,
         "userId": "2"
      }
   ]
}

僅限縮圖錄製

設定個別參與者錄製時，您可以選擇僅將縮圖寫入 S3 儲存貯體。若要使用此功能，請在建立階段時將 mediaType 設為 NONE。如此可確保不會有任何 HLS 區段產生；系統仍會建立縮圖並寫入您的 S3 儲存貯體。


POST /CreateStage HTTP/1.1
Content-type: application/json
{
   "autoParticipantRecordingConfiguration": { 
      "storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/AbCdef1G2hij",
      "mediaTypes": ["NONE"],
      "thumbnailConfiguration": {
         "recordingMode": "INTERVAL",
         "storage": ["LATEST", "SEQUENTIAL"],
         "targetIntervalSeconds": 60
      }
   },
   "name": "TestStage",
   "participantTokenConfigurations": [ 
      { 
         "capabilities": ["PUBLISH", "SUBSCRIBE"],
         "duration": 20160,
         "userId": "1"
      },
      { 
         "capabilities": ["PUBLISH", "SUBSCRIBE"],
         "duration": 20160,
         "userId": "2"
      }
   ]
}

錄製內容

當個別參與者錄製處於作用中狀態時，系統會開始將 HLS 影片區段、中繼資料檔案及縮圖寫入階段建立時所提供的 S3 儲存貯體。此內容可用於後續處理或作為隨需影片播放。

請注意，錄製結束後，「IVS 參與者錄製狀態會變更 – 錄製結束」事件會透過 EventBridge 傳送。建議您只在接收此事件之後播放或處理錄製的串流。如需詳細資訊，請參閱搭配 IVS 即時串流使用 EventBridge。

以下是即時 IVS 工作階段錄製的範例目錄結構和內容：


s3://mybucket/stageId/stageSessionId/participantId/timestamp
   events
      recording-started.json
      recording-ended.json
   media
      hls
	 multivariant.m3u8
         high
            playlist.m3u8
            1.mp4
      thumbnails
         high
            1.jpg
            2.jpg
      latest_thumbnail
         high
            thumb.jpg

events 資料夾包含對應於錄製事件的中繼資料檔案。JSON 中繼資料檔案會在錄製開始、成功結束或以失敗結束時產生：

events/recording-started.json
events/recording-ended.json
events/recording-failed.json

指定的 events 資料夾將包含 recording-started.json 以及 recording-ended.json 或 recording-failed.json。它們包含與錄製的工作階段及其輸出格式相關的中繼資料。JSON 的詳細資訊如下所示。

media 資料夾包含支援的媒體內容。hls 子資料夾包含錄製工作階段期間產生的所有媒體和資訊清單檔案，而且此子資料夾可以使用 IVS 播放器播放。如果已設定，thumbnails 和 latest_thumbnail 子資料夾會包含在錄製工作階段期間產生的 JPEG 縮圖媒體檔案。

JSON 中繼資料檔案

此中繼資料為 JSON 格式。其中包含下列資訊：

欄位	類型	必要	描述
`stage_arn`	string	是	錄製來源舞台 ARN。
`session_id`	string	是	字串，表示錄製的參與者所在舞台的 `session_id`。
`participant_id`	string	是	字串，表示錄製的參與者識別碼。
`recording_started_at`	string	有條件	錄製開始時，RFC 3339 UTC 時間戳記。如果 `recording_status` 為 `RECORDING_START_FAILED`，則無法使用此選項。此外，請參閱下文 `recording_ended_at` 中的備註。
`recording_ended_at`	string	有條件	錄製結束時，RFC 3339 UTC 時間戳記。當 `recording_status` 為 `"RECORDING_ENDED"` 或 `"RECORDING_ENDED_WITH_FAILURE"` 時才可用。注意：`recording_started_at` 和 `recording_ended_at` 是這些事件產生時的時間戳記，未必與 HLS 影片區段時間戳記完全一致。若要準確判斷錄製的持續時間，請使用 `duration_ms` 欄位。
`recording_status`	string	是	錄製的狀態。有效值：`"RECORDING_STARTED"`、`"RECORDING_ENDED"`、`"RECORDING_START_FAILED"`、`"RECORDING_ENDED_WITH_FAILURE"`。
`recording_status_message`	string	有條件	狀態的描述性資訊。當 `recording_status` 為 `"RECORDING_ENDED"` 或 `"RECORDING_ENDED_WITH_FAILURE"` 時才可用。
`media`	object	是	包含此錄製可用媒體內容之列舉物件的物件。有效值：`"hls"`。
`hls`	object	是	說明 Apple HLS 格式輸出的列舉欄位。
`duration_ms`	integer	有條件	錄製的 HLS 內容的持續時間，以毫秒為單位。當 `recording_status` 為 `"RECORDING_ENDED"` 或 `"RECORDING_ENDED_WITH_FAILURE"` 時才可用。如果在任何錄製完成之前發生失敗，它為 0。
`path`	string	是	儲存 HLS 內容之 S3 字首的相對路徑。
`playlist`	string	是	HLS 主播放清單檔案的名稱。
`renditions`	object	是	中繼資料物件的轉譯 (HLS 變體) 陣列。總是至少有一個轉譯。
`path`	string	是	為此轉譯儲存 HLS 內容之 S3 字首的相對路徑。
`playlist`	string	是	此轉譯的媒體播放清單檔案名稱。
`thumbnails`	object	有條件	描述縮圖輸出的列舉欄位。僅當縮圖組態的 `storage` 欄位包括 `SEQUENTIAL` 時才可用
`path`	string	是	儲存循序縮圖內容之 S3 字首的相對路徑。
`renditions`	object	是	中繼資料物件的轉譯 (縮圖變體) 陣列。總是至少有一個轉譯。
`path`	string	是	為此轉譯儲存縮圖內容之 S3 字首的相對路徑。
`latest_thumbnail`	object	有條件	描述縮圖輸出的列舉欄位。僅當縮圖組態的 `storage` 欄位包括 `LATEST` 時才可用。
`path`	string	是	儲存 `latest_thumbnail` 之 S3 字首的相對路徑。
`renditions`	object	是	中繼資料物件的轉譯 (縮圖變體) 陣列。總是至少有一個轉譯。
`path`	string	是	針對此轉譯儲存最新縮圖之 S3 字首的相對路徑。
`version`	string	是	中繼資料結構描述的版本。

範例：recording-started.json


{
   "version": "v1",
   "stage_arn": "arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij",
   "session_id": "st-ZyXwvu1T2s",
   "participant_id": "xYz1c2d3e4f",
   "recording_started_at": "2024-03-13T13:17:17Z",
   "recording_status": "RECORDING_STARTED",
   "media": {
      "hls": {
         "path": "media/hls",
         "playlist": "multivariant.m3u8",
         "renditions": [
            {
               "path": "high",
               "playlist": "playlist.m3u8"
            }
         ]
      },
      "thumbnails": {
         "path": "media/thumbnails",
         "renditions": [
            {
               "path": "high"
            }
         ]
      },
      "latest_thumbnail": {
         "path": "media/latest_thumbnail",
         "renditions": [
            {
               "path": "high"
            }
         ]
      }
   }
}

範例：recording-ended.json


{
   "version": "v1",
   "stage_arn": "arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij",
   "session_id": "st-ZyXwvu1T2s",
   "participant_id": "xYz1c2d3e4f",
   "recording_started_at": "2024-03-13T19:44:19Z",
   "recording_ended_at": "2024-03-13T19:55:04Z",
   "recording_status": "RECORDING_ENDED",
   "media": {
      "hls": {
         "duration_ms": 645237,
         "path": "media/hls",
         "playlist": "multivariant.m3u8",
         "renditions": [
            {
               "path": "high",
               "playlist": "playlist.m3u8"
            }
         ]
      },
      "thumbnails": {
         "path": "media/thumbnails",
         "renditions": [
            {
               "path": "high"
            }
         ]
      },
      "latest_thumbnail": {
         "path": "media/latest_thumbnail",
         "renditions": [
            {
               "path": "high"
            }
         ]
      }
   }
}

範例：recording-failed.json


{
   "version": "v1",
   "stage_arn": "arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij",
   "session_id": "st-ZyXwvu1T2s",
   "participant_id": "xYz1c2d3e4f",
   "recording_started_at": "2024-03-13T19:44:19Z",
   "recording_ended_at": "2024-03-13T19:55:04Z",
   "recording_status": "RECORDING_ENDED_WITH_FAILURE",
   "media": {
      "hls": {
         "duration_ms": 645237,
         "path": "media/hls",
         "playlist": "multivariant.m3u8",
         "renditions": [
            {
               "path": "high",
               "playlist": "playlist.m3u8"
            }
         ]
      },
      "thumbnails": {
         "path": "media/thumbnails",
         "renditions": [
            {
               "path": "high"
            }
         ]
      },
      "latest_thumbnail": {
         "path": "media/latest_thumbnail",
         "renditions": [
            {
               "path": "high"
            }
         ]
      }
   }
}

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

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

文件慣用形式

錄製

複合錄製

選取您的 Cookie 偏好設定

自訂 Cookie 偏好設定

必要

效能

功能

廣告

無法儲存 Cookie 偏好設定