IVS 複合錄製 | 即時串流

本文件說明如何在伺服器端合成中使用複合錄製功能。複合錄製可讓您產生 IVS 階段的 HLS 錄製檔，方法是使用 IVS 伺服器將所有階段發布者有效地合併至一個檢視，然後將產生的影片儲存到 S3 儲存貯體。

必要條件

若要使用複合錄製，您必須具有包含作用中發布者的舞台，並使用 S3 儲存貯體作為錄製目的地。下面我們描述了一種使用 EventBridge 事件將合成錄製到 S3 儲存貯體的可能工作流程。您也可以根據自己的應用程式邏輯啟動和停止合成。

注意：在階段上的發布者參與者閒置 60 秒後，合成會執行自動關閉。此時，合成會終止並轉換為 STOPPED 狀態。合成會在保持 STOPPED 狀態幾分鐘後自動刪除。如需詳細資訊，請參閱「伺服器端合成」中的合成生命週期。

複合錄製範例：以 S3 儲存貯體為目的地的 StartComposition

下列範例顯示對 StartComposition 端點的典型呼叫，並將 S3 指定為合成的唯一目的地。只要合成變更為 ACTIVE 狀態，影片片段和中繼資料就會開始寫入 storageConfiguration 物件指定的 S3 儲存貯體。若要建立具有不同配置的合成，請參閱伺服器端合成中的「版面配置」和 IVS Real-Time Streaming API Reference。

請求

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

{
   "destinations": [
      {
         "s3": {
            "encoderConfigurationArns": [
              "arn:aws:ivs:ap-northeast-1:927810967299:encoder-configuration/PAAwglkRtjge"
            ],
            "storageConfigurationArn": "arn:aws:ivs:ap-northeast-1:927810967299:storage-configuration/ZBcEbgbE24Cq"
         }
      }
   ],
   "idempotencyToken": "db1i782f1g9",
   "stageArn": "arn:aws:ivs:ap-northeast-1:927810967299:stage/WyGkzNFGwiwr"
}

回應

{
    "composition": {
        "arn": "arn:aws:ivs:ap-northeast-1:927810967299:composition/s2AdaGUbvQgp",
        "destinations": [
            {
                "configuration": {
                    "name": "",
                    "s3": {
                        "encoderConfigurationArns": [
                            "arn:aws:ivs:ap-northeast-1:927810967299:encoder-configuration/PAAwglkRtjge"
                        ],
                        "recordingConfiguration": {
                            "format": "HLS"
                        },
                        "storageConfigurationArn": "arn:aws:ivs:ap-northeast-1:927810967299:storage-configuration/ZBcEbgbE24Cq"
                    }
                },
                "detail": {
                    "s3": {
                        "recordingPrefix": "MNALAcH9j2EJ/s2AdaGUbvQgp/2pBRKrNgX1ff/composite"
                    }
                },
                "id": "2pBRKrNgX1ff",
                "state": "STARTING"
            }
        ],
        "layout": null,
        "stageArn": "arn:aws:ivs:ap-northeast-1:927810967299:stage/WyGkzNFGwiwr",
        "startTime": "2023-11-01T06:25:37Z",
        "state": "STARTING",
        "tags": {}
    }
}

出現在 StartComposition 回應中的 recordingPrefix 欄位可用來決定複製內容的儲存位置。

錄製內容

當合成轉換到 ACTIVE 狀態時，您將開始看到 HLS 影片片段和中繼資料檔案寫入到呼叫 StartComposition 時提供的 S3 儲存貯體。這些內容可用於後續處理或作為隨需影片播放。

請注意，合成上線之後，即會發出「IVS 合成狀態變更」事件，並且可能需要一點時間才能寫入清單檔案和影片片段。建議您只在收到「IVS 合成狀態變更 (工作階段結束)」事件之後，才播放或處理錄製的串流。如需詳細資訊，請參閱搭配 IVS 即時串流使用 EventBridge。

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

MNALAcH9j2EJ/s2AdaGUbvQgp/2pBRKrNgX1ff/composite
   events
      recording-started.json
      recording-ended.json
   media
      hls

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

指定的 events 資料夾將包含 recording-started.json 以及 recording-ended.json 或 recording-failed.json。

它們包含與錄製的工作階段及其輸出格式相關的中繼資料。JSON 的詳細資訊如下所示。

media 資料夾包含支援的媒體內容。hls 子資料夾包含合成工作階段期間產生的所有媒體和清單檔案，並且可以使用 IVS 播放器播放。HLS 清單檔案位於 multivariant.m3u8 資料夾中。

StorageConfiguration 的儲存貯體政策

建立 StorageConfiguration 物件時，IVS 會取得將內容寫入指定 S3 儲存貯體的存取權。該存取權透過修改 S3 儲存貯體的政策來授予。如果以移除 IVS 存取權的方式變更儲存貯體的政策，則進行中和新的錄製將會失敗。

以下範例顯示允許 IVS 寫入 S3 儲存貯體的 S3 儲存貯體政策：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CompositeWrite-y1d212y",
            "Effect": "Allow",
            "Principal": {
                "Service": "ivs-composite.ap-northeast-1.amazonaws.com"
            },
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::my-s3-bucket/*",
            "Condition": {
                "StringEquals": {
                    "s3:x-amz-acl": "bucket-owner-full-control"
                },
                "Bool": {
                    "aws:SecureTransport": "true"
                }
            }
        }
    ]
}

JSON 中繼資料檔案

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

範例：recording-started.json

{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-11-01T06:01:36Z",
  "recording_status": "RECORDING_STARTED",
  "media": {
    "hls": {
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

範例：recording-ended.json

{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-10-27T17:00:44Z",
  "recording_ended_at": "2023-10-27T17:08:24Z",
  "recording_status": "RECORDING_ENDED",
  "media": {
    "hls": {
      "duration_ms": 460315,
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

範例：recording-failed.json

{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-10-27T17:00:44Z",
  "recording_ended_at": "2023-10-27T17:08:24Z",
  "recording_status": "RECORDING_ENDED_WITH_FAILURE",
  "media": {
    "hls": {
      "duration_ms": 460315,
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

從私人儲存貯體播放錄製的內容

預設情況下，錄製內容為私有；因此，直接使用 S3 URL 無法存取這些物件。如果您嘗試使用 IVS 播放器或其他播放器開啟 HLS 多重變數播放清單 (m3u8 檔案) 進行播放，就會收到錯誤訊息 (例如「您沒有存取所請求資源的許可」)。不過，您可以使用 Amazon CloudFront CDN (內容交付網路) 播放這些檔案。

CloudFront 分佈可設定為從私有儲存貯體提供內容。普遍情況下，這比擁有可開放存取的儲存貯體來繞過 CloudFront 提供的控制項更好。您可以設定分佈，透過建立原始存取控制 (OAC) 從私有儲存貯體提供服務；該身分是對私有來源儲存貯體具有讀取許可的特殊 CloudFront 使用者。您可以在建立分發之後，透過 CloudFront 主控台或 API 建立 OAC。請參閱《Amazon CloudFront 開發人員指南》中的建立新的原始存取控制。

在啟用 CORS 的情況下使用 CloudFront 設定播放

此範例說明開發人員如何在啟用 CORS 的情況下設定 CloudFront 分佈，以便從任何網域播放錄製檔。這在開發階段特別有用，但您可以修改以下範例以符合生產需求。

步驟 1：建立 S3 儲存貯體

建立將用來存放錄製檔的 S3 儲存貯體。請注意，儲存貯體必須位在您用於 IVS 工作流程的相同區域中。

將 CORS 許可政策新增至儲存貯體：

步驟 2：建立 CloudFront 分佈

請參閱《CloudFront 開發人員指南》中的建立 CloudFront 分佈。

使用 AWS Console 輸入以下資訊：

然後儲存 CloudFront 分佈。

步驟 3：設定 S3 儲存貯體政策

建立 StorageConfiguration 之後，您會在 S3 儲存貯體政策中看到兩個項目，一個允許 CloudFront 讀取內容，另一個允許 IVS 寫入內容。在範例：具備 CloudFront 和 IVS 存取權的 S3 儲存貯體政策部分中，顯示了具有 CloudFront 和 IVS 存取權的最終儲存貯體政策範例。

步驟 4：播放錄製檔

成功設定 CloudFront 分佈並更新儲存貯體政策之後，您應該可以使用 IVS 播放器播放錄製檔：

範例：具備 CloudFront 和 IVS 存取權的 S3 儲存貯體政策

下面的程式碼片段描繪了一段 S3 儲存貯體政策，該政策允許 CloudFront 將內容讀取到私有儲存貯體，允許 IVS 將內容寫入儲存貯體。注意：請勿將下面的程式碼片段複製並貼上到自己的儲存貯體中。您的政策應包含與自己 CloudFront 分佈和 StorageConfiguration 相關的 ID。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CompositeWrite-7eiKaIGkC9DO",
      "Effect": "Allow",
      "Principal": {
        "Service": "ivs-composite.ap-northeast-1.amazonaws.com"
      },
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::eicheane-test-1026-2-ivs-recordings/*",
      "Condition": {
        "StringEquals": {
          "s3:x-amz-acl": "bucket-owner-full-control"
        },
        "Bool": {
          "aws:SecureTransport": "true"
        }
      }
    },
    {
      "Sid": "AllowCloudFrontServicePrincipal",
      "Effect": "Allow",
      "Principal": {
        "Service": "cloudfront.amazonaws.com"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::eicheane-test-1026-2-ivs-recordings/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::844311324168:distribution/E1NG4YMW5MN25A"
        }
      }
    }
  ]
}

故障診斷

已知問題

在合成進行時，透過複合錄製寫入的媒體播放清單擁有 #EXT-X-PLAYLIST-TYPE:EVENT 標籤。合成完成後，標籤會更新為 #EXT-X-PLAYLIST-TYPE:VOD。為了獲得流暢的播放體驗，我們建議您只在成功完成合成後使用此播放清單。