fuchsia.hardware.audio.signalprocessing

VENDOR_SPECIFIC

特定于供应商。一种处理元素，未包含在任何后续类型定义中。

CONNECTION_POINT

控制流水线通道混合和路由。

GAIN

增益控制，也称为音量控制。

AUTOMATIC_GAIN_CONTROL

自动增益控制。 无论输入信号如何变化，都能自动保持合适的信号电平。

AUTOMATIC_GAIN_LIMITER

自动增益限制器。 自动将信号强度维持在指定水平以下。 低于该电平的输入不受影响，高于该电平的峰值会被衰减。

动态

改变信号的动态范围，例如动态范围压缩。

静音

忽略。

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

降低低于 frequency 的增益，可选 q，即高通。

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 的级别。

HARDWIRED

互连采用硬接线方式（将始终插接）。

CAN_ASYNC_NOTIFY

互连可以拔出/插入，并且可以异步通知插拔状态变化。

高于

在阈值之上应用动态处理。

低于

在低于阈值的情况下应用动态处理。

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

膝点区域之上或之下的输入与输出分贝比率（请参阅 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，则频段始终处于启用状态。 为了使均衡器频段正常工作，封装的均衡器处理元素也必须启动且不被绕过。

可选。

4

所有频段的最低频率（以 Hz 为单位）。

必填。

5

所有频段的最大频率（以 Hz 为单位）。

必填。

6

所有频段的最大品质因数（通常用“Q”表示）。 此参数用于指示频次过渡的窄度。Q 值越高，陷波/峰值越窄，切除/搁架越陡峭。必须为正值。

可选。如果指定，则必须是有限值。

7

以分贝为单位的最小增益。

如果存在 supported_controls 且包含 SUPPORTS_TYPE_PEAK、SUPPORTS_TYPE_LOW_SHELF 或 SUPPORTS_TYPE_HIGH_SHELF，则为必需。必须是有限值。 否则为不允许。

8

最大增益（以分贝为单位）。

如果存在 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

增益（以分贝为单位）。

对于 PEAK、LOW_SHELF 和 HIGH_SHELF 的 EqualizerBandType，此参数为必需参数。必须是有限值。 不可用于 NOTCH、LOW_CUT 和 HIGH_CUT 的 EqualizerBandType。

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 必须开始或结束元素序列。如果某个 RING_BUFFER 或 PACKET_STREAM 元素在 EdgePair 中被列为 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 中唯一提及该元素的 EdgePair）。

必需。必须包含至少一个条目。

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。