Fuchsia.media

AudioCapturer

AudioCapturer 是由 fuchsia.media.Audio 的 CreateAudioCapturer 方法傳回的介面，可根據建立時傳送的旗標，透過目前的預設音訊輸入裝置或目前預設音訊輸出裝置擷取音訊。

格式支援

請參閱下方的「Get|Set)StreamType」。根據預設，擷取的串流類型會先由 AudioCapturer 在建立時繫結的來源目前設定的串流類型決定。使用者可以透過 GetStreamType 擷取此類型，或選擇讓媒體重新取樣，或透過呼叫 SetStreamType 轉換為所選的類型。注意：串流類型只能在系統未執行時設定，這表示沒有待處理的擷取地區 (使用 CaptureAt 指定)，且系統目前並非在「非同步」擷取模式下執行。

緩衝區和記憶體管理

音訊資料會擷取到使用者在 AddPayloadBuffer 呼叫期間提供給 AudioCapturer 提供的共用記憶體緩衝區 (VMO)。請注意下列與酬載緩衝區管理相關的規定。

必須先提供酬載緩衝區，才能啟動任何擷取作業。在酬載緩衝區建立前，嘗試透過 CaptureAt 或 StartAsyncCapture 啟動擷取作業，都會發生錯誤。
如有任何待處理的擷取作業，酬載緩衝區可能無法變更。
設定酬載緩衝區後，就無法變更串流類型。
酬載緩衝區必須是音訊影格大小 (以位元組為單位) 的整數
以「非同步」模式執行時 (如下所示)，酬載緩衝區的大小至少必須為 StartAsyncCapture 時指定的 frame_per_packet 大小的兩倍。
使用者提供的酬載緩衝區控制代碼必須可讀取、可寫入、可對應及轉移。
使用者應一律將酬載緩衝區視為唯讀。

同步與非同步擷取模式

AudioCapturer 介面可在兩種互斥模式下使用：同步和非同步。以下將說明各種模式及其優缺點。

同步模式

根據預設，AudioCapturer 執行個體會以「同步處理」模式執行。只有在使用者至少提供一個要擷取的區域時，才能使用 CaptureAt 方法擷取資料。系統會按照透過 CaptureAt 方法的傳回值，接收並傳回用戶端做為 StreamPackets ，以這種方式提供的區域。如果 AudioCapturer 執行個體有可擷取的資料，但沒有可擷取的資料 (因為沒有其他待處理的區域需要填入)，下一個產生的酬載會在下一個產生的 StreamPacket 上設定 Discontinuity 標記，表示其為溢位。同步模式無法與非同步模式搭配使用。當 CaptureAt 提供的可用區域仍在等待填入時，嘗試呼叫 StartAsyncCapture 時發生錯誤。

如果使用者已提供過去 AudioCapturer 執行個體要填入的區域，但想要收回這些區域，則可使用捨棄 AllPackets 方法。呼叫 DropAllPackets 方法會導致系統傳回所有待處理區域，但傳回 NO_TIMESTAMP 做為其 StreamPacket 的 PTS。如需時間戳記和不連續標記的討論，請參閱下方的「時間與溢位」。捨棄 AllPackets 作業後，系統會產生 OnEndOfStream 事件。雖然 AudioCapturer 在傳回已完成區域後絕不會覆寫酬載緩衝區的任何區域，但可能會覆寫部分已填入緩衝區中未填入的部分，而該緩衝區因捨棄 AllPackets 作業而傳回。

非同步模式

在「非同步」模式下執行時，用戶端不需要明確提供要由 AudioCapturer 執行個體填入的共用緩衝區區域。而是會呼叫 StartAsyncCapture 並提供回呼介面和每個回呼所擷取的影格數，進入「非同步」模式。以非同步模式執行後，AudioCapturer 執行個體會找出要擷取的酬載緩衝區區域、擷取指定影格數量，然後使用 OnPacketCapture FIDL 事件以 StreamPackets 形式提供這些影格。使用者可能會使用 StopAsyncCapture 方法停止擷取 AudioCapturer 執行個體，並傳回「sync」模式。

嘗試下列任何作業都視為錯誤。

在尚未建立酬載緩衝區時嘗試進入「非同步」擷取模式。
為每個酬載指定可擷取的影格數量，但不允許在已建立的共用酬載緩衝區同時存在至少兩個連續擷取酬載。
如要在 AudioCapturer 執行個體以「非同步」模式執行時，使用 CaptureAt 方法傳送要擷取的區域。
如要在 AudioCapturer 執行個體以「非同步」模式執行時呼叫捨棄 AllPackets。
在不先停止的情況下，嘗試重新啟動「非同步」模式擷取作業。
在停止過程中嘗試 SetGain 以外的任何作業。

透過 StopAsyncCapture 作業進行同步處理

停止非同步擷取模式並返回同步擷取模式，是一項需要耗費時間的作業。除了 SetGain 外，使用者不得在呼叫 StopAsyncCapture (包括再次呼叫 StopAsyncCapture) 後，在 AudioCapturer 介面上呼叫任何其他方法，直到停止作業完成為止。因此，使用者必須能和停止作業進行同步處理。為此，我們提供兩種機制。

第一種是使用 StopAsyncCapture (而非 NoReply 變化版本)。在系統呼叫使用者的回呼後，使用者即可確定停止作業已經完成，且 AudioCapturer 執行個體已返回同步作業模式。

如要確認停止作業是否已完成，第二種方法是在呼叫 StopAsyncCapture 後，透過使用者提供的 AudioCapturerCallback 介面傳送的封包標記。要求停止時，系統會將任何部分填入的封包傳回給使用者，且傳回的最後封包一律會設定串流結束標記 (kFlagsEos)，以表示這是序列中的最後一個影格。如果沒有可傳回的部分封包，AudioCapturer 會合成沒有時間戳記的空封包，並將偏移/長度設為零，以傳送設有結束串流標記的封包。當使用者在呼叫停止後看到串流結尾標記時，AudioCapturer 已完成停止作業，並返回同步運作模式。

時間與溢位

由 AudioCapturer 執行個體產生的所有媒體封包，其 PTS 欄位會填入音訊的擷取時間，以參考時鐘時間軸提供的時間戳記表示。注意：這個時間戳記實際上是擷取時間戳記，而不是呈現時間戳記 (比 PTS 還多)，主要用來代表基礎系統對第一個音訊影格擷取時間的最佳預估時間，包括所有外板和硬體引發的緩衝延遲時間。因此，AudioCapturer 產生的所有時間戳記應都在過去 (相對於串流參考時鐘時間軸上的「現在」)。

「所有內容都有明確的時間戳記」規則的例外是，在同步模式下作業時捨棄提交的區域。捨棄的封包不含任何資料，但 FIDL 要求執行所有待處理方法傳回值回呼。因此，區域會傳回使用者，但時間戳記會設為 NO_TIMESTAMP，而酬載大小會設為零。部分填入的酬載將具有有效的時間戳記，但酬載大小比最初要求少。最後一個捨棄的酬載 (如果有可捨棄) 後面會接著 OnEndOfStream 事件。

如果第二個封包包含的音訊影格在第一個封包中的音訊最後一個影格後，剛好擷取到一個命名影格時間，然後由 AudioCapturer 執行個體傳遞的兩個 StreamPack 是「連續」。如果這個關係未保留，第二個 StreamPacket 會在其 flags 欄位中設定 STREAM_PACKET_FLAG_DISCONTINUITY 位元。

即使每次產生的 StreamPacket 都會提供明確的時間戳記，我們仍建議依照上次停止時間後傳送的影格數量來計算時間，避免只使用原始擷取時間戳記。這是因為在持續封包上寫入的明確時間戳記，可能會因為拍攝時間軸參考時鐘是否因所選音訊影格速率而異，而有少量的捨入錯誤。

使用者應一律預期 AudioCapturer 產生的第一個 StreamPacket 設定含有不連續標記，因為之前沒有其他封包。同樣地，在 IgnoreAllPackets 或 Stop/Start 週期之後的第一個 StreamPacket 將一律中斷。之後，StreamPacket 停止連續的兩個原因可能只有以下兩個：

使用者以同步模式運作，且提供的地區不足以快速填滿。如果未在需要從來源緩衝區清除資料的下一個連續連續影格時，發生溢位就會發生溢位，這時 AudioCapturer 會將下一個擷取的區域標記為不連續。
使用者以非同步模式運作，某些內部錯誤會阻礙 AudioCapturer 執行個體以連續方式擷取下一個音訊畫面。這可能是系統負載過高或硬體錯誤，但一般來說，這種情況應該不會發生。但在實務上，如果會，系統會將下一個產生的封包標記為停機。

同步與非同步的取捨

使用者可自行決定要在同步或非同步模式下操作，而且視使用者的需求而定，這兩種方式各有優缺點。

同步模式在背景只需要一個 Zircon 管道，因此可以節省一些小量。此外，使用者還能完全控管緩衝區管理作業。使用者可以明確指定音訊擷取的位置和順序。因此，如果使用者不需要一律擷取資訊，只要停止並稍後再重新啟動擷取作業即可 (只要停止提供封包，稍後再繼續擷取即可)。無論酬載大小，都不需要統一，用戶端可以指定合適的精細程度酬載。

同步模式的主要缺點是，如要擷取每個封包，就必須傳送兩則訊息。其中一個用於告知 AudioCapturer 要擷取的執行個體，另一個用於通知使用者系統已擷取封包。最終可能會增加負擔，並有可能使用戶端設計變複雜。

非同步模式的優點是只需要 1/2 的訊息，但在「非同步」模式下操作時，AudioCapturer 執行個體無法得知使用者是否正在處理即時傳送的 StreamPackets，並且無法自動偵測溢位狀況。「非同步」模式的使用者應謹慎使用大小適中的緩衝區，確保在 AudioCapturer 強制覆寫資料時，使用者能夠處理資料。

AddPayloadBuffer

將酬載緩衝區新增至目前與連線相關聯的緩衝區組合。StreamPacket 結構結構會使用 StreamPacket.payload_buffer_id 欄位，參照目前組合中的酬載緩衝區。

叫用這個方法時，ID 為 id 的緩衝區不得位於目前集合中，否則服務會關閉連線。

要求

名稱	類型
`id`	`uint32`
`payload_buffer`	`handle<vmo>`

BindGainControl

繫結至這個 AudioCapturer 的增益控制。

要求

名稱	類型
`gain_control_request`	`server_end<fuchsia.media.audio/GainControl>`

CaptureAt

明確指定共用酬載緩衝區的區域，供音訊輸入擷取。

要求

名稱	類型
`payload_buffer_id`	`uint32`
`payload_offset`	`uint32`
`frames`	`uint32`

回應

名稱	類型
`captured_packet`	`StreamPacket`

DiscardAllPackets

要求

<EMPTY>

回應

<EMPTY>

DiscardAllPacketsNoReply

要求

<EMPTY>

GetReferenceClock

擷取串流的參考時鐘。傳回的帳號代碼將擁有「READ」、「DUPLICATE」和「TRANSFER」權利，且會參照「MONOTONIC」和「CONTINUOUS」的 zx::clock。

要求

<EMPTY>

回應

名稱	類型
`reference_clock`	`handle<clock>`

GetStreamType

取得目前設定的串流類型。注意：如果是剛建立且尚未明確設定串流類型的 AudioCapturer，系統會擷取 AudioCapturer 繫結來源 (輸入或循環輸出輸出) 的串流類型，也就是在建立 AudioCapturer 時繫結的串流類型。即使這符合用戶端所需的格式，仍須呼叫 SetPcmStreamType。

要求

<EMPTY>

回應

名稱	類型
`stream_type`	`StreamType`

OnEndOfStream

表示串流已結束。

回應

<EMPTY>

OnPacketProduced

這個外掛程式能傳送服務產生的封包。當用戶端使用完酬載記憶體時，用戶端必須呼叫 ReleasePacket 來釋出酬載記憶體。

回應

名稱	類型
`packet`	`StreamPacket`

ReleasePacket

釋出與先前透過 OnPacketProduced 傳送的封包相關聯的酬載記憶體。

要求

名稱	類型
`packet`	`StreamPacket`

RemovePayloadBuffer

從目前與連線相關聯的緩衝區組合中移除酬載緩衝區。

叫用此方法時，ID 為 id 的緩衝區必須存在於目前集合中，否則服務會關閉連線。

要求

名稱	類型
`id`	`uint32`

SetPcmStreamType

設定要放送的串流類型。視需要將來源內容重新格式化/重新取樣，以產生要求的串流類型。必須在建立酬載緩衝區之前呼叫。

要求

名稱	類型
`stream_type`	`AudioStreamType`

SetReferenceClock

設定控制此擷取器播放速率的參考時鐘。如果輸入參數是有效的 zx::clock，則必須具備 READ、DUPLICATE、TRANSFER 權限，且指的是同時具有 MONOTONIC 和 CONTINUOUS 的時鐘。如果傳遞無效的時鐘 (例如未經初始化的 zx::clock())，這表示串流會使用 AudioCore 產生的「彈性」時鐘 (追蹤音訊裝置)。

新增擷取器酬載緩衝區後，就無法呼叫 SetReferenceClock。也無法再次呼叫這項作業 (即使是在擷取之前也不例外)。如果用戶端需要最初 CLOCK_MONOTONIC 的參考時鐘，但稍後可能會有所變化，則應建立單純時鐘的複本，將其設為串流的參考時鐘，然後視需要進行速率調整。

要求

名稱	類型
`reference_clock`	`handle<clock>?`

SetUsage

設定擷取串流的使用。這可能會即時變更，但傳輸中的封包可能會受到新的用法影響。擷取器預設使用 FOREGROUND 用途。

要求

名稱	類型
`usage`	`AudioCaptureUsage`

StartAsyncCapture

將 AudioCapturer 設為「async」擷取模式，並開始產生確切的「frames_per_packet」影格的封包。StreamSink 的 OnPacketProduced 事件將用於通知用戶端產生的封包。

要求

名稱	類型
`frames_per_packet`	`uint32`

StopAsyncCapture

停止以「非同步」擷取模式擷取，並 (選擇性) 提供可在需要明確同步處理時，用戶端可能會使用的回呼。

要求

<EMPTY>

回應

<EMPTY>

StopAsyncCaptureNoReply

要求

<EMPTY>

AudioConsumer

播放及控制音訊的介面。

BindVolumeControl

繫結至這個 AudioConsumer 音量控制項，以便控管和通知。

要求

名稱	類型
`volume_control_request`	`server_end<fuchsia.media.audio/VolumeControl>`

CreateStreamSink

為具有指定屬性的取用端建立 StreamSink。

您可以透過這個方法取得多個串流接收器，但這些接收器需要依序使用，而非並行使用。使用這個方法建立的第一個串流接收器可做為傳入邏輯取用端的唯一封包來源，直到串流接收器關閉或該接收器呼叫 EndOfStream 方法為止。此時會使用第二個串流接收器，依此類推。

如果提供了不支援的壓縮類型，則會以 ZX_ERR_INVALID_ARGS 的單數值為關閉 stream_sink_request 要求。

要求

名稱	類型
`buffers`	`vector<vmo>[16]`
`stream_type`	`AudioStreamType`
`compression`	`Compression?`
`stream_sink_request`	`server_end<StreamSink>`

OnEndOfStream

表示串流結束前的最後一個封包已經轉譯。

回應

<EMPTY>

SetRate

要求變更轉譯器播放速率。1.0 表示正常播放。不支援負費率。更新後的狀態會反映新的費率。任何新建的 StreamSink 預設速率都是 1.0。

要求

名稱	類型
`rate`	`float32`

開始

如 flags 所指示開始算繪。

media_time 表示與 reference_time 對應的封包時間戳記。通常這是第一個轉譯的封包時間戳記。如果提供的封包沒有時間戳記，這個值應為 NO_TIMESTAMP。傳遞 NO_TIMESTAMP 的 media_time 值會選擇預設的媒體時間，建立方式如下：1. 首次開始時，預設媒體時間是指傳送至串流接收器的第一個封包的時間戳記。2. 停止後繼續播放時，預設媒體時間是指串流停止的媒體時間。

reference_time 是應開始算繪的單調系統時間。若是供應導向的來源，這必須是傳送第一個封包 (或即將傳送) 的時間加上前置時間，這個時間必須落在 AudioConsumerStatus 中指定的範圍內。以需求為導向的來源，客戶必須確保在開始時間符合前置時間要求。如果將預設值 0 傳遞給 reference_time，取用端就會根據封包的可用性、前置時間要求，以及是否已指定 LOW_LATENCY 來選擇開始時間。

實際的開始時間將反映在更新後的狀態中。

要求

名稱	類型
`flags`	`AudioConsumerStartFlags`
`reference_time`	`zx/Time`
`media_time`	`int64`

停止

呼叫此方法後，盡快停止轉譯。實際的停靠時間將反映在更新後的狀態中。

要求

<EMPTY>

WatchStatus

使用長取得模式取得取用者目前的狀態。狀態變更時，取用端就會針對先前回報的狀態值而回應這個方法，一開始只會針對初始狀態值傳回。

要求

<EMPTY>

回應

名稱	類型
`status`	`AudioConsumerStatus`

AudioCore

BindUsageVolumeControl

繫結至指定用量的音量控制通訊協定。

要求

名稱	類型
`usage`	`Usage`
`volume_control`	`server_end<fuchsia.media.audio/VolumeControl>`

CreateAudioCapturer

建立 AudioCapturer，這個方法是從目前的預設音訊輸入裝置擷取，或根據為回送標記所傳遞的值，從目前的預設音訊輸出裝置循環播放。

要求

名稱	類型
`loopback`	`bool`
`audio_in_request`	`server_end<AudioCapturer>`

CreateAudioCapturerWithConfiguration

根據指定需求建立 AudioCapturer。

pcm_stream_type 會設定要放送的串流類型。這會導致來源內容視需要重新格式化/重新取樣，以便產生要求的串流類型。

Fuchsia 使用 usage 來決定使用者體驗。詳情請參閱 AudioCaptureUsage。

configuration 必須初始化為變化版本，或是無法建立擷取器。

要求

名稱	類型
`stream_type`	`AudioStreamType`
`configuration`	`AudioCapturerConfiguration`
`audio_capturer_request`	`server_end<AudioCapturer>`

CreateAudioRenderer

建立 AudioRenderer，可將音訊輸出到預設裝置。

要求

名稱	類型
`audio_out_request`	`server_end<AudioRenderer>`

EnableDeviceSettings

已淘汰

要求

名稱	類型
`enabled`	`bool`

GetDbFromVolume

查詢對應至特定 usage 的體積百分比 [0, 1] 的分貝值。這與 BindUsageVolumeControl 中 VolumeControl 的對應相同。

要求

名稱	類型
`usage`	`Usage`
`volume`	`float32`

回應

名稱	類型
`gain_db`	`float32`

GetVolumeFromDb

查詢與特定 usage 的 gain_db 值相對應的量百分比 [0, 1]。這與 BindUsageVolumeControl 中 VolumeControl 使用的對應相同。

要求

名稱	類型
`usage`	`Usage`
`gain_db`	`float32`

回應

名稱	類型
`volume`	`float32`

LoadDefaults

重新載入平台政策設定。如果平台未提供設定，則會改回預設設定。

要求

<EMPTY>

ResetInteractions

重新初始化目前管理 audio_core 中串流互動的規則組合。預設行為是「NONE」。

要求

<EMPTY>

SetCaptureUsageGain

設定擷取器套用的用量增益。根據預設，所有擷取用量的增益會設為 Unity (0 db)。

要求

名稱	類型
`usage`	`AudioCaptureUsage`
`gain_db`	`float32`

SetInteraction

設定 audio_core 可同時處理多個進行中串流的互動。如果用量 active 的串流正在處理音訊，而且 affected 的串流也是如此，則指定的行為會套用至「用量」affected 的串流。

要求

名稱	類型
`active`	`Usage`
`affected`	`Usage`
`behavior`	`Behavior`

SetRenderUsageGain

設定套用至轉譯器的「使用率提升」。根據預設，所有轉譯用量的增益會設為 Unity (0 db)。

要求

名稱	類型
`usage`	`AudioRenderUsage`
`gain_db`	`float32`

AudioDeviceEnumerator

AddDeviceByChannel

淘汰

系統已不再支援 StreamConfig，請改用 Audio Composite (請參閱音訊驅動程式架構)。

已淘汰：20

要求

名稱	類型
`device_name`	`string[256]`
`is_input`	`bool`
`channel`	`fuchsia.hardware.audio/StreamConfig`

GetDeviceGain

增益集/靜音/AGC 控制項

請注意，每項作業都需要 device_token 來指定適當的輸入/輸出。

Get 指令會傳回裝置獲得回報的 device_token；如果要求的 device_token 無效，或是裝置在 Get 指令處理前已從系統中移除，則可傳回 ZX_KOID_INVALID。

設定讓指定無效裝置權杖的指令遭到忽略，且不會對系統造成任何影響。此外，使用者不需要在每次呼叫時，控制音訊裝置的所有取得設定。只有已設定在 set_flags 參數中相應旗標的設定會受到影響。舉例來說，傳遞 SetAudioGainFlag_MuteValid 會導致 SetDeviceGain 呼叫只關注 gain_info 結構中的靜音設定，而傳遞 (SetAudioGainFlag_GainValid | SetAudioGainFlag_MuteValid) 資料會導致靜音和增益狀態同時發生變更。

要求

名稱	類型
`device_token`	`uint64`

回應

名稱	類型
`device_token`	`uint64`
`gain_info`	`AudioGainInfo`

GetDevices

取得目前正在使用的音訊裝置清單。

要求

<EMPTY>

回應

名稱	類型
`devices`	`vector<AudioDeviceInfo>`

OnDefaultDeviceChanged

已淘汰

回應

名稱	類型
`old_default_token`	`uint64`
`new_default_token`	`uint64`

OnDeviceAdded

新增或移除裝置時，或是裝置屬性變更時傳送的事件。

回應

名稱	類型
`device`	`AudioDeviceInfo`

OnDeviceGainChanged

回應

名稱	類型
`device_token`	`uint64`
`gain_info`	`AudioGainInfo`

OnDeviceRemoved

回應

名稱	類型
`device_token`	`uint64`

SetDeviceGain

要求

名稱	類型
`device_token`	`uint64`
`gain_info`	`AudioGainInfo`
`valid_flags`	`AudioGainValidFlags`

AudioRenderer

定義於 fuchsia.media/audio_renderer.fidl

AudioRender 隨時可以處於兩種狀態的其中一種：「可設定」或「操作」。只要轉譯器有要轉譯的封包排入佇列，就算是運作；否則，這個轉譯器可以「可設定」。AudioRenderer 進入作業狀態後，系統會禁止對「設定」方法的呼叫，並會導致音訊服務中斷用戶端的連線。以下為設定方法：AddPayloadBuffer、SetPcmStreamType、SetStreamType、SetPtsUnits、SetPtsContinuityThreshold。

如果必須重新設定 AudioRenderer，用戶端必須確保在呼叫這些「設定」方法時，沒有任何封包仍排入佇列。因此，最佳做法是先在 AudioRenderer 上呼叫 DiscardAllPackets (最好在 DiscardAllPackets 之前呼叫 Stop)，然後再重新設定轉譯器。

AddPayloadBuffer

將酬載緩衝區新增至目前與連線相關聯的緩衝區組合。StreamPacket 結構結構會使用 StreamPacket.payload_buffer_id 欄位，參照目前組合中的酬載緩衝區。

叫用這個方法時，ID 為 id 的緩衝區不得位於目前集合中，否則服務會關閉連線。

要求

名稱	類型
`id`	`uint32`
`payload_buffer`	`handle<vmo>`

BindGainControl

繫結至這個 AudioRenderer 的增益控制。

要求

名稱	類型
`gain_control_request`	`server_end<fuchsia.media.audio/GainControl>`

DiscardAllPackets

捨棄先前透過 SendPacket 或 SendPacketNoReply 傳送但尚未釋放的封包。在所有封包發布後，系統就會傳送回應。

要求

<EMPTY>

回應

<EMPTY>

DiscardAllPacketsNoReply

捨棄先前透過 SendPacket 或 SendPacketNoReply 傳送但尚未釋放的封包。

要求

<EMPTY>

EnableMinLeadTimeEvents

啟用或停用這個 AudioRenderer 最短時鐘前置時間 (以奈秒為單位) 的通知。如果在將「enabled」設為 true 的情況下呼叫這個方法，系統會立即觸發 AudioRenderer 目前的最短前置時間 OnMinLeadTimeChanged 事件。如果值改變，系統就會以新的值引發 OnMinLeadTimeChanged 事件。這個行為會持續到使用者呼叫 EnableMinLeadTimeEvents(false) 為止。

「最短時鐘前置時間」是指封包必須送達的時間 (相對於播放時鐘轉換)，封包必須送達的時間 (相對於播放時鐘轉換)，才可組合，也就是參照時鐘所瞭解之前所需的時間。例如...

讓 X 封包的 PTS 為 P(X)
讓轉換 PTS 的函式 -> RefClock 為 R(p) (這個函式取決於對 Play 的呼叫(...)
盡量縮短前置時間

如果 R(P(X)) < RefClock.Now() + MLT 這個封包就是延遲，而封包的部分 (或全部) 必須略過，才能在排定的時間顯示封包。

min_lead_time_nsec = 0 值是一個特殊值，表示 AudioRenderer 尚未轉送至輸出裝置。如果在 AudioRenderer 轉送前呼叫 Play，系統會捨棄任何播放的封包。用戶端應等到 min_lead_time_nsec > 0 後再呼叫 Play。

要求

名稱	類型
`enabled`	`bool`

EndOfStream

表示串流已結束。這個方法的精確語意取決於繼承介面。

要求

<EMPTY>

GetMinLeadTime

雖然您可以在 SetPcmStreamType 之前呼叫 GetMinLeadTime，但沒什麼理由這麼做。這是因為前置時間是格式/費率函式，因此系統會在 SetPcmStreamType 後重新計算前置時間。如果在 SetPcmStreamType 之前 (搭配 EnableMinLeadTimeEvents(true)) 啟用最低前置時間事件，系統就會產生回應 SetPcmStreamType 的事件。

要求

<EMPTY>

回應

名稱	類型
`min_lead_time_nsec`	`int64`

GetReferenceClock

擷取串流的參考時鐘。傳回的帳號代碼將擁有「READ」、「DUPLICATE」和「TRANSFER」權利，且會參照「MONOTONIC」和「CONTINUOUS」的 zx::clock。

要求

<EMPTY>

回應

名稱	類型
`reference_clock`	`handle<clock>`

OnMinLeadTimeChanged

回應

名稱	類型
`min_lead_time_nsec`	`int64`

暫停

立即將 AudioRenderer 設為暫停狀態，然後回報建立媒體和參考時間軸 (如有要求) 之間的關係。

進行此呼叫時，如果 AudioRenderer 處於暫停狀態，系統會傳回先前建立的時間軸值 (如果要求)。

要求

<EMPTY>

回應

名稱	類型
`reference_time`	`int64`
`media_time`	`int64`

PauseNoReply

要求

<EMPTY>

播放

立即將 AudioRenderer 進入播放狀態。使用呼叫端提供的特定值 (或如果未指定預設值，則使用預設值) 啟動媒體時間軸的提前。在選用的回呼中，會傳回最終使用的時間戳記值，這些設定會設定媒體與參考時間軸之間的持續關係 (即如何在顯示時間戳記的網域與本機系統時間的領域之間進行轉譯)。

當地系統時間以奈秒為單位； media_time 是以使用者在 SetPtsUnits 函式中定義的單位指定；如果未呼叫 SetPtsUnits，則指定奈秒。

將 AudioRenderer 放入播放狀態的效果，可建立 1) 使用者針對這個特定 AudioRenderer 定義的媒體 (或呈現) 時間軸，以及 2) 實際系統參考時間軸之間的關係。為了溝通如何在時間軸之間進行轉譯，Play() 回呼會在每個時間網域中提供對等的時間戳記。第一個值 (「reference_time」) 按照這個轉譯器的參照時鐘指定；第二個值 (「media_time」) 則是媒體即時對應至該當地時間的時間點。休息時，音訊串流中「media_time」的影格應根據參考時鐘，在「reference_time」顯示。

注意：當呼叫這個 API 時， media_time 會立即啟動。呼叫端指定的系統時間可能是過去或未來的系統時間 (在不常見的情況下)。只需使用這個值和指定的媒體時間，即可判斷媒體時間對應到「現在」的時間，接著媒體時間會與已提交的封包顯示時間戳記交錯，以判斷接下來應顯示哪些媒體影格。

透過對應的 reference_time 和 media_time 值，使用者可將某個時間軸的任意時間值轉譯為另一個時間軸。呼叫 SetPtsUnits(pts_per_sec_numerator, pts_per_sec_denominator) 並取得 Play 的「ref_start」和「media_start」值後，接著適用於任何「ref_time」：

media_time = ( (ref_time - ref_start) / 1e9 * (pts_per_sec_numerator / pts_per_sec_denominator) ) + media_start

反之，如果是任何顯示時間戳記「media_time」：

ref_time = ( (media_time - media_start) * (pts_per_sec_denominator / pts_per_sec_numerator) * 1e9 ) + ref_start

視使用者的用途而定，使用者可選擇不要指定其中一個時間戳記，或是兩者都不要指定。提供特殊值「NO_TIMESTAMP」可以省略時間戳記。AudioRenderer 會使用以下規則自動推斷任何省略的時間戳記值：

參照時間如果省略「reference_time」，AudioRenderer 會根據目前繫結此 AudioRenderer 的輸出裝置最短的前置時間，選取「安全」參照時間以開始簡報。舉例來說，如果 AudioRenderer 繫結至包含至少 3 mSec 的內部音訊輸出，而 HDMI 輸出需要至少 75 m 秒的前置時間，則 AudioRenderer 可能會 (如果省略「reference_time」) 從現在選取參考時間 80 分。

如果省略 media_time，AudioRenderer 會選擇兩個值中的其中一個。

如果 AudioRenderer 從暫停狀態繼續恢復，且封包在暫停後沒有遭到捨棄，則 AudioRenderer 會使用相應的 media_time 值，而不是呈現暫停畫面的時間點。
如果 AudioRenderer 在啟動或「捨棄封包」作業後首次進入播放狀態，系統會將初始 media_time 設為待處理封包佇列中第一個酬載的 PTS。如果待處理佇列為空白，初始 media_time 會設為零。

收到要求時，AudioRenderer 會傳回 Play 呼叫傳回值中選取的「reference_time」和「media_time」(無論是否明確指定)。

範例

使用者已使用 SendPacket 將部分音訊排入佇列，並只想盡快開始播放。使用者可在未提供明確的時間戳記 (Play(NO_TIMESTAMP, NO_TIMESTAMP)) 的情況下呼叫 Play。
使用者已使用 SendPacket 將部分音訊排入佇列，並希望在指定的「reference_time」開始播放，以便與一些其他媒體串流同步，不論是最初或捨棄封包之後。使用者會呼叫 Play(reference_time, NO_TIMESTAMP)。
使用者已使用 SendPacket 將部分音訊加入佇列。第一批封包的 PTS 為零，且使用者希望盡快開始播放，但想要略過 PTS 0 和 PTS「media_time」之間的所有音訊內容。使用者會呼叫 Play(NO_TIMESTAMP, media_time)。
使用者已使用 SendPacket 將部分音訊排入佇列，且想要將此媒體與其他裝置上的其他播放器同步。所分散玩家的協調者會向每位玩家傳送明確訊息，指示他們在時間 (根據群組共用的參考時鐘)「reference_time」，在 PTS「media_time」顯示音訊。此時，使用者會呼叫 Play(reference_time, media_time)。

要求

名稱	類型
`reference_time`	`int64`
`media_time`	`int64`

回應

名稱	類型
`reference_time`	`int64`
`media_time`	`int64`

PlayNoReply

要求

名稱	類型
`reference_time`	`int64`
`media_time`	`int64`

RemovePayloadBuffer

從目前與連線相關聯的緩衝區組合中移除酬載緩衝區。

叫用此方法時，ID 為 id 的緩衝區必須存在於目前集合中，否則服務會關閉連線。

要求

名稱	類型
`id`	`uint32`

SendPacket

將封包傳送至服務。服務與相關聯的酬載記憶體完成處理後，系統就會傳送回應。

packet 必須適用於目前緩衝區集，否則服務會關閉連線。

要求

名稱	類型
`packet`	`StreamPacket`

回應

<EMPTY>

SendPacketNoReply

將封包傳送至服務。這個介面未定義接收器如何得知接收器何時使用相關聯的酬載記憶體。繼承介面必須定義該設定。

packet 必須適用於目前緩衝區集，否則服務會關閉連線。

要求

名稱	類型
`packet`	`StreamPacket`

SetPcmStreamType

設定用戶端要傳送的串流類型。使用這個方法表示串流編碼為 AUDIO_ENCODING_LPCM。

您必須在 Play 或 PlayNoReply 之前呼叫這個方法。呼叫 SetPcmStreamType 後，用戶端接著必須傳送 AddPayloadBuffer 要求，然後傳送各種 StreamSink 方法，例如 SendPacket/SendPacketNoReply。

要求

名稱	類型
`type`	`AudioStreamType`

SetPtsContinuityThreshold

設定使用者提供明確使用者提供的 PTS 與預期 PTS 之間的閾值上限 (以秒為單位)。如果超過這個門檻，轉譯器就不會再將串流視為「連續」。

預設為使用目前定義的 PTS 單位的一半 PTS「刻點」。大部分的使用者都不需要變更這個值。

範例：使用者從容器播放 48KHz 音訊，而這個音訊也包含影片，因此需要與音訊同步。時間戳記是由容器明確提供每個封包，並以 mSec 單位表示。也就是說，媒體時間軸 (1 mSec) 的單一刻點就代表 48 個音訊影格。在此情況下，應用程式會將音訊封包傳送給 AudioRenderer，每個封包大小剛好是 470 個音訊影格，每個影格的明確時間戳記都會設為最佳顯示時間 (根據這個媒體時鐘的解析度)。因此，從 0 開始，時間戳記是...

[ 0、10、20、29、39、49、59、69、78、88、... ]

在此範例中，如果嘗試使用顯示時間計算封包中音訊的起始影格數，將不是主要時間。第一個時間戳記是正確的 (根據定義)，但會是時間戳記和影格編號回到校正之前的 24 個封包 (第 24 個封包會從第 11280 個音訊影格開始，並且其 PTS 正好是 235)。

修正這種情況的一種方法是將串流的 PTS 持續性門檻 (即 CT) 設為等於媒體時鐘內含單一刻點的影格數的 1/2，會四捨五入。在此情境中，也就是 24.0 音訊影格或 500 uSec。只要封包預期的 PTS 位於明確提供的 PTS 範圍 +/-CT 影格中，就會視為持續播放上一個音訊影格。在本例中，呼叫「SetPtsContinuityThreshold(0.0005)」是非常不錯的方式。

其他可能的用途：針對未設為參考時鐘的時鐘明確排程音訊的使用者，可在出現停止行為前，使用這個值控制可接受的同步處理錯誤上限。例如，如果使用者根據復原的常見媒體時鐘安排音訊時間，但尚未將該時鐘做為參考時鐘，且他們將 CT 設定為 20mSec，則 AudioRenderer 會刻意將顯示中斷點插入 20 分的偏移錯誤，以顧及這項錯誤。

如果使用者需要處理容器，因為其時間戳記可能比 PTS 滴答的 +/- 1/2 不準確，可以將這個值設為更大的尺寸。如果已知，這應是容器時間戳記中不正確的最大層級。這項作業無法設定為在絕對時間戳記明確遵循的情況下，可容許的最大偏誤層級。最後，使用者可以將這個數字設為非常大的值 (例如 86400.0 秒)，以有效地在第一次收到之後忽略「所有」時間戳記，進而將所有音訊視為先前傳送的封包。反之，如果使用者「一律」明確安排音訊封包排程，則可將 CT 指定為 0。

注意：明確指定高頻率 PTS 單位，可據此降低預設持續性門檻。這個門檻會在內部以 1/8192 子頁框的整數儲存。預設閾值的計算方式如下：RoundUp((AudioFPS/PTSTicksPerSec) * 4096) / (AudioFPS * 8192) 基於上述原因，指定頻率大於 8192 倍的 PTS 單位 (如果未呼叫 SetPtsUnit，則可接受預設 PTS 門檻為 1 nanosec 的預設 PTS 單位)。

要求

名稱	類型
`threshold_seconds`	`float32`

SetPtsUnits

設定顯示 (媒體) 時間軸使用的單位。根據預設，PTS 單位為奈秒 (例如使用 1e9 的分子和分母為 1 呼叫)。這個比例必須介於 1/60 (每分鐘 1 次滴答) 和 1e9/1 (每滴答 1 秒) 之間。

要求

名稱	類型
`tick_per_second_numerator`	`uint32`
`tick_per_second_denominator`	`uint32`

SetReferenceClock

設定控制這個轉譯器播放速率的參照時鐘。如果輸入參數是有效的 zx::clock，則必須具備 READ、DUPLICATE、TRANSFER 權限，且指的是同時具有 MONOTONIC 和 CONTINUOUS 的時鐘。如果傳遞無效的時鐘 (例如未經初始化的 zx::clock())，這表示串流會使用 AudioCore 產生的「彈性」時鐘 (追蹤音訊裝置)。

呼叫 SetPcmStreamType 後，就無法呼叫 SetReferenceClock。也無法再次呼叫 (即使尚未設定轉譯器格式)。如果用戶端需要最初 CLOCK_MONOTONIC 的參考時鐘，但稍後可能會有所變化，則應建立單純時鐘的複本，將其設為串流的參考時鐘，然後視需求進行速率調整。

要求

名稱	類型
`reference_clock`	`handle<clock>?`

SetUsage

設定轉譯串流的用法。呼叫 SetPcmStreamType 後可能無法呼叫此方法。預設用量為 MEDIA。

要求

名稱	類型
`usage`	`AudioRenderUsage`

ProfileProvider

定義於 fuchsia.media/profile_provider.fidl

RegisterHandlerWithCapacity

將執行緒註冊為媒體執行緒。這會通知媒體子系統，為符合音訊或視訊期限，這個執行緒應套用進階的排程設定檔。

name 是要套用至 thread_handle 提供的執行緒的系統排程角色名稱，不同的產品可能會根據要求的角色自訂基礎排程策略。period 是系統建議的排程間隔。如果執行緒沒有偏好的排程間隔，period 可以是零。capacity 是指執行緒必須執行以達到良好效能或符合 period 定義的排程期限的排程間隔比例。如果工作負載沒有明確的執行階段要求，capacity 可以是零。請注意，根據執行緒每個時段所需的最糟情況，capacity 應該是合理估計值。資源用量過大要求可能會遭到拒絕，或導致其他執行緒的效能縮減，以符合資源限制。

容量、最長執行階段和期間有下列關係：

容量 = 執行階段上限 / 週期

在此情況下：

0 <= 執行階段上限 <= 期間，0 <= 容量 <= 1

至於異質系統，應根據系統中最高效能處理器規劃 / 測量容量。系統會自動調整有效容量，以因應較慢的處理器和作業點，並避免速度過慢的處理器和作業點，無法符合要求的排程參數 (前提是這些項目在合理範圍內)。

傳回已套用的週期和容量 (實際最長執行階段上限)，其中任一值可能是零來表示不適用。

要求

名稱	類型
`thread_handle`	`handle<thread>`
`name`	`string[64]`
`period`	`zx/Duration`
`capacity`	`float32`

回應

名稱	類型
`period`	`zx/Duration`
`capacity`	`zx/Duration`

RegisterMemoryRange

註冊用於媒體處理的記憶體範圍。這會通知媒體子系統，為符合音訊或視訊期限，這個記憶體應套用較高的記憶體設定檔。

name 是要套用至 vmar_handle 所提供記憶體的系統記憶體角色名稱，不同的產品可能會根據要求的角色自訂基礎記憶體策略。

新增時間：15 張

要求

名稱	類型
`vmar_handle`	`handle<vmar>`
`name`	`string[64]`

回應

<EMPTY>

UnregisterHandler

將執行緒的排程設定檔重設為預設值。

要求

名稱	類型
`thread_handle`	`handle<thread>`
`name`	`string[64]`

回應

<EMPTY>

UnregisterMemoryRange

重設記憶體範圍的記憶體設定檔。

新增時間：15 張

要求

名稱	類型
`vmar_handle`	`handle<vmar>`

回應

<EMPTY>

SessionAudioConsumerFactory

建立繫結至工作階段的音訊使用者介面。

CreateAudioConsumer

建立 AudioConsumer，這是播放音訊的介面，並繫結至特定工作階段。session_id 是要算繪音訊的媒體工作階段 ID。

要求

名稱	類型
`session_id`	`uint64`
`audio_consumer_request`	`server_end<AudioConsumer>`

SimpleStreamSink

定義於 fuchsia.media/stream.fidl

使用 StreamBufferSet 管理緩衝區的 StreamSink。

AddPayloadBuffer

將酬載緩衝區新增至目前與連線相關聯的緩衝區組合。StreamPacket 結構結構會使用 StreamPacket.payload_buffer_id 欄位，參照目前組合中的酬載緩衝區。

叫用這個方法時，ID 為 id 的緩衝區不得位於目前集合中，否則服務會關閉連線。

要求

名稱	類型
`id`	`uint32`
`payload_buffer`	`handle<vmo>`

DiscardAllPackets

捨棄先前透過 SendPacket 或 SendPacketNoReply 傳送但尚未釋放的封包。在所有封包發布後，系統就會傳送回應。

要求

<EMPTY>

回應

<EMPTY>

DiscardAllPacketsNoReply

捨棄先前透過 SendPacket 或 SendPacketNoReply 傳送但尚未釋放的封包。

要求

<EMPTY>

EndOfStream

表示串流已結束。這個方法的精確語意取決於繼承介面。

要求

<EMPTY>

RemovePayloadBuffer

從目前與連線相關聯的緩衝區組合中移除酬載緩衝區。

叫用此方法時，ID 為 id 的緩衝區必須存在於目前集合中，否則服務會關閉連線。

要求

名稱	類型
`id`	`uint32`

SendPacket

將封包傳送至服務。服務與相關聯的酬載記憶體完成處理後，系統就會傳送回應。

packet 必須適用於目前緩衝區集，否則服務會關閉連線。

要求

名稱	類型
`packet`	`StreamPacket`

回應

<EMPTY>

SendPacketNoReply

將封包傳送至服務。這個介面未定義接收器如何得知接收器何時使用相關聯的酬載記憶體。繼承介面必須定義該設定。

packet 必須適用於目前緩衝區集，否則服務會關閉連線。

要求

名稱	類型
`packet`	`StreamPacket`

StreamBufferSet

定義於 fuchsia.media/stream.fidl

管理串流的一組酬載緩衝區。這個介面通常會與 StreamSink 或 StreamSource 一起繼承，以在用戶端與服務之間傳輸元素串流。

AddPayloadBuffer

將酬載緩衝區新增至目前與連線相關聯的緩衝區組合。StreamPacket 結構結構會使用 StreamPacket.payload_buffer_id 欄位，參照目前組合中的酬載緩衝區。

叫用這個方法時，ID 為 id 的緩衝區不得位於目前集合中，否則服務會關閉連線。

要求

名稱	類型
`id`	`uint32`
`payload_buffer`	`handle<vmo>`

RemovePayloadBuffer

從目前與連線相關聯的緩衝區組合中移除酬載緩衝區。

叫用此方法時，ID 為 id 的緩衝區必須存在於目前集合中，否則服務會關閉連線。

要求

名稱	類型
`id`	`uint32`

StreamProcessor

作業總覽：

建立

透過 CodecFactory 建立 - 參閱 CodecFactory
透過 LicenseSession 建立 - 請參閱 LicenseSession

取得輸入限制

OnInputConstraints() - 在建立串流處理器後不久，串流處理器會傳送來路不明的訊息。

提供輸入緩衝區

SetInputBufferPartialSettings()

提交輸入資料

QueueInputPacket() + OnFreeInputPacket() 可逾時，但可能就此之前多次處理所有輸入封包...

取得輸出限制和格式

OnOutputConstraints()
這個元件會在用戶端至少傳送一則 QueueInput* 訊息後傳送該訊息，即使 StreamProcessor 背後的基礎處理器在根本不需要任何輸入資料即可判斷輸出限制也是如此。這個伺服器行為可避免用戶端在輸入傳送前，對顯示的輸出限製做出不正確的依附元件。
在傳送大量輸入資料後 (包括透過 OnFreeInputPacket() 回收大量輸入封包)，用戶端必須容許此延遲抵達的時間。
在第一次輸出資料之前，這則訊息可能會多次送達。

提供輸出緩衝區

SetOutputBufferPartialSettings() / CompleteOutputBufferPartialSettings()

資料流程 (選用 EndOfStream)

OnOutputPacket() / RecycleOutputPacket() / QueueInputPacket() / OnFreeInputPacket() / QueueInputEndOfStream() / OnOutputEndOfStream()

半信任的串流處理器伺服器 - SW 解碼器會以獨立 (功能極少) 的方式執行，以免解碼 SW 含有安全漏洞，用來接管 StreamProcessor 伺服器。在遠大於其他介面的情況下，串流處理器介面的用戶端會使用解碼器和處理個別安全性情境的串流，保護自身免於無效的伺服器行為，例如完全不含 packet_index 的行為，以及其他無效的伺服器行為。從一種安全性情境中填入壓縮資料後，請不要在單一 StreamProcessor 執行個體中放置太多信任資料，不要在先前已向 StreamProcessor 伺服器指出的任何緩衝區之間混用資料。請改為建立個別的 StreamProcessor 執行個體，供不同安全性的用戶端內容使用。雖然 HW 型解碼器的圖片看起來有點不同，且不在這個段落的範圍內，但用戶端仍應使用獨立的 StreamProcessor 執行個體，處理獨立的用戶端內容。

此通訊協定的方法所採取的行動和事項狀態的說明，會以類似串流處理器伺服器同步執行的方法提供，但實際上，訊息處理是非同步的 FIDL 介面。除非另有說明，否則描述的狀態會從用戶端視角讀取。從伺服器傳回的事件當然就是以非同步方式傳送，而如果每個 StreamProcessor 執行個體處理多個串流的用戶端需要注意特定事件是來自目前的串流，還是某些較舊的閒置串流，就必須注意。

Sync() 方法的主要用途是讓用戶端明確防止在系統中同時分配新舊緩衝區，因為媒體緩衝區可能會大幅較大，視媒體緩衝區而定。Sync() 方法只有在所有先前對 StreamProcessor 通訊協定的呼叫均在 StreamControl 排序網域中生效時，才傳送回應，才能達成上述目標。如果用戶端可能過於遠離 StreamProcessor 伺服器 (例如要求在一列中建立大量串流)，也可以使用 Sync() 等待串流處理器伺服器接收最新資料。也可以在偵錯期間使用，確保串流處理器伺服器不會卡住。呼叫 Sync() 完全非必要，且絕對不需要，因為可能只需要排除重疊的資源用量。

您可以將 StreamProcessor 執行個體重複使用在其他串流，這種做法有時可能會略過重新分配緩衝區的程序。當你在尋找新位置時 (可透過 StreamProcessor 介面切換至新的串流)，這種做法就能派上用場。

CloseCurrentStream

這樣會「關閉」目前的串流，但不會離開目前的串流。此外，這則訊息可以選擇是否釋出輸入緩衝區或輸出緩衝區。

如果沒有任何進行中的串流，stream_lifetime_ordinal 必須為 0，否則伺服器會關閉管道。如有正在執行的串流，stream_lifetime_ordinal 必須是最近的有效串流，無論該串流是否仍在進行中。否則，伺服器會關閉管道。

如果訊息之間沒有任何新使用中的串流，則這些訊息不會視為錯誤，這可讓用戶端利用這則訊息關閉目前串流，停止在使用者不再關注的串流上浪費處理效能，之後再決定應釋出緩衝區並再次傳送這則訊息，且在嘗試讓用戶端緩衝區之間釋放 buffer 並/或 release_output_buffers，避免在用戶端緩衝區之間重疊，且在兩者之間保留新串流。

另請參閱 Sync()。

要求

名稱	類型
`stream_lifetime_ordinal`	`uint64`
`release_input_buffers`	`bool`
`release_output_buffers`	`bool`

CompleteOutputBufferPartialSettings

SetOutputBufferPartialSettings() 之後，伺服器在用戶端傳送 CompleteOutputBufferPartialSettings() 之後才會傳送 OnOutputConstraints()、OnOutputFormat()、OnOutputPacket() 或 OnOutputEndOfStream()。

部分用戶端或許可以在 SetOutputBufferPartialSettings() 之後傳送 CompleteOutputBufferPartialSettings() - 在此情況下，用戶端必須做好準備才能接收輸出，但不知道緩衝區數量或封包數量，這類用戶端可能會在內部延遲處理所接收的輸出內容，直到用戶端知道 sysmem 的緩衝區數量和封包數量為止。

其他用戶端可能會先等待 sysmem 進行分配、準備接收輸出，然後傳送 FullOutputBufferPartialSettings()。

要求

名稱	類型
`buffer_lifetime_ordinal`	`uint64`

EnableOnStreamFailed

允許伺服器在串流失敗時使用 OnStreamFailed()，而非伺服器，僅關閉整個 StreamProcessor 管道。

如果串流失敗時伺服器未顯示這則訊息，伺服器會關閉 StreamProcessor 管道，而非傳送 OnStreamFailed()。

要求

<EMPTY>

FlushEndOfStreamAndCloseStream

此為選填訊息。

此訊息僅在這個串流的 QueueInputEndOfStream() 之後才有效。stream_lifetime_ordinal 輸入參數必須與 QueueInputEndOfStream() 的 stream_lifetime_ordinal 相符，否則伺服器會關閉管道。

用戶端可以使用這個訊息來清除 (而非捨棄) 串流的最後一個輸入資料，讓串流處理工具伺服器在所有輸入資料進入下一個串流之前，產生對應的輸出資料，而不會強迫用戶端等待 OnOutputEndOfStream() 再將另一個串流的資料排入佇列。

QueueInputEndOfStream() 和 FlushEndOfStreamAndCloseStream() 之間的差異：QueueInputEndOfStream() 代表用戶端不再有其他串流輸入資料 (而某些串流處理器需要這項資訊，才能發出最後的輸出資料)。已傳送 QueueInputEndOfStream() 並不會導致用戶端之後無法透過關閉目前的串流 (無論是否有串流開關) 徹底捨棄目前的串流。相反地，FlushEndOfStreamAndCloseStream() 是由用戶端發出的要求，會處理所有先前排入佇列的輸入資料，包括在移至任何較新的串流前顯示為 OnOutputEndOfStream() 的邏輯「EndOfStream」(成功情況)，這基本上會將近遊處理程序從捨棄，改為只針對這個串流清除。

使用這則訊息的用戶端可以開始為新串流提供輸入資料，而不會捨棄舊的串流資料。這就是訊息的目的：讓用戶端能清除 (而非捨棄) 舊串流的最後資料，而非在關閉或切換捨棄的串流時的預設值。

由於舊的串流尚未處理完成，而且不會捨棄舊串流的資料，因此用戶端必須準備好繼續處理 OnOutputConstraints() 訊息，直到 stream_lifetime_ordinal 完成為止。當 OnOutputEndOfStream()、OnStreamFailed() 或 StreamProcessor 管道關閉時，用戶端就會知道 stream_lifetime_ordinal 已完成。

要求

名稱	類型
`stream_lifetime_ordinal`	`uint64`

OnFreeInputPacket

當串流處理器用完此封包中的資料時 (但不一定會處理資料)，伺服器就會傳送此訊息，而用戶端可重新填入封包。

在新的 buffer_lifetime_ordinal 開始，系統就不會傳送所有封包，所以一開始所有封包都不會在用戶端中釋放。

透過這個事件收到可用的輸入緩衝區後，串流處理工具用戶端可在設定適當的偏移值和長度 (設有相同的封包_index) 後呼叫 QueueInputBuffer，以便重複使用 packet_index。

OnFreeInputPacket() 不會表示輸入封包中的資料已順利處理，只代表 StreamProcessor 不再需要輸入資料。如果用戶端需要知道哪些輸入資料已產生對應的輸出，建議您使用 timestamp_ish 值。

任何依賴 OnFreeInputPacket() 和 OnStreamFailed() 的相對順序，不建議使用並淘汰。請改用 timstamp_ish 值來建立產生的對應輸出封包。請注意，即使使用 timestamp_ish 值，也不一定意味著具有特定 timestamp_ish 值的輸入資料處理作業已完成，正如在部分 StreamProcessor 中產生的資料，從輸入封包衍生的資料可以無限期保留下來，以便在輸入資料產生主要輸出資料 (時間戳記：timestamp_ish 值的輸出資料) 後長時間保留供參考。StreamProcessor 介面目前無法提供任何方法，導致 StreamProcessor 捨棄所有從輸入封包衍生的資料，且這類機制一旦新增至 StreamProcessor 通訊協定，就會是選用的 StreamProcessor 能力，因為某些依賴外部方式處理資料的 StreamProcessor 實作無法完全捨棄，因為在外部處理的資料不一定需要捨棄輸入封包的衍生資料一律不會為不同串流產生或提供任何輸出資料。

OnFreeInputPacket() 的順序不一定會與 QueueInputPacket() 的順序相同。我們強烈建議不要依賴相同順序並淘汰該順序。即使 OnFreeInputPacket() 訊息的順序因相互關係而遭到破壞，用戶端仍可正常運作 (但目前無法在 OnStreamFailed() 中打散)。

回應

名稱	類型
`free_input_packet`	`PacketHeader`

OnInputConstraints

伺服器會在 StreamProcessor 建立作業完成後不久，就會傳送此訊息，指出輸入緩衝區限制。在 StreamProcessor 的生命週期內，「min」和「max」輸入限制不會改變。

緩衝區大小和數量的「最大值」值夠大，足以支援伺服器在輸入時要求最嚴苛的格式。「建議」值應適用於建立 StreamProcessor 期間所傳輸 FormatDetails 的輸入內容。如果用戶端使用 QueueInputFormatDetails() 變更輸入格式，則「建議」值不一定適合。在這種情況下，由用戶端決定合適的值，您可以改為建立新的 StreamProcessor 執行個體，或瞭解這個通訊協定範圍以外的適當值。

查看 StreamBufferConstraints 的留言。

系統保證會在 StreamProcessor 建立期間或之後不久，將這則訊息未經請求傳送至 StreamProcessor 用戶端。用戶端不應仰賴這是最先送達用戶端的訊息。

特定 StreamProcessor 執行個體不保證「min」和「max」輸入限制不會變更。伺服器處理 QueueInputFormatDetails() 時，「建議」值可能會有效變更。在通訊協定中，除了為用戶端建立新的 StreamProcessor 例項，也沒有任何其他方式，因此無法取得新的「建議」值。

回應

名稱	類型
`input_constraints`	`StreamBufferConstraints`

OnOutputConstraints

這個事件會通知用戶端新的輸出內容限制。

這則訊息會根據其他輸出內容 (例如輸出封包、輸出格式、串流端輸出) 進行排序。

在串流的第一個 OnOutputPacket() 之前，伺服器保證會傳送至少一個 OnOutputConstraints() 和一個 OnOutputFormat()。如果緩衝區設定已適合串流，則伺服器就不得在 OnOutputConstraints() 中設定 buffer_constraints_action_required，(buffer_constraints_action_required false，代表緩衝區設定已順利)。用戶端必須容許多則 OnOutputConstraints() (和 1 則 OnOutputFormat() 訊息) 在第一個輸出封包之前。只要用戶端尚未移至新串流，則除非用戶端設定輸出緩衝區，否則伺服器不會傳送其他 OnOutputConstraints()。

這則訊息可在串流期間由伺服器傳送。如果 buffer_constraints_action_required false，則放心忽略訊息，但用戶端可能會選擇保留新的限制，方便之後用戶端重新設定緩衝區 (如果情況允許)。如果日後伺服器需要變更輸出設定，伺服器可以傳送含有 buffer_constraints_action_required true 的新 OnOutputConstraints()。

在 buffer_constraints_action_required true 上，不想要完整處理串流中輸出緩衝區設定的用戶端應該先完全完成處理程序，或者至少在開始新串流前，至少重新設定輸出內容 (如果用戶端需要重新傳送輸入資料)。這樣可避免在輸出緩衝區設定變更 (會再次達到相同的中串流輸出設定變更) 之前開始新的串流進行無用重試作業。

同樣地，部分伺服器可能只支援中游格式變更，或者只有在緩衝區大小足以處理格式變更前後一併處理時，才會支援中游格式的變更。這類伺服器仍應指出 buffer_constraints_action_required，但然後在用戶端重新設定輸出緩衝區後傳送 OnStreamFailed() (當然，處理中串流輸出設定變更非常好，但視格式而定，有時不一定可行)。當用戶端透過新的串流，從用戶端邏輯整體媒體時間軸中附近的位置開始重新串流時，輸出緩衝區就已經適合較大的輸出，因此新串流不需要任何中游輸出緩衝區重新設定，因此只需要在用戶端嘗試重新設定串流時，才能重新設定輸出緩衝區。我們不建議伺服器傳送 OnStreamFailed()，只是因為在串流中需要不同的輸出緩衝區設定，而未先傳送內含 buffer_constraints_action_required 的 OnOutputConstraints()，並等待用戶端重新設定輸出緩衝區 (以避免無用的用戶端在設定變更前，從邏輯位置重新使用新串流)。

如果 buffer_constraints_action_required 設為 true，伺服器在用戶端設定/重新設定輸出緩衝區之前，不會為此串流傳送任何 OnOutputPacket()。

如果用戶端放棄處理任何中間串流的 OnOutputConstraints() 或中游 OnOutputFormat() 的串流，應完全忽略所有含有 buffer_constraints_action_required false 的 OnOutputConstraints()。否則，用戶端可能幾乎沒有處理作業失敗，或是伺服器實作可能無法使用 buffer_constraints_action_required false，擔心簡單的用戶端中斷連線。

所有用戶端都必須需要處理第一個輸出封包之前的 1..multiple OnOutputConstraints() 訊息，以及第一個輸出封包之前的 1..multiple OnOutputConstraints() 訊息，即使是不想支援任何中串流輸出緩衝區重新設定或中串流的 OnOutputFormat() 訊息都一樣。

此訊息會按照 OnOutputFormat() 的輸出封包排序。

回應

名稱	類型
`output_config`	`StreamOutputConstraints`

OnOutputEndOfStream

由 StreamProcessor 用戶端傳送 QueueInputEndOfStream() 後，在合理的時間範圍內， StreamProcessor 伺服器會傳送對應的 OnOutputEndOfStream()。與 QueueInputEndOfStream() 類似，OnOutputEndOfStream() 每個串流最多會傳送一次。

這則訊息後，系統就不會傳送這個串流的其他串流資料。已處理這個串流的所有輸入資料。

雖然 StreamProcessor 用戶端不需要 QueueInputEndOfStream() (除非用戶端想要使用 FlushEndOfStreamAndCloseStream())，但如果 StreamProcessor 伺服器收到 QueueInputEndOfStream()，且用戶端沒有關閉串流，StreamProcessor 伺服器就必須產生對應的 OnOutputEndOfStream() 伺服器，或者必須在無錯誤的情況下傳送 OnOutputEndOfStream()。理想的 StreamProcessor 伺服器會透過 error_ 旗標處理並回報串流錯誤，且在不傳送 OnStreamFailed() 的情況下完成串流處理。但無論如何，以上列出的選項都是 OnOutputEndOfStream() 在 QueueInputEndOfStream() 之後不會發生的方法。

這則訊息之後，這個 stream_lifetime_ordinal 不會再有 OnOutputPacket() 或 OnOutputConstraints() 訊息。如果伺服器不遵循這項規則，用戶端應關閉 StreamProcessor 管道。

error_detected_before bool 的語意與 OnOutputPacket() 中的 error_detected_before bool 相同。

回應

名稱	類型
`stream_lifetime_ordinal`	`uint64`
`error_detected_before`	`bool`

OnOutputFormat

這個訊息是由伺服器在任何串流的第一個輸出封包之前傳送，也可能在串流的輸出封包之間傳送，也可能是依照輸出封包排序，並依據 OnOutputConstraints() 排序。

伺服器會保證每個串流的第一個封包優先於 OnOutputFormat()。

伺服器會保證 OnOutputConstraints() 與 OnOutputPacket() 之間有 OnOutputFormat()。也就是說，用戶端基本上可以清除任何 OnOutputConstraints() 上的輸出格式，原因是伺服器會在 anyquent OnPacket() 之前提出子 OnPacket()。

如果伺服器在 OnOutputConstraints() 中設定 buffer_constraints_action_required，則在用戶端重新設定輸出緩衝區之前，伺服器不會傳送 OnOutputFormat() (因此也不會傳送 OnOutputPacket())。

伺服器可在兩個輸出封包之間傳送 OnOutputFormat()。

伺服器不會傳送兩則相鄰的 OnOutputFormat() 訊息，且之間沒有輸出封包。但是，OnOutputFormat() 訊息無法保證後續的封包，因為伺服器可能會改為傳送 OnOutputEndOfStream() 或 OnStreamFailed()。

如果客戶不想流暢處理中串流輸出格式變更，則應確保用戶端未處理的任何串流都沒有任何中游格式變更，或是用戶端應確保重試處理作業時，在舊格式結束且新格式開始的時間點後，都會從新的嘗試開始重新嘗試。否則，用戶端可以再次再次變更相同的中串流格式變更。

在串流期間傳送這則訊息的一個例子，就是影片解碼器輸出的影格大小在串流中改變。

並非所有伺服器都能流暢處理格式變更。如果能流暢處理格式變更，則可能需要輸出緩衝區重新設定，才能順利處理格式變更。請參閱 OnOutputConstraints() 的註解區塊，進一步瞭解伺服器和用戶端應如何行為 (尤其是當伺服器和用戶端無法順暢處理輸出限制變更和/或輸出格式變更時)。

如果伺服器未如預期在串流開始時傳送這則訊息，最常見的原因是用戶端尚未處理含有 buffer_constraints_action_required true 的 OnOutputConstraints() (使用 SetOutputBufferPartialSettings() 等設定輸出緩衝區)。

回應

名稱	類型
`output_format`	`StreamOutputFormat`

OnOutputPacket

這是串流處理器向串流處理器用戶端發出輸出封包的方式。

順序十分可觀。

除非 buffer_lifetime_ordinal 已開啟，否則用戶端最終應呼叫 RecycleOutputPacket() (可能多次切換串流後)。串流變更不會改變哪些封包在用戶端忙碌狀態，而非由伺服器釋放。

相關緩衝區一律是封包 buffer_index 欄位中指定的緩衝區。

如果是支援的低階緩衝區類型，StreamProcessor 可在低階緩衝區實際發生緩衝區中任何可用資料時，也能自由發送輸出封包，這種機制能夠發出與 OnOutputPacket() 訊息分隔開來的資料信號。針對這類低階緩衝區類型，所發出的封包中資料下游使用者必須加入低階緩衝區信號機制，才能知道何時可安全使用資料。使用影片解碼器和 gralloc 樣式的緩衝區時，這種現象最可能切合需求。

此錯誤_bool(s) 允許 (但非必要) StreamProcessor 伺服器回報在 AU 或 AU 之間發生的錯誤。

此串流中最後傳送的輸出封包結束時，error_detected_之前的範圍就會開始；如果這個串流之前沒有輸出封包，則會從串流開始時開始。範圍會在 output_packet 開頭。

error_detected_before bool 各自獨立，因此您可以分別指出停電與目前封包是否受損。

error_detected_during 的範圍是從此 output_packet 的結尾算起。

回應

名稱	類型
`output_packet`	`Packet`
`error_detected_before`	`bool`
`error_detected_during`	`bool`

OnStreamFailed

串流失敗，但 StreamProcessor 執行個體仍可用於新的串流。

只有在用戶端先前傳送 EnableOnStreamFailed() 時，伺服器才會傳送此訊息。如果用戶端沒有傳送 EnableOnStreamFailed()，則伺服器會改為關閉 StreamProcessor 管道。

我們建議串流處理者伺服器實作來處理串流錯誤 (最好也可透過 OnOutputPacket() 和 OnOutputEndOfStream() 的 error_ 布林值進行回報)，但是串流處理工具伺服器無法達成此效果，但即使串流處理工具伺服器無法達成此效果，但仍可清楚指出串流處理工具使用串流失敗 (例如 Enable 命令失敗，以致用串流處理者)。

理想的 StreamProcessor 伺服器會在不傳送這則訊息的情況下處理輸入資料問題，但如果 StreamProcessor 伺服器可以完全遏止串流失敗，因此建議傳送這則訊息，而不要關閉 StreamProcessor 管道的伺服器端，且不會對後續的串流造成任何負面影響。

系統不會再從伺服器收到有關串流失敗的訊息。這包括用戶端原本可正常使用的任何 OnOutputEndOfStream()。

回應

名稱	類型
`stream_lifetime_ordinal`	`uint64`
`error`	`StreamError`

QueueInputEndOfStream

通知伺服器已傳送這個串流的所有 QueueInputPacket() 訊息。

如果串流未先關閉 (由用戶端或 OnStreamFailed() 或 StreamProcessor 關閉)，則之後會有相對應的 OnOutputEndOfStream()。

只有在伺服器在伺服器看見串流之前 (例如啟動新的串流) 前完成串流處理時，才會產生對應的 OnOutputEndOfStream() 訊息。如要強制伺服器在關閉前完成串流，請在 QueueInputEndOfStream() 之前使用 FlushEndOfStreamAndCloseStream()，再啟動任何新串流。另一種強制伺服器先完成串流再關閉的方法，就是先等待 OnOutputEndOfStream() 再執行關閉串流的動作。

如果用戶端並未傳送 QueueInputEndOfStream()，除了以「EndOfStream」標記的形式提供標記，讓所有輸入資料在處理完成之後，都能在用戶端明確顯示；如果用戶端從未傳送 QueueInputEndOfStream()，則無須等候任何等候時間，一律都會導致所有輸入資料經過處理到輸出中。部分串流處理器含有一些內部延遲資料，這些資料只會透過其他輸入資料「或」這個 EndOfStream 標記推送。理論上來說，這個訊息可以在 InputData 網域層級中獲得清除，但只有在串流處理工具距離串流才剛在 StreamControl 網域層級關閉時，清除才會生效。光是這樣的訊息不夠充分，無法做為 StreamControl 層級的整體清除管道。為此，請先傳送這則訊息，然後傳送 FlushEndOfStreamAndCloseStream() (應該可以在此時將新串流的輸入資料排入佇列，而不會捨棄這個舊串流的資料)，或等到 OnOutputEndOfStream() 再關閉目前的串流。

如果用戶端在第一個串流的 QueueInputEndOfStream() 之後，針對這個串流傳送 QueueInputPacket()、QueueInputFormatDetails()、QueueInputEndOfStream()，伺服器應關閉 StreamProcessor 管道。

要求

名稱	類型
`stream_lifetime_ordinal`	`uint64`

QueueInputFormatDetails

如果輸入格式的詳細資料仍與建立 StreamProcessor 時指定的相同，則不需要這則訊息，也不必傳送這則訊息。

如果串流不存在，這則訊息就會建立串流。

用戶端在用戶端傳送至少一則 QueueInput* 訊息之後，伺服器才會傳送 OnOutputConstraints()。

只要 StreamProcessor 執行個體支援新格式，所有伺服器都必須在串流開始時允許 QueueInputFormatDetails()，不會發生錯誤。在技術上，這樣可讓伺服器僅支援 StreamProcessor 建立期間設定的確切輸入格式，也就是出於設計考量。嘗試切換格式且串流 StreamProcessor 管道失敗的用戶端，應在建立前使用新的輸入格式透過 CodecFactory 建立全新的 StreamProcessor 執行個體再試一次，然後再放棄。

這些格式詳細資料只會覆寫建立串流處理器期間指定的格式詳細資料。下一個串流會預設為串流處理器建立期間設定的格式詳細資料。

這則訊息可以在第一個串流的開頭處允許，就像任何串流的開頭一樣。指定的格式不需要與建立串流處理器時指定的格式相符。但如果格式不相符，StreamProcessor 管道可能會按上述方式關閉。

要求

名稱	類型
`stream_lifetime_ordinal`	`uint64`
`format_details`	`FormatDetails`

QueueInputPacket

這則訊息會將輸入資料排入串流處理器進行處理。

如果串流不存在，這則訊息會建立新的串流。

用戶端在用戶端傳送至少一則 QueueInput* 訊息之後，伺服器才會傳送 OnOutputConstraints()。

即使串流處理器尚未產生第一個 OnOutputConstraints()，或即使 StreamProcessor 為先前排入佇列的輸入封包產生 OnFreeInputPacket()，用戶端仍須繼續透過這則訊息傳送輸入資料。只要沒有可用封包，輸入資料就必須繼續保持，以確保伺服器一定會產生第一個 OnOutputConstraints()。

要求

名稱	類型
`packet`	`Packet`

RecycleOutputPacket

用戶端使用完輸出封包後，用戶端需要透過這個方法告知串流處理器，這個輸出封包可以重新用於更多輸出。

系統不允許回收串流處理工具伺服器已經可用的輸出封包。在允許的情況下，允許用戶端回收已明確或隱含輸出緩衝區 de-configuration() 取消的輸出封包。詳情請參閱 buffer_lifetime_ordinal。伺服器必須忽略任何這類過時的 RecycleOutputPacket() 呼叫。

要求

名稱	類型
`available_output_packet`	`PacketHeader`

SetInputBufferPartialSettings

這是 SetInputBufferSettings() 的替代方案。

當用戶端使用 sysmem 分配緩衝區時，系統會使用此訊息，而不是 SetInputBufferSettings()+AddInputBuffer()。而是透過單一 SetInputBufferPartialSettings() 提供 StreamProcessor，以及讓 StreamProcessor 用來將限制傳送至 sysmem 的 BufferCollectionToken。sysmem 會透過其 BufferCollection 管道 (而非透過 StreamProcessor 管道) 向用戶端和 StreamProcessor 通知分配的緩衝區。

除非 sysmem 通知用戶端緩衝區分配作業已完成且成功，否則用戶端不得執行 QueueInput...()。

伺服器應準備好在伺服器尚未收到緩衝區配置資訊前看到 QueueInput...() 顯示，因為 QueueInput...() 和 sysmem 配置完成到達不同管道時，伺服器必須容許任一排序，所以用戶端知道配置作業已完成，無法表示伺服器知道配置已完成。然而，伺服器會預期配置作業已確實完成，並可能會在向 sysmem 要求資訊時，立即從 sysmem 取得配置資訊。

要求

名稱	類型
`input_settings`	`StreamBufferPartialSettings`

SetOutputBufferPartialSettings

這是 SetOutputBufferSettings() 的替代方案。

用戶端使用 sysmem 分配緩衝區時，系統會使用此訊息，而不是 SetOutputBufferSettings() +AddOutputBuffer()。相反地，透過單一 SetOutputBufferPartialSettings() 提供 StreamProcessor，和一個 BufferCollectionToken，就會用於將限制傳送至 sysmem。 sysmem 一律會透過 BufferCollection 管道 (而非 StreamProcessor 管道) 向用戶端和 StreamProcessor 通知分配的緩衝區。

用戶端收到 OnOutputConstraints() 後，您「必須」設定輸出緩衝區，且 buffer_constraints_action_required 設為 true，stream_lifetime_ordinal 等於用戶端目前的 stream_lifetime_ordinal (即使有進行中的串流)，並在沒有目前串流時允許。

關閉目前的串流發生於 StreamControl 排序網域，因此在 CloseCurrentStream() 或 FlushEndOfStreamAndCloseStream() 後，用戶端必須先收到後續的 Sync() 完成作業，用戶端才會知道已無當前串流。

另請參閱 FullOutputBufferPartialSettings()。

要求

名稱	類型
`output_settings`	`StreamBufferPartialSettings`

同步

完成後，先前的 StreamProcessor 呼叫都會在伺服器端完成其作業，但「除外」，使用 QueueInputPacket() 處理佇列中的資料。

這項呼叫的主要用途，是讓用戶端在 CloseCurrentStream() 中，release_input_buffers 和/或 release_output_buffers 設為 true 後生效，直到用戶端分配新緩衝區並重新設定輸入和/或輸出緩衝區為止。對於媒體緩衝區使用其整體集區的資源類型，不一定與耗用的資源相比，這種資源用量的重疊部分可能非常值得。尤其是在用戶端多次重新設定緩衝區時。

請注意，在分配新的媒體緩衝區之前，Sync() 不足以實現整個媒體緩衝區資源使用系統的非重疊情形，但這項做法有助於達成此目標。

Sync() 會傳輸輸出排序網域和 StreamControl 排序網域，但不會傳輸 InputData 排序網域。

這項要求可用於避免達到代表 10 的 kMaxInFlightStreams。持續執行 <= 8 個傳輸中串流的用戶端，可以輕鬆維持在 10 以下限制中。儘管通訊協定允許重複的 SetInputBufferSettings() 和類似做法，但傳送垃圾內容的用戶端在伺服器或管道本身落後時，可能會預期管道只是關閉。

要求

<EMPTY>

回應

<EMPTY>

StreamSink

定義於 fuchsia.media/stream.fidl

使用封包串流。這個介面通常會與 StreamBufferSet 一併沿用，以便將基本串流從用戶端傳輸至服務。

DiscardAllPackets

捨棄先前透過 SendPacket 或 SendPacketNoReply 傳送但尚未釋放的封包。在所有封包發布後，系統就會傳送回應。

要求

<EMPTY>

回應

<EMPTY>

DiscardAllPacketsNoReply

捨棄先前透過 SendPacket 或 SendPacketNoReply 傳送但尚未釋放的封包。

要求

<EMPTY>

EndOfStream

表示串流已結束。這個方法的精確語意取決於繼承介面。

要求

<EMPTY>

SendPacket

將封包傳送至服務。服務與相關聯的酬載記憶體完成處理後，系統就會傳送回應。

packet 必須適用於目前緩衝區集，否則服務會關閉連線。

要求

名稱	類型
`packet`	`StreamPacket`

回應

<EMPTY>

SendPacketNoReply

將封包傳送至服務。這個介面未定義接收器如何得知接收器何時使用相關聯的酬載記憶體。繼承介面必須定義該設定。

packet 必須適用於目前緩衝區集，否則服務會關閉連線。

要求

名稱	類型
`packet`	`StreamPacket`

StreamSource

定義於 fuchsia.media/stream.fidl

產生一連串封包。這個介面通常會與 StreamBufferSet 一併沿用，以便將基本串流從服務傳輸至用戶端。

DiscardAllPackets

要求

<EMPTY>

回應

<EMPTY>

DiscardAllPacketsNoReply

要求

<EMPTY>

OnEndOfStream

表示串流已結束。

回應

<EMPTY>

OnPacketProduced

這個外掛程式能傳送服務產生的封包。當用戶端使用完酬載記憶體時，用戶端必須呼叫 ReleasePacket 來釋出酬載記憶體。

回應

名稱	類型
`packet`	`StreamPacket`

ReleasePacket

釋出與先前透過 OnPacketProduced 傳送的封包相關聯的酬載記憶體。

要求

名稱	類型
`packet`	`StreamPacket`

UsageAudioConsumerFactory

建立音訊用戶的介面，用於進行本機轉譯。

CreateAudioConsumer

建立 AudioConsumer，這是在指定使用值的情況下播放音訊的介面。提交至這類使用者的音訊一律會在本機轉譯。

要求

名稱	類型
`usage`	`AudioRenderUsage`
`audio_consumer_request`	`server_end<AudioConsumer>`

UsageGainListener

監控用量增益設定變更的通訊協定。

裝置會在沒有裝置時關閉。

OnGainMuteChanged

系統會在連線時立即呼叫，並在每次用量增加設定變更時呼叫。

用戶端必須回應才能確認事件。未確認事件的用戶端最終會中斷連線。

注意：這個 API 未實作靜音回報功能；muted 一律為 false。

要求

名稱	類型
`muted`	`bool`
`gain_dbfs`	`float32`

回應

<EMPTY>

UsageGainReporter

設定用量提升情形的通訊協定。

RegisterListener

在 device_token 識別的裝置上，將事件監聽器連線至 usage 用量增益設定變更串流。「用量增益」並非由任何用戶端直接設定，而是每部裝置的用量設定轉譯結果，並經過進行中的靜音/降低排除調整後加總。

裝置可能會將相同音量等級對應到不同的 DBF，因此需要 device_unique_id 才能縮排裝置。

如果用戶端需要在執行階段選取 ID，AudioDeviceEnumerator 會提供裝置和裝置的專屬 ID 的程式輔助存取權。

要求

名稱	類型
`device_unique_id`	`string[36]`
`usage`	`Usage`
`usage_gain_listener`	`UsageGainListener`

UsageReporter

設定音訊使用情況的通訊協定。

觀看

要求

名稱	類型
`usage`	`Usage`
`usage_watcher`	`UsageWatcher`

UsageWatcher

用於監聽音訊用量政策狀態變更的通訊協定。

這個 API 不會反映使用者動作，例如降低音量或忽略串流。

OnStateChanged

在首次連線時以及觀察到的用量變更時呼叫。提供的用量一律為繫結用量；提供用途，以便這個通訊協定的實作可能會繫結超過一項用量。

用戶端必須回應才能確認事件。未確認事件的用戶端最終會中斷連線。

要求

名稱	類型
`usage`	`Usage`
`state`	`UsageState`

回應

<EMPTY>

結構化

AacConstantBitRate

廣闊	類型	說明	預設
`bit_rate`	`uint32`	每秒位元數	無預設

AacEncoderSettings

廣闊	類型	預設
`transport`	`AacTransport`	無預設
`channel_mode`	`AacChannelMode`	無預設
`bit_rate`	`AacBitRate`	無預設
`aot`	`AacAudioObjectType`	無預設

AacTransportAdts

在 fuchsia.media/stream_common.fidl 中定義

ADTS 中的 AAC

<EMPTY>

AacTransportLatm

在 fuchsia.media/stream_common.fidl 中定義

洛杉磯的 AAC

廣闊	類型	說明	預設
`mux_config_present`	`bool`	是否存在 MuxConfiguration 串流元素	無預設

AacTransportRaw

在 fuchsia.media/stream_common.fidl 中定義

原始 AAC 存取單元。

<EMPTY>

AudioCompressedFormatAac

<EMPTY>

AudioCompressedFormatSbc

<EMPTY>

AudioDeviceInfo

廣闊	類型	預設
`name`	`string`	無預設
`unique_id`	`string`	無預設
`token_id`	`uint64`	無預設
`is_input`	`bool`	無預設
`gain_info`	`AudioGainInfo`	無預設
`is_default`	`bool`	無預設

AudioGainInfo

廣闊	類型	說明	預設
`gain_db`	`float32`		無預設
`flags`	`AudioGainInfoFlags`		無預設

AudioStreamType

說明音訊基本串流的類型。

廣闊	類型	預設
`sample_format`	`AudioSampleFormat`	無預設
`channels`	`uint32`	無預設
`frames_per_second`	`uint32`	無預設

壓縮

說明套用至串流的壓縮。這個類型可與 AudioStreamType 或 VideoStreamType 搭配使用，代表中型專用的壓縮類型。

廣闊	類型	說明	預設
`type`	`CompressionType`	套用至串流的壓縮類型。這通常是 ENCODING 的值之一，但不能使用 `AUDIO_ENCODING_LPCM` 和 `VIDEO_ENCODING_UNCOMPRESSED`，因為系統會將這些編碼視為未壓縮。	無預設
`parameters`	`vector<uint8>[8192]?`	特定類型的不透明「頻外」參數，用於說明串流的壓縮。	無預設

EncryptionPattern

在 fuchsia.media/stream_common.fidl 中定義

EncryptionPattern

模式加密會在子取樣 (SubsampleEntry 的已加密_位元組) 的受保護的範圍中，採用經過加密且清晰的 16 位元組區塊模式。這個結構會指定已加密的資料區塊數量，後方則是清除資料區塊的數量。

廣闊	類型	說明	預設
`clear_blocks`	`uint32`		無預設
`encrypted_blocks`	`uint32`		無預設

Metadata

定義於 fuchsia.media/metadata.fidl

廣闊	類型	說明	預設
`properties`	`vector<Property>`		無預設

參數

在 fuchsia.media/stream_common.fidl 中定義

參數

一般參數。

我們希望盡可能減少對這個一般「參數」結構的使用，也就是盡可能定義更多串流專用參數語意。

廣闊	類型	預設
`scope`	`string`	無預設
`name`	`string`	無預設
`value`	`Value`	無預設

PcmFormat

在 fuchsia.media/stream_common.fidl 中定義

PcmFormat

PCM 音訊格式詳細資料。

廣闊	類型	預設
`pcm_mode`	`AudioPcmMode`	無預設
`bits_per_sample`	`uint32`	無預設
`frames_per_second`	`uint32`	無預設
`channel_map`	`vector<AudioChannelId>[16]`	無預設

資源

定義於 fuchsia.media/metadata.fidl

廣闊	類型	說明	預設
`label`	`string`		無預設
`value`	`string`		無預設

SbcEncoderSettings

在 fuchsia.media/stream_common.fidl 中定義

SBC 編碼器的設定。

SBC 編碼器會取用已簽署的 16 位元線性 PCM 範例並傳回編碼的 SBC 影格。SBC 編碼器 PCM 資料，分成 sub_bands * block_count 個 PCM 影格。這個編碼器可接受任意畫面邊界的 PCM 資料，但 EOS 排入佇列時，輸出內容可能為零填補，讓輸出作業完成整個批次。

廣闊	類型	說明	預設
`sub_bands`	`SbcSubBands`		SbcSubBands.SUB_BANDS_8
`allocation`	`SbcAllocation`		SbcAllocation.ALLOC_LOUDNESS
`block_count`	`SbcBlockCount`		SbcBlockCount.BLOCK_COUNT_4
`channel_mode`	`SbcChannelMode`		無預設
`bit_pool`	`uint64`	SBC 位元集區值。	無預設

StreamPacket

定義於 fuchsia.media/stream.fidl

說明 StreamSink 耗用或由 StreamSource 產生的封包。

廣闊	類型	說明	預設
`pts`	`int64`	封包顯示的時間 (根據呈現時鐘)。	NO_TIMESTAMP
`payload_buffer_id`	`uint32`	這個封包使用的酬載緩衝區 ID。當此結構與 `StreamBufferSet` 搭配使用時，這個欄位是透過 `StreamBufferSet.AddPayloadBuffer` 提供的酬載緩衝區 ID。在這種情況下，這個值必須識別目前集合中的酬載緩衝區。其他介面可能會為這個欄位定義不同的語意。	無預設
`payload_offset`	`uint64`	酬載緩衝區中封包酬載的偏移。這個值加上 `payload_size` 值必須小於或等於參照的酬載緩衝區大小。	無預設
`payload_size`	`uint64`	酬載的大小 (以位元組為單位)。這個值加上 `payload_offest` 值必須小於或等於參照的酬載緩衝區大小。	無預設
`flags`	`uint32`	一組位元或設定的標記 (請見下方常數)，說明這個封包的屬性。	0
`buffer_config`	`uint64`	與這個封包相關聯的緩衝區設定。這個欄位的語意取決於使用這個結構的介面。在許多情況下，這個欄位不會使用。這個欄位適用於明確識別緩衝區設定 (即酬載緩衝區組合) 的情況。在這類情況下，`payload_buffer_id` 會參照此欄位識別的緩衝區設定中的酬載緩衝區。	0
`stream_segment_id`	`uint64`	與此封包相關聯的串流區段。這個欄位的語意取決於使用這個結構的介面。在許多情況下，這個欄位不會使用。這個欄位是用來區分串流屬性 (例如編碼) 的連續片段，其中串流屬性 (例如編碼) 可能與片段不同。	0

StreamType

說明基本串流的類型。

廣闊	類型	說明	預設
`medium_specific`	`MediumSpecificStreamType`	中型特定類型資訊。	無預設
`encoding`	`string[255]`	編碼 (請參閱下方常數)。這個值會以字串表示，以便在不修改這個檔案的情況下導入新的編碼。	無預設
`encoding_parameters`	`vector<uint8>?`	編碼專屬的參數，有時稱為「頻外資料」。一般來說，這項資料會與壓縮的串流相關聯，並提供解壓縮串流所需的參數。除了串流的生產者和消費者以外，其他各方通常都不透明。	無預設

SubpictureStreamType

說明子畫面基本串流的類型。

<EMPTY>

SubsampleEntry

在 fuchsia.media/stream_common.fidl 中定義

SubsampleEntry

子範例是樣本中的位元組範圍，內容包含明確的位元組範圍，後面接著加密的位元組範圍。這個結構會指定子樣本中每個範圍的大小。

廣闊	類型	說明	預設
`clear_bytes`	`uint32`		無預設
`encrypted_bytes`	`uint32`		無預設

TextStreamType

說明文字基本串流的類型。

<EMPTY>

TimelineFunction

定義於 fuchsia.media/timeline_function.fidl

TimelineFunction 代表主體時間軸與參照時間軸與線性關係之間的關係。

舉例來說，假設參考時間是系統的單聲道時鐘，而主體時間是某些媒體 (如影片) 的顯示時間。

reference_time 是播放開始時的單音時鐘值。假設播放是從媒體開始時開始播放，subject_time 為 0。因此我們選擇 reference_delta 和 subject_delta，讓 subject_delta / reference_delta 代表所需的播放速率，例如 0/1 代表暫停播放，1/1 代表正常播放。

公式

透過函式，我們可以根據參考時間軸值 r (其中 reference_delta > 0) 判斷主體時間軸值 s：

s = (r - reference_time) * (subject_delta / reference_delta) + subject_time

同樣地，我們可以根據主旨時間軸值 s，找到參考時間軸值 r，並使用此公式 (其中 subject_delta > 0)：

r = (s -subject_time) * (reference_delta / subject_delta) + Referenc_time

選擇時間值

時間值可以是任意值，我們的線性關係也不會相同，但我們可以使用這些值來代表分段線性關係中的片段邊界。

舉例來說，如果使用者執行略過章節，我們可以使用時間軸函式說明 subject_time 是要略過的時間點，reference_time 現在加上一些週期，而一般播放率的差異比率為 1/1。

廣闊	類型	說明	預設
`subject_time`	`int64`	主題時間軸中的值，與 reference_time 相關。	0
`reference_time`	`int64`	與 Subject_time 相關聯的參考時間軸值。	0
`subject_delta`	`uint32`	與 reference_delta 相對應的主題時間軸變化。	0
`reference_delta`	`uint32`	參考時間軸中的 Subject_delta 變化。不得為零。	1

VideoStreamType

說明影片基本串流的類型。

廣闊	類型	說明	預設
`pixel_format`	`fuchsia.images/PixelFormat`	已淘汰：13	無預設
`color_space`	`ColorSpace`		無預設
`width`	`uint32`	影片影格的尺寸 (以像素為單位)。	無預設
`height`	`uint32`		無預設
`coded_width`	`uint32`	影片影格的尺寸 (以像素為單位)。這些值必須等於或大於各自的寬度/高度值。	無預設
`coded_height`	`uint32`		無預設
`pixel_aspect_ratio_width`	`uint32`	顯示頁框時，單一像素的長寬比。	無預設
`pixel_aspect_ratio_height`	`uint32`		無預設
`stride`	`uint32`	主要影片平面中每個「編碼」列的位元組數。	無預設

VideoUncompressedFormat

在 fuchsia.media/stream_common.fidl 中定義

VideoUncompressedFormat

未壓縮影片格式的詳細資料。

廣闊	類型	預設
`image_format`	`fuchsia.sysmem/ImageFormat_2`	無預設
`fourcc`	`uint32`	無預設
`primary_width_pixels`	`uint32`	無預設
`primary_height_pixels`	`uint32`	無預設
`secondary_width_pixels`	`uint32`	無預設
`secondary_height_pixels`	`uint32`	無預設
`planar`	`bool`	無預設
`swizzled`	`bool`	無預設
`primary_line_stride_bytes`	`uint32`	無預設
`secondary_line_stride_bytes`	`uint32`	無預設
`primary_start_offset`	`uint32`	無預設
`secondary_start_offset`	`uint32`	無預設
`tertiary_start_offset`	`uint32`	無預設
`primary_pixel_stride`	`uint32`	無預設
`secondary_pixel_stride`	`uint32`	無預設
`primary_display_width_pixels`	`uint32`	無預設
`primary_display_height_pixels`	`uint32`	無預設
`has_pixel_aspect_ratio`	`bool`	false
`pixel_aspect_ratio_width`	`uint32`	1
`pixel_aspect_ratio_height`	`uint32`	1

無效

<EMPTY>

ENUMS

AacAudioObjectType 嚴格

類型：uint32

名稱	值	說明
MPEG2_AAC_LC	`0`	MPEG-2 低複雜度
MPEG4_AAC_LC	`1`	MPEG-4 低複雜度

AacChannelMode 嚴格

類型：uint32

名稱	值	說明
單色	`0`
限時	`2`

AacVariableBitRate 嚴格

類型：uint32

在 fuchsia.media/stream_common.fidl 中定義

可變位元率模式，實際產生的位元率會因輸入信號和其他編碼設定而異。

請參閱 https://wiki.hydrogenaud.io/index.php?title=Fraunhofer_FDK_AAC#Bitrate_Modes

名稱	值	說明
V1	`1`
V2	`2`
V3	`3`
V4	`4`
V5	`5`

AudioBitrateMode 嚴格

類型：uint32

名稱	值	說明
未指定	`0`
CBR	`1`
越南	`2`

AudioCapture 使用嚴格

類型：uint32

會加註用來擷取音訊的串流用途。音訊政策會使用 AudioCaptureUsage 判定音訊串流的互動方式。

名稱	值	說明
背景	`0`	「串流」是用來在背景擷取音訊。這些串流隨時都有可能處於啟用狀態，而且會視為具有特殊權限。範例：監聽啟動字詞
前景	`1`	串流適用於一般擷取功能。當串流建立者位於前景時，如果串流用途是音訊擷取，則應使用此串流。範例：錄音工具
SYSTEM_AGENT	`2`	串流用於與系統代理程式互動。只有在使用者表示意圖與感興趣的方互動時，才能使用這項功能。例如：Google 助理、Siri、Alexa
通訊	`3`	串流適合用於某種即時使用者互動。語音/視訊通訊應該使用這個值。

AudioChannelId 嚴格

類型：uint32

在 fuchsia.media/stream_common.fidl 中定義

AudioChannelId

用於指定揚聲器位置 / 類型適用的音訊管道。

TODO(dustingreen)：是否需要更多管道 ID？

名稱	值	說明
略過	`0`
LF	`1`
得分	`2`
CF	`3`
LS	`4`
RS	`5`
低頻率	`6`
CS	`7`
LR	`8`
得分	`9`
END_DEFINED	`10`
EXTENDED_CHANNEL_ID_BASE	`1862270976`
最快	`2147483647`

AudioOutputRoutingPolicy 嚴格

類型：uint32

名稱	值	說明
ALL_PLUGGED_OUTPUTS	`0`
LAST_PLUGGED_OUTPUT	`1`

AudioPcmMode 嚴格

類型：uint32

在 fuchsia.media/stream_common.fidl 中定義

AudioPcmMode

名稱	值	說明
LINEAR	`0`
阿拉	`1`
桑葚紫	`2`

AudioRender 使用嚴格設定

類型：uint32

針對用來轉譯音訊的串流，加上註解。 AudioRenderer 的用法在建立後即無法變更。音訊政策會使用 AudioRenderUsage 判定音訊串流的互動方式。

名稱	值	說明
背景	`0`	訊息串的用途是調整環境音或背景音效。如果串流能在沒有結果的情況下中斷，則應使用此功能。
媒體	`1`	串流適用於一般功能。屬於正常功能的串流應使用此功能。
幹擾	`2`	串流的目的是中斷裝置的任何執行，用於通知等乾擾的串流應使用此方式。
SYSTEM_AGENT	`3`	串流用於與系統代理程式互動。這可用來回應使用者啟動的觸發條件。
通訊	`4`	串流適合用於某種即時使用者互動。語音/視訊通訊應該使用這個值。

AudioSampleFormat 嚴格

類型：uint32

列舉支援的音訊樣本格式。

名稱	值	說明
UNSIGNED_8	`1`	8 位元未簽署樣本，樣本大小為 1 位元組。
SIGNED_16	`2`	16 位元已簽署樣本、主機端端字元，樣本大小為 2 個位元組。
SIGNED_24_IN_32	`3`	24 位元帶正負號樣本，採 32 位元為主機端，取樣大小為 4 個位元組。
FLOAT	`4`	32 位元浮點樣本，樣本大小為 4 個位元組。

行為嚴格

類型：uint32

如有多個啟用項目，系統會對串流套用這些行為。

名稱	值	說明
無	`0`	混合不同串流內容。
丹麥克朗	`1`	套用增益值，設法消滅其中一個串流的音量。(-14.0db)
關閉	`2`	套用增益值，將其中一個串流設為靜音。(-160.0db)

CodecProfile 彈性

類型：uint32

在 fuchsia.media/stream_common.fidl 中定義

允許的轉碼器設定檔清單。這份清單應該很有彈性，因為轉碼器日後可能會加入。如有需要，可同時包含視訊和音訊設定檔。

新增時間：11 張

名稱	值	說明
H264PROFILE_BASELINE	`0`
H264PROFILE_MAIN	`1`
H264PROFILE_EXTENDED	`2`
H264PROFILE_HIGH	`3`
H264PROFILE_HIGH10PROFILE	`4`
H264PROFILE_HIGH422PROFILE	`5`
H264PROFILE_HIGH444PREDICTIVEPROFILE	`6`
H264PROFILE_SCALABLEBASELINE	`7`
H264PROFILE_SCALABLEHIGH	`8`
H264PROFILE_STEREOHIGH	`9`
H264PROFILE_MULTIVIEWHIGH	`10`
VP8PROFILE_ANY	`11`
VP9PROFILE_PROFILE0	`12`
VP9PROFILE_PROFILE1	`13`
VP9PROFILE_PROFILE2	`14`
VP9PROFILE_PROFILE3	`15`
HEVCPROFILE_MAIN	`16`
HEVCPROFILE_MAIN10	`17`
HEVCPROFILE_MAIN_STILL_PICTURE	`18`
MJPEG_BASELINE	`19`

ColorSpace 嚴格

類型：uint32

名稱	值	說明
不明	`0`
NOT_APPLICABLE	`1`
JPEG	`2`
HD_REC709	`3`
SD_REC601	`4`

Lc3FrameDuration 彈性

類型：uint32

在 fuchsia.media/stream_common.fidl 中定義

已新增：HEAD

名稱	值	說明
D10_MS	`1`
D7P5_MS	`2`

SbcAllocation 嚴格

類型：uint32

名稱	值	說明
ALLOC_LOUDNESS	`0`
ALLOC_SNR	`1`

SbcBlockCount 嚴格

類型：uint32

名稱	值	說明
BLOCK_COUNT_4	`4`
BLOCK_COUNT_8	`8`
BLOCK_COUNT_12	`12`
BLOCK_COUNT_16	`16`

SbcChannelMode 嚴格

類型：uint32

名稱	值	說明
單色	`0`
DUAL	`1`
限時	`2`
JOINT_STEREO	`3`

SbcSubBands 嚴格

類型：uint32

名稱	值	說明
SUB_BANDS_4	`4`
SUB_BANDS_8	`8`

StreamError strict

類型：uint32

在 fuchsia.media/stream_common.fidl 中定義

StreamError

此錯誤代碼會封裝各種可能從 StreamProcessor 伺服器發出的錯誤。該訊息可以做為 OnStreamFailed 事件或管道的聲學訊息傳送。

名稱	值	說明
不明	`1`	發生不明原因的內部錯誤。
INVALID_INPUT_FORMAT_DETAILS	`2`	用戶端提供的輸入格式詳細資料無效。
INCOMPATIBLE_BUFFERS_PROVIDED	`3`	伺服器收到的緩衝區不適合執行作業。例如，解碼器收到的輸出緩衝區太小，無法解碼影格時，就會發生這種情況。
EOS_PROCESSING	`4`	輸入 EOS (串流結束) 處理失敗，因此串流失敗。目前，如果核心轉碼器在處理 EOS 時觸發，就會發生上述情況。
DECODER_UNKNOWN	`16777217`	內部解碼器錯誤，原因不明。
DECODER_DATA_PARSING	`16777218`	輸入無法剖析的資料。只有部分剖析問題/錯誤會以這種方式回報。毀損的輸入資料可能會以其他 StreamError 的形式回報，或是不會導致 StreamError。
ENCODER_UNKNOWN	`33554433`	內部編碼器錯誤，原因不明。
DECRYPTOR_UNKNOWN	`50331649`	發生不明原因的內部解密工具錯誤。
DECRYPTOR_NO_KEY	`50331650`	要求的 KeyId 無法用於去密碼器。如果該金鑰可供使用，用戶端可能會再試一次。

VideoColorSpace 嚴格

類型：uint32

名稱	值	說明
INVALID	`0`

資料表

AudioCompressedFormatCvsd

在 fuchsia.media/stream_common.fidl 中定義

AudioCompressFormatCvsd 暫時沒有任何欄位，因為我們會使用 Bluetooth Core Spec v5.3 第 9.2 節建議的參數值。

已新增：HEAD

序數	廣闊	類型	說明

AudioCompressedFormatLc3

在 fuchsia.media/stream_common.fidl 中定義

AudioCompressFormatLc3 不含任何欄位。設定解碼器的必要參數會嵌入為 FormatDetails.oob_bytes 中的 Codec_specific_Configuration (指派數字第 6.12.5 節)。

已新增：HEAD

序數	廣闊	類型	說明

AudioConsumerStatus

代表取用端的狀態。初始狀態下，缺少 error 和 presentation_timeline。待開發客戶時間欄位一律顯示。

序數	廣闊	類型	說明
1	`error`	`AudioConsumerError`	如果有，表示存在目前有效的錯誤狀況。如果沒有錯誤，則會顯示這個字串。
2	`presentation_timeline`	`TimelineFunction`	如果有，則指出呈現時間軸與局部單聲道時鐘 (兩者皆以奈秒為單位) 之間的目前關係。如果不是，表示沒有任何關係。一開始不存在。「顯示時間軸」是指封包上的 `pts` (呈現時間戳記) 值。這個時間軸函式可用於根據該封包的 `pts` 值，判定會呈現封包的本地單時針時間。
3	`min_lead_time`	`uint64`	表示 `AudioConsumer` 支援的最短前置時間 (以奈秒為單位)。換句話說，提供給 `AudioConsumer.Start` 的 `media_time` 與第一個封包上的 pt 之間的差距有多小。系統會裁剪這個範圍以外的值。
4	`max_lead_time`	`uint64`	表示此 `AudioConsumer` 支援的前置時間上限 (以奈秒表示)。換句話說，提供給 `AudioConsumer.Start` 的 `media_time` 與第一個封包上的 pt 之間的差距有多大。系統會裁剪這個範圍以外的值。

CvsdEncoderSettings

在 fuchsia.media/stream_common.fidl 中定義

CVSD 編碼器的設定。這個檔案目前沒有任何欄位，因為我們會使用 Bluetooth Core Spec v5.3 第 9.2 節建議的參數值。

已新增：HEAD

序數	廣闊	類型	說明

DecryptedFormat

在 fuchsia.media/stream_common.fidl 中定義

DecryptedFormat

這是指解密內容的格式。在傳送輸出封包之前，StreamProcessor 伺服器必須先傳送這個標記。目前，已解密的輸出結果不會產生其他格式詳細資料。

序數	廣闊	類型	說明
1	`ignore_this_field`	`bool`

EncryptedFormat

在 fuchsia.media/stream_common.fidl 中定義

EncryptedFormat

解密串流處理器的串流格式詳細資料酬載。這是一個稀疏的資料表，用於指定解密作業所需的參數，而非資料串流。只有在欄位變更的情況下，才需要更新欄位；重複相同值則不需要更新。

序數	廣闊	類型	說明
3	`init_vector`	`InitVector`	`init_vector` 會與鍵和內容區塊搭配使用，藉此建立鏈結中的第一個加密區塊，並衍生加密區塊鏈中的後續加密區塊。使用方式：您必須在將輸入封包傳送至解密工具之前設定這個值。在資料串流中，這可能會多次變更。
4	`subsamples`	`vector<SubsampleEntry>`	`subsamples` 是用來識別子樣本的清楚加密部分。使用方式：如要執行整個樣本加密，請勿傳送這個參數。在資料串流中，這可能會多次變更。
5	`pattern`	`EncryptionPattern`	`pattern` 是用來識別用於模式加密的明確加密區塊。使用方式： CENC 和 CBC1 都禁止使用，也不適用於 CENS 和 CBCS。如有需要，必須在將輸入封包傳送至解密工具之前進行設定。在資料串流中，這可能會多次變更。
6	`scheme`	`string`	`scheme` 指定要使用的加密配置，例如 `fuchsia.media.ENCRYPTION_SCHEME_CENC`。使用方式：您必須在傳送輸入封包之前設定這個值。只有在某些情況下，才能在直播中變更配置。為串流選擇加密配置後，配置只能設為 `fuchsia.media.ENCRYPTION_SCHEME_UNENCRYPTED` 或相同的初始加密配置。配置任何時間點都可以設為 `fuchsia.media.ENCRYPTION_SCHEME_UNENCRYPTED`。
8	`key_id`	`KeyId`	`key_id` 會識別解密後續資料時應使用的金鑰。使用方式：您必須設定這個值，才能將輸入封包傳送至解密工具。在資料串流中，這可能會多次變更。

FormatDetails

在 fuchsia.media/stream_common.fidl 中定義

FormatDetails

這會說明 StreamProcessor (輸入與輸出的個別執行個體) 的輸入或輸出內容格式。

序數	廣闊	類型	說明
1	`format_details_version_ordinal`	`uint64`
2	`mime_type`	`string`
3	`oob_bytes`	`vector<uint8>`
4	`domain`	`DomainFormat`
5	`pass_through_parameters`	`vector<Parameter>`
6	`encoder_settings`	`EncoderSettings`	向編碼器指示如何將原始資料編碼。解碼器可能會忽略這個欄位，但會保留使用這個欄位設定的遭拒要求，因為這類要求並不合理。
7	`timebase`	`uint64`	輸入封包 timestamp_ish 每秒的時間基數。當輸入時間戳記套用至輸入封包有效部分的位元組 0 (位元組 0 未直接對應任何輸出封包有效部分的位元組 0) 時，時間集只會用於選擇性的 timestamp_ish 值進行推斷。如果因為輸入缺少時間戳記，或因為以編碼器輸入區塊大小的遞增方式提供輸入內容 (根據編碼器設定，並由用戶端獨立計算)，則不設定時間戳記推論。設定是否需要使用時間戳記推論，或已知可以接受用戶端接受。
8	`profile`	`CodecProfile`	指定編碼器或解碼器的轉碼器設定檔。如果是編碼器：這個值是完全選用的值。用戶端可能會想要指定基於通訊協定相容性原因 (例如 WebRTC) 的轉碼器設定檔。不過，如果未設定值，編碼器便可自由選擇任何支援的轉碼器設定檔。解碼器：這個值是選用項目，但提供最佳做法 (至少包含至少未加密串流)。容器格式包含經過編碼的設定檔，因此應提供給解碼器。某些格式 (例如 VP9 和 AV1) 會在其元素串流中加入經過編碼的設定檔，因此這些解碼器或許能找出串流的設定檔。無論如何，用戶端應盡可能提供經過編碼的設定檔。新增時間：11 張

H264EncoderSettings

在 fuchsia.media/stream_common.fidl 中定義

H264 編碼器設定。

序數	廣闊	類型	說明
1	`bit_rate`	`uint32`	編碼串流的目標每秒位元數。如果省略，系統會解讀為 200,000。
2	`frame_rate`	`uint32`	已編碼串流的每秒影格數。如果省略，系統會解讀為 30。
3	`gop_size`	`uint32`	每個主要畫面格的圖片數量。如果設為「0」，將停用鍵影格編碼，除非 force_key_frame 設為 true。如果省略，系統會解讀為 8。
4	`variable_frame_rate`	`bool`	是否要啟用畫面更新率調整功能，以符合目標位元率。如果省略，系統會解讀為 false。
5	`min_frame_rate`	`uint32`	啟用 `variable_frame_rate` 時，允許的最低畫面更新率。如果省略，系統會解讀為 10。
6	`force_key_frame`	`bool`	如果設為 true，下一個影格編碼將是關鍵影格。省略時，會解讀為 false。
7	`quantization_params`	`H264QuantizationParameters`	允許自訂量化參數以進行編碼。這項設定後提交的每個影格都會使用新的值。如果省略此屬性，就不會變更編碼器預設值。

H264QuantizationParameters

在 fuchsia.media/stream_common.fidl 中定義

自訂 h264 編碼器參數，以進行巨集區塊量化。這個值可以介於 0 到 51 之間，數字越小表示品質/位元率越高。雖然編碼器應盡可能支援這些欄位，但部分編碼器可能會忽略這些欄位。您可以設定這個表格，或是不設定這個資料表中的部分欄位，因為編碼器可以決定其自己的預設值。如果無法使用指定值達成指定的位元率，使用者應該會預期產生的編碼串流位元率與要求的位元率不同。

序數	廣闊	類型	說明
1	`i_base`	`uint32`	關鍵影格量化的起始值。
2	`i_min`	`uint32`	用來將關鍵影格量化的最小允許值。
3	`i_max`	`uint32`	用於將關鍵影格量化的最大允許值。
4	`p_base`	`uint32`	預測影格量化的起始值。
5	`p_min`	`uint32`	用來將預測影格量化的最小允許值。
6	`p_max`	`uint32`	用於將預測影格量化的最大允許值。

HevcEncoderSettings

在 fuchsia.media/stream_common.fidl 中定義

HEVC/H265 編碼器設定。

序數	廣闊	類型	說明
1	`bit_rate`	`uint32`	編碼串流的目標每秒位元數。如果省略，則預設值為 200,000。
2	`frame_rate`	`uint32`	已編碼串流的每秒影格數。如果省略，預設值為 30。
3	`gop_size`	`uint32`	每個主要畫面格的圖片數量。如未省略，預設值為 8。

InputAudioCapturerConfiguration

設定擷取器設定，該擷取器會從輸入裝置接收串流。

序數	廣闊	類型	說明
1	`usage`	`AudioCaptureUsage`

Lc3EncoderSettings

在 fuchsia.media/stream_common.fidl 中定義

LC3 編碼器的設定。包含 LC3 規格 v1.0 中所述的參數。含有非 PcmFormat 表示的欄位。

已新增：HEAD

序數	廣闊	類型	說明
1	`nbytes`	`uint16`	用於音訊影格編碼的外部位元組數值。根據 LC3 規格 v1.0，每個音訊管道的輸出位元組大小值可能不同，但對於 Fuchsia 的用途，我們會為所有管道使用相同的 `nbytes` 值。
2	`frame_duration`	`Lc3FrameDuration`	影格時間長度會與取樣頻率搭配使用，以決定影格大小。

LoopbackAudioCapturerConfiguration

用於接收回送串流系統輸出的擷取器設定。

序數	廣闊	類型	說明

MSbcEncoderSettings

在 fuchsia.media/stream_common.fidl 中定義

mSBC 編碼器的設定。因為 mSBC 編碼器使用 HFP Spec v1.8 所要求的值，因此沒有設定。

已新增：HEAD

序數	廣闊	類型	說明

封包

封包代表與串流處理器之間的輸入或輸出資料區塊。

串流處理器輸出內容：

雖然封包是透過 OnOutputPacket() 處理用戶端，但串流處理器會避免修改參照的輸出資料。用戶端呼叫 RecycleOutputPacket(packet_index) 後，串流處理工具會通知用戶端再次正常執行參照的資料變更。

串流處理器輸入：

用戶端最初包含所有封包_index(es)，之後會再次取得可透過 OnFreeInputPacket() 填入的封包_index。用戶端不得修改 QueueInputPacket() 和 OnFreeInputPacket() 之間的參照資料。

序數	廣闊	類型	說明
1	`header`	`PacketHeader`
2	`buffer_index`	`uint32`	這個封包所參照的緩衝區。如為單一緩衝區模式，此值將一律為 0，但在多緩衝區模式下，封包的指定傳輸間隔可參照任何緩衝區。封包只有相關緩衝區時，且封包處於傳輸中狀態時才會有關聯的緩衝區，而封包沒有可用時。預設值會降低意外不當使用索引 0 的可能性 (如果未填入資料，這樣就會以顯而易見的方式表示，而非在您將緩衝區 0 重複解碼，而不是使用正確的緩衝區時，不明顯的資料損毀)。 TODO(dustingreen)：試著將 FIDL 資料表預設值改成有意義，在存取欄位時就不能抱怨 !has。目前這裡指定的預設設定並不會執行任何動作。
3	`stream_lifetime_ordinal`	`uint64`	值 1 是建立串流處理器後允許的最低值。用戶端傳送的值必須是奇數。值只能增加。 stream_lifetime_ordinal 代表串流的生命週期。特定串流專用的所有訊息均含有 stream_lifetime_ordinal 值，且與特定串流相關的所有訊息的值都相同。
4	`start_offset`	`uint32`	相關緩衝區的哪個部分會使用這個封包。這些憑證適用於正在傳輸至串流處理器的輸入資料，且適用於串流處理器的輸出資料。如為壓縮格式和未壓縮音訊，[start_offset, start_offset + valid_length_bytes) 中的資料是此封包參照的連續有效資料。針對未壓縮的影格，FormatDetails 是判斷哪些位元組相關的主要方式。FormatDetails 中的偏移量與此處的 start_offset 相關。valid_length_bytes 必須夠大，才能包含完整的像素資料，包括最後一行的完整行距 (不只是最後一行的像素寬度)。雖然已填入這些值，但部分未壓縮影片緩衝區屬於 CPU 無法讀取的類型。這裡所列出的欄位並不代表 CPU 能夠讀取未壓縮的影格。
5	`valid_length_bytes`	`uint32`	必須大於 0。每個封包的有效資料語意會因資料類型而異，如下所示。未壓縮影片 - 無法將影片影格分割成各個封包。每個封包都是一個影片影格。未壓縮音訊 - 無論浮點數、線性或 uLaw 為何，封包都必須包含非負數的完整音訊影格，其中單一音訊影格會包含同一時間點的所有聲道資料。若為 LFE 管道或其他類似情況採用串流處理器專屬內部詳細資料，則應該在 StreamProcessor 伺服器實作時隱藏該功能。壓縮的資料輸入 - 封包至少必須包含 1 個位元組的資料。另請參閱 stream_input_bytes_min。系統允許以任意位元組邊界分割 AU，包括在 AU 標頭中的邊界。壓縮的資料輸出 - 不需要串流處理器來填滿每個輸出封包的緩衝區。
6	`timestamp_ish`	`uint64`	這個值不得嚴格說出時間戳記。這是任意未簽署的 64 位元數字，在某些情況下，串流處理器會從輸入封包中未經修改的輸入封包傳送至確切對應的輸出封包。如要將 timestamp_ish 值從輸入套用到輸出，必須符合下列條件： promise_separate_access_units_on_input 必須是 true 特定輸入封包的 has_timestamp_ish 必須為 true，才能將 timestamp_ish 值 (可能) 套用到輸出 StreamProcessor 執行個體本身會決定 (非同步) 輸入封包會產生輸出封包 - 如果特定輸入內容從未產生輸出封包，則輸入上的 timestamp_ish 值一律不會顯示在任何輸出封包上，取決於輸入和輸出格式的特性，以及解碼器是否願意彙整處理中串流值。
7	`start_access_unit`	`bool`	如果 promise_separate_access_units_on_input (TODO(dustingreen)) 或任何類似的輸出模式為 true，就必須根據位元組 0「是」還是「不是」存取單元的啟動條件，設定適當的布林值。用戶端必須知道，且必須正確設定該布林值。伺服器可推論此佈林值為 false 時，位元組 0 是先前啟動 AU 接續作業的第一個位元組。start_offset 的位元組為「位元組 0」。) 如果 promise_separate_access_units_on_input 為 false，系統就會忽略這個布林值。
8	`known_end_access_unit`	`bool`	用戶端完全不需要將布林值設為 true。如果 promise_separate_access_units_on_input 為 true，針對輸入資料，如果此封包的最後一個位元組不是 AU 的最後一個位元組，此佈林值就必須為 false，如果這個封包的最後一個位元組是 AU 的最後一個位元組，此佈林值就「可」為 true。如果用戶端只傳送一個 AU，而該時間有意透過解碼器盡可能縮短延遲時間，則應將該布林值設為 true 時，應將其設為 true。如果 promise_separate_access_units_on_input 為 false，系統就會忽略這個布林值。
9	`key_frame`	`bool`	用於壓縮影片封包。如果沒有出現，則應假設其不明。如果值為 false，表示封包不屬於索引鍵影格的一部分。如為 true，表示封包屬於索引鍵影格的一部分。

PacketHeader

PacketHeader

參照免費封包時，我們會單獨使用 PacketHeader 而非 Packet，因為即使封包是自由封包，並沒有有意義的偏移或長度等。

已填入的封包也有 PacketHeader。

序數廣闊類型說明

1

buffer_lifetime_ordinal

uint64

這是這個標頭所參照的緩衝區設定生命週期。

對特定 buffer_lifetime_ordinal 而言，封包_索引才有意義。

請參閱 StreamBufferPartialSettings.buffer_lifetime_ordinal。

針對 QueueInputPacket() 伺服器接收的 buffer_lifetime_ordinal 不是目前輸入的 buffer_lifetime_ordinal，關閉管道。

如果是 OnFreeInputPacket() 和 RecycleOutputPacket()，接收器 (用戶端或伺服器) 必須忽略含有過時 buffer_lifetime_ordinal 的訊息。

2

packet_index

uint32

整體封包_index 值會由 0..count-1 密集封裝，以分別輸入和輸出。且可依任何順序排入佇列。

用戶端和伺服器應根據已知繫結驗證 package_index，如果封包超出邊界，就會中斷連線。

以單一緩衝區模式執行時，緩衝區索引一律為 0。

封包_index 值並非任何關於封包使用順序的任何資訊。用戶端應該不會預期一段時間內的順序都會保持不變 - 串流處理器可自由保留一段時間，以保留輸入或輸出封包一段時間，在此期間，其他封包_索引值可多次使用。

就特定正常運作的 StreamProcessor 執行個體而言，在並行處理的封包中，封包_index 值會是唯一的。伺服器應驗證用戶端不會重複使用封包，且用戶端應視需要進行驗證，以避免未定義或非預期的用戶端行為。

StreamBufferConstraints

這個結構會傳遞 buffer_constraints_version_ordinal。

過去，這個資料表傳送的欄位比目前多，但這些欄位都已淘汰，改為使用 sysmem。

這個結構會分別用於串流輸入和串流輸出。

欄位相關注意事項：

如果是未壓縮影片，請以個別緩衝區 (緩衝區模式) 分隔及完整影格則一律是必要作業。

序數	廣闊	類型	說明
1	`buffer_constraints_version_ordinal`	`uint64`	這是伺服器對限制設定的版本號碼，可讓伺服器判斷用戶端何時符合伺服器傳送的最新限制。除非用戶端已指定輸出設定，以及具有 buffer_constraints_version_ordinal >= 最新 buffer_constraints_version_ordinal 且有 buffer_constraints_action_required 的緩衝區，伺服器會發出輸出資料。詳情請參閱 buffer_constraints_action_required 註解。系統不允許使用 buffer_constraints_version_ordinal 來簡化初始狀態處理。除了 0 以外，我們允許奇數或偶數版本序數 (相對於 stream_lifetime_ordinal，用戶端和伺服器都沒有理由考慮最新版本已過時，因此拒絕偶數值也沒有好處)。
2	`default_settings`	`StreamBufferSettings`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
3	`per_packet_buffer_bytes_min`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
4	`per_packet_buffer_bytes_recommended`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
5	`per_packet_buffer_bytes_max`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
6	`packet_count_for_server_min`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
7	`packet_count_for_server_recommended`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
8	`packet_count_for_server_recommended_max`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
9	`packet_count_for_server_max`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
10	`packet_count_for_client_min`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
11	`packet_count_for_client_max`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
12	`single_buffer_mode_allowed`	`bool`	已淘汰 - 忽略。已過時。
13	`is_physically_contiguous_required`	`bool`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()

StreamBufferPartialSettings 資源

序數	廣闊	類型	說明
1	`buffer_lifetime_ordinal`	`uint64`	包含的訊息會啟動新的 buffer_lifetime_ordinal。輸入和輸出會有一個獨立的 buffer_lifetime_ordinal。請勿重複使用相同的值。值必須是奇數。值只能增加 (允許增加超過 2)。 buffer_lifetime_ordinal 生命週期從 SetInputBufferSettings() 或 SetOutputBufferSettings() 開始，結束於 CloseCurrentStream() 較早，使用 release_input_buffers/release_output_buffers 組合或 SetOutputBufferSettings()，於串流中輸出設定變更時採用新的 buffer_lifetime_ordinal。
2	`buffer_constraints_version_ordinal`	`uint64`	這個值代表用戶端目前/已瞭解的限製版本。由於輸入的限制不會變更 (設定可以變更，但目前的限制與輸入時限制的同步處理問題並沒有設定比較)，因此這個值必須一律為 0。針對輸出，這可讓伺服器判斷用戶端何時準備就緒，再伺服器會產生更多輸出。如果沒有使用中的串流，用戶端可以使用相同的 buffer_constraints_version_ordinal 重新設定緩衝區。
3	`single_buffer_mode`	`bool`	已淘汰 - 忽略。已過時。
4	`packet_count_for_server`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
5	`packet_count_for_client`	`uint32`	已淘汰 - 忽略。使用 fuchsia.sysmem.BufferCollection.SetConstraints()
6	`sysmem_token`	`fuchsia.sysmem/BufferCollectionToken`	BufferCollectionToken 管道的用戶端端，StreamProcessor 會使用此管道將限制傳送至 sysmem，並瞭解 sysmem 配置的緩衝區。用戶端會保證 sysmem 已知該權杖 (透過 BufferCollectionToken.Sync()、BufferCollection.Sync() 或 BufferCollectionEvents.OnDuplicatedTokensKnownByServer())。

StreamBufferSettings

已淘汰，請改用 SetStreamBufferPartialSettings() 和 StreamBufferPartialSettings。

已淘汰 - 忽略。請改用 SetStreamBufferPartialSettings。

序數	廣闊	類型	說明
1	`buffer_lifetime_ordinal`	`uint64`	已淘汰 - 忽略。請改用 SetStreamBufferPartialSettings。
2	`buffer_constraints_version_ordinal`	`uint64`	已淘汰 - 忽略。請改用 SetStreamBufferPartialSettings。
3	`packet_count_for_server`	`uint32`	已淘汰 - 忽略。請改用 SetStreamBufferPartialSettings。
4	`packet_count_for_client`	`uint32`	已淘汰 - 忽略。請改用 SetStreamBufferPartialSettings。
5	`per_packet_buffer_bytes`	`uint32`	已淘汰 - 忽略。請改用 SetStreamBufferPartialSettings。
6	`single_buffer_mode`	`bool`	已淘汰 - 忽略。請改用 SetStreamBufferPartialSettings。

StreamOutputConstraints

串流處理器控管的輸出設定，包括輸出的 StreamBufferConstraints 和輸出的 FormatDetails。

序數廣闊類型說明

1

stream_lifetime_ordinal

uint64

如果用戶端一律在接收到 OnOutputConstraints() 時立即重新設定輸出緩衝區，且 buffer_constraints_action_required true，即可放心忽略此欄位。

即使用戶端已要求伺服器忽略含有相同 stream_lifetime_ordinal 的串流其餘部分，或這個 stream_lifetime_ordinal 欄位設為 0 的情況下，用戶端仍可忽略 OnOutputConstraints() 訊息，即使 buffer_constraints_action_required true，如果最近已完成的伺服器端輸出設定並非伺服器對新串流的需求/需求，該伺服器必須透過 OnOutputConstraints() 以新的 stream_lifetime_ordinal 和 buffer_constraints_action_required，重新傳送必要的輸出設定。

2

buffer_constraints_action_required

bool

傳遞緩衝區限制時，訊息會指出是否需要操作。這裡的 false 值允許傳送較新的限制，而不強制執行緩衝區重新設定。如果為 false，用戶端將無法假設立即重新設定輸出緩衝區可以安全。如果為 true，用戶端可以假設立即設定一次輸出緩衝區十分安全。

用戶端可以忽略具有 buffer_constraints_action_required false 的緩衝區限製版本。伺服器不得將相同 buffer_constraints_version_ordinal 的 buffer_constraints_action_required 從 false 變更為 true。

進行每項設定時，用戶端必須使用新的緩衝區、先前不得用於其他串流的緩衝區，而且先前不得用於任何其他 StreamProcessor 用途的緩衝區。這項規則存在很多合理原因，都與串流中途的變化，以及串流邊界的變化相關。用戶端每次都應使用新的緩衝區。

當這個要求為 true 時，伺服器已解除所有低層級輸出緩衝區的回應，因為伺服器可以同時執行有效的轉換至新緩衝區，並捨棄其餘的浮動式訊息。您不需要使用 Sync()，在相關格式允許的範圍內有效達到非重疊的資源用量。

如果 buffer_constraints_action_required 為 true，伺服器必須在用戶端設定 (或重新設定) 輸出緩衝區之後，才能傳送更多輸出資料。

3

buffer_constraints

StreamBufferConstraints

StreamOutputFormat

序數廣闊類型說明

1

stream_lifetime_ordinal

uint64

即使用戶端已要求伺服器忽略含有相同 stream_lifetime_ordinal 的串流的剩餘部分，或這個 stream_lifetime_ordinal 欄位設為 0 的情況下，則用戶端仍可忽略 OnOutputFormat() 訊息，即使有 buffer_constraints_action_required，如果最近已完成的伺服器端輸出設定並非伺服器對新串流的需求/需求，該伺服器必須透過 OnOutputConstraints() 以新的 stream_lifetime_ordinal 和 buffer_constraints_action_required，重新傳送必要的輸出設定。

該伺服器必須在串流的第一個輸出封包之前傳送 OnOutputFormat()。

2

format_details

FormatDetails

如果 format_details.format_details_version_ordinal 變更，用戶端應檢查新格式的詳細資料，並判斷是否必須根據新格式進行調整。伺服器會保證如果格式已變更，format_details.format_details_version_ordinal 會變更，但對 format_details.format_details_version_ordinal 所做的變更，並不保證格式詳細資料實際上已變更。除非串流中的串流內格式發生變更，否則強烈建議伺服器不要變更串流的第一個輸出資料之前的時間 format_details.format_details_version_ordinal。不必要的中串流內格式變更，可能導致無須處理中串流格式變更的簡易用戶端直接關閉管道。在這種情況下，格式變更之前在串流的第一個輸出資料都不算是「串流內」，這對於偵測 / 設定串流格式而言很有幫助。

請注意，如果輸出緩衝區不一定需要重新設定，儘管有格式變更，我們鼓勵 (而非強制) 伺服器在傳送新格式詳細資料的訊息上設定 buffer_constraints_action_required false。較簡單的伺服器可以將整個輸出情況視為一大重點，並且需要在輸出情況發生任何變更時，重新設定輸出緩衝區。

用戶端不一定能處理含有 buffer_constraints_action_required false 的新 buffer_constraints，但用戶端應一律追蹤最新的 format_details。

已更新的 format_details 會根據已傳送的輸出封包排序，並套用至所有後續封包，直到下一個 version_ordinal 較大的 version_details 中。不打算處理中串流格式變更的簡單用戶端，仍應持續追蹤最新收到的 format_details，直到第一個輸出封包送達為止，然後鎖定格式詳細資料，處理這些格式詳細資料，並確認從伺服器接收到的所有 format_details.format_details_version_ordinal 格式詳細資料都與鎖定的資料相同，直到用戶端完成串流為止。即使是如此簡單的用戶端，也必須容許 format_details.format_details_version_ordinal 多次變更，才能從串流 (任何串流是指第一個串流或後續串流) 開始輸出資料前多次進行變更。如此一來，串流處理器就能要求指定輸出緩衝區和輸出格式，並在伺服器在收到第一個串流資料輸出之前，能夠知道完整建立初始輸出格式詳細資料所需的一切資訊之後，選擇由伺服器選擇調整輸出設定。這樣可簡化串流處理工具伺服器實作作業，並巧妙的串流處理器伺服器猜測輸出設定，可在任何輸入資料之前縮短延遲時間，同時即使猜測結果有誤，也能修正輸出設定 (包括格式詳細資料)。

指定 format_details.format_details_version_ordinal 是否實際上會變更片中廣告為各個串流的處理器及個別串流詳細資料，而且未在此處的註解中指定，而且在大多數情況下，也取決於串流處理工具輸入內容的格式是否改變。用戶端使用的格式通常可以支援中游格式變更，雖然很常見，但用戶端卻知道，用戶端打算處理的所有串流都不會有中流格式變更。

UsageStateDucked

音訊使用狀態，該狀態是由政策決定，會暫時降低有此用量的所有串流音量。

序數	廣闊	類型	說明

UsageStateMuted

音訊使用狀態，此狀態已做出政策決定，以便暫時將有此用量的所有串流音量設為靜音。

序數	廣闊	類型	說明

UsageStateUnadjusted

此狀態的音訊使用狀態，也就是說，系統不會對使用該使用情形的串流執行政策。

序數	廣闊	類型	說明

聯合國

AacBitRate 嚴格

在 fuchsia.media/stream_common.fidl 中定義

序數	Variant	類型	說明
1	`constant`	`AacConstantBitRate`
2	`variable`	`AacVariableBitRate`

AacTransport 彈性

在 fuchsia.media/stream_common.fidl 中定義

序數	Variant	類型
1	`raw`	`AacTransportRaw`
2	`latm`	`AacTransportLatm`
3	`adts`	`AacTransportAdts`

AudioCapturerConfiguration 嚴格

音訊擷取器的設定。

序數	Variant	類型	說明
1	`loopback`	`LoopbackAudioCapturerConfiguration`
2	`input`	`InputAudioCapturerConfiguration`

AudioCompressFormat 彈性

在 fuchsia.media/stream_common.fidl 中定義

序數	Variant	類型	說明
1	`aac`	`AudioCompressedFormatAac`
2	`sbc`	`AudioCompressedFormatSbc`
3	`cvsd`	`AudioCompressedFormatCvsd`	已新增：HEAD
4	`lc3`	`AudioCompressedFormatLc3`	已新增：HEAD

AudioConsumerError 嚴格

代表 AudioConsumer 錯誤狀況。

序數	Variant	類型	說明
1	`place_holder`	`Void`

音訊格式嚴格

在 fuchsia.media/stream_common.fidl 中定義

AudioFormat

序數	Variant	類型	說明
1	`compressed`	`AudioCompressedFormat`
2	`uncompressed`	`AudioUncompressedFormat`

AudioUncompedFormat 嚴格

在 fuchsia.media/stream_common.fidl 中定義

AudioUncompressedFormat

序數	Variant	類型	說明
1	`pcm`	`PcmFormat`

加密格式彈性

在 fuchsia.media/stream_common.fidl 中定義

CryptoFormat

加密 (加密或解密) 格式詳細資料。

序數	Variant	類型	說明
1	`encrypted`	`EncryptedFormat`
2	`decrypted`	`DecryptedFormat`

網域格式嚴格

在 fuchsia.media/stream_common.fidl 中定義

DomainFormat

序數	Variant	類型
1	`audio`	`AudioFormat`
2	`video`	`VideoFormat`
3	`crypto`	`CryptoFormat`

EncoderSettings彈性

在 fuchsia.media/stream_common.fidl 中定義

編碼器設定指示器如何對原始格式編碼。

序數	Variant	類型	說明
1	`sbc`	`SbcEncoderSettings`
2	`aac`	`AacEncoderSettings`
3	`h264`	`H264EncoderSettings`
4	`hevc`	`HevcEncoderSettings`
5	`cvsd`	`CvsdEncoderSettings`	已新增：HEAD
6	`lc3`	`Lc3EncoderSettings`	已新增：HEAD
7	`msbc`	`MSbcEncoderSettings`	已新增：HEAD

Medium specificStreamType 嚴格

所有中型串流類型結構的聯集。

序數	Variant	類型
1	`audio`	`AudioStreamType`
2	`video`	`VideoStreamType`
3	`text`	`TextStreamType`
4	`subpicture`	`SubpictureStreamType`

用量嚴格

序數	Variant	類型	說明
1	`render_usage`	`AudioRenderUsage`
2	`capture_usage`	`AudioCaptureUsage`

UsageState 彈性

串流或一組串流的音訊政策強制執行狀態。

序數	Variant	類型
1	`unadjusted`	`UsageStateUnadjusted`
2	`ducked`	`UsageStateDucked`
3	`muted`	`UsageStateMuted`

值嚴格

在 fuchsia.media/stream_common.fidl 中定義

值

用於一般「參數」結構體中的通用「value」。

序數	Variant	類型
1	`bool_value`	`bool`
2	`uint64_value`	`uint64`
3	`int64_value`	`int64`
4	`string_value`	`string`
5	`bytes_value`	`vector<uint8>`

VideoCompressFormat 嚴格

在 fuchsia.media/stream_common.fidl 中定義

VideoCompressedFormat

壓縮影片格式詳細資料。

序數	Variant	類型	說明
1	`temp_field_todo_remove`	`uint32`

影片格式嚴格

在 fuchsia.media/stream_common.fidl 中定義

VideoFormat

影片 (壓縮或未壓縮) 格式的詳細資料。在這種情況下，「未壓縮」可能包含區塊式圖片壓縮格式，但這類格式仍可隨機快速存取圖片資料。

序數	Variant	類型	說明
1	`compressed`	`VideoCompressedFormat`
2	`uncompressed`	`VideoUncompressedFormat`

帳單

AudioConsumerStartFlags 嚴格

類型：uint32

傳送至 AudioConsumer.Start 的旗標。

名稱	值	說明
LOW_LATENCY	1	表示應盡可能降低延遲時間。
SUPPLY_DRIVEN	2	表示封包傳送的時間，是由外部程序 (而非以要求為準) 決定。設定此標記後，由於封包到達率與顯示率不符，因此服務應預期溢位或溢位。如未設定此標記，封包會隨需求送達。

AudioGetInfoFlags 嚴格

類型：uint32

名稱	值	說明
關閉	1
AGC_SUPPORTED	2
AGC_ENABLED	4

AudioGetValidFlags 嚴格

類型：uint32