本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
Kinesis 视频流结构
您可以使用以下结构向 Kinesis 视频流的实例提供数据。
StreamDefinition/StreamInfo
C++ 层中的 StreamDefinition 对象在独立于平台的代码中封装 StreamInfo 对象，并在构造函数中提供一些默认值。
成员字段
| 字段 | 数据类型 | 描述 | 默认值 |
|---|---|---|---|
| stream_name | string |
可选的流名称。有关流名称长度的更多信息，请参阅制作人 SDK 限制。每个流应具有唯一的名称。 | 如果未指定名称，则将随机生成一个名称。 |
| retention_period | duration<uint64_t,
ratio<3600>> |
流的保留期，以秒为单位。指定 0 表示不保留。 |
3600 (1 小时) |
| tags | const map<string, string>*
|
包含用户信息的键-值对的映射。如果流已有一组标志，则新标志将附加到现有一组标志之后。 | 无标签 |
| kms_key_id | string |
要用于加密流的 Amazon KMS 密钥 ID。有关更多信息，请参阅Kinesis Video Streams 中的数据保护： | 默认 KMS 密钥 (aws/kinesis-video)。 |
| streaming_type | STREAMING_TYPE 枚举 |
STREAMING_TYPE_REALTIME 是唯一受支持的值。 |
|
| content_type | string |
流的内容格式。Kinesis Video Streams 控制台可以播放video/h264该格式的内容。 |
video/h264 |
| max_latency | duration<uint64_t, milli> |
数据流的最大延迟，以毫秒为单位。当缓冲持续时间超过此时间量时，将调用流延迟压力回调（如果指定）。指定 0 表示将不调用流延迟压力回调。 |
milliseconds::zero() |
| fragment_duration | duration<uint64_t> |
所需的片段持续时间，以秒为单位。此值与 key_frame_fragmentation 值结合使用。如果此值为false，Kinesis Video Streams 将在该持续时间过去后在关键帧上生成片段。例如，高级音频编码 (AAC) 音频流将每个帧作为关键帧。指定 key_frame_fragmentation = false 将导致在经过此持续时间之后，在关键帧上片段化，生成 2 秒的片段。 |
2 |
| timecode_scale | duration<uint64_t, milli> |
MKV 时间码标度以毫秒为单位，这指定 MKV 集簇中帧的时间码粒度。MKV 帧时间码始终相对于集簇的开始。MKV 使用一个有符号的 16 位值 (0-32767) 来表示集簇内的时间码（片段）。验证帧时间码是否可以用给定的时间码比例来表示。默认时间码标度值 1 毫秒确保可以表示的最大帧为 32767 ms ~ = 32 秒。这是在Kinesis Video Streams 服务配额指定的最大片段持续时间（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 |
是否接收应用程序级片段 ACK（确认）。 | true 意味着开发工具包接收 ACK 并相应操作。 |
| restart_on_error | bool |
是否在出现特定错误时重启。 | true 意味着开发工具包在出现任意错误时将尝试重新启动流。 |
| recalculate_metrics | bool |
是否重新计算指标。每个检索度量的调用可以重新计算这些值，以获取最新的“正在运行”值，这可能会导致较小的 CPU 影响。在极低功耗/容量的设备上，可能需要将此值设置为 false 以避免占用 CPU 周期。否则，我们不建议使用false此值。 |
true |
| nal_adaptation_flags | uint32_t |
指定网络抽象层单元 (NALU) 自适应标志。如果比特流为 H.264 编码，则可以将其按原始数据或包装为 NALU 进行处理。后者可以为 Annex-B 或 AVCC 格式。大多数基本流制作者和使用者（读取编码器和解码器）都使用 Annex-B 格式，因为它具有诸如错误恢复等优点。高级系统使用 AVCC 格式，这是 MPEG、HLS、DASH 等的默认格式。控制台播放使用浏览器的 MSE (Media Source Extensions) 来解码和播放使用 AVCC 格式的流。对于 H.264（以及对于 M-JPEG 和 H.265），开发工具包提供自适应功能。 许多基本流采用以下格式。在此示例中，
对于 H.264，编解码器私有数据 (CPD) 位于 SPS（序列参数集）和 PPS（图像参数集）参数中，并且可以调整为 AVCC 格式。除非媒体管道单独提供 CPD，否则应用程序可以从帧中提取 CPD。它可以通过查找第一个 IDR 帧（其中应包含 SPS 和 PPS），提取两个 NALU（它们是 有关更多信息，请参阅NAL 适配标志： |
默认情况下，帧数据和编解码器私有数据均为从 Annex-B 格式更改为 AVCC 格式。 |
| frame_rate | uint32_t |
预期的帧率。此值用于更好地计算缓冲需求。 | 25 |
| avg_bandwidth_bps | uint32_t |
流的预期平均带宽。此值用于更好地计算缓冲需求。 | 4 * 1024 * 1024 |
| buffer_duration | duration<uint64_t> |
流缓冲持续时间，以秒为单位。SDK 将帧保留在内容存储中的时间最长buffer_duration，之后随着窗口向前移动，之前的帧会被丢弃。如果被丢弃的帧尚未发送到后端，则会调用丢弃的帧回调。如果当前缓冲区持续时间大于 max_latency，则将调用流延迟压力回调。收到片段持久 ACK 时，缓冲区将修剪到下一个片段开始位置。这指示内容已持久保留到云中，因此不再需要在本地设备上存储内容。 |
120 |
| replay_duration | duration<uint64_t> |
如果启用了重新启动，则在出错期间向后滚动当前读取器进行重播的持续时间（以秒为单位）。回滚操作将在缓冲开始位置停止（在刚启动流式传输时，或者出现持久 ACK 时）。回滚将尝试停留在指示片段开始的关键帧上。如果 “导致重启” 的错误并不表示主机已死亡（主机仍处于活动状态且其内部缓冲区中包含帧数据），则回滚将在最后收到的 ACK 帧处停止。然后，它滚动到下一个关键帧，因为整个片段已经存储在主机内存中。 | 40 |
| connection_staleness | duration<uint64_t> |
如果 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 |
| codecPrivateData大小 | uint32_t |
编解码器私有数据缓冲区大小。 | 0 |
ClientMetrics
通过调用来填充ClientMetrics对象getKinesisVideoMetrics。
成员字段
| 字段 | 数据类型 | 描述 |
|---|---|---|
| version | UINT32 |
结构的版本，在 CLIENT_METRICS_CURRENT_VERSION 宏中定义。 |
| contentStoreSize | UINT64 |
整体内容存储大小，以字节为单位。这是在 DeviceInfo.StorageInfo.storageSize 中指定的值。 |
| contentStoreAvailable大小 | UINT64 |
当前可用存储大小（以字节为单位）。 |
| contentStoreAllocated大小 | UINT64 |
当前分配的大小。由于内部记账和内存存储的实施，分配大小 + 可用大小应略小于总存储大小。 |
| totalContentViews大小 | UINT64 |
所有流的所有内容视图的已分配内存大小。这不计入存储大小。此内存使用 MEMALLOC 宏分配，可以覆盖该值以提供自定义分配器。 |
| totalFrameRate | UINT64 |
在所有流上观察到的总帧率。 |
| totalTransferRate | UINT64 |
在所有流上观察到的总流速率，以每秒字节数为单位。 |
StreamMetrics
通过调用来填充StreamMetrics对象getKinesisVideoMetrics。
成员字段
| 字段 | 数据类型 | 描述 |
|---|---|---|
| version | UINT32 |
结构的版本，在 STREAM_METRICS_CURRENT_VERSION 宏中定义。 |
| currentViewDuration | UINT64 |
累积帧的时间长度。在快速联网的情况下，此持续时间要么为零，要么为帧持续时间（在传输帧时）。如果持续时间长于中max_latency指定的时间StreamDefinition，则会调用直播延迟回调（如果已指定）。持续时间以 100 纳秒为单位指定，这是 PIC 层的默认时间单位。 |
| overallViewDuration | UINT64 |
整体查看持续时间。如果直播配置为没有 ACK 或持久性，则该值会随着帧放入 Kinesis 视频流而增长，并变为等于buffer_duration中的。StreamDefinition启用 ACK 并收到持久的 ACK 后，缓冲区会被修剪到下一个关键帧。这是因为 ACK 时间戳表示整个片段的开头。持续时间以 100 纳秒为单位指定，这是 PIC 层的默认时间单位。 |
| currentViewSize | UINT64 |
当前缓冲区的大小，以字节为单位。 |
| overallViewSize | UINT64 |
整体视图大小，以字节为单位。 |
| currentFrameRate | UINT64 |
当前流观察到的帧率。 |
| currentTransferRate | UINT64 |
当前流观察到的传输速率，以每秒字节数为单位。 |