fuchsia.hardware.audio.signalprocessing

VENDOR_SPECIFIC

廠商專屬。任何後續類型定義未涵蓋的處理元素類型。

CONNECTION_POINT

控制管道通道的混合和路徑。

GAIN

增益控制，又稱音量控制。

AUTOMATIC_GAIN_CONTROL

自動增益控制。 無論輸入內容如何變化，都會自動維持適當的訊號強度。

AUTOMATIC_GAIN_LIMITER

自動增益限制器。 自動將訊號強度維持在指定等級以下。 低於此層級的輸入內容不受影響，高於此層級的輸入內容則會衰減。

DYNAMICS

改變信號的動態範圍，例如壓縮動態範圍。

關閉

。

DELAY

延遲。

EQUALIZER

等化器。

SAMPLE_RATE_CONVERSION

取樣率轉換。

RING_BUFFER

環形緩衝區。音訊資料的來源或接收器，透過跨程序循環緩衝區傳輸。這是三種可啟動/結束處理管道的元素類型之一。 如果驅動程式包含這類型的元素，就必須支援該元素 ID 的複合方法 GetRingBufferFormats 和 CreateRingBuffer。

DAI_INTERCONNECT

數位音訊介面互連。這是三種可啟動/結束處理管道的元素類型中的第二種。 如果驅動程式包含這類型的元素，就必須支援該元素 ID 的複合方法 GetDaiFormats 和 SetDaiFormat。

PACKET_STREAM

封包串流。音訊資料的來源或接收器，透過離散封包傳輸。這是三種可啟動/結束處理管道的元素類型中的第三種。 如果驅動程式包含這類型的元素，就必須支援該元素 ID 的複合方法 GetPacketStreamFormats 和 CreatePacketStream。

尖峰

frequency附近的gain_db增加/減少，可選用q。

NOTCH

窄頻拒絕可大幅衰減 frequency，並可選擇使用 q。

LOW_CUT

使用選用的 q (又稱高通) 將增益調低至 frequency 以下。

HIGH_CUT

降低高於 frequency 的增益 (可選用 q)，又稱低通。

LOW_SHELF

將增益值調低至 frequency 以下，即可達到 gain_db 的平穩效果。

HIGH_SHELF

增益值超過 frequency 時，增益值會減少 gain_db，並達到高原期。

數位

處理元素增益會在數位網域中套用。

ANALOG

處理元素增益會套用至類比網域。

混合

處理元件增益會使用數位和類比硬體混合。

分貝

以分貝為單位指定增益，例如 -103.0dB 或 +3.2dB。

PERCENT

增幅以百分比表示，例如 10.0% 或 80.5%。

尖峰

以峰值指定位準增益。

RMS

指定為 RMS 的等級。

有線

互連網路已透過有線連接 (會一直插上電源)。

CAN_ASYNC_NOTIFY

互連網路可以拔除/插入，並以非同步方式通知插頭狀態變更。

高於

在超過門檻時套用動態處理。

BELOW

在門檻以下套用動態處理。

1

插座偵測功能。

必填。

1

這個 DAI 互連網路的插頭狀態。

必填。

2

驅動程式對這個 DAI 互連以外外部延遲的最佳估計值，因為管道目前已設定。

用戶端判斷最低前置時間 (播放期間) 和最低擷取延遲時間 (擷取期間) 的需求時，必須將 external_delay 納入考量。

如果未包含，則 external_delay 為不明；用戶端可自行處理 (例如視為零或其他時間長度、自動偵測等)。

選用。如要指定，必須為非負數。

1

這項通訊協定中的 Dynamics 元素可能支援多個頻段。每個頻帶都會在 DynamicsElementState 中指定多個參數，這些參數可透過 SetElementState 變更。bands 向量中的元素數量決定了這個處理元素支援的頻帶數量。

此為必要項目。至少須包含一個項目。

2

這個處理元素支援的控制項 (即透過呼叫 SetElementState 變更的控制項)。

選用。

1

這個頻帶的專屬 ID，僅須在對應的 Element 內保持專屬，且在與 SignalProcessing 通訊協定相關聯的管道關閉前有效。

必填。

1

樂團的專屬 ID。必須與 Dynamics bands 中指定的其中一個 id 相符。

2

頻帶的最低頻率 (以 Hz 為單位)。 這個欄位可以是 0，例如單一頻帶動態處理，可指定 (連同 max_frequency) 頻帶為全範圍。

3

頻帶的最高頻率 (以 Hz 為單位)。 舉例來說，這個欄位可能是奈奎斯特頻率，適用於單一頻帶動態處理，可指定 (連同 min_frequency) 頻帶為全範圍。

必填。

4

動態主處理作業的起始值 (以輸入 dB 為準，受 knee_width_db 限制)。部分信號處理作業 (例如 input_gain 和 output_gain) 不會受到這個值影響。

此為必要項目。必須是有限值。

5

動態處理作業會套用 ABOVE 或 BELOW 門檻。

WatchElementState的必要條件。 如果未在 supported_controls 中設定 DynamicsSupportedControls.THRESHOLD_TYPE，則不允許在 SetElementState 中使用。

6

高於或低於膝部區域的輸入/輸出 dB 比率 (請參閱 threshold_type)。

此為必要項目。必須是有限值。

7

膝部區域的寬度，以輸入 dB 為單位。如有此值，不得為負數。 如未納入，膝蓋區域的寬度將未指定。 值為零代表「硬」膝蓋，值越大代表「軟」膝蓋。 膝蓋位於 threshold_db 的中心。

選用。如果指定，則必須是有限值。 如果未在 supported_controls 中設定 DynamicsSupportedControls.KNEE_WIDTH，則不允許在 SetElementState 中使用。

8

攻擊時間。 如未加入，則攻擊時間未指定。

選用。如要指定，必須為非負數。 如果未在 supported_controls 中設定 DynamicsSupportedControls.ATTACK，則不允許在 SetElementState 中使用。

9

發布時間。 如果未納入，發布時間則未指定。

選用。如要指定，必須為非負數。 如果未在 supported_controls 中設定 DynamicsSupportedControls.RELEASE，則不允許在 SetElementState 中使用。

10

以分貝為單位輸出 (又稱補償或後) 增益值。如果未納入，則輸出增益未指定。

選用。如果指定，則必須是有限值。 如果未在 supported_controls 中設定 DynamicsSupportedControls.OUTPUT_GAIN，則不允許在 SetElementState 中使用。

11

以分貝為單位輸入輸入 (又稱前置) 增益值。 如果未加入，則輸入增益未指定。

選用。如果指定，則必須是有限值。 如果未在 supported_controls 中設定 DynamicsSupportedControls.INPUT_GAIN，則不允許在 SetElementState 中使用。

12

音量類型 (峰值或 RMS)。 如未納入，則為未指定等級類型。

選用。 如果未在 supported_controls 中設定 DynamicsSupportedControls.LEVEL_TYPE，則不允許在 SetElementState 中使用。

13

預先查看時間。 如未加入，則預測時間未指定。

選用。如要指定，必須為非負數。 如果未在 supported_controls 中設定 DynamicsSupportedControls.LOOKAHEAD，則不允許在 SetElementState 中使用。

14

連結的聲道 (又稱「立體聲連結」，適用於 2 管道系統)。 如果未納入，連結的頻道選項會未指定。 如為 true，動態回應會套用至所有管道。 如果為 false，每個管道都會有自己的動態回應。

選用。 如果未在 supported_controls 中設定 DynamicsSupportedControls.LINKED_CHANNELS，則不允許在 SetElementState 中使用。

1

每個 ID 都必須與 Dynamics.bands 中的 ID 相符，且 ID 不得重複。 band_states 至少須有一個元素。由 band_states 控制的頻段取決於各個 band.id。

此為必要項目。至少須包含一個項目。

1

這個元素的專屬 ID。這個 ID 的範圍僅限於SignalProcessing 通訊協定生命週期，也就是與通訊協定相關聯的管道關閉為止。

必填。

2

處理元素類型。

必填。

3

處理元素的類型專屬參數。

ElementTypes DAI_INTERCONNECT、DYNAMICS、EQUALIZER、GAIN、VENDOR_SPECIFIC 必須使用。 如果為 AUTOMATIC_GAIN_CONTROL、AUTOMATIC_GAIN_LIMITER、 CONNECTION_POINT、DELAY、MUTE、PACKET_STREAM、RING_BUFFER 或 SAMPLE_RATE_CONVERSION 類型的元素指定，則為無效。

5

如果包含，則為處理元素的文字說明。

選用。如有提供，不得留空。

6

如為 true，處理元素可透過 SetElementState 停止。 如果未納入或設為 false，系統一律會啟動處理元素。

選用。

7

如為 true，即可透過 SetElementState 略過處理元素。 如果未納入或為 false，就無法略過處理元素。 根據定義，DAI_INTERCONNECT、RING_BUFFER 或 PACKET_STREAM 類型的元素無法略過，且絕不能將這個欄位設為 true。

選用。

1

處理元素的類型專屬狀態參數。

如果停用這個處理元素，並提供類型專屬狀態，則類型專屬狀態僅供參考 (例如停止的元素狀態，如果要在不提供額外取代狀態資訊的情況下重新啟動)。

DAI_INTERCONNECT、DYNAMICS、EQUALIZER、GAIN 和 VENDOR_SPECIFIC 元素皆須提供這項資訊。 如果為 AUTOMATIC_GAIN_CONTROL、AUTOMATIC_GAIN_LIMITER、 CONNECTION_POINT、DELAY、MUTE、PACKET_STREAM、RING_BUFFER 或 SAMPLE_RATE_CONVERSION 類型的元素指定，則為無效。

4

如果包含，則為八位元組的不透明物件，用於將供應商專屬資訊從驅動程式庫傳達至 SignalProcessing 用戶端。

選用 (即使元素類型不是 VENDOR_SPECIFIC，也可以使用)。

5

這個處理元素的啟動/停止狀態。 如為 true，系統會啟動與元素相關聯的硬體。如果為 false，則會停止。

如果對應的 Element省略 can_stop 或設為 false，這個欄位就絕不會是 false。

停止處理的元素不會提供其抽象功能。 停止的元素不會傳送音訊資料。

必填。

6

這個處理元素的略過狀態。 如為 true，系統會略過與元素相關聯的硬體。如果設為 False 或未提供，系統就不會略過相關聯的硬體。

根據預設，系統不會略過處理元素。如果對應的 Element 省略 can_bypass 或設為 false，則這個欄位一律不得設為 true。

略過的元素不會影響音訊在拓撲中的流動。 音訊會通過已略過的元素，且不會變更。

選用。

7

如果包含此欄位，則表示驅動程式對元素硬體從 started 從 false 變更為 true 後，進入完全運作模式所需時間的最佳預估值。舉例來說，硬體可能需要一段時間才能在變更電源狀態後完全運作。

如果未考量 turn_on_delay，音訊元素啟動時可能會遺失音訊串流的初始影格。如果未提供，turn_on_delay 的來源不明。

選用。如要指定，必須為非負數。

8

如果包含此屬性，則為驅動程式庫對元素硬體從 started 從 true 變更為 false 後，進入完全停用模式所需時間的最佳估計值。舉例來說，硬體可能需要一段時間才能在電源狀態變更後完全停止。

如果未考量 turn_off_delay，系統發出/擷取的影格數量會超出用戶預期，而音訊元素則會關閉電源。 如果未提供，turn_off_delay 的來源不明。

選用。如要指定，必須為非負數。

9

如果包含此項目，則為驅動程式根據目前設定 (包括 bypassed 狀態) 估算的延遲時間。

時間敏感型用戶在判斷 (播放) 最短前置時間和最短擷取延遲時間的需求時，應將這個值納入考量。

如果是 RING_BUFFER 類型的元素，這項延遲不應包含暫時緩衝處理所增加的固有延遲，因為需要複製資料進出環形緩衝區，而這項延遲包含在 RingBufferProperties 欄位 driver_transfer_bytes 中。

選用。如要指定，必須為非負數。

1

這個通訊協定中的等化器是由多個頻帶建構而成，每個頻帶都會在這裡和 EqualizerElementState 中指定多個參數，這些參數可透過 SetElementState 變更。bands 向量的元素數量決定了這個處理元素支援的頻帶數量。

此為必要項目。至少須包含一個項目。

2

這個等化器支援的控制項 (即透過 SetElementState 變更的控制項)。

選用。

3

如果包含這個屬性且值為 true，則可透過 SetElementState 停用個別頻段。如果未納入或設為 False，系統一律會啟用頻段。 如要讓 EQ 頻段正常運作，封閉式等化器處理元素也必須啟動，且不得略過。

選用。

4

所有頻帶的最低頻率 (以 Hz 為單位)。

必填。

5

所有頻帶的最高頻率，以 Hz 為單位。

必填。

6

所有頻帶的最大品質因數，通常以「Q」表示。 這表示頻率轉換的範圍有多窄。Q 值越高，代表凹口/尖峰越窄，且剪切/擱架越陡峭。必須為正數。

選用。如果指定，必須是有限值。

7

以 dB 為單位的最低增益。

如果 supported_controls 存在且包含 SUPPORTS_TYPE_PEAK、SUPPORTS_TYPE_LOW_SHELF 或 SUPPORTS_TYPE_HIGH_SHELF，則為必要項目。必須是有限值。 否則為不允許。

8

以 dB 為單位的最大增益。

如果 supported_controls 存在且包含 SUPPORTS_TYPE_PEAK、SUPPORTS_TYPE_LOW_SHELF 或 SUPPORTS_TYPE_HIGH_SHELF，則為必填。必須是有限值。 否則為不允許。

1

這個樂團的專屬 ID。只能在對應的 Element 中不得重複。只有在與 SignalProcessing 通訊協定相關聯的管道關閉前有效。

必填。

1

樂團的專屬 ID。必須與 Equalizer bands 中指定的其中一個 id 相符。

必填。

2

錶帶類型。

必要元素。如果是對 SetElementState 的呼叫，則必須在 Element.supported_controls 中設定 type 的對應 SUPPORTS_TYPE_... EqualizerSupportedControls 位元。

3

頻帶的中心頻率。

必要元素。如果這是對 SetElementState 的呼叫，且代表這個頻帶的頻率有所變化，則必須在 Element.supported_controls 中設定 CAN_CONTROL_FREQUENCY。

4

品質因素，通常以「Q」表示。 表示頻率轉換的幅度。Q 值越高，代表凹口/峰值越窄，且切口/架子越陡峭。必須為正數。

選用。 如果用於 SetElementState，且代表這個頻帶的 q 發生變化，則必須在 Element.supported_controls 中設定 CAN_CONTROL_Q。必須是有限值。

5

以 dB 為單位表示增益。

對 PEAK、LOW_SHELF 和 HIGH_SHELF 的 EqualizerBandType 為必要。必須是有限值。 EqualizerBandType 不允許用於 NOTCH、LOW_CUT 和 HIGH_CUT。

6

啟用/停用頻帶。 如果停用，音訊仍會通過等化器，但這個頻段不會有任何作用。

如果 WatchElementState 的回傳值中沒有這個值，則會啟用頻帶。如果在 SetElementState 呼叫中省略，頻帶的啟用/停用狀態不會變更。

將 ElementState.bypassed 設為 true 即可略過整個封閉式處理元素，但不會變更這個欄位的值。不過，等化器頻段必須啟動，且不得略過封閉式等化器處理元素，才能正常運作。

選用。

2

這個等化器處理元素中各頻帶的狀態。

band_states 向量的元素數量必須等於或小於對應 Equalizer 中傳回的 bands 元素數量。band_states 至少須有一個元素。由 band_states 控制的頻段取決於各個 band.id。

此為必要項目。至少須包含一個項目。

1

指定增益的數字代表的意義，例如百分比。

必填。

2

如果納入，增益會套用至指定的 GainDomain。如未納入，增益網域會未指定。

選用。

3

GainType 格式的最低增益。

此為必要項目。必須是有限值。

4

以 GainType 格式獲得最大增益。

此為必要項目。必須是有限值。

5

增益的最小步階，格式為 GainType，這個值不得為負數，但可為零，表示有效連續的值範圍。不得超過 max_gain 至 min_gain。 用戶端可透過 WatchElementState 呼叫查詢實際增益集。

此為必要項目。必須是有限值。

1

目前增益，格式為 GainType。

此為必要項目。必須是有限值。

1

指出互連是否已插入。

必填

2

指出目前 plugged 狀態的設定時間 (使用 ZX_CLOCK_MONOTONIC)。不得為負數。

必填。

1

用戶端可設定的類型專屬元素狀態參數。

如果元素已停用，這個欄位 (以及 SettableElementState 中的所有其他欄位) 的變更純粹是資訊性質，必須等到元素啟用後才會生效。

如未設定，系統會保留元素先前的 type_specific 狀態。

DYNAMICS、EQUALIZER、GAIN 和 VENDOR_SPECIFIC 類型為選填。 如果為 AUTOMATIC_GAIN_CONTROL、AUTOMATIC_GAIN_LIMITER、CONNECTION_POINT、 DAI_INTERCONNECT、DELAY、MUTE、PACKET_STREAM、RING_BUFFER 或 SAMPLE_RATE_CONVERSION 元素指定，則為無效。

2

如有提供，則為八位元組的不透明物件，用於將廠商專屬資訊從用戶端傳達至音訊驅動程式庫。這項功能適用於任何元素類型，不限於 VENDOR_SPECIFIC 元素。

選用。

3

是否要啟動或停止這個處理元素。 停止處理的元素不會提供其抽象功能。 具體來說，音訊資料不會流經已停止的元素。

如果對應的 Element 傳回的 can_stop 等於 false，則這個欄位不得設為 false，否則 SetElementState 會傳回 ZX_ERR_INVALID_ARGS。如未設定，元素先前的 started 狀態將維持不變。

選用。

4

是否要略過這個處理元素。 略過的元素不會影響音訊在拓撲中的流動。 具體來說，音訊會通過略過的元素，且不會有任何變化。

如果對應的 Element 省略 can_bypass 或將其設為 false，則這個欄位不得設為 true。如果發生這種情況，SetElementState 會失敗並傳回錯誤 ZX_ERR_INVALID_ARGS。如未設定，元素先前的 bypassed 狀態將維持不變。

選用。

1

這個拓撲的專屬 ID。這個 ID 的範圍僅限於SignalProcessing 通訊協定生命週期，也就是與通訊協定相關聯的管道關閉為止。

必填。

2

處理元素邊緣配對的向量，用於指定元素之間的連線。 處理元素會透過邊緣配對連接，形成多元素管道。 拓撲可包含多個不同的管道：拓撲不一定要是單一互連序列 (例如拓撲 A->B->C D->E->F 是有效的)。

如要定義多個可能的設定，讓用戶端可以選取其中一種，請在 GetTopologies 中傳回多個 Topology 項目。

如果裝置支援多個拓撲項目，則每個特定拓撲不一定要包含所有元素。不過，每個元素都必須包含在至少一個拓撲中。

在每個拓撲中，每個連線元素序列都必須以 DAI_INTERCONNECT、RING_BUFFER 或 PACKET_STREAM 類型的元素開頭，並以 DAI_INTERCONNECT、RING_BUFFER 或 PACKET_STREAM 類型的元素結尾。

DAI_INTERCONNECT 元素可啟動或結束元素序列，但 RING_BUFFER 或 PACKET_STREAM 元素必須啟動或結束元素序列。如果 EdgePair 中列出某個 RING_BUFFER 或 PACKET_STREAM 元素為 processing_element_id_from，則在該拓撲中，這個元素不得列在另一個 EdgePair 中為 processing_element_id_to (反之亦然)。

在特殊情況下，DAI_INTERCONNECT 元素可以參照自身，也就是 EdgePair 可能包含相等的 processing_element_id_from 和 processing_element_id_to 值。不過，這個元素不得與拓撲中的其他元素連線 (這個 EdgePair 必須是 processing_elements_edge_pairs 中唯一提及該元素的元素)。

此為必要項目。至少須包含一個項目。

1

2

1

2

1

3

1

2

3

4

1

2

1

2

1

2

3

4

6

1

2

3

4

6

KNEE_WIDTH

如果已設定，SetElementState 可以變更動態頻段的 knee_width_db 參數。

ATTACK

如果已設定，SetElementState 可以變更動態頻段的 attack 參數。

發行

如果已設定，SetElementState 可以變更動態頻段的 release 參數。

OUTPUT_GAIN

如果已設定，SetElementState 可以變更動態頻段的 output_gain_db 參數。

INPUT_GAIN

如果已設定，SetElementState 可以變更動態頻段的 input_gain_db 參數。

LOOKAHEAD

如果已設定，SetElementState 可以變更動態頻段的 lookahead 參數。

LEVEL_TYPE

如果已設定，SetElementState 可以變更動態頻段的 level_type 參數。

LINKED_CHANNELS

如果已設定，SetElementState 可以變更動態頻段的 linked_channels 參數。

THRESHOLD_TYPE

如果已設定，SetElementState 可以變更動態頻段的 threshold_type 參數。

CAN_CONTROL_FREQUENCY

如果已設定，SetElementState 可以變更等化器頻段的 frequency。

CAN_CONTROL_Q

如果已設定，SetElementState 可以變更等化器頻帶的 q。

SUPPORTS_TYPE_PEAK

如果設定這項政策，SetElementState 可以將樂團的 type 變更為 EqualizerBandType.PEAK。

SUPPORTS_TYPE_NOTCH

如果設定這項政策，SetElementState 可以將樂團的 type 變更為 EqualizerBandType.NOTCH。

SUPPORTS_TYPE_LOW_CUT

如果設定這項政策，SetElementState 可以將樂團的 type 變更為 EqualizerBandType.LOW_CUT。

SUPPORTS_TYPE_HIGH_CUT

如果設定這項政策，SetElementState 可以將樂團的 type 變更為 EqualizerBandType.HIGH_CUT。

SUPPORTS_TYPE_LOW_SHELF

如果設定，SetElementState 可以變更樂團的 type EqualizerBandType.LOW_SHELF。

SUPPORTS_TYPE_HIGH_SHELF

如果設定這項政策，SetElementState 可以將樂團的 type 變更為 EqualizerBandType.HIGH_SHELF。