錄製內容儲存貯體政策 StorageConfiguration JSON 中繼資料檔案從私人儲存貯體播放錄製的內容故障診斷已知問題

複合錄製 (即時串流)

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

必要條件

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

為每個發布者建立 IVS 階段和參與者權杖。
創建一個 EncoderConfiguration（表示如何呈現錄製的視頻的對象）。
創建一個 S3 存儲桶和一個 StorageConfiguration（將存儲記錄內容的位置）。
加入並發布到階段。
當您收到「參與者已發佈」EventBridge 事件時，請StartComposition以 S3 DestinationConfiguration 物件作為目的地呼叫
幾秒鐘後，您應該能看到 HLS 片段已被保留在 S3 儲存貯體中。

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

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

以下範例顯示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 合成狀態變更 (工作階段結束)」事件之後，才播放或處理錄製的串流。如需詳細資訊，請參閱搭 EventBridge 配 IVS 即時串流使用。

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


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

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 播放器播放。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 格式。其中包含下列資訊：

欄位	類型	必要	描述
`stage_arn`	string	是	作為合成來源而使用的階段 ARN。
`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	是	此轉譯的媒體播放清單檔案名稱。
`resolution_height`	int	有條件	編碼影片的像素解析度高度。轉譯包含影片軌道時才可用。
`resolution_width`	int	有條件	編碼影片的像素解析度寬度。轉譯包含影片軌道時才可用。
`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_started_at`	string	有條件	錄製開始時，RFC 3339 UTC 時間戳記。如果 `recording_status` 為 `RECORDING_START_FAILED`，則無法使用此選項。請參閱上面的 `recording_ended_at` 備註。
`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"` 時才可用。
`version`	string	是	中繼資料結構描述的版本。

範例：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 許可政策新增至儲存貯體：

在 AWS Console 中，前往 S3 儲存貯體許可索引標籤。

複製下面的 CORS 政策，並將其粘貼到跨來源資源共用 (CORS)下。這將啟用 S3 儲存貯體上的 CORS 存取。


[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT",
            "POST",
            "DELETE",
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [
            "x-amz-server-side-encryption",
            "x-amz-request-id",
            "x-amz-id-2"
        ]
    }
]

步驟 2：建立 CloudFront 分發

請參閱CloudFront 開發人員指南中的建立發 CloudFront 行版。

使用 AWS Console 輸入以下資訊：

對於此欄位	選擇此項目
原始網域	在上一步建立的 S3 儲存貯體
原始存取	原始存取控制設定 (建議使用)，使用預設參數
預設的快取行為：檢視器通訊協定	重新引導 HTTP 到 HTTPS
預設快取行為：允許的 HTTP 方法	GET、HEAD 和 OPTIONS
預設快取行為：快取索引鍵和原始請求	CachingDisabled 政策
預設快取行為：原始要求政策	CORS-S3Origin
預設快取行為：回應標頭政策	SimpleCORS
Web 應用程式防火牆	啟用安全保護

然後保存 CloudFront 分發。

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

刪除您 StorageConfiguration 為 S3 儲存貯體設定的任何項目。這將移除為該儲存貯體建立政策時自動新增的任何儲存貯體政策。
轉到您的 CloudFront 分發，確保所有分發字段都處於上一步中定義的狀態，並複製存儲桶策略（使用複製策略按鈕）。
前往您的 S3 儲存貯體。在許可索引標籤上選取編輯儲存貯體政策，然後貼上您在上一步複製的儲存貯體政策。完成此步驟之後，值區政策應該僅具有該 CloudFront 策略。
創建一個 StorageConfiguration，指定 S3 存儲桶。

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

步驟 4：播放錄製檔

成功設定 CloudFront 發行版並更新儲存貯體政策後，您應該可以使用 IVS 播放程式播放錄製檔：

成功啟動合成，並確定您已將錄製檔存放在 S3 儲存貯體中。
在執行此範例中的步驟 1 到步驟 3 之後，視訊檔案應該可以透過 CloudFront URL 取用。您的 CloudFront URL 是 Amazon CloudFront 主控台中「詳細資料」索引標籤上的分發網域名稱。外觀大致如下：

a1b23cdef4ghij.cloudfront.net
要通過 CloudFront 分發播放錄製的視頻，請在 s3 存儲桶下找到multivariant.m3u8文件的對象密鑰。外觀大致如下：

FDew6Szq5iTt/9NIpWJHj0wPT/fjFKbylPb3k4/composite/media/hls/multivariant.m3u8
將對象鍵附加到 CloudFront URL 的末尾。您的最終 URL 大致如下：

https://a1b23cdef4ghij.cloudfront.net/FDew6Szq5iTt/9NIpWJHj0wPT/fjFKbylPb3k4/composite/media/hls/multivariant.m3u8
現在，您可以將最終 URL 新增到 IVS 播放器的來源屬性中，以觀看完整的錄製檔。若要觀看錄製的影片，您可以使用《IVS 播放器 SDK：Web 指南》當中入門裡的示範。

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

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


{
  "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"
        }
      }
    }
  ]
}

故障診斷

組合不會寫入 S3 儲存貯體 — 請確定 S3 儲存貯體和StorageConfiguration 物件已在相同區域中建立。另外，請檢查您的儲存貯體政策，確保 IVS 可以存取值區；請參閱儲存貯體政策。 StorageConfiguration
表演時我找不到合成 ListCompositions-作品是短暫的資源。一旦變更為最終狀態，就會在幾分鐘後自動刪除。
我的合成會自動停止：如果階段上超過 60 秒都沒有發布者，合成將自動停止。

已知問題

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

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

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

文件慣用形式

伺服器端合成

OBS 和鞭子 Support