fuchsia.audio

已新增：HEAD

通訊協定

DelayWatcher

定義於 fuchsia.audio/delay.fidl

請留意變更時間有所延遲。

WatchDelay

如果知道目前的延遲時間，第一次呼叫會立即傳回。後續呼叫將遭到封鎖，直到延遲時間變更為止。最多只能有一項未公開的呼叫，否則管道可能會關閉。

要求

名稱類型
payload DelayWatcherWatchDelayRequest

回應

名稱類型
payload DelayWatcherWatchDelayResponse

GainControl

定義於 fuchsia.audio/gain.fidl

啟用音訊增益的控管與監控功能。這個介面通常是拆開其他介面。

旋鈕

這個介面公開了兩個直角旋鈕：

  • gain 旋鈕控制「相關分貝」中的單一值。將值設為 0 時，不會套用增益、正值增加增值，而負值的增值則不會套用。根據情境而定，增值可能會與輸入串流的相對值或相對的絕對參照點相比套用，例如喇叭的最大音量。

    這個旋鈕沒有定義的最大或最小值。個別實作項目可能會限制使用實作定義的最大值，或者將值低於實作定義的最小值 (相當於「靜音」) 以下所有值，但這不是必要行為。

  • 「Mute」滑桿可控制單一布林值。當 true 時，GainControl 會設為靜音，有效增益則為負無限大。當 false 時，增益是由「復原」旋鈕控制。

時段設定

「再次」和「靜音」旋鈕可以安排在未來的時間。排程的發生時間是與參考時鐘相對，而參照時鐘必須在這個通訊協定建立時建立。

TODO(https://fxbug.dev/42176154)：排程語意可能會有所變動

SetGain

設定增益滑鈕。

要求

名稱類型
payload GainControlSetGainRequest

回應

名稱類型
payload GainControl_SetGain_Result

SetMute

設定靜音旋鈕。

要求

名稱類型
payload GainControlSetMuteRequest

回應

名稱類型
payload GainControl_SetMute_Result

StreamSink

在 fuchsia.audio/stream_sink.fidl 中定義

用於跨程序音訊串流傳輸的封包接收器，由音訊使用者實作，並由音訊生產者使用。

結束

表示已結束串流。音訊轉譯器等消費者端會在串流結束前的最後一個封包轉譯時通知用戶端，因此用戶端會知道何時該變更播放器的 UI 狀態，讓使用者知道內容播放完畢。此方法在邏輯上限定於目前的區隔。SetSegment 要求和 (通常) 更多封包可能會遵循這項要求。

要求

<EMPTY>

OnWillClose

在取用端關閉之前傳送，用於指出取用端關閉連線的原因。傳送此事件後，取用端不得再傳送任何訊息並立即關閉連線。

回應

名稱類型
payload StreamSinkOnWillCloseRequest

PutPacket

將封包放進接收器。

要求

名稱類型
payload StreamSinkPutPacketRequest

StartSegment

開始新區隔。系統會將這項要求之後和下一個要求之前的封包指派給該區隔。

要求

名稱類型
payload StreamSinkStartSegmentRequest

WillClose

在生產端關閉之前傳送，以指出生產端關閉連線的原因。傳送這項要求後，生產端必須避免再傳送任何訊息，並立即關閉連線。

要求

名稱類型
payload StreamSinkWillCloseRequest

結構化

UnspecifiedBestEffort

定義於 fuchsia.audio/stream_sink.fidl

<EMPTY>

UnspecifiedContinuous

定義於 fuchsia.audio/stream_sink.fidl

<EMPTY>

ENUMS

ChannelConfig 彈性

類型：uint32

定義於 fuchsia.audio/format.fidl

頻道的空間分配。

名稱值說明
1

Front.C (置中)
2

正面 (左) | 前置鏡頭 (右)
3

Front.L | Front.R | Back.L | Back.R (又稱「四個角落」)
4

Front.L | Front.R | Back.C (又稱「LRS」)
5

Front.L | Front.R | Front.C | Back.C (又稱「LRCS」)
6

Front.L | Front.R | Front.C | LFE | Side.L | Side.R

CompressionType 彈性

類型：uint32

定義於 fuchsia.audio/compression.fidl

名稱值說明
0
1
2
3
4
5
6
7
8
9
10
11
12
13

GainError 彈性

類型：uint32

定義於 fuchsia.audio/gain.fidl

GainControl 傳回的錯誤類型。

名稱值說明
1

尚未填寫所有必填欄位。
2

彈性欄位含有不支援的選項。當使用 API 版本 X+1 建構的用戶端與使用 API 版本 X 建構的伺服器通訊時，就可能發生這種情況。

SampleType 彈性

類型：uint32

定義於 fuchsia.audio/format.fidl

表示個別音訊樣本的類型。

名稱值說明
1
2
3
4
5

資料表

壓縮

如 fuchsia.audio/compression.fidl 定義

說明套用至串流的壓縮。

序數欄位類型說明
type CompressionType

套用至串流的壓縮類型。
oob_parameters vector<uint8>[32768]

說明串流壓縮的不透明「頻外」參數。這個欄位的格式是 CompressionType 的函式。這些程式碼會傳遞必要的解碼器參數，以便解壓縮說明的串流。許多壓縮類型不需要這個欄位。

DelayWatcherWatchDelayRequest

定義於 fuchsia.audio/delay.fidl

序數欄位類型說明

DelayWatcherWatchDelayResponse

定義於 fuchsia.audio/delay.fidl

序數欄位類型說明
delay zx/Duration

選用。如未指定，表示延遲時間不明。

格式

定義於 fuchsia.audio/format.fidl

說明未參照壓縮的音訊串流專用格式。在支援壓縮的情況下，這個類型應與 fuchsia.media2.Compression 合併。未壓縮的音訊串流使用 LPCM 編碼。

序數欄位類型說明
sample_type SampleType

個別樣本的類型。
channel_count uint32

每影格的取樣數量。
frames_per_second uint32

每秒影格數。
channel_layout ChannelLayout

每個管道的空間分配。

GainControlSetGainRequest

定義於 fuchsia.audio/gain.fidl

序數欄位類型說明
how GainUpdateMethod

如何更新取得旋鈕。

必填。
when fuchsia.media2/RealTime

套用這項更新的時機。

必填。

GainControlSetMuteRequest

定義於 fuchsia.audio/gain.fidl

序數欄位類型說明
muted bool

靜音旋鈕的新值。

必填。
when fuchsia.media2/RealTime

套用這項更新的時機。

必填。

GainControl_SetGain_Response

定義於 fuchsia.audio/gain.fidl

序數欄位類型說明

GainControl_SetMute_Response

定義於 fuchsia.audio/gain.fidl

序數欄位類型說明

封包

在 fuchsia.audio/stream_sink.fidl 中定義

說明透過 StreamSink 傳送的封包。

序數欄位類型說明
payload fuchsia.media2/PayloadRange

這個封包的酬載位置。這是必填欄位。
timestamp Timestamp

指出這個封包何時應呈現的時間戳記。省略這個欄位即表示使用 unspecified_best_effort 時間戳記。
capture_timestamp zx/Time

以系統單調時間值來擷取這個封包的時間。此為選用欄位，可擷取器設定用來指出擷取這個封包的時間。
flags PacketFlags

說明封包的旗標。省略這個欄位表示所有標記都很清楚。
front_frames_to_drop uint32

指出解碼器從這個輸入封包產生的輸出封包前方應捨棄多少影格。這個值僅適用於壓縮串流。如果省略這個欄位，則不應捨棄任何前端影格。
back_frames_to_drop uint32

指出解碼器從這個輸入封包產生的輸出封包背面應捨棄多少影格。這個值僅適用於壓縮串流。如果省略這個欄位，則不應該捨棄任何背景影格。
encryption_properties fuchsia.drm/PacketEncryptionProperties

說明此封包套用的加密方式。省略此欄位表示封包未加密。

RampFunctionLinearSlope

定義於 fuchsia.audio/gain.fidl

獲利會沿著線性領域，繪製一條線性的斜率。

舉例來說，從 -2.3dB 到 -1.6dB 的交流道，是 0.1 到 0.5 的線性領域交流道。如果套用時間超過 4 毫秒，則再次更新的順序如下：

  • 用 0 毫秒時獲得 = 0.1 = -2.3dB
  • 1 毫秒時，獲利 = 0.2 = -2.0dB
  • 2 毫秒時增益 = 0.3 = -1.8dB
  • 3 毫秒時獲得 = 0.4 = -1.7dB
  • 於 4 毫秒時增加 = 0.5 = -1.6dB

請注意，dB 的變化會遵循對數 (而非線性) 曲線。

序數欄位類型說明

RampedGain

定義於 fuchsia.audio/gain.fidl

說明增加增益指令。套用此指令時，系統會使用指定函式，在指定持續時間內，從目前值降級至目標值。

序數欄位類型說明
target_gain_db float32
duration zx/Duration
function RampFunction

RingBuffer 資源

定義於 fuchsia.audio/ring_buffer.fidl

音訊資料的環形緩衝區。

每個環形緩衝區都包含生產端 (寫入緩衝區) 和取用端 (從緩衝區讀取資料的使用者)。此外，每個環形緩衝區都與參照時鐘相關聯，可延長緩衝區的時間。

PCM 資料

PCM 音訊的環形緩衝區是一個視窗，會形成可能無限的影格序列。每個影格都會獲派一個「影格編號」，其中第一個影格的編號為 0。您可在環形緩衝區偏移 (X % RingBufferFrames) * BytesPerFrame 找到影格 X，其中 RingBufferFrames 是影格中的環形緩衝區大小，BytesPerFrame 是單一影格的大小。

並行通訊協定

每個環形緩衝區各有一個生產端和單一取用端，且會按時間同步處理。在每個時間點 T 時，我們會根據環形緩衝區的參照時鐘定義兩個函式：

  • SafeWritePos(T) 是生產端允許寫入的最低 (最舊) 影格編號。生產端可以寫入這個框架或任何較高編號的影格。

  • SafeReadPos(T) 是使用者可以讀取的最高 (最年輕) 影格編號。取用者可讀取這個影格或任何小於編號的影格。

為避免衝突，我們將這些項目定義為 1：

SafeWritePos(T) = SafeReadPos(T) + 1

為避免競爭，必須設置單一生產端，但可能會有多位消費者。此外，由於生產端和取用端會依照「時間」同步處理，因此我們必須設定明確的圍欄來確保快取一致性：生產端必須在每次寫入後插入適當的圍欄 (以便清除 CPU 快取，並防止編譯器重新排序)，且取用端必須在每次讀取前插入適當的圍欄 (這樣可讓 CPU 快取失效並避免編譯載入作業失效)。

由於緩衝區的大小有限，因此生產端/取用端無法無限在日後/過去的寫入/讀取作業。我們將 P 影格配置給生產端和 C 影格，並由建立環形緩衝區的人選擇 P + C <= RingBufferFrames 和 P 和 C。

決定日期：P和C

在實務上，生產者/消費者通常會定期寫入/讀取影格數。舉例來說，生產端可能會每 Dp 毫秒醒來以寫入 DpFrameRate 影格，其中 FrameRate 是 PCM 串流的影格速率。如果生產端在 T 時間喚醒，則最多花費到下一個 Dp 期間寫入這些影格。這表示它可以安全寫入的最低影格編號為 SafeWritePos(T+Dp)，相當於 SafeWritePos(T) + DpFrameRate。生產端會從位置開始寫入 DpFrameRate 影格。整個區域 (SafeWritePos(T) 到 2DpFrameRate ) 都必須在 T 時分配給生產端。為消費者做出類似的論點，我們將有以下限制：

P >= 2DpFrameRate
C >= 2Dc*FrameRate
RingBufferFrames >= P + C

因此，在實務上，P 和 C 可從生產端和取用端使用的批次大小衍生，其中批次大小受限於環形緩衝區大小。

定義 SafeWritePos

SafeWritePos 的定義 (隱含，SafeReadPos) 必須在架構外提供。

非 PCM 資料

非 PCM 資料的處理方式與 PCM 資料類似，但位置會以「位元組偏移」而非「影格數」表示，其中無限順序的起始位置為位元組偏移 0。

序數欄位類型說明
buffer fuchsia.mem/Buffer

實際的環形緩衝區。producer_bytes 和 consumer_bytes 的總和必須 <= buffer.size。

必填。
format Format

緩衝區中的音訊資料編碼。必填。
producer_bytes uint64

分配給生產端的位元組數。

如果是 PCM 編碼，P = producer_bytes / BytesPerFrame(format)，其中 P 必須為積分。

非 PCM 編碼沒有限制，但個別編碼可能會要求更嚴格的要求。

必填。
consumer_bytes uint64

分配給消費者的位元組數。

如果是 PCM 編碼，C = consumer_bytes / BytesPerFrame(format)，其中 C 必須為積分。

非 PCM 編碼沒有限制，但個別編碼可能會要求更嚴格的要求。

必填。
reference_clock handle<clock>

環形緩衝區的參考時鐘。

必填。
reference_clock_domain uint32

reference_clock 的網域。請參閱 fuchsia.hardware.audio.ClockDomain。TODO(https://fxbug.dev/42066209)：如果 fuchsia.hardware.audio 不需要匯入 fuchsia.audio，可以直接在下方使用該類型。

選用。如未指定，則會預設為 CLOCK_DOMAIN_EXTERNAL。

StreamSinkOnWillCloseRequest

定義於 fuchsia.audio/stream_sink.fidl

序數欄位類型說明
reason fuchsia.media2/ConsumerClosedReason

連線關閉的原因。

StreamSinkPutPacketRequest 資源

定義於 fuchsia.audio/stream_sink.fidl

序數欄位類型說明
packet Packet

說明封包。這是必填欄位。
release_fence handle<eventpair>

系統會在取用端完成封包時關閉事件配對，且可能會重複使用與該封包相關聯的緩衝區區域。封包可能會按任何順序發布。服務可能會複製發布圍欄，因此必須使用正確的 ZX_RIGHT_DUPLICATE 傳送。這是選填欄位。

StreamSinkStartSegmentRequest

定義於 fuchsia.audio/stream_sink.fidl

序數欄位類型說明
segment_id int64

用於識別區隔。指定連線的新區隔 ID 必須一律嚴格增加。這是必填欄位。

StreamSinkWillCloseRequest

定義於 fuchsia.audio/stream_sink.fidl

序數欄位類型說明
reason fuchsia.media2/ProducerClosedReason

連線關閉的原因。

聯合國

ChannelLayout 彈性

定義於 fuchsia.audio/format.fidl

表示在音訊串流中歸納出的聲道分配方式。

序數Variant類型說明
config ChannelConfig

這個值會說明每個管道的分配情形。管道設定必須與 channel_count 一致。

GainControl_SetGain_Result (嚴格)

定義於 fuchsia.audio/gain.fidl

序數Variant類型說明
response GainControl_SetGain_Response
err GainError

GainControl_SetMute_Result 嚴格

定義於 fuchsia.audio/gain.fidl

序數Variant類型說明
response GainControl_SetMute_Response
err GainError

GainUpdateMethod 彈性

定義於 fuchsia.audio/gain.fidl

支援的取得更新類型。

序數Variant類型說明
gain_db float32

立即將增益設為這個值。
ramped RampedGain

利用坡道逐漸變化增益。

RampFunction 彈性

定義於 fuchsia.audio/gain.fidl

支援的遞增函式類型。

序數Variant類型說明
linear_slope RampFunctionLinearSlope

時間戳記彈性

在 fuchsia.audio/stream_sink.fidl 中定義

指出音訊封包在串流時間軸中的位置。

序數Variant類型說明
specified int64

直播時間軸的指定時間。單位會有所不同，在建立連線時會提供。
unspecified_continuous UnspecifiedContinuous

表示如果前一個封包，該封包應在前一個封包之後立即顯示。如果先前沒有任何封包，這個選項就等於 specified 值 0。

這個選項表示即使封包延遲抵達，串流時間軸也不應「滑動」。封包應在前一個封包之後立即顯示，無論封包抵達時間為何，系統都會保留產生的時間。
unspecified_best_effort UnspecifiedBestEffort

表示封包應在前一個封包之後盡快提供 (如果存在的話)，否則應盡快呈現。

這個選項暗示如果封包送達的時間太晚，無法在前一個封包之後立即顯示，串流時間應「slip」。如果未加上時間戳記的串流中發生空隙，或許是因為缺少上游來源所致，通常就會使用此選項。

帳單

封包旗標彈性

類型：uint32

在 fuchsia.audio/stream_sink.fidl 中定義

說明封包的旗標。

名稱值說明
1

表示僅提供此封包，以便解譯較晚的封包。解碼器應捨棄從這個封包產生的解壓縮封包。

業者

名稱值類型說明
MAX_COMPRESSION_PARAMETERS_SIZE 32768 uint64

大小上限為 Compression.parameters。