本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # GetHLSStreamingSessionURL 检索直播的 HTTP 直播 (HLS) 网址。然后，您可以在浏览器或媒体播放器中打开 URL 来查看直播内容。 `StreamName`和`StreamARN`参数都是可选的，但在调用此 API 操作`StreamARN`时必须指定`StreamName`或。 要通过 HLS 提供数据，Amazon Kinesis 视频流需要满足以下要求： + [视频播放曲目要求](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/video-playback-requirements.html)。 + 数据保留必须大于 0。 + [每个片段的视频轨道必须包含 H.264 格式的高级视频编码 (AVC) 或 H.265 格式的 HEVC（MPEG-4 规范 ISO/IEC 14496-15）中的编解码器私有数据。](https://www.iso.org/standard/55980.html)有关使流数据适应给定格式的信息，请参阅 [NAL 适应标志](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-reference-nal.html)。 + 每个片段的音轨（如果存在）必须包含 AAC 格式的编解码器私有数据（A [AC 规范 ISO/IEC ](https://www.iso.org/standard/43345.html) 13818-7）。 Kinesis Video Streams HLS 会话包含分散的 MPEG-4 形式（也称为 MP4 f 或 CMAF）或 MPEG-2 形式（也称为 TS 块，HLS 规范也支持这种片段）。有关 HLS 片段类型的更多信息，请参阅 [HLS](https://tools.ietf.org/html/draft-pantos-http-live-streaming-23) 规范。 以下过程说明如何将 HLS 与 Kinesis Video Streams 配合使用： 1. 调用 `GetDataEndpoint` API 获取终端节点。然后使用 [--endpoint-url 参数将`GetHLSStreamingSessionURL`请求发送到此端点](https://docs.aws.amazon.com/cli/latest/reference/)。 1. 使用`GetHLSStreamingSessionURL`检索 HLS 网址。Kinesis Video Streams 创建一个 HLS 直播会话，用于使用 HLS 协议访问直播中的内容。 `GetHLSStreamingSessionURL`返回会话的 HLS *主播放列表*（使用 HLS 进行直播所需的根资源）的经过身份验证的 URL（包括加密的会话令牌）。 **注意** 请勿将此令牌共享或存储在未经授权的实体可以访问的地方。该令牌提供对直播内容的访问权限。使用与 AWS 凭证相同的措施来保护令牌。 通过播放列表提供的媒体仅包含请求的直播、时间范围和格式。没有其他媒体数据（例如请求的窗口之外的帧或备用比特率）可用。 1. 向支持 HLS 协议的媒体播放器提供 HLS 主播放列表的 URL（包含加密的会话令牌）。Kinesis Video Streams 通过主播放列表网址提供 HLS 媒体播放列表、初始化片段和媒体片段。初始化片段包含流的编解码器私有数据，以及设置视频或音频解码器和渲染器所需的其他数据。媒体片段包含 H.264 编码的视频帧或 AAC 编码的音频样本。 1. 媒体播放器会收到经过身份验证的 URL，并正常请求流元数据和媒体数据。当媒体播放器请求数据时，它会调用以下操作： + **获取HLSMaster播放列表：**检索 HLS 主播放列表，其中包含每首曲目的`GetHLSMediaPlaylist`动作网址以及媒体播放器的其他元数据，包括估计的比特率和分辨率。 + **获取HLSMedia播放列表：**检索 HLS 媒体播放列表，其中包含一个网址，用于通过`GetMP4InitFragment`操作访问 MP4 初始化片段，以及使用操作 URLs 访问 MP4 媒体片段。`GetMP4MediaFragment`HLS 媒体播放列表还包含有关播放器需要播放的直播的元数据，例如是还`PlaybackMode``LIVE`是`ON_DEMAND`。对于具有以下内容的会话，HLS 媒体播放列表通常是静态`PlaybackType`的。`ON_DEMAND`HLS 媒体播放列表会不断更新，其中包含会话的新片段`PlaybackType`。`LIVE`视频轨道和包含特定曲目媒体的音轨（如果适用）都有不同的 HLS MP4 媒体 URLs 播放列表。 + **Get MP4InitFragment：**检索 MP4初始化片段。媒体播放器通常会在加载任何媒体片段之前加载初始化片段。此片段包含 `fytp` “” 和 `moov` “” MP4 原子以及初始化媒体播放器解码器所需的子原子。 初始化片段与 Kinesis 视频流中的片段不对应。它仅包含直播和相应轨道的编解码器私有数据，媒体播放器需要这些数据来解码媒体帧。 + **获取 MP4MediaFragment：**检索 MP4媒体片段。这些片段包含 `moof` “” 和 `mdat` “” MP4 原子及其子原子，包含编码片段的媒体帧及其时间戳。 **注意** 每个片段中包含的编解码器私有数据 (CPD) 包含特定于编解码器的初始化信息，例如帧速率、分辨率和编码配置文件，这些信息是正确解码片段所必需的。对于 TS 和 MP4，直播会话期间都支持更改 CPD。因此，会话中的片段可以在 CPD 中包含不同的信息，而不会中断播放。对于每个直播会话，只允许更改 500 个 CPD。 **重要** 不支持追踪更改。在所查询的媒体中，曲目必须保持一致。如果直播中的片段从只有视频变为同时包含音频和视频，或者将 AAC 音轨更改为 A-Law 音轨，则直播将失败。 通过此操作检索到的数据是可计费的。有关信息，请参阅 [ 定价](https://aws.amazon.com/kinesis/video-streams/pricing/)。 + **获取TSFragment：**检索包含直播中所有轨道的初始化和媒体数据的 MPEG TS 片段。 **注意** 如果`ContainerFormat`是`MPEG_TS`，则使用此 API 代替`GetMP4InitFragment`和`GetMP4MediaFragment`来检索流媒体。 通过此操作检索到的数据是可计费的。有关更多信息，请参阅 [Kinesis Video Streams](https://aws.amazon.com/kinesis/video-streams/pricing/) 定价。 直播会话网址不得在玩家之间共享。如果多个媒体播放器共享会话，则该服务可能会限制该会话。有关连接限制，请参阅 [Kinesis Video Streams](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html) 配额。 您可以通过监控 `GetMP4MediaFragment.OutgoingBytes` Amazon CloudWatch 指标来监控媒体播放器消耗的数据量。有关使用 CloudWatch 监控 Kinesis Video Streams 的信息，[请参阅监控 Kinesis](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/monitoring.html) 视频流。有关定价信息，请参阅 [Amazon Kinesis Video Stream](https://aws.amazon.com/kinesis/video-streams/pricing/) s 定价[AWS 和定价。](https://aws.amazon.com/pricing/)HLS 会话和传出 AWS 数据均需收费。 请参阅文档指南中的视频播放示例：[使用检索 HLS 直播会话网址 AWS CLI](hls-playback.md#retrieve-hls-url)和[示例：在 HTML 中使用 HLS 和 JavaScript](hls-playback.md#how-hls-ex1)。 有关 HLS 的更多信息，请参阅 [Apple 开发者网站上](https://developer.apple.com)的 [HTTP 直播](https://developer.apple.com/streaming/)。 **重要** 如果在调用 Kinesis Video Streams 存档媒体 API 后出现错误，则除了 HTTP 状态代码和响应正文外，还会包含以下信息： `x-amz-ErrorType`HTTP 标头 — 除了 HTTP 状态码提供的错误类型外，还包含更具体的错误类型。 `x-amz-RequestId`HTTP 标头 — 如果你想向报告问题 AWS，如果给出请求编号，支持团队可以更好地诊断问题。 HTTP 状态码和 ErrorType 标头都可用于对错误是否可重试以及在什么条件下做出编程决策，并提供有关客户端程序员可能需要采取哪些操作才能成功重试的信息。 有关更多信息，请参阅本主题底部的**错误**部分以及[常见错误](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/CommonErrors.html)。 ## 请求语法 ``` POST /getHLSStreamingSessionURL HTTP/1.1 Content-type: application/json { "ContainerFormat": "string", "DiscontinuityMode": "string", "DisplayFragmentTimestamp": "string", "Expires": number, "HLSFragmentSelector": { "FragmentSelectorType": "string", "TimestampRange": { "EndTimestamp": number, "StartTimestamp": number } }, "MaxMediaPlaylistFragmentResults": number, "PlaybackMode": "string", "StreamARN": "string", "StreamName": "string" } ``` ## URI 请求参数 该请求不使用任何 URI 参数。 ## 请求正文 请求接受采用 JSON 格式的以下数据。 ** [ContainerFormat](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 指定应使用哪种格式来包装媒体。指定`FRAGMENTED_MP4`容器格式会将媒体打包成 MP4 片段（f MP4 或 CMAF）。这是推荐的包装，因为包装开销最小。另一个容器格式选项是`MPEG_TS`。HLS 自 MPEG TS 区块发布以来一直支持，有时是旧版 HLS 播放器唯一支持的封装。MPEG TS 的封装开销通常为 5-25%。这意味着 MPEG TS 需要的带宽和成本通常比 f 多 5-25%。MP4 默认值为 `FRAGMENTED_MP4`。 类型：字符串 有效值：`FRAGMENTED_MP4 | MPEG_TS` 必需：否 ** [DiscontinuityMode](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 指定何时将标记片段之间不连续性的标记添加到媒体播放列表中。 媒体播放器通常会根据每个片段的时间戳来建立要播放的媒体内容的时间表。这意味着，如果片段之间存在任何重叠或间隙（如果设置[HLSFragmentSelector](API_reader_HLSFragmentSelector.md)为，则通常如此`SERVER_TIMESTAMP`），则媒体播放器时间轴在某些地方的片段之间也会有小间隙，并且会覆盖其他位置的帧。媒体播放器时间轴中的间隙可能会导致播放停滞，而重叠可能会导致播放抖动。当片段之间存在不连续标记时，媒体播放器应重置时间轴，从而在上一个片段之后立即播放下一个片段。 支持以下模式： + `ALWAYS`：在 HLS 媒体播放列表中的每个片段之间都放置了一个不连续标记。`ALWAYS`如果片段时间戳不准确，建议使用值。 + `NEVER`: 任何地方都没有放置不连续标记。建议使用值，`NEVER`以确保媒体播放器时间轴最准确地映射到制作者时间戳。 + `ON_DISCONTINUITY`：在间隙或重叠超过 50 毫秒的片段之间放置不连续标记。对于大多数播放场景，建议使用值，`ON_DISCONTINUITY`这样只有在媒体时间轴出现重大问题（例如缺少片段）时，才会重置媒体播放器时间轴。 默认值为`ALWAYS`何时设置[HLSFragmentSelector](API_reader_HLSFragmentSelector.md)为`SERVER_TIMESTAMP`，`NEVER`何时设置为`PRODUCER_TIMESTAMP`。 类型：字符串 有效值：`ALWAYS | NEVER | ON_DISCONTINUITY` 必需：否 ** [DisplayFragmentTimestamp](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 指定片段开始时间戳何时应包含在 HLS 媒体播放列表中。通常，媒体播放器将播放头的位置报告为相对于播放会话中第一个片段开始的时间。但是，当开始时间戳包含在 HLS 媒体播放列表中时，某些媒体播放器可能会根据片段时间戳将当前播放头报告为绝对时间。这对于创建向观众显示媒体挂钟时间的播放体验非常有用。 默认值为 `NEVER`。如果[HLSFragmentSelector](API_reader_HLSFragmentSelector.md)是`SERVER_TIMESTAMP`，则时间戳将是服务器启动时间戳。同样，如果[HLSFragmentSelector](API_reader_HLSFragmentSelector.md)是`PRODUCER_TIMESTAMP`，则时间戳将是生产者的开始时间戳。 类型：字符串 有效值：`ALWAYS | NEVER` 必需：否 ** [Expires](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 请求的会话到期之前的时间（以秒为单位）。此值可以介于 300（5 分钟）和 43200（12 小时）之间。 会话过期后，无法对该会话进行任何新的调用`GetHLSMasterPlaylist``GetHLSMediaPlaylist``GetMP4InitFragment``GetMP4MediaFragment`、、、、或`GetTSFragment`。 默认值为 300（5 分钟）。 类型：整数 有效范围：最小值为 300。最大值为 43200。 必需：否 ** [HLSFragmentSelector](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 所请求片段的时间范围和时间戳的来源。 如果为`ON_DEMAND`或，则此参数`PlaybackMode`为必填项`LIVE_REPLAY`。如果是，则此参数是可选 PlaybackMode 的```LIVE`。如果`PlaybackMode`是`LIVE`，则`FragmentSelectorType`可以设置，但`TimestampRange`不应设置。如果`PlaybackMode`为`ON_DEMAND`或`LIVE_REPLAY`，则`TimestampRange`必须同时设置`FragmentSelectorType`和。 类型：[HLSFragmentSelector](API_reader_HLSFragmentSelector.md) 对象 必需：否 ** [MaxMediaPlaylistFragmentResults](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** HLS 媒体播放列表中返回的最大片段数。 如果`PlaybackMode`为`LIVE`，则返回最新的片段，直至该值。如果`PlaybackMode`为`ON_DEMAND`，则返回最旧的片段，不超过这个最大数目。 当 HLS 直播媒体播放列表中有更多片段时，视频播放器通常会在开始播放之前缓冲内容。增加缓冲区大小会增加播放延迟，但会降低播放期间发生重新缓冲的可能性。我们建议直播的 HLS 媒体播放列表至少包含 3 个片段，最多 10 个片段。 如果为`LIVE`或，则默认为 5 个片段，如果`PlaybackMode`为`LIVE_REPLAY`，则`PlaybackMode`默认为 1,000 `ON_DEMAND`。 5,000 个片段的最大值对应于包含 1 秒片段的直播上超过 80 分钟的视频，对应于包含 10 秒片段的直播上超过 13 小时的视频。 类型：长整型 有效范围：最小值为 1。最大值为 5000。 必需：否 ** [PlaybackMode](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 是检索实时、实时重播还是存档的按需数据。 这三种类型的会话的特点包括： + **`LIVE`**：对于此类会话，HLS 媒体播放列表会不断更新最新片段。我们建议媒体播放器每隔一秒钟检索一个新的播放列表。在媒体播放器中播放此类会话时，用户界面通常会显示 “实时” 通知，没有用于在播放窗口中选择要显示的位置的滑块控件。 **注意** 在`LIVE`模式下，即使片段之间存在间隙（也就是说，如果缺少片段），最新的可用片段也会包含在 HLS 媒体播放列表中。这样的间隙可能会导致媒体播放器停止播放或导致播放跳跃。在此模式下，如果片段早于播放列表中的最新片段，则不会将其添加到 HLS 媒体播放列表中。如果在将后续片段添加到播放列表后丢失的片段变为可用，则不会添加较旧的片段，也不会填补空白。 + **`LIVE_REPLAY`**: 对于此类会话，HLS 媒体播放列表的更新方式与更新`LIVE`模式的方式类似，不同之处在于它首先包含给定开始时间的片段。片段不是在摄取时添加片段，而是在下一个片段的持续时间过去时添加片段。例如，如果会话中的片段长度为两秒，则每两秒钟就会向媒体播放列表中添加一个新片段。此模式非常有用，可以从检测到事件时开始播放，并继续直播截至会话创建时尚未收录的媒体。此模式还可用于流式传输先前存档的媒体，而不受该`ON_DEMAND`模式下 1,000 个片段限制的限制。 + **`ON_DEMAND`**：对于此类会话，HLS 媒体播放列表包含会话的所有片段，但不超过中`MaxMediaPlaylistFragmentResults`指定的数字。每个会话只能检索一次播放列表。在媒体播放器中播放此类会话时，用户界面通常会显示一个滑块控件，用于在播放窗口中选择要显示的位置。 在所有播放模式下，如果`FragmentSelectorType`是`PRODUCER_TIMESTAMP`，如果有多个片段的开始时间戳相同，则片段数最大（即最新片段）的片段将包含在 HLS 媒体播放列表中。其他片段不包括在内。具有不同时间戳但持续时间重叠的片段仍包含在 HLS 媒体播放列表中。这可能会导致媒体播放器出现意外行为。 默认值为 `LIVE`。 类型：字符串 有效值：`LIVE | LIVE_REPLAY | ON_DEMAND` 必需：否 ** [StreamARN](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 要检索 HLS 主播放列表网址的直播的亚马逊资源名称 (ARN)。 必须指定`StreamName`或`StreamARN`。 类型：字符串 长度限制：最小长度为 1。长度上限为 1024。 模式：`arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+` 必需：否 ** [StreamName](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 要检索 HLS 主播放列表网址的直播名称。 必须指定`StreamName`或`StreamARN`。 类型：字符串 长度限制：最小长度为 1。最大长度为 256。 模式：`[a-zA-Z0-9_.-]+` 必需：否 ## 响应语法 ``` HTTP/1.1 200 Content-type: application/json { "HLSStreamingSessionURL": "string" } ``` ## 响应元素 如果此操作成功，则该服务将会发送回 HTTP 200 响应。 服务以 JSON 格式返回以下数据。 ** [HLSStreamingSessionURL](#API_reader_GetHLSStreamingSessionURL_ResponseSyntax) ** 媒体播放器可用于检索 HLS 主播放列表的 URL（包含会话令牌）。 类型：字符串 ## 错误 有关所有操作的常见错误的信息，请参阅[常见错误类型](CommonErrors.md)。 ** ClientLimitExceededException ** Kinesis Video Streams 已限制该请求，因为你已超过限制。稍后再尝试拨打电话。有关限制的信息，请参阅 [Kinesis Video Streams](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html) 配额。 HTTP 状态代码：400 ** InvalidArgumentException ** 指定参数超出其限制、不受支持或无法使用。 HTTP 状态代码：400 ** InvalidCodecPrivateDataException ** 视频流中至少一条轨道中的编解码器私有数据对此操作无效。 HTTP 状态代码：400 ** MissingCodecPrivateDataException ** 在视频流的至少一条轨道中未发现编解码器的私有数据。 HTTP 状态代码：400 ** NoDataRetentionException ** `GetImages`请求的直播不保留数据（即 a `DataRetentionInHours` 为 0）。 HTTP 状态代码：400 ** NotAuthorizedException ** 状态码：403，调用者无权对给定直播执行操作，或者令牌已过期。 HTTP 状态代码：401 ** ResourceNotFoundException ** `GetImages`当 Kinesis Video Streams 找不到你指定的直播时，将引发此错误。 `GetHLSStreamingSessionURL`如果请求`PlaybackMode`的会话在请求的时间范围内`LIVE_REPLAY`没有片段，`ON_DEMAND`或者在过去 30 秒内没有片段的流请求`PlaybackMode`的`LIVE`会话为或时，则会`GetDASHStreamingSessionURL`抛出此错误。 HTTP 状态代码：404 ** UnsupportedStreamMediaTypeException ** 无法根据播放会话的第一个片段中轨道的编解码器来确定媒体的类型（例如 h.264 或 h.265 视频或 AAC IDs 或 G.711 音频）。轨道 1 的编解码器 ID 应为`V_MPEG/ISO/AVC`，轨道 2 的编解码器 ID 也应为（可选）。`A_AAC` HTTP 状态代码：400 ## 另请参阅 有关以特定语言之一使用此 API 的更多信息 AWS SDKs，请参阅以下内容： + [AWS 命令行界面 V2](https://docs.aws.amazon.com/goto/cli2/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 适用于.NET 的 SDK V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 适用于 C\$1\$1 的 SDK](https://docs.aws.amazon.com/goto/SdkForCpp/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 适用于 Go v2 的 SDK](https://docs.aws.amazon.com/goto/SdkForGoV2/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 适用于 Java 的 SDK V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS JavaScript V3 版软件开发工具包](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 适用于 Kotlin 的 SDK](https://docs.aws.amazon.com/goto/SdkForKotlin/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 适用于 PHP 的 SDK V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS Python 软件开发工具包](https://docs.aws.amazon.com/goto/boto3/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 适用于 Ruby V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForRubyV3/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL)