VENDOR_SPECIFIC

Vendor Specific. A type of processing element not covered by any subsequent type definition.

CONNECTION_POINT

Controls pipelines channel mixing and routing.

GAIN

Gain control, a.k.a. Volume control.

AUTOMATIC_GAIN_CONTROL

Automatic Gain Control. Automatically maintains a suitable signal level regardless of variation of its input.

AUTOMATIC_GAIN_LIMITER

Automatic Gain Limiter. Automatically maintains a signal level below a level specified. Input below the level is unaffected, and peaks above the level are attenuated.

DYNAMICS

Alters the dynamic range of the signal, e.g. dynamic range compression.

MUTE

Mute.

DELAY

Delay.

EQUALIZER

Equalizer.

SAMPLE_RATE_CONVERSION

Sample Rate Conversion.

ENDPOINT

The start/end of a pipeline.

Deprecation

Use RING_BUFFER or DAI_INTERCONNECT instead.

RING_BUFFER

Ring Buffer. This is the first of two types of elements that can start/end processing pipelines.

DAI_INTERCONNECT

Digital Audio Interface Interconnect. This is the second of two types of elements that can start/end processing pipelines.

RING_BUFFER

The endpoint represents a ring buffer. A ring buffer processing element's id allows for multi-ring buffer topologies to be supported by a driver providing the fuchsia.hardware.audio/Composite API.

DAI_INTERCONNECT

The endpoint represents a Digital Audio Interface Interconnect, e.g. connecting an SoC audio subsystem to a DAC + amplifier hardware codec.

PEAK

Increase/decrease in gain_db in the vicinity of a frequency with an optional q.

NOTCH

Narrow band rejection significantly attenuating a frequency with an optional q.

LOW_CUT

Decrease gain below a frequency with an optional q, a.k.a high pass.

HIGH_CUT

Decrease gain above a frequency with an optional q, a.k.a low pass.

LOW_SHELF

Decrease gain below a frequency for a gain_db amount with a plateau effect.

HIGH_SHELF

Decrease gain above a frequency for a gain_db amount with a plateau effect.

DIGITAL

The processing element gain is applied in the digital domain.

ANALOG

The processing element gain is applied in the analog domain.

MIXED

The processing element gain is mixed using digital and analog hardware.

DECIBELS

Gain specified in dB, for example -103.0dB or +3.2dB.

PERCENT

Gain specified as a percentage, for example 10.0% or 80.5%.

PEAK

Level Gain specified as peak.

RMS

Level specified as RMS.

HARDWIRED

Interconnect is hardwired (will always be plugged in).

CAN_ASYNC_NOTIFY

Interconnect can be unplugged/plugged and can asynchronously notify of plug state changes.

ABOVE

Apply dynamics processing above the threshold.

BELOW

Apply dynamics processing below the threshold.

1

Plug Detect Capabilities.

Required.

1

The plug state for this DAI interconnect.

Required.

2

The driver's best estimate of the external delay beyond this DAI endpoint, as the pipeline is currently configured.

external_delay must be taken into account by the client when determining the requirements for minimum lead time (during playback) and minimum capture delay (during capture).

If not included, external_delay is unknown; the client may treat it however it chooses (e.g. consider it zero or some other duration, autodetect it, etc).

Optional. If specified, must be non-negative.

1

Dynamics elements in this protocol may support multiple bands. Each band specifies a number of parameters in DynamicsElementState that can be changed with SetElementState. The number of elements in the bands vector determines the number of bands supported by this processing element.

Required. Must contain at least one entry.

2

The controls supported by this processing element (i.e. that can be changed by a call to SetElementState).

Optional.

1

Unique ID for this band, only required to be unique within the corresponding Element, and valid until the channel associated with the SignalProcessing protocol is closed.

Required.

1

Unique ID for the band. Must match one of the ids specified in Dynamics bands.

2

Minimum frequency for the band in Hz. This field could be 0, for instance for single band dynamics processing to specify (together with max_frequency) that the band is full range.

3

Maximum frequency for the band in Hz. This field could be the Nyquist frequency, for instance for single band dynamics processing to specify (together with min_frequency) that the band is full range.

Required.

4

The value beyond which the dynamics main processing starts (subject to the knee_width_db), in input dB. Some signal processing like input_gain and output_gain are not affected by this value.

Required. Must be finite.

5

Dynamics processing is applied ABOVE or BELOW the threshold.

Required for WatchElementState. Disallowed in SetElementState if DynamicsSupportedControls.THRESHOLD_TYPE is not set in supported_controls.

6

The input-to-output dB ratio above or below (see threshold_type) the knee region.

Required. Must be finite.

7

The width of the knee region, in input dB. If present, cannot be negative. If not included, the width of the knee region is unspecified. A value of zero is a "hard" knee; larger values lead to "softer" knees. This knee is centered on threshold_db.

Optional. If specified, must be finite. Disallowed in SetElementState if DynamicsSupportedControls.KNEE_WIDTH is not set in supported_controls.

8

Attack time. If not included, the attack time is unspecified.

Optional. If specified, must be non-negative. Disallowed in SetElementState if DynamicsSupportedControls.ATTACK is not set in supported_controls.

9

Release time. If not included, the release time is unspecified.

Optional. If specified, must be non-negative. Disallowed in SetElementState if DynamicsSupportedControls.RELEASE is not set in supported_controls.

10

Output (a.k.a. make up or post) gain value in dB. If not included, the output gain is unspecified.

Optional. If specified, must be finite. Disallowed in SetElementState if DynamicsSupportedControls.OUTPUT_GAIN is not set in supported_controls.

11

Input (a.k.a. pre) gain value in dB. If not included, the input gain is unspecified.

Optional. If specified, must be finite. Disallowed in SetElementState if DynamicsSupportedControls.INPUT_GAIN is not set in supported_controls.

12

Level type (peak or RMS). If not included, the level type is unspecified.

Optional. Disallowed in SetElementState if DynamicsSupportedControls.LEVEL_TYPE is not set in supported_controls.

13

Look-ahead time. If not included, the look-ahead time is unspecified.

Optional. If specified, must be non-negative. Disallowed in SetElementState if DynamicsSupportedControls.LOOKAHEAD is not set in supported_controls.

14

Linked channels (a.k.a. Stereo linked for 2-channel systems). If not included, the linked channels option is unspecified. If true, the dynamics response is applied to all channels. If false, each channel has its own dynamics response.

Optional. Disallowed in SetElementState if DynamicsSupportedControls.LINKED_CHANNELS is not set in supported_controls.

1

Each id must match an id from Dynamics.bands and ids cannot be repeated. band_states must have at least one element. The bands controlled by band_states are determined by each band.id.

Required. Must contain at least one entry.

1

Unique ID for this element. The scope of this id is only within the SignalProcessing protocol lifespan, i.e. until the channel associated with the protocol is closed.

Required.

2

Processing element type.

Required.

3

Type-specific parameters for the processing element.

Required for ElementTypes DAI_INTERCONNECT, DYNAMICS, EQUALIZER, GAIN, VENDOR_SPECIFIC. Invalid if specified for elements of type AUTOMATIC_GAIN_CONTROL, AUTOMATIC_GAIN_LIMITER, CONNECTION_POINT, DELAY, MUTE, RING_BUFFER or SAMPLE_RATE_CONVERSION.

4

Can the processing element be disabled via SetElementState.

Deprecation

Use can_bypass instead.

5

If included, a textual description of the processing element.

Optional. If present, must not be empty.

6

If true, the processing element can be stopped via SetElementState. If not included or false, the processing element is always started.

Optional.

7

If true, the processing element can be bypassed via SetElementState. If not included or false, the processing element cannot be bypassed.

Optional.

1

Type-specific state parameters for the processing element.

If this processing element is disabled and its type-specific state is provided, then the type-specific state is only informational (e.g. the state of a stopped element, if it were to be re-started without also providing additional superceding state information).

Required for DAI_INTERCONNECT, DYNAMICS, EQUALIZER, GAIN and VENDOR_SPECIFIC elements. Invalid if specified for elements of type AUTOMATIC_GAIN_CONTROL, AUTOMATIC_GAIN_LIMITER, CONNECTION_POINT, DELAY, MUTE, RING_BUFFER or SAMPLE_RATE_CONVERSION.

2

Enable/disable state for the processing element.

Deprecation

Use bypassed instead.

3

How much latency this element adds, if enabled.

Deprecation

Use processing_delay instead.

4

If included, an opaque object of octets for conveying vendor-specific information from the driver to SignalProcessing clients.

Optional (permitted even if the element's type is not VENDOR_SPECIFIC).

5

The start/stop state for this processing element. If true, the hardware associated with the element is started. If false, it is stopped.

If the corresponding Element omitted can_stop or set it to false, then this field can never be false.

A stopped processing element does not provide its abstracted functionality. No audio data flows through stopped elements.

Required.

6

The bypass state for this processing element. If true, the hardware associated with the element is bypassed. If false or missing, the associated hardware is not bypassed.

By default, processing elements are not bypassed. If the corresponding Element omitted can_bypass or set it to false, then this field can never be set to true.

A bypassed element does not affect the flow of audio through the topology. Audio flows through a bypassed element, unchanged.

Optional.

7

If included, the driver's best estimate of the amount of time it takes the element's hardware to enter a fully operational mode after started has changed from false to true. Hardware may require some duration to reach a fully operational mode after changing its power state, for example.

If turn_on_delay is not taken into account, then an audio stream's initial frames might be lost while audio elements are powering up. If not included, turn_on_delay is unknown.

Optional. If specified, must be non-negative.

8

If included, the driver's best estimate of the amount of time it takes the element's hardware to enter a fully disabled mode after started has changed from true to false. Hardware may require some duration to get into a fully stopped state after a change in power state, for example.

If turn_off_delay is not taken into account, more frames will be emitted/captured than a client might expect, while audio elements are powering down. If not included, turn_off_delay is unknown.

Optional. If specified, must be non-negative.

9

If included, the driver's best estimate of the delay added by this processing element, as it is currently configured (including bypassed state).

This value should be taken into account by timing-sensitive clients, when determining the requirements for (playback) minimum lead time and minimum capture delay.

For an element of type RING_BUFFER, this delay should not include the inherent delay added by the temporary buffering needed to copy data in and out of a ring buffer, which is contained in the RingBufferProperties field driver_transfer_bytes.

Optional. If specified, must be non-negative.

1

Specifies what the endpoint represents.

Required.

2

Plug Detect Capabilities. Required.

1

If included the plug detect state for this endpoint.

Required for servers.

1

Equalizers in this protocol are built by a number of bands, each specifying a number of parameters here and in EqualizerElementState that can be changed with SetElementState. The number of elements of the bands vector determines the number of bands supported by this processing element.

Required. Must contain at least one entry.

2

The controls supported by this equalizer (i.e. that can be changed via SetElementState).

Optional.

3

If included and true, individual bands can be disabled via SetElementState. If not included or false, bands are always enabled. For EQ bands to be functional, the enclosing equalizer processing element must also be started and not bypassed.

Optional.

4

Minimum frequency for all bands, in Hz.

Required.

5

Maximum frequency for all bands, in Hz.

Required.

6

Maximum quality factor, usually denoted by "Q", for all bands. This indicates how narrow the frequency transition is. Higher Q values imply narrower notches/peaks and steeper cuts/shelves. Must be positive.

Optional. If specified, must be finite.

7

Minimum gain in dB.

Required, if supported_controls is present and includes SUPPORTS_TYPE_PEAK, SUPPORTS_TYPE_LOW_SHELF or SUPPORTS_TYPE_HIGH_SHELF. Must be finite. Disallowed, otherwise.

8

Maximum gain in dB.

Required, if supported_controls is present and includes SUPPORTS_TYPE_PEAK, SUPPORTS_TYPE_LOW_SHELF or SUPPORTS_TYPE_HIGH_SHELF. Must be finite. Disallowed, otherwise.

1

Unique ID for this band. Must only be unique within the corresponding Element. Only valid until the channel associated with the SignalProcessing protocol is closed.

Required.

1

Unique ID for the band. Must match one of the ids specified in Equalizer bands.

Required.

2

Type of band.

Required. If this is a call to SetElementState, then the corresponding SUPPORTS_TYPE_... EqualizerSupportedControls bit for type must be set in Element.supported_controls.

3

Center frequency for the band.

Required. If this is a call to SetElementState and represents a change in this band's frequency, then CAN_CONTROL_FREQUENCY must be set in Element.supported_controls.

4

Quality factor, usually denoted as "Q". Indicates how narrow the frequency transition is. Higher Q values imply narrower notches/peaks and steeper cuts/shelves. Must be positive.

Optional. If used in SetElementState and represents a change in this band's q, then CAN_CONTROL_Q must be set in Element.supported_controls. Must be finite.

5

Gain in dB.

Required, for EqualizerBandType of PEAK, LOW_SHELF and HIGH_SHELF. Must be finite. Disallowed, for EqualizerBandType of NOTCH, LOW_CUT and HIGH_CUT.

6

Enable/disable the band. If disabled, audio still flows through the equalizer but this band has no effect.

If absent in the return value from WatchElementState, the band is enabled. If omitted in a SetElementState call, the band's enable/disable state is unchanged.

Bypassing the entire enclosing processing element (by setting ElementState.bypassed to true) does not change this field's value, although for an equalizer band to be functional, its enclosing equalizer processing element must be both started and not bypassed.

Optional.

1

The states of the bands in this equalizer processing element.

Deprecation

Use band_states instead.

2

The states of the bands in this equalizer processing element.

The number of elements of the band_states vector must be equal or smaller than the number of elements of the bands returned in returned in the corresponding Equalizer. band_states must have at least one element. The bands controlled by band_states are determined by each band.id.

Required. Must contain at least one entry.

1

Specifies what the numbers for gain represent, e.g. a percentage.

Required.

2

If included, the gain is applied in the specified GainDomain. If not included, the gain domain is unspecified.

Optional.

3

Minimum gain in GainType format.

Required. Must be finite.

4

Maximum gain in GainType format.

Required. Must be finite.

5

Minimum gain step in GainType format, this value must not be negative, but may be zero to convey an effectively continuous range of values. Must not exceed max_gain - min_gain. The actual gain set may be queried by the client with a WatchElementState call.

Required. Must be finite.

1

Current gain in GainType format.

Required. Must be finite.

1

Indicates whether the interconnect is currently plugged in.

Required

2

Indicates when the current plugged state was set, using ZX_CLOCK_MONOTONIC. Cannot be negative.

Required.

1

Type-specific element-state parameters that can be set by clients.

If an element is disabled, changes in this field (and all others in SettableElementState) are purely informational and take no effect until the element is enabled.

If not set, then the element's previous type_specific state is preserved.

Optional for DYNAMICS, EQUALIZER, GAIN and VENDOR_SPECIFIC types. Invalid if specified for AUTOMATIC_GAIN_CONTROL, AUTOMATIC_GAIN_LIMITER, CONNECTION_POINT, DAI_INTERCONNECT, DELAY, MUTE, RING_BUFFER or SAMPLE_RATE_CONVERSION elements.

2

If included, an opaque object of octets for conveying vendor-specific information from a client to the audio driver. This can be used with any element type, not just VENDOR_SPECIFIC elements.

Optional.

3

Whether to start or stop this processing element. A stopped processing element does not provide its abstracted functionality. Specifically, no audio data flows through a stopped element.

If the corresponding Element returned can_stop equals to false, then this field must not be set to false -- SetElementState will return ZX_ERR_INVALID_ARGS in that case. If not set, then the element's previous started state will be unchanged.

Optional.

4

Whether to bypass this processing element. A bypassed element does not affect the flow of audio through the topology. Specifically, audio flows through a bypassed element, without change.

If the corresponding Element omits can_bypass or sets it to false, then this field must not be set to true. If this occurs, SetElementState will fail and return error ZX_ERR_INVALID_ARGS. If not set, then the element's previous bypassed state will be unchanged.

Optional.

1

Unique ID for this topology. The scope of this id is only within the SignalProcessing protocol lifespan, i.e. until the channel associated with the protocol is closed.

Required.

2

Vector of processing elements edge pairs that specify connections between elements. Processing elements are connected by edge pairs, to form multi-element pipelines. A Topology can contain more than one distinct pipeline: the Topology need not be a single interconnected sequence (e.g. Topology A->B->C D->E->F is valid).

To define multiple possible configurations where one possibility can be selected by the client, return multiple Topology entries in GetTopologies.

If a device does support multiple Topology entries, then each specific Topology is not required to include every Element. However, every element must be included in at least one Topology.

Within each Topology, every sequence of connected elements must begin with an element of type DAI_INTERCONNECT or RING_BUFFER, and must end with an element of type DAI_INTERCONNECT or RING_BUFFER.

An DAI_INTERCONNECT element is permitted to be the endpoint for an element sequence, but a RING_BUFFER is required to be one. If a certain RING_BUFFER element is listed in an EdgeList entry as a processing_element_id_from, then within that Topology it must not be listed in any EdgeList entry as a processing_element_id_to (and vice versa).

Required. Must contain at least one entry.

1

Latency added to the pipeline as a zx.Duration.

2

Latency added to the pipeline as a number of frames.

1

2

1

2

1

3

1

2

3

4

1

2

1

2

1

2

3

4

5

6

1

2

3

4

5

6

KNEE_WIDTH

If set, SetElementState can change a dynamics band's knee_width_db parameter.

ATTACK

If set, SetElementState can change a dynamics band's attack parameter.

RELEASE

If set, SetElementState can change a dynamics band's release parameter.

OUTPUT_GAIN

If set, SetElementState can change a dynamics band's output_gain_db parameter.

INPUT_GAIN

If set, SetElementState can change a dynamics band's input_gain_db parameter.

LOOKAHEAD

If set, SetElementState can change a dynamics band's lookahead parameter.

LEVEL_TYPE

If set, SetElementState can change a dynamics band's level_type parameter.

LINKED_CHANNELS

If set, SetElementState can change a dynamics band's linked_channels parameter.

THRESHOLD_TYPE

If set, SetElementState can change a dynamics band's threshold_type parameter.

CAN_CONTROL_FREQUENCY

If set, SetElementState can change an equalizer band's frequency.

CAN_CONTROL_Q

If set, SetElementState can change an equalizer band's q.

SUPPORTS_TYPE_PEAK

If set, SetElementState can change a band's type to EqualizerBandType.PEAK.

SUPPORTS_TYPE_NOTCH

If set, SetElementState can change a band's type to EqualizerBandType.NOTCH.

SUPPORTS_TYPE_LOW_CUT

If set, SetElementState can change a band's type to EqualizerBandType.LOW_CUT.

SUPPORTS_TYPE_HIGH_CUT

If set, SetElementState can change a band's type to EqualizerBandType.HIGH_CUT.

SUPPORTS_TYPE_LOW_SHELF

If set, SetElementState can change a band's type EqualizerBandType.LOW_SHELF.

SUPPORTS_TYPE_HIGH_SHELF

If set, SetElementState can change a band's type to EqualizerBandType.HIGH_SHELF.