本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Kinesis 影片串流結構 您可以使用下列結構，將資料提供給 Kinesis 影片串流的執行個體。 **Topics** + [StreamDefinition/StreamInfo](#producer-reference-structures-stream-streaminfo) + [ClientMetrics](#producer-reference-structures-stream-clientmetrics) + [StreamMetrics](#producer-reference-structures-stream-streammetrics) ## StreamDefinition/StreamInfo `StreamDefinition` 物件在 C\$1\$1 層中包裝 `StreamInfo` 物件於獨立於平台的代碼中，並提供建構函數中的某些預設值。 ### 成員欄位 **** | 欄位 | 資料類型 | Description | 預設值 | | --- | --- | --- | --- | | stream\$1name | string | 選用的串流名稱。如需更多關於串流名稱長度的資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。每個串流皆應有唯一的名稱。 | 如果未指定名稱，則會產生隨機的名稱。 | | retention\$1period | duration> | 串流的保留期間以秒為單位。指定 0 代表沒有保留。 | 3600 (一小時) | | tags | const map\$1 | 包含使用者資訊之金鑰值對的對應。如果串流已有一組標籤，則新標籤會附加到現有的一組標籤之後。 | 無標籤 | | kms\$1key\$1id | string | 用於加密串流的 AWS KMS 金鑰 ID。如需詳細資訊，請參閱[Kinesis Video Streams 中的資料保護](how-kms.md)。 | 預設 KMS 金鑰 (aws/kinesisvideo)。 | | streaming\$1type | STREAMING\$1TYPE 列舉 | 唯一支援的值為 STREAMING\$1TYPE\$1REALTIME。 | | | content\$1type | string | 串流的內容格式。Kinesis Video Streams 主控台可以 video/h264 格式播放內容。 | video/h264 | | max\$1latency | duration | 串流的最大延遲，以毫秒為單位。當緩衝持續時間超過此時間量時，會呼叫串流延遲壓力回呼 (如果指定)。指定 0 表示將不呼叫串流延遲壓力回呼。 | milliseconds::zero() | | fragment\$1duration | duration | 您要的片段持續時間，以秒為單位。此值與 key\$1frame\$1fragmentation 值結合使用。如果此值為 false，Kinesis Video Streams 會在超過此持續時間後，在金鑰影格上產生片段。例如，進階音訊編碼 (AAC) 音訊串流將每個影格做為關鍵影格。指定 key\$1frame\$1fragmentation = false 導致在經過此持續時間之後在關鍵影格上片段化，產生 2 秒的片段。 | 2 | | timecode\$1scale | duration | MKV 時間碼比例以毫秒為單位，這用於指定 MKV 叢集中影格的時間碼精細度。MKV 影格時間碼一律相對於叢集的開始。MKV 使用簽章的 16 位元值 (0-32767) 來代表時間碼在叢集 (片段) 中。確認框架時間碼可以使用指定的時間碼比例來表示。時間碼規模的預設值 1 毫秒可確保最大的影格，則可以代表 32767 毫秒 \$1= 32 秒。這是超過最大持續時間指定片段 [Amazon Kinesis Video Streams 服務配額](limits.md)為 10 秒。 | 1 | | key\$1frame\$1fragmentation | bool | 是否在關鍵影格上產生片段。如果為 true，則開發套件在每次關鍵影格出現時會產生片段的開始。如果為 false，Kinesis Video Streams 至少會等待 ，fragment\$1duration並在關鍵影格上產生新的片段。 | true | | frame\$1timecodes | bool | 是否使用影格時間碼或者使用目前時間回呼產生時間戳記。許多編碼器不會產生時間戳記的影格。因此false，指定此參數可確保影格在放入 Kinesis Video Streams 時加上時間戳記。 | true | | absolute\$1fragment\$1times | bool | Kinesis Video Streams 使用 MKV 作為其基礎封裝機制。有關影格的時間碼 MKV 規格嚴格的相對於叢集 (片段) 的開始。不過，在叢集的時間碼可以絕對或相對於串流的開始時間。如果時間戳記是相對的，PutMedia 服務 API 呼叫會使用可選的串流開始時間戳記並調節叢集時間戳記。該服務隨時儲存區段及其絕對時間戳記。 | true | | fragment\$1acks | bool | 是否接收應用程式層級片段 ACKs（確認）。 | true，表示軟體開發套件接收 ACK 並依此操作。 | | restart\$1on\$1error | bool | 是否在出現特定錯誤時重新啟動。 | true，表示在出現任何錯誤時開發套件將嘗試重新啟動串流。 | | recalculate\$1metrics | bool | 是否重新計算指標。每個擷取指標的呼叫可以重新計算這些值，以獲取最新的「執行中」值，這可能會產生較小的 CPU 影響。您可能需要設定為 false 在極低功耗/容量的裝置上以避免佔用 CPU 週期。否則，我們不建議使用 false做為此值。 | true | | nal\$1adaptation\$1flags | uint32\$1t | 指定網路抽象層單位 (NALU) 調節旗標。如果位元串流是 H.264 編碼，則在 NALU 中可以處理做為原始資料或封裝。這些可以為 Annex-B 或 AVCC 格式。大多數基本串流生產者和消費者 （讀取編碼器和解碼器） 都使用 Annex-B 格式，因為它具有優勢，例如錯誤復原。較高層級的系統使用 AVCC 格式的預設格式，適用於 MPEG、HLS、DASH 等。主控台播放使用瀏覽器的 MSE (Media Source Extensions) 來解碼和播放使用 AVCC 格式的串流。對於 H264 (以及對於 M-JPEG 和 H265)，開發套件提供自我調節功能。 許多基本串流採用以下格式。在此範例中，`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\$1rate | uint32\$1t | 預期的影格率。此值用於更完善計算緩衝需求。 | 25 | | avg\$1bandwidth\$1bps | uint32\$1t | 串流的預期平均頻寬。此值用於更完善計算緩衝需求。 | 4 \$1 1024 \$1 1024 | | buffer\$1duration | duration | 串流緩衝持續時間，以秒為單位。SDK 會將內容存放區中的影格保留最多 buffer\$1duration，之後會隨著視窗向前移動而捨棄先前的影格。如果正在捨棄的影格尚未傳送至後端，則會呼叫捨棄的影格回呼。如果目前緩衝區持續時間大於 max\$1latency，則將呼叫延遲壓力回呼。收到片段持續 ACK 時，緩衝區會裁剪到下一個片段啟動。這表示其內容的已長期存放在雲端，所以不再需要在執行個體的本機裝置的內容儲存。 | 120 | | replay\$1duration | duration | 如果啟用重新啟動，則在錯誤期間向後滾動目前讀取器以重播的持續時間，以秒為單位。轉返操作將在緩衝開始時停止 (在剛啟動串流時或已出現持續的 ACK 時)。轉返嘗試停留在顯示片段開始的關鍵影格上。如果 ' 導致重新啟動的錯誤並未指示無效主機 （主機仍然有效，並在其內部緩衝區中包含影格資料），則轉返會在最後收到的 ACK 影格停止。它會將轉發到下一個金鑰影格，因為整個片段已存放在主機記憶體。 | 40 | | connection\$1staleness | duration | 如果 SDK 未收到緩衝 ACK，則會呼叫串流過時回呼的時間，以秒為單位。它表示正在從裝置傳送影格，但後端未確認它們。此條件表示在中間躍點或負載平衡器的連線已中斷。 | 30 | | codec\$1id | string | MKV 音軌的轉碼器 ID。 | V\$1MPEG4/ISO/AVC | | track\$1name | string | MKV 音軌名稱。 | kinesis\$1video | | codecPrivateData | unsigned char\$1 | 編解碼器私有資料 (CPD) 緩衝區。如果媒體管道在串流啟動之前具有 CPD 的相關資訊，則可以在 StreamDefinition.codecPrivateData 中發送。此時將複製位元，在建立串流的呼叫之後可以重新使用緩衝區或將其釋放。不過，如果資料在建立串流時無法使用，則可以在KinesisVideoStream.start(cpd)函數的其中一個過載中設定。 | null | | codecPrivateDataSize | uint32\$1t | 編解碼器私有資料緩衝區大小。 | 0 | ## ClientMetrics **ClientMetrics** 物件透過呼叫 `getKinesisVideoMetrics` 來填充。 ### 成員欄位 **** | 欄位 | 資料類型 | Description | | --- | --- | --- | | version | UINT32 | 結構的版本，在 CLIENT\$1METRICS\$1CURRENT\$1VERSION 巨集中定義。 | | contentStoreSize | UINT64 | 整體內容存放區大小，以位元組為單位。這是 DeviceInfo.StorageInfo.storageSize 中指定的值。 | | contentStoreAvailableSize | UINT64 | 目前可用的儲存大小，以位元組為單位。 | | contentStoreAllocatedSize | UINT64 | 目前配置的大小。由於內部記帳和內容存放區的實施，配置加上可用的大小應略小於總儲存空間的大小。 | | totalContentViewsSize | UINT64 | 所有串流的所有內容視圖的已分配記憶體大小。這不會計入儲存體大小。此記憶體使用 MEMALLOC 巨集分配，可以覆蓋該值以提供自訂分配器。 | | totalFrameRate | UINT64 | 在所有串流上觀察到的總影格率。 | | totalTransferRate | UINT64 | 在所有串流上觀察到的總串流速率，以每秒位元組數為單位。 | ## StreamMetrics 透過呼叫 ** 來填充 **StreamMetrics`getKinesisVideoMetrics` 物件。 ### 成員欄位 **** | 欄位 | 資料類型 | Description | | --- | --- | --- | | version | UINT32 | 結構的版本，在 STREAM\$1METRICS\$1CURRENT\$1VERSION 巨集中定義。 | | currentViewDuration | UINT64 | 累積影格的時間長度。在快速聯網案例中，此持續時間為零或影格持續時間 （正在傳輸影格時）。如果持續時間超過 中max\$1latency指定的持續時間StreamDefinition，則會在指定時呼叫串流延遲回呼。以 100 奈秒 (ns) 為單位指定持續時間，這是 PIC 層的預設時間單位。 | | overallViewDuration | UINT64 | 整體檢視持續時間。如果串流設定沒有 ACKs或持久性，此值會隨著影格放入 Kinesis 影片串流而增加，並等於 buffer\$1duration中的 StreamDefinition。啟用 ACKs並收到持續的 ACK 時，緩衝區會修剪為下一個金鑰影格。這是因為 ACK 時間戳記表示整個片段的開頭。以 100 奈秒 (ns) 為單位指定持續時間，這是 PIC 層的預設時間單位。 | | currentViewSize | UINT64 | 目前緩衝區的大小，以位元組為單位。 | | overallViewSize | UINT64 | 整體檢視大小，以位元組為單位。 | | currentFrameRate | UINT64 | 目前串流觀察到的影格率。 | | currentTransferRate | UINT64 | 目前串流觀察到的傳輸速率，以每秒位元組數為單位。 |