本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Kinesis 视频流结构 您可以使用以下结构向 Kinesis 视频流的实例提供数据。 **Topics** + [StreamDefinition/StreamInfo](#producer-reference-structures-stream-streaminfo) + [ClientMetrics](#producer-reference-structures-stream-clientmetrics) + [StreamMetrics](#producer-reference-structures-stream-streammetrics) ## StreamDefinition/StreamInfo C\+\+ 层中的 `StreamDefinition` 对象在独立于平台的代码中封装 `StreamInfo` 对象，并在构造函数中提供一些默认值。 ### 成员字段 **** | 字段 | 数据类型 | 说明 | 默认 值 | | --- | --- | --- | --- | | stream\_name | string | 可选的流名称。有关流名称长度的更多信息，请参阅[制作人 SDK 配额](limits.md#producer-sdk-limits)。每个流应具有唯一的名称。 | 如果未指定名称，则将随机生成一个名称。 | | retention\_period | duration> | 流的保留期，以秒为单位。指定 0 表示不保留。 | 3600 (1 小时) | | tags | const map\* | 包含用户信息的键-值对的映射。如果流已有一组标志，则新标志将附加到现有一组标志之后。 | 无标签 | | kms\_key\_id | string | 用于加密直播的密 Amazon KMS 钥 ID。有关更多信息，请参阅 [Kinesis Video Streams 中的数据保护](how-kms.md)。 | 默认 KMS 密钥 (aws/kinesisvideo)。 | | streaming\_type | STREAMING\_TYPE 枚举 | STREAMING\_TYPE\_REALTIME 是唯一受支持的值。 | | | content\_type | string | 流的内容格式。Kinesis Video Streams 控制台可以播放video/h264该格式的内容。 | video/h264 | | max\_latency | duration | 数据流的最大延迟，以毫秒为单位。当缓冲持续时间超过此时间量时，将调用流延迟压力回调（如果指定）。指定 0 表示将不调用流延迟压力回调。 | milliseconds::zero() | | fragment\_duration | duration | 所需的片段持续时间，以秒为单位。此值与 key\_frame\_fragmentation 值结合使用。如果此值为false，Kinesis Video Streams 将在该持续时间过去后在关键帧上生成片段。例如，高级音频编码 (AAC) 音频流将每个帧作为关键帧。指定 key\_frame\_fragmentation = false 将导致在经过此持续时间之后，在关键帧上片段化，生成 2 秒的片段。 | 2 | | timecode\_scale | duration | MKV 时间码标度以毫秒为单位，这指定 MKV 集簇中帧的时间码粒度。MKV 帧时间码始终相对于集簇的开始。MKV 使用一个有符号的 16 位值 (0-32767) 来表示集簇内的时间码（片段）。验证帧时间码是否可以用给定的时间码比例来表示。默认时间码标度值 1 毫秒确保可以表示的最大帧为 32767 ms \~ = 32 秒。这是在[亚马逊 Kinesis Video Streams 服务配额](limits.md)指定的最大片段持续时间（10 秒）内。 | 1 | | key\_frame\_fragmentation | bool | 是否在关键帧上生成片段。如果为 true，则开发工具包将在每次出现关键帧时生成片段的开始。如果false，Kinesis Video Streams fragment\_duration 至少会等待，然后在紧随其后的关键帧上生成一个新的片段。 | true | | frame\_timecodes | bool | 是否使用帧时间码或者使用当前时间回调生成时间戳。许多编码器不在帧中生成时间戳。因此，指定false此参数可确保帧在放入 Kinesis Video Streams 时带有时间戳。 | true | | absolute\_fragment\_times | bool | Kinesis Video Streams 使用 MKV 作为其底层打包机制。MKV 规范具有严格的帧时间码，相对于集簇（片段）的开始位置，但集簇时间码可以是绝对的，也可以相对于流的开始时间。如果时间戳是相对的，PutMedia 服务 API 调用将使用可选的流开始时间戳并调整集群时间戳。该服务始终存储片段及其绝对时间戳。 | true | | fragment\_acks | bool | 是否接收应用程序级片段 ACKs （确认）。 | true，这意味着 SDK 将收到 ACKs并采取相应的行动。 | | restart\_on\_error | bool | 是否在出现特定错误时重启。 | true 意味着开发工具包在出现任意错误时将尝试重新启动流。 | | recalculate\_metrics | bool | 是否重新计算指标。每个检索度量的调用可以重新计算这些值，以获取最新的“正在运行”值，这可能会导致较小的 CPU 影响。在极低功耗/容量的设备上，可能需要将此值设置为 false 以避免占用 CPU 周期。否则，我们不建议使用false此值。 | true | | nal\_adaptation\_flags | uint32\_t | 指定网络抽象层单元 (NALU) 自适应标志。如果比特流采用 H.264 编码，则可以将其作为原始数据处理或打包进去。 NALUs后者可以为 Annex-B 或 AVCC 格式。大多数基本流制作者和使用者（读取编码器和解码器）都使用 Annex-B 格式，因为它具有诸如错误恢复等优点。高级系统使用 AVCC 格式，这是 MPEG、HLS、DASH 等的默认格式。控制台播放使用浏览器的 MSE (Media Source Extensions) 来解码和播放使用 AVCC 格式的流。对于 H.264（以及对于 M-JPEG 和 H.265），开发工具包提供自适应功能。
许多基本流采用以下格式。在此示例中，`Ab` 是 Annex-B 开始代码（001 或 0001）。
Ab(Sps)Ab(Pps)Ab(I-frame)Ab(P/B-frame) Ab(P/B-frame)…. Ab(Sps)Ab(Pps)Ab(I-frame)Ab(P/B-frame) Ab(P/B-frame)

对于 H.264，编解码器私有数据 (CPD) 位于 SPS（序列参数集）和 PPS（图像参数集）参数中，并且可以调整为 AVCC 格式。除非媒体管道单独提供 CPD，否则应用程序可以从帧中提取 CPD。它可以通过查找第一个 IDR 帧（其中应包含 SPS 和 PPS），提取两个 NALUs （它们是`Ab(Sps)Ab(Pps)`），然后将其设置在 CPD 中来实现。`StreamDefinition`
有关更多信息，请参阅 [网络抽象层 (NAL) 适配标记参考](producer-reference-nal.md)。 | 默认情况下，帧数据和编解码器私有数据均为从 Annex-B 格式更改为 AVCC 格式。 | | frame\_rate | uint32\_t | 预期的帧率。此值用于更好地计算缓冲需求。 | 25 | | avg\_bandwidth\_bps | uint32\_t | 流的预期平均带宽。此值用于更好地计算缓冲需求。 | 4 \* 1024 \* 1024 | | buffer\_duration | duration | 流缓冲持续时间，以秒为单位。SDK 将帧保留在内容存储中的时间最长buffer\_duration，之后随着窗口向前移动，之前的帧会被丢弃。如果被丢弃的帧尚未发送到后端，则会调用丢弃的帧回调。如果当前缓冲区持续时间大于 max\_latency，则将调用流延迟压力回调。收到片段持久 ACK 时，缓冲区将修剪到下一个片段开始位置。这指示内容已持久保留到云中，因此不再需要在本地设备上存储内容。 | 120 | | replay\_duration | duration | 如果启用了重新启动，则在出错期间向后滚动当前读取器进行重播的持续时间（以秒为单位）。回滚操作将在缓冲开始位置停止（在刚启动流式传输时，或者出现持久 ACK 时）。回滚将尝试停留在指示片段开始的关键帧上。如果 “导致重启” 的错误并不表示主机已失效（主机仍处于活动状态且其内部缓冲区中包含帧数据），则回滚将在最后收到的 ACK 帧处停止。然后，它滚动到下一个关键帧，因为整个片段已经存储在主机内存中。 | 40 | | connection\_staleness | duration | 如果 SDK 未收到缓冲 ACK，则调用直播陈旧回调的时间（以秒为单位）。它表示帧是从设备发送的，但后端没有确认它们。这表明在中间跳转时或者负载均衡器上出现了断开的连接。 | 30 | | codec\_id | string | MKV 音轨的编解码器 ID。 | V\_MPEG4/ISO/AVC | | track\_name | string | MKV 音轨名称。 | kinesis\_video | | codecPrivateData | unsigned char\* | 编解码器私有数据 (CPD) 缓冲区。如果媒体管道在流启动之前具有 CPD 的相关信息，则可以在 StreamDefinition.codecPrivateData 中发送。此时将复制位，在创建流的调用之后可以重用或释放缓冲区。但是，如果创建流时数据不可用，则可以在KinesisVideoStream.start(cpd)函数的其中一个重载中对其进行设置。 | null | | codecPrivateDataSize | uint32\_t | 编解码器私有数据缓冲区大小。 | 0 | ## ClientMetrics 通过调用来填充**ClientMetrics**对象`getKinesisVideoMetrics`。 ### 成员字段 **** | 字段 | 数据类型 | 说明 | | --- | --- | --- | | 版本 | UINT32 | 结构的版本，在 CLIENT\_METRICS\_CURRENT\_VERSION 宏中定义。 | | contentStoreSize | UINT64 | 整体内容存储大小，以字节为单位。这是在 DeviceInfo.StorageInfo.storageSize 中指定的值。 | | contentStoreAvailable大小 | UINT64 | 当前可用存储大小（以字节为单位）。 | | contentStoreAllocated大小 | UINT64 | 当前分配的大小。由于内部记账和内存存储的实施，分配大小 \+ 可用大小应略小于总存储大小。 | | totalContentViews大小 | UINT64 | 所有流的所有内容视图的已分配内存大小。这不计入存储大小。此内存使用 MEMALLOC 宏分配，可以覆盖该值以提供自定义分配器。 | | totalFrameRate | UINT64 | 在所有流上观察到的总帧率。 | | totalTransferRate | UINT64 | 在所有流上观察到的总流速率，以每秒字节数为单位。 | ## StreamMetrics 通过调用来填充**StreamMetrics**对象`getKinesisVideoMetrics`。 ### 成员字段 **** | 字段 | 数据类型 | 说明 | | --- | --- | --- | | 版本 | UINT32 | 结构的版本，在 STREAM\_METRICS\_CURRENT\_VERSION 宏中定义。 | | currentViewDuration | UINT64 | 累积帧的时间长度。在快速联网的情况下，此持续时间要么为零，要么为帧持续时间（在传输帧时）。如果持续时间长于中max\_latency指定的时间StreamDefinition，则会调用直播延迟回调（如果已指定）。持续时间以 100 纳秒为单位指定，这是 PIC 层的默认时间单位。 | | overallViewDuration | UINT64 | 整体查看持续时间。如果将直播配置为 “否” ACKs 或 “持久性”，则该值会随着帧放入 Kinesis 视频流而增长，并变为等于buffer\_duration中的。StreamDefinition启用并收到持久 ACKs 的 ACK 后，缓冲区会被修剪到下一个关键帧。这是因为 ACK 时间戳表示整个片段的开头。持续时间以 100 纳秒为单位指定，这是 PIC 层的默认时间单位。 | | currentViewSize | UINT64 | 当前缓冲区的大小，以字节为单位。 | | overallViewSize | UINT64 | 整体视图大小，以字节为单位。 | | currentFrameRate | UINT64 | 当前流观察到的帧率。 | | currentTransferRate | UINT64 | 当前流观察到的传输速率，以每秒字节数为单位。 |