S3 前缀录制内容字节范围播放列表缩略图合并片段化的流 JSON 元数据文件查找录制的呈现播放私有存储桶中的录制内容

自动录制到 Amazon S3（低延迟直播功能）

本节提供有关 Amazon IVS 低延迟流媒体的 auto-record-to-S3 功能的信息。我们讨论录制的 Amazon IVS 流的数据存储。并对存储内容和元数据文件架构予以说明。我们还讨论了录制内容的播放。

有关详细信息……	请参阅 ...
设置和停止视频录制	Amazon IVS 入门中的使用可选录制创建通道
API	IVS API 参考
成本	Amazon IVS 成本

S3 前缀

S3 前缀是所录制的每个实时流的唯一目录结构。实时流的所有媒体和元数据文件都写在此目录中。对于启用了录制功能的频道，S3 前缀是在直播会话开始时生成的，并将在录制开始和结束时在 CloudWatch 活动中提供。

S3 前缀采用以下格式：


/ivs/v1/<aws_account_id>/<channel_id>/<year>/<month>/<day>/<hours>/<minutes>/<recording_id>

其中：

aws_account_id 是您的 AWS 账户的 ID（在您创建 AWS 账户时生成），通过该 ID 可创建通道。
channel_id 是通道 ARN 的资源 ID 部分（Amazon Resource Name 的最后一部分）。请参阅术语表中的 ARN。
<year>/<month>/<day>/<hours>/<minutes> 是录制开始时的 UTC 时间戳。
recording_id 是为每个录制会话生成的唯一 ID。

例如：


ivs/v1/123456789012/AsXego4U6tnj/2020/6/23/20/12/j8Z9O91ndcVs

录制内容

录制开始时，视频段和元数据文件将写入为通道配置的 S3 存储桶。这些内容可用于后处理或作为按需视频播放。

请注意，直播开始并触发 “录制开始” EventBridge 事件后，需要一段时间才能写入清单文件和视频片段。我们建议仅在发送“录制结束”事件后回放或处理录制的流。（请参阅将 Amazon EventBridge 与 IVS 配合使用。）

以下是 Amazon IVS 实时会话录制的示例目录结构和内容：


ivs/v1/123456789012/AsXego4U6tnj/2020/6/23/20/12/j8Z9O91ndcVs/
   events
      recording-started.json
      recording-ended.json
   media
      hls
      thumbnails

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 包含实时会话期间生成的所有媒体和清单文件，并且可使用 Amazon IVS 播放器播放。此文件夹中有两种类型的 HLS 清单，即标准主清单 master.m3u8 和启用字节范围的清单 byte-range-multivariant.m3u8。因此，每个呈现文件夹都包含 playlist.m3u8 和一个 byte-range-variant.m3u8 文件。（请参阅下面的字节范围播放列表。）
thumbnails 包含实时会话期间生成的缩略图图像。缩略图每分钟生成并写入存储桶一次。（要更改此行为，请覆盖录制配置上的 thumbnailConfiguration 属性。）

重要提示：media 文件夹中的内容是动态生成并由第一次接收到的视频片段的特征决定的；文件夹内容可能不代表最终特征（例如，呈现质量）。不要对静态路径做任何假设。要查找可用的 HLS 呈现及其路径，请使用以下所述的 JSON 元数据文件。

字节范围播放列表

除标准的 auto-record-to HLS 播放列表外，-S3 功能还支持字节范围的播放列表生成。字节范围播放列表符合第 4 版 HLS 规范。这样可以进行更精细的内容剪辑：在字节范围播放列表中，呈现索引文件中的每个片段引用视频块的字节子范围，提供比标准的 10 秒媒体文件大小更高的粒度。对于字节范围的播放列表，片段持续时间与为流配置的关键帧间隔相同。

缩略图

借助录制配置中的 thumbnailConfiguration 属性，您可以启用或禁用直播会话的缩略图录制，并修改了可为直播会话生成缩略图的时间间隔。缩略图间隔可以从 1 秒到 60 秒不等；默认情况下，缩略图录制处于启用状态，间隔为 60 秒。有关详细信息，请参阅 Amazon IVS API 参考。

缩略图配置还可能包括 storage 字段（SEQUENTIAL 和/或 LATEST）和分辨率指标（LOWEST_RESOLUTION、SD、HD 或 FULL_HD）。以下是每个选项的分辨率：

160 <= LOWEST_RESOLUTION <= 360

360 < SD <= 480

480 < HD <= 720

720 < FULL_HD <= 1080

合并片段化的流

录制配置的 recordingReconnectWindowSeconds 属性允许您指定一个时段（以秒为单位），在此期间，如果流中断并启动了新流，Amazon IVS 会尝试录制到与上一个流相同的 S3 前缀。换句话说，如果广播断开连接，然后在指定的间隔内重新连接，则多个流将被视为单个广播并合并在一起。

IVS 在 Amazon 中录制状态更改事件 EventBridge：录制结束事件和录制结束的 JSON 元数据文件至少会延迟，因recordingReconnectWindowSeconds为 Amazon IVS 会等待确保新的直播不会启动。

有关设置合并流功能的说明，请参阅《Amazon IVS 入门》中的步骤 4：使用可选录制创建通道。

资格

要将多个流录制到相同的 S3 前缀，所有流都必须满足某些条件：

视频的宽度和高度必须相同。
帧速率必须相同。
后续流的比特率之差必须小于或等于原始流比特率的 50%。
视频和音频编解码器必须相同。

备注：

最多合并 20 个流后，系统就会创建一个新的 S3 前缀。
48 小时后，系统将创建一个新的 S3 前缀。例如，如果第一个广播持续 48 小时，并在 recordingReconnectWindowSeconds 间隔内启动另一个广播，则下一个广播不会合并到第一个 S3 前缀中。
每个流必须在上一个流完成 10 秒或更长时间后开始。

已知问题

如果 recordingReconnectWindowSeconds 已启用并使用 Web 广播 SDK，则录制到相同的 S3 前缀可能不起作用，因为 Web 广播 SDK 会动态更改比特率和质量。

JSON 元数据文件

当记录状态更改事件发生时，会生成相应的 Amazon CloudWatch 指标，并在 S3 前缀中写入元数据文件。（请参阅监控 Amazon IVS 低延迟直播功能。）

此元数据采用 JSON 格式，并包含以下信息：

字段	类型	必需	描述
`channel_arn`	字符串	是	广播实时流通道的 ARN。
`media`	对象	是	包含可用于此录制的媒体内容的枚举对象的对象。有效值：`"hls"`、`"thumbnails"`。
`hls`	对象	是	描述 Apple HLS 格式输出的枚举字段。
`duration_ms`	integer	条件	所录制 HLS 内容的时长（以毫秒为单位）。此选项仅在 `recording_status` 为 `"RECORDING_ENDED"` 或 `"RECORDING_ENDED_WITH_FAILURE"` 时可用。如果在完成任何录制之前发生故障，则该值为 0。
`path`	字符串	是	存储 HLS 内容的 S3 前缀的相对路径。
`playlist`	字符串	是	HLS 主播放列表文件的名称。
`byte_range_playlist`	字符串	是	HLS 字节范围多变体播放列表的名称。
`renditions`	对象	是	元数据对象的呈现数组（HLS 变体）。始终至少有一个呈现。
`path`	字符串	是	为此呈现存储 HLS 内容的 S3 前缀的相对路径。
`playlist`	字符串	是	此呈现的媒体播放列表文件的名称。
`byte_range_playlist`	字符串	是	此呈现的字节范围播放列表的名称。
`resolution_height`	int	条件	编码视频的像素分辨率高度。仅当呈现包含视频轨道时，此选项才可用。
`resolution_width`	int	条件	编码视频的像素分辨率宽度。仅当呈现包含视频轨道时，此选项才可用。
`thumbnails`	object	条件	描述缩略图输出的枚举字段。仅当缩略图配置的 `recordingMode` 为 `INTERVAL` 时才可用。
`path`	字符串	条件	存储缩略图内容的 S3 前缀的相对路径。仅当缩略图配置的 `recordingMode` 为 `INTERVAL` 时才可用。
`resolution_height`	int	是	缩略图的高度。默认值：源渲染的分辨率。该值受相关录制配置中的用户输入影响；具体来说，是 `thumbnailConfiguration.resolution` 值。
`resolution_width`	int	是	缩略图的宽度。默认值：源渲染的分辨率。该值受相关录制配置中的用户输入影响；具体来说，是 `thumbnailConfiguration.resolution` 值。
`latest thumbnail`	对象	是	描述最新缩略图输出的枚举字段。仅当缩略图配置的 `storage` 包含 `LATEST` 时才可用。
`resolution_height`	int	是	缩略图的高度。默认值为源渲染的分辨率。该值受相关录制配置中的用户输入影响；具体来说，是 `thumbnailConfiguration.resolution` 值。
`resolution_width`	int	是	缩略图的宽度。默认值为源渲染的分辨率。该值受相关录制配置中的用户输入影响；具体来说，是 `thumbnailConfiguration.resolution` 值。
`recording_ended_at`	字符串	条件	录制结束时的 RFC 3339 UTC 时间戳。此选项仅在 `recording_status` 为 `"RECORDING_ENDED"` 或 `"RECORDING_ENDED_WITH_FAILURE"` 时可用。 `recording_started_at` 和 `recording_ended_at` 是这些事件生成时的时间戳，可能与 HLS 视频片段的时间戳不完全一致。要准确确定录制的持续时间，请使用 `duration_ms` 字段。
`recording_started_at`	字符串	是	录制开始时的 RFC 3339 UTC 时间戳。请参阅上面有关 `recording_ended_at` 的注释。
`recording_status`	字符串	是	录制的状态。有效值：`"RECORDING_STARTED"`、`"RECORDING_ENDED"`、`"RECORDING_ENDED_WITH_FAILURE"`。
`recording_status_message`	字符串	条件	状态的描述性信息。此选项仅在 `recording_status` 为 `"RECORDING_ENDED"` 或 `"RECORDING_ENDED_WITH_FAILURE"` 时可用。
`version`	字符串	是	元数据架构的版本。

示例：recording_started.json


{
   "version" : "v1",
   "channel_arn" : "arn:aws:ivs:us-west-2:123456789012:channel/AsXego4U6tnj",
   "recording_started_at" : "2020-06-12T12:53:26Z",
   "recording_status : "RECORDING_STARTED",
   "media" : {
      "hls" : {
         "path" : "media/hls",
         "playlist" : "master.m3u8",
         "byte_range_playlist": "byte-range-multivariant.m3u8",
         "renditions" : [
            {
               "path" : "480p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 480,
               "resolution_width" : 852
            },
            {
               "path" : "360p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 360,
               "resolution_width" : 640
            },
            {
               "path" : "160p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 160,
               "resolution_width" : 284
            },
            {
               "path" : "720p60",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 720,
               "resolution_width" : 1280
            }
         ]
      },
      "thumbnails": {
         "path": "media/thumbnails",
         "resolution_height": 480,
         "resolution_width": 852
      },
      "latest_thumbnail": {
         "path": "media/latest_thumbnail/thumb.jpg",
         "resolution_height": 480,
         "resolution_width": 852
      }
   }
}

示例：recording_ended.json


{
   "version" : "v1",
   "channel_arn" : "arn:aws:ivs:us-west-2:123456789012:channel/AsXego4U6tnj",
   "recording_ended_at" : "2020-06-14T12:53:20Z",
   "recording_started_at" : "2020-06-12T12:53:26Z",
   "recording_status" : "RECORDING_ENDED",
   "media" : {
      "hls" : {
         "duration_ms" : 172794489,
         "path" : "media/hls",
         "playlist" : "master.m3u8",
         "byte_range_playlist": "byte-range-multivariant.m3u8",
         "renditions" : [
            {
               "path" : "480p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 480,
               "resolution_width" : 852
            },
            {
               "path" : "360p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 360,
               "resolution_width" : 640
            },
            {
               "path" : "160p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 160,
               "resolution_width" : 284
            },
            {
               "path" : "720p60",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 720,
               "resolution_width" : 1280
            }
         ]
      },
      "thumbnails": {
         "path": "media/thumbnails",
         "resolution_height": 480,
         "resolution_width": 852
      },
      "latest_thumbnail": {
         "path": "media/latest_thumbnail/thumb.jpg",
         "resolution_height": 480,
         "resolution_width": 852
      }
   }
}

示例：recording_failed.json


{
   "version" : "v1",
   "channel_arn" : "arn:aws:ivs:us-west-2:123456789012:channel/AsXego4U6tnj",
   "recording_ended_at" : "2020-06-14T12:53:20Z",
   "recording_started_at" : "2020-06-12T12:53:26Z",
   "recording_status" : "RECORDING_ENDED",
   "media" : {
      "hls" : {
         "duration_ms" : 172794489,
         "path" : "media/hls",
         "playlist" : "master.m3u8",
         "byte_range_playlist": "byte-range-multivariant.m3u8",
         "renditions" : [
            {
               "path" : "480p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 480,
               "resolution_width" : 852
            },
            {
               "path" : "360p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 360,
               "resolution_width" : 640
            },
            {
               "path" : "160p30",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 160,
               "resolution_width" : 284
            },
            {
               "path" : "720p60",
               "playlist" : "playlist.m3u8",
               "byte_range_playlist": "byte-range-variant.m3u8",
               "resolution_height" : 720,
               "resolution_width" : 1280
            }
         ]
      },
      "thumbnails": {
         "path": "media/thumbnails",
         "resolution_height": 480,
         "resolution_width": 852
      },
      "latest_thumbnail": {
         "path": "media/latest_thumbnail/thumb.jpg",
         "resolution_height": 480,
         "resolution_width": 852
      }
   }
}

查找录制的呈现

当您将内容流式传输到 Amazon IVS 频道时， auto-record-to-s3 会使用源视频生成多个格式副本。通过使用自适应比特率流 (ABR)，Amazon IVS 播放器会根据需要自动切换呈现（比特率），以优化不同网络条件下的播放效果。

在实时流式处理过程中生成的每个呈现都录制在 S3 录制前缀内的唯一路径中。在录制开始和停止期间，分辨率详细信息、路径和播放列表文件名会存储在 JSON 元数据文件中。如果录制配置的 renditionSelection 值是 ALL，则选择所有渲染进行录制。如果 renditionSelection 为 CUSTOM，用户必须选择以下一个或多个选项：LOWEST_RESOLUTION、SD、HD 以及 FULL_HD。以下是每个选项的分辨率：

160 <= LOWEST_RESOLUTION <= 360

360 < SD <= 480

480 < HD <= 720

720 < FULL_HD <= 1080

重要提示：不要对静态呈现路径或生成的呈现列表做任何假设，因为这些信息可能会变化。不要假定特定呈现始终可用于 Amazon IVS 录制。要确定可用的呈现、分辨率和路径，请参阅元数据文件。

录制前缀中的 event/recording_started.json 或 event/recording_ended.json 文件包含录制前缀中媒体文件的路径和名称。所有 path 元素均相对于层次结构中的上一个路径。media > hls 下的元素描述了 HLS 资产，并在此级别定义了主播放列表名称和路径。

下面是一个 Python 代码片段，显示如何使用 S3 录制前缀和元数据文件生成主播放列表路径：


def get_master_playlist(metadata_json, s3_recording_prefix):
   return s3_recording_prefix + '/' + metadata_json['media']['hls']['path'] + '/' + metadata_json['media']['hls']['playlist']

media > hls > renditions 下的元素描述所录制呈现的列表。resolution_height 和 resolution_width 属性可用于确定视频分辨率。path 和 playlist 元素可用于派生呈现播放列表路径。使用这些字段可确定要使用哪个呈现进行任何后处理。

要发现录制文件的最高可用再现播放列表，您可以订阅 “IVS 录制状态更改” 事件。 EventBridge （请参见将 Amazon EventBridge 与 IVS 配合使用。）下面是一个示例 Python 脚本，演示如何使用订阅这些事件的 lambda 函数。


import json
import boto3
s3 = boto3.resource('s3')

def get_highest_rendition_playlist(bucket_name, prefix_name):
   object_path = "{}/events/recording-started.json".format(prefix_name)
   object = s3.Object(bucket_name, object_path)
   body = str(object.get()['Body'].read().decode('utf-8'))
   metadata = json.loads(body)
   media_path = metadata["media"]["hls"]["path"]
   renditions = metadata["media"]["hls"]["renditions"]

   highest_rendition = None
   highest_rendition_size = 0

   for rendition in renditions:
       current_rendition_size = rendition["resolution_height"]
       if (current_rendition_size > highest_rendition_size):
           highest_rendition_size = current_rendition_size
           highest_rendition = rendition

   highest_rendition_playlist = media_path + '/' + highest_rendition['path'] + '/' + highest_rendition['playlist']
   return highest_rendition_playlist


def lambda_handler(event, context):
   prefix_name = event["detail"]["recording_s3_key_prefix"]
   bucket_name = event["detail"]["recording_s3_bucket_name"]
   rendition_playlist = get_highest_rendition_playlist(bucket_name, prefix_name)
   print("Highest rendition playlist: {}/{}".format(prefix_name, rendition_playlist))

   return {
       'statusCode': 200,
       'body': rendition_playlist
   }

播放私有存储桶中的录制内容

默认情况下，使用“自动录制到 Amazon S3”功能录制的对象为私有；因此，使用直接 S3 URL 无法访问这些对象。如果您尝试使用 Amazon IVS 播放器或其他播放器打开 HLS 主清单（m3u8 文件）进行播放，您将收到错误信息（例如，“您无权访问请求的资源”）。相反，您可以使用 Amazon CloudFront CDN（内容分发网络）播放这些文件。

亚马逊 CloudFront 配送

CloudFront 可以将发行版配置为提供来自私有存储桶的内容。通常，这比拥有可公开访问的存储桶更可取，在这种存储桶中，读取可以绕过提供的 CloudFront控件。通过创建源访问控制 (OAC)，可以将您的分配设置为从私有存储桶提供服务，该访问控制是具有私有源存储桶读取权限的特殊 CloudFront 用户。您可以在创建发行版之后通过 CloudFront 控制台或 API 创建 OAC。请参阅创建新的源访问控制。

从亚马逊播放 CloudFront

使用 OAC 设置发行版以访问私有存储桶后，您的视频文件应该可以通过 CloudFront URL 进行使用。您的 CloudFront URL 是 AWS CloudFront 控制台详细信息选项卡上的分发域名。它应该如下所示：

a1b23cdef4ghij.cloudfront.net.

若要通过分配对录制的视频进行流式传输，请查找 master.m3u8 文件的对象键。它应该如下所示：


ivs/v1/012345678912/a0bCDeFGH1IjK/2021/4/20/12/03/aBcdEFghIjkL/media/hls/master.m3u8

将对象密钥附加到 CloudFront 网址的末尾。您的最终 URL 如下所示：


https://a1b23cdef4ghij.cloudfront.net/ivs/v1/012345678912/a0bCDeFGH1IjK/2021/4/20/12/03/aBcdEFghIjkL/media/hls/master.m3u8

要通过 Web 浏览器进行播放，请确保在两者 CloudFront和 S3 存储桶中都配置 CORS。要进行 CloudFront 配置，请按照创建源请求策略中的说明将 CORS-S3 Origin 请求策略和 SimpleCors 响应标头策略附加到分配中 CloudFront 。请参阅以下示例配置控制台页面：

有关 S3 CORS 配置，请参阅 CORS 配置，为您的 S3 存储桶创建相应的规则。

现在，您可以播放录制的视频，就像直接从存储桶播放一样。

有关更多信息，请参阅限制对 Amazon S3 源的访问。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

撤消查看者会话

将 Amazon EventBridge 与 IVS 配合使用