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 狀態， 內容播放完畢後這個方法的邏輯範圍限定為目前的區隔。A 罩杯 收到 SetSegment 要求和 (通常) 還有更多封包可以處理這項要求。

要求

<空白>

OnWillClose

在消費者即將結束及停止購物前傳送，說明消費者為何選擇放棄 以獲得最佳效能和最安全的連線傳送此事件後，取用端必須避免傳送 並立即關閉連線。

回應

名稱類型
payload StreamSinkOnWillCloseRequest

PutPacket

將封包放入接收器。

要求

名稱類型
payload StreamSinkPutPacketRequest

StartSegment

建立新區隔。後續和下一個此要求之後的封包 會指派給區隔

要求

名稱類型
payload StreamSinkStartSegmentRequest

WillClose

在生產者關閉前立即傳送，以指出生產者關閉 以獲得最佳效能和最安全的連線傳送這項要求後，製作者不得再傳送任何要求 並立即關閉連線。

要求

名稱類型
payload StreamSinkWillCloseRequest

結構

UnspecifiedBestEffort

在 fuchsia.audio/stream_sink.fidl 中定義的

<空白>

UnspecifiedContinuous

在 fuchsia.audio/stream_sink.fidl 中定義的

<空白>

ENUMS

ChannelConfig 彈性

類型：uint32

定義於 fuchsia.audio/format.fidl

管道的空間指派。

名稱值說明
1

前端 (中心)
2

Front.L (左) |前置 R (右)
3

第一線 |第一線 |返回 |Back.R，稱作「四個角」
4

第一線 |第一線 |Back.C，又稱「LRS」
5

第一線 |第一線 |Front.C |Back.C，又稱「LRCS」
6

第一線 |第一線 |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

說明套用至串流的壓縮。

Ordinal欄位類型說明
type CompressionType

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

說明串流壓縮的不透明「頻外」參數。 這個欄位是 CompressionType 的函式。與解碼器參數 所需的 Pod 值許多壓縮類型不需要 這個欄位。

DelayWatcherWatchDelayRequest

定義於 fuchsia.audio/delay.fidl

Ordinal欄位類型說明

DelayWatcherWatchDelayResponse

定義於 fuchsia.audio/delay.fidl

Ordinal欄位類型說明
delay zx/Duration

選用。如未指定，誤點是未知的。

格式

定義於 fuchsia.audio/format.fidl

說明不參照壓縮的音訊串流所使用的格式。地點 壓縮功能，此類型應與 fuchsia.media2.Compression 合併。 未壓縮的音訊串流使用 LPCM 編碼。

Ordinal欄位類型說明
sample_type SampleType

個別樣本的類型。
channel_count uint32

每個影格的樣本數。
frames_per_second uint32

每秒影格數。
channel_layout ChannelLayout

每個管道的空間分配。

GainControlSetGainRequest

定義於 fuchsia.audio/gain.fidl

Ordinal欄位類型說明
how GainUpdateMethod

如何更新增加旋鈕。

必填。
when fuchsia.media2/RealTime

套用這項更新的時機。

必填。

GainControlSetMuteRequest

定義於 fuchsia.audio/gain.fidl

Ordinal欄位類型說明
muted bool

靜音旋鈕的新值。

必填。
when fuchsia.media2/RealTime

套用這項更新的時機。

必填。

GainControl_SetGain_Response

定義於 fuchsia.audio/gain.fidl

Ordinal欄位類型說明

GainControl_SetMute_Response

定義於 fuchsia.audio/gain.fidl

Ordinal欄位類型說明

封包

在 fuchsia.audio/stream_sink.fidl 中定義的

說明透過 StreamSink 傳送的封包。

Ordinal欄位類型說明
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 中的變化會採用對數 (非線性) 曲線。

Ordinal欄位類型說明

RampedGain

定義於 fuchsia.audio/gain.fidl

說明漸進式增益指令。套用此指令時，獲利為 從目前值增加為目標值 (超過指定值) 並以指定函式產生時間長度

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

RingBuffer 資源

在 fuchsia.audio/ring_buffer.fidl 中定義

音訊資料的環形緩衝區。

每個環形緩衝區都有一個生產端 (可寫入緩衝區) 和取用端 (從緩衝區讀取的資料)。此外，每個環形緩衝區都有關聯 以及能夠為緩衝區保留時間的參考時鐘。

PCM 資料

PCM 音訊的環形緩衝區是可能無限序列的時間區間 影格速率系統會為每個影格指派一個「影格編號」其中第一個影格 無限序列的編號為 0影格 X 位於環形緩衝區 偏移 (X % RingBufferFrames) * BytesPerFrame，其中 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 資料類似，但位置除外 以「位元組偏移」表示而不是「框架編號」，因為 序列從位元組偏移 0 開始。

Ordinal欄位類型說明
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 中定義的

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

連結關閉的原因。

StreamSinkPutPacketRequest 資源

在 fuchsia.audio/stream_sink.fidl 中定義的

Ordinal欄位類型說明
packet Packet

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

用戶端處理完封包和緩衝區區域後，事件配對就會關閉 便可重複使用。封包可按任何順序釋放。 服務可以複製釋出圍欄，因此必須以右側傳送 ZX_RIGHT_DUPLICATE。這是選填欄位。

StreamSinkStartSegmentRequest

在 fuchsia.audio/stream_sink.fidl 中定義的

Ordinal欄位類型說明
segment_id int64

用來識別區隔。請務必一律嚴格採用特定連線的新區隔 ID 而且數量仍在持續增加這是必填欄位。

StreamSinkWillCloseRequest

在 fuchsia.audio/stream_sink.fidl 中定義的

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

連結關閉的原因。

聯合國

ChannelLayout 彈性

定義於 fuchsia.audio/format.fidl

表示在音訊小串流中預計對頻道的指派作業。

OrdinalVariant類型說明
config ChannelConfig

這個值說明每個管道的指派作業。頻道 設定必須符合《channel_count》。

GainControl_SetGain_Result 嚴格

定義於 fuchsia.audio/gain.fidl

OrdinalVariant類型說明
response GainControl_SetGain_Response
err GainError

GainControl_SetMute_Result 嚴格

定義於 fuchsia.audio/gain.fidl

OrdinalVariant類型說明
response GainControl_SetMute_Response
err GainError

GainUpdateMethod 彈性

定義於 fuchsia.audio/gain.fidl

支援的增益類型。

OrdinalVariant類型說明
gain_db float32

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

使用坡道逐步變更增減效果。

RampFunction 彈性

定義於 fuchsia.audio/gain.fidl

支援的漸進函式類型。

OrdinalVariant類型說明
linear_slope RampFunctionLinearSlope

時間戳記彈性

在 fuchsia.audio/stream_sink.fidl 中定義的

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

OrdinalVariant類型說明
specified int64

直播時間軸中的特定時間。單位不同，連線時會提供 因此狀態是已建立的。
unspecified_continuous UnspecifiedContinuous

表示封包應在前一個封包之後立即呈現 (如有) 輸出封包如果沒有之前的封包，這個選項等同於 specified的值為 0。

這個選項表示串流時間軸不應「slip」，即使封包是封包 卻遲到封包應緊接在前一個封包後 且無論封包的抵達時間為何，系統都會保留產生的時間。
unspecified_best_effort UnspecifiedBestEffort

表示封包應在前一個封包後盡快顯示， 我們會盡快提供該政策。

這個選項代表如果封包太晚送達，串流時間應「出貨」 而要在前一個封包後立即轉譯這個選項通常在短時間內使用 發生在沒有時間戳記的串流中，或許是由有損的上游來源引起的。

商業智慧

PacketFlags 彈性

類型：uint32

在 fuchsia.audio/stream_sink.fidl 中定義的

說明封包的旗標。

名稱值說明
1

指出系統只提供這個封包，以便系統解讀後續的封包。A 罩杯 解碼器應會捨棄從此封包產生的已解壓縮封包。

觀測站

名稱值類型說明
MAX_COMPRESSION_PARAMETERS_SIZE 32768 uint64

大小上限為 Compression.parameters。