本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
GetHLSStreamingSessionURL
检索直播的 HTTP 直播 (HLS) 网址。然后,您可以在浏览器或媒体播放器中打开 URL 来查看直播内容。
StreamName
和StreamARN
参数都是可选的,但在调用此 API 操作StreamARN
时必须指定StreamName
或。
要通过 HLS 提供数据,Amazon Kinesis 视频流需要满足以下要求:
-
数据保留必须大于 0。
-
每个片段的视频轨道必须包含 H.264 格式的高级视频编码 (AVC) 或 H.265 格式的 HEVC(MPEG-4 规范 ISO/IEC 14496-15)中的编解码器私有数据。
有关使流数据适应给定格式的信息,请参阅 NAL 适应标志。 -
每个片段的音轨(如果存在)必须包含 AAC 格式的编解码器私有数据(AAC 规范 ISO/IEC 13818
-7)。
Kinesis Video Streams HLS 会话包含分散的 MPEG-4 形式(也称为 fmP4 或 CMAF)或 MPEG-2 形式(也称为 TS 块,HLS 规范也支持这种片段)。有关 HLS 片段类型的更多信息,请参阅 HLS
以下过程说明如何将 HLS 与 Kinesis Video Streams 配合使用:
-
调用
GetDataEndpoint
API 获取终端节点。然后使用 --endpoint-url 参数将GetHLSStreamingSessionURL
请求发送到此端点。 -
使用
GetHLSStreamingSessionURL
检索 HLS 网址。Kinesis Video Streams 创建一个 HLS 直播会话,用于使用 HLS 协议访问直播中的内容。GetHLSStreamingSessionURL
返回会话的 HLS 主播放列表(使用 HLS 进行直播所需的根资源)的经过身份验证的 URL(包括加密的会话令牌)。注意
请勿将此令牌共享或存储在未经授权的实体可以访问的地方。该令牌提供对直播内容的访问权限。使用与 Amazon 凭证相同的措施来保护令牌。
通过播放列表提供的媒体仅包含请求的直播、时间范围和格式。没有其他媒体数据(例如请求的窗口之外的帧或备用比特率)可用。
-
向支持 HLS 协议的媒体播放器提供 HLS 主播放列表的 URL(包含加密的会话令牌)。Kinesis Video Streams 通过主播放列表网址提供 HLS 媒体播放列表、初始化片段和媒体片段。初始化片段包含流的编解码器私有数据,以及设置视频或音频解码器和渲染器所需的其他数据。媒体片段包含 H.264 编码的视频帧或 AAC 编码的音频样本。
-
媒体播放器会收到经过身份验证的 URL,并正常请求流元数据和媒体数据。当媒体播放器请求数据时,它会调用以下操作:
-
getHLSMasterPlaylist:检索 HLS 主播放列表,其中包含每首曲目的
GetHLSMediaPlaylist
动作网址以及媒体播放器的其他元数据,包括估计的比特率和分辨率。 -
getHLSMediaPlaylist:检索 HLS 媒体播放列表,其中包含用于通过操作访问 MP4 初始化片段的网址,以及用于通过
GetMP4InitFragment
操作访问 MP4 媒体片段的网址。GetMP4MediaFragment
HLS 媒体播放列表还包含有关播放器需要播放的直播的元数据,例如是还PlaybackMode
LIVE
是ON_DEMAND
。对于具有以下内容的会话,HLS 媒体播放列表通常是静态PlaybackType
的。ON_DEMAND
HLS 媒体播放列表会不断更新,其中包含会话的新片段PlaybackType
。LIVE
视频曲目和音轨(如果适用)有一个不同的 HLS 媒体播放列表,其中包含特定曲目的 MP4 媒体网址。 -
getMP4InitFragment:检索 MP4 初始化片段。媒体播放器通常会在加载任何媒体片段之前加载初始化片段。此片段包含 “
fytp
” 和 “moov
” MP4 原子,以及初始化媒体播放器解码器所需的子原子。初始化片段与 Kinesis 视频流中的片段不对应。它仅包含直播和相应轨道的编解码器私有数据,媒体播放器需要这些数据来解码媒体帧。
-
获取 MP4MediaFragment:检索 MP4 媒体片段。这些片段包含 “
moof
” 和 “mdat
” MP4 原子及其子原子,包含编码片段的媒体帧及其时间戳。注意
对于 HLS 直播会话,支持更改轨内编解码器私有数据 (CPD)。在直播会话中提供第一个媒体片段后,片段可以包含每首曲目的 CPD 更改。因此,会话中的片段在 CPD 中可能具有不同的分辨率、比特率或其他信息,而不会中断播放。但是,加载这些不同的媒体片段时,对曲目编解码器或曲目编解码器格式所做的任何更改都可能返回错误。例如,如果流中的片段从只有视频变为同时包含音频和视频,或者将 AAC 音轨更改为 ALAW 音轨,则直播将失败。对于每个直播会话,只允许更改 500 个 CPD。
通过此操作检索到的数据是可计费的。有关信息,请参阅 定价
。 -
GettsFragment:检索包含直播中所有曲目的初始化和媒体数据的 MPEG TS 片段。
注意
如果
ContainerFormat
是MPEG_TS
,则使用此 API 代替GetMP4InitFragment
和GetMP4MediaFragment
来检索流媒体。通过此操作检索到的数据是可计费的。有关更多信息,请参阅 Kinesis Video Streams
定价。
-
直播会话网址不得在玩家之间共享。如果多个媒体播放器共享会话,该服务可能会限制该会话。有关连接限制,请参阅 Kinesis Video Stream s 限制。
您可以通过监控 GetMP4MediaFragment.OutgoingBytes
Amazon CloudWatch 指标来监控媒体播放器消耗的数据量。有关使用 CloudWatch 监控 Kinesis Video Streams 的信息,请参阅监控 Kinesis 视频流。有关定价信息,请参阅亚马逊 Kinesis Video Stream
有关 HLS 的更多信息,请参阅 Apple 开发者网站上
重要
如果在调用 Kinesis Video Streams 存档媒体 API 后出现错误,则除了 HTTP 状态代码和响应正文外,还会包含以下信息:
-
x-amz-ErrorType
HTTP 标头 — 除了 HTTP 状态码提供的错误类型外,还包含更具体的错误类型。 -
x-amz-RequestId
HTTP 标头 — 如果你想向报告问题 Amazon,如果给出请求编号,支持团队可以更好地诊断问题。
HTTP 状态码和 ErrorType 标头都可用于对错误是否可重试以及在什么条件下做出编程决策,并提供有关客户端程序员可能需要采取哪些操作才能成功重试的信息。
有关更多信息,请参阅本主题底部的错误部分以及常见错误。
请求语法
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
-
指定应使用哪种格式来包装媒体。指定
FRAGMENTED_MP4
容器格式会将媒体打包为 MP4 片段(fmP4 或 CMAF)。这是推荐的包装,因为包装开销最小。另一个容器格式选项是MPEG_TS
。HLS 自 MPEG TS 区块发布以来一直支持,有时是旧版 HLS 播放器唯一支持的封装。MPEG TS 的封装开销通常为 5-25%。这意味着 MPEG TS 需要的带宽和成本通常比 fMP4 高 5-25%。默认值为
FRAGMENTED_MP4
。类型:字符串
有效值:
FRAGMENTED_MP4 | MPEG_TS
必需:否
- DiscontinuityMode
-
指定何时将标记片段之间不连续性的标记添加到媒体播放列表中。
媒体播放器通常会根据每个片段的时间戳来建立要播放的媒体内容的时间表。这意味着,如果片段之间存在任何重叠或间隙(如果设置HLSFragmentSelector为,则通常如此
SERVER_TIMESTAMP
),则媒体播放器时间轴在某些地方的片段之间也会有小间隙,并且会覆盖其他位置的帧。媒体播放器时间轴中的间隙可能会导致播放停滞,而重叠可能会导致播放抖动。当片段之间存在不连续标记时,媒体播放器应重置时间轴,从而在上一个片段之后立即播放下一个片段。支持以下模式:
-
ALWAYS
:在 HLS 媒体播放列表中的每个片段之间都放置了一个不连续标记。ALWAYS
如果片段时间戳不准确,建议使用值。 -
NEVER
: 任何地方都没有放置不连续标记。建议使用值,NEVER
以确保媒体播放器时间轴最准确地映射到制作者时间戳。 -
ON_DISCONTINUITY
:在间隙或重叠超过 50 毫秒的片段之间放置不连续标记。对于大多数播放场景,建议使用值,ON_DISCONTINUITY
这样只有在媒体时间轴出现重大问题(例如缺少片段)时,才会重置媒体播放器时间轴。
默认值为
ALWAYS
何时设置HLSFragmentSelector为SERVER_TIMESTAMP
,NEVER
何时设置为PRODUCER_TIMESTAMP
。类型:字符串
有效值:
ALWAYS | NEVER | ON_DISCONTINUITY
必需:否
-
- DisplayFragmentTimestamp
-
指定片段开始时间戳何时应包含在 HLS 媒体播放列表中。通常,媒体播放器将播放头的位置报告为相对于播放会话中第一个片段开始的时间。但是,当开始时间戳包含在 HLS 媒体播放列表中时,某些媒体播放器可能会根据片段时间戳将当前播放头报告为绝对时间。这对于创建向观众显示媒体挂钟时间的播放体验非常有用。
默认值为
NEVER
。如果HLSFragmentSelector是SERVER_TIMESTAMP
,则时间戳将是服务器启动时间戳。同样,如果HLSFragmentSelector是PRODUCER_TIMESTAMP
,则时间戳将是生产者的开始时间戳。类型:字符串
有效值:
ALWAYS | NEVER
必需:否
- Expires
-
请求的会话到期之前的时间(以秒为单位)。此值可以介于 300(5 分钟)和 43200(12 小时)之间。
会话过期后,无法对该会话进行任何新的调用
GetHLSMasterPlaylist
GetHLSMediaPlaylist
GetMP4InitFragment
GetMP4MediaFragment
、、、、或GetTSFragment
。默认值为 300(5 分钟)。
类型:整数
有效范围:最小值为 300。最大值为 43200。
必需:否
- HLSFragmentSelector
-
所请求片段的时间范围和时间戳的来源。
如果
PlaybackMode
为ON_DEMAND
或,则需要此参数LIVE_REPLAY
。如果是,则此参数是可选 PlaybackMode 的LIVE
。如果PlaybackMode
是LIVE
,则FragmentSelectorType
可以设置,但TimestampRange
不应设置。如果PlaybackMode
为ON_DEMAND
或LIVE_REPLAY
,则TimestampRange
必须同时设置FragmentSelectorType
和。类型:HLSFragmentSelector 对象
必需:否
- MaxMediaPlaylistFragmentResults
-
HLS 媒体播放列表中返回的最大片段数。
如果
PlaybackMode
为LIVE
,则返回最新的片段,直至该值。如果PlaybackMode
为ON_DEMAND
,则返回最旧的片段,不超过这个最大数目。当 HLS 直播媒体播放列表中有更多片段时,视频播放器通常会在开始播放之前缓冲内容。增加缓冲区大小会增加播放延迟,但会降低播放期间发生重新缓冲的可能性。我们建议直播的 HLS 媒体播放列表至少包含 3 个片段,最多 10 个片段。
如果为
LIVE
或,则默认为 5 个片段,如果PlaybackMode
为LIVE_REPLAY
,则PlaybackMode
默认为 1,000ON_DEMAND
。5,000 个片段的最大值对应于包含 1 秒片段的直播上超过 80 分钟的视频,对应于包含 10 秒片段的直播上超过 13 小时的视频。
类型:长整型
有效范围:最小值为 1。最大值为 5000。
必需:否
- PlaybackMode
-
是检索实时、实时重播还是存档的按需数据。
这三种类型的会话的特点包括:
-
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
-
要检索 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
-
要检索 HLS 主播放列表网址的直播名称。
必须指定
StreamName
或StreamARN
。类型:字符串
长度限制:最小长度为 1。最大长度为 256。
模式:
[a-zA-Z0-9_.-]+
必需:否
响应语法
HTTP/1.1 200
Content-type: application/json
{
"HLSStreamingSessionURL": "string"
}
响应元素
如果此操作成功,则该服务将会发送回 HTTP 200 响应。
服务以 JSON 格式返回以下数据。
- HLSStreamingSessionURL
-
媒体播放器可用于检索 HLS 主播放列表的 URL(包含会话令牌)。
类型:字符串
错误
有关所有操作返回的常见错误的信息,请参阅 常见错误。
- ClientLimitExceededException
-
Kinesis Video Streams 已限制该请求,因为你已超过限制。稍后再尝试拨打电话。有关限制的信息,请参阅 Kinesis Video Streams 限制。
HTTP 状态代码:400
- InvalidArgumentException
-
指定参数超出其限制、不受支持或无法使用。
HTTP 状态代码:400
- InvalidCodecPrivateDataException
-
视频流中至少一条轨道中的编解码器私有数据对此操作无效。
HTTP 状态代码:400
- MissingCodecPrivateDataException
-
在视频流的至少一条轨道中未发现编解码器的私有数据。
HTTP 状态代码:400
- NoDataRetentionException
-
GetImages
请求的直播不保留数据(即 aDataRetentionInHours
为 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
-
无法根据播放会话的第一个片段中轨道的编解码器 ID 来确定媒体的类型(例如 h.264 或 h.265 视频或 AAC 或 G.711 音频)。轨道 1 的编解码器 ID 应为
V_MPEG/ISO/AVC
,轨道 2 的编解码器 ID 也应为(可选)。A_AAC
HTTP 状态代码:400
另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息,请参阅以下内容: