Honoring Asian Pacific American Heritage Month. See how.

fuchsia.hardware.audio.signalprocessing

Added: 7

PROTOCOLS

Connector

Defined in fuchsia.hardware.audio.signalprocessing/connector.fidl

For an overview of the signal processing protocols see Audio Signal Processing

SignalProcessingConnect

Connect to a SignalProcessing protocol. Multiple connections may be supported, if a new connection request is not supported, i.e. the maximum number of connections have already been created, for instance one, then the channel will be closed with an ZX_ERR_ALREADY_BOUND epitaph. If signal processing is not supported at all, then the channel will be closed with a ZX_ERR_NOT_SUPPORTED epitaph. This method is named SignalProcessingConnect instead of Connect because this protocol is intended to be composed, and hence the more verbose name allows differentiation and improved clarity.

Request

NameType
protocol request<SignalProcessing>

Reader

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

For an overview see [Signal Processing Interface].

GetElements

Returns a vector of supported processing elements. Must return one or more processing elements, or ZX_ERR_NOT_SUPORTED.

Request

<EMPTY>

Response

NameType
result Reader_GetElements_Result

GetTopologies

Returns a vector of supported topologies. Must return one or more topologies, or ZX_ERR_NOT_SUPORTED. If more than one topology is returned, then the client may choose any of the topologies from the list with SetTopology. If only one topology is returned, then the topology definition is informational only since the one and only topology used can't be changed with SetTopology. If GetElements returns one or more elements, GetTopologies must return one or more topologies.

Request

<EMPTY>

Response

NameType
result Reader_GetTopologies_Result

WatchElementState

Get the processing element state via a hanging get. For a given processing_element_id, the driver will reply to the first WatchElement sent by the client. The driver will not respond to subsequent client WatchElement calls for a given processing_element_id until any field of the Element table changes from what was most recently reported for that processing_element_id.

Request

NameType
processing_element_id uint64

Response

NameType
state ElementState

SignalProcessing

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

For an overview see [Signal Processing Interface].

GetElements

Returns a vector of supported processing elements. Must return one or more processing elements, or ZX_ERR_NOT_SUPORTED.

Request

<EMPTY>

Response

NameType
result Reader_GetElements_Result

GetTopologies

Returns a vector of supported topologies. Must return one or more topologies, or ZX_ERR_NOT_SUPORTED. If more than one topology is returned, then the client may choose any of the topologies from the list with SetTopology. If only one topology is returned, then the topology definition is informational only since the one and only topology used can't be changed with SetTopology. If GetElements returns one or more elements, GetTopologies must return one or more topologies.

Request

<EMPTY>

Response

NameType
result Reader_GetTopologies_Result

SetElementState

Controls a processing element using a unique id returned by GetElements. Returns ZX_ERR_INVALID_ARGS if the processing_element_id does not match an id returned by GetElements or the type of TypeSpecificElementState does not match the ElementType of the processing element returned by GetElements for this id. The driver may return ZX_ERR_INVALID_ARGS if the state values are invalid, i.e. any of the values violates rules specified in this protocol, e.g. trying to change an EQUALIZER processing element's EqualizerBandState frequency when this processing element did not advertise CAN_CONTROL_FREQUENCY in its supported_controls.

SetElementState may be called before or after non-SignalProcessing protocol calls. If called after non-SignalProcessing protocol calls then SetElementState may or may not require renegotiation of the driver state as reached with calls of the protocol composing SignalProcessing, e.g. Dai. For instance, SetElementState changing an AGL processing element's parameters may not require renegotiation of the Dai state because changing a gain parameter usually does not change the set of supported audio formats. By contrast, if SetElementState changes the parameters of a CONNECTION_POINT element, the change may require renegotiation because it may invalidate the set of supported formats returned in a previous GetDaiFormats Dai protocol call.

It is the driver's job to determine when renegotiation is required. If renegotiation is required, then SetElementState must return ZX_ERR_BAD_STATE and the client must close the protocol channel such that the protocol negotiations are started over. The client then must make the SetElementState call that returned ZX_ERR_BAD_STATE before any non-SignalProcessing protocol calls.

Request

NameType
processing_element_id uint64
state ElementState

Response

NameType
result SignalProcessing_SetElementState_Result

SetTopology

Sets the topology to be used using an id to the vector returned by GetTopologies. If GetTopologies returns more than one Topology, SetTopology must be called to put the driver in an initialized state. If GetTopologies returns only one Topology, SetTopology is optional and has no effect.

SetTopology may be called before or after non-SignalProcessing protocol calls. If called after non-SignalProcessing protocol calls, then SetTopology may return ZX_ERR_BAD_STATE to indicate that the operation can not proceed without renegotiation of the driver state. See SetElementState for further discussion.

Request

NameType
topology_id uint64

Response

NameType
result SignalProcessing_SetTopology_Result

WatchElementState

Get the processing element state via a hanging get. For a given processing_element_id, the driver will reply to the first WatchElement sent by the client. The driver will not respond to subsequent client WatchElement calls for a given processing_element_id until any field of the Element table changes from what was most recently reported for that processing_element_id.

Request

NameType
processing_element_id uint64

Response

NameType
state ElementState

STRUCTS

EdgePair

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

Edge pairs between processing elements used to define ordering in processing elements arrangements.

FieldTypeDescriptionDefault
processing_element_id_from uint64 No default
processing_element_id_to uint64 No default

Reader_GetElements_Response

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

FieldTypeDescriptionDefault
processing_elements vector<Element>[64] No default

Reader_GetTopologies_Response

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

FieldTypeDescriptionDefault
topologies vector<Topology>[64] No default

SignalProcessing_SetElementState_Response

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

<EMPTY>

SignalProcessing_SetTopology_Response

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

<EMPTY>

ENUMS

ElementType flexible

Type: uint32

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

NameValueDescription
1

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

2

Define pipelines start/end.

3

Controls pipelines channel mixing and routing.

4

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

5

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

6

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.

7

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

8

Mute.

9

Delay.

10

Equalizer.

11

Sample Rate Conversion.

EqualizerBandType flexible

Type: uint64

Defined in fuchsia.hardware.audio.signalprocessing/equalizer.fidl

Type of the equalizer band.

NameValueDescription
1

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

2

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

3

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

4

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

5

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

6

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

GainDomain flexible

Type: uint8

Defined in fuchsia.hardware.audio.signalprocessing/gain.fidl

Hardware domain of the gain, e.g. ANALOG.

NameValueDescription
1

The processing element gain is applied in the digital domain.

2

The processing element gain is applied in the analog domain.

3

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

GainType strict

Type: uint8

Defined in fuchsia.hardware.audio.signalprocessing/gain.fidl

Gain type of representation.

NameValueDescription
1

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

2

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

LevelType strict

Type: uint8

Defined in fuchsia.hardware.audio.signalprocessing/dynamics.fidl

Level type.

NameValueDescription
1

Level Gain specified as peak.

2

Level specified as RMS.

ThresholdType strict

Type: uint8

Defined in fuchsia.hardware.audio.signalprocessing/dynamics.fidl

Threshold type.

NameValueDescription
1

Apply dynamics processing above the threshold.

2

Apply dynamics processing below the threshold.

TABLES

Dynamics

Defined in fuchsia.hardware.audio.signalprocessing/dynamics.fidl

Parameters for an Element with type equal to DYNAMICS.

OrdinalFieldTypeDescription
bands vector<DynamicsBand>[64]

Dynamics elements in this protocol may support multiple bands, each specifying a number of parameters in DynamicsElementState that can be changed with SetElement. The number of elements of the bands vector determines the number of bands supported by this processing element.

supported_controls DynamicsSupportedControls

The controls supported by this processing element.

DynamicsBand

Defined in fuchsia.hardware.audio.signalprocessing/dynamics.fidl

Parameters for a Dynamics element band.

OrdinalFieldTypeDescription
id uint64

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.

DynamicsBandState

Defined in fuchsia.hardware.audio.signalprocessing/dynamics.fidl

State for a single band within an Element with type equal to DYNAMICS. Servers may include control band fields even if the values are not able to be changed by the client (i.e. the bits are not set in supported_controls).

OrdinalFieldTypeDescription
id uint64

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

min_frequency uint32

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

max_frequency uint32

Maximum frequency for the band in Hz. Required. 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.

threshold_db float32

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

threshold_type ThresholdType

Dynamics processing is applied ABOVE or BELOW the threshold. Required for a server. A client must not include this field in a SetElement if DynamicsSupportedControls.THRESHOLD_TYPE is not set in supported_controls.

ratio float32

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

knee_width_db float32

The width of the knee region, in input dB. Optional. 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. A client must not include this field in a SetElement if DynamicsSupportedControls.KNEE_WIDTH is not set in supported_controls.

attack zx/duration

Attack time. Optional. If not included, the attack time is unspecified. A client must not include this field in a SetElement if DynamicsSupportedControls.ATTACK is not set in supported_controls.

release zx/duration

Release time. Optional. If not included, the release time is unspecified. A client must not include this field in a SetElement if DynamicsSupportedControls.RELEASE is not set in supported_controls.

output_gain_db float32

Output (a.k.a. make up or post) gain value in dB. Optional. If not included, the output gain is unspecified. A client must not include this field in a SetElement if DynamicsSupportedControls.OUTPUT_GAIN is not set in supported_controls.

input_gain_db float32

input (a.k.a. pre) gain value in dB. Optional. If not included, the input gain is unspecified. A client must not include this field in a SetElement if DynamicsSupportedControls.INPUT_GAIN is not set in supported_controls.

level_type LevelType

Level type (peak or RMS). Optional. If not included, the level type is unspecified. A client must not include this field in a SetElement if DynamicsSupportedControls.LEVEL_TYPE is not set in supported_controls.

lookahead zx/duration

Look-ahead time. Optional. If not included, the look-ahead time is unspecified. A client must not include this field in a SetElement if DynamicsSupportedControls.LOOKAHEAD is not set in supported_controls.

linked_channels bool

Linked channels (a.k.a. Stereo linked for 2-channel systems). Optional. 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. A client must not include this field in a SetElement if DynamicsSupportedControls.LINKED_CHANNELS is not set in supported_controls.

DynamicsElementState

Defined in fuchsia.hardware.audio.signalprocessing/dynamics.fidl

State for an Element with type equal to DYNAMICS.

OrdinalFieldTypeDescription
band_states vector<DynamicsBandState>[64]

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

Element

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

OrdinalFieldTypeDescription
id uint64

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.

type ElementType

Processing element type. Required.

type_specific TypeSpecificElement

If included, type specific parameters for the processing element.

can_disable bool

If included and true, the processing element can be disabled via ElementSetState. If not included or false, the processing element is always enabled.

description string[256]

If included, a textual description of the processing element.

ElementState

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

OrdinalFieldTypeDescription
type_specific TypeSpecificElementState

If included, 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, for instance if a SetElementState enables a disabled processing element providing a TypeSpecificElementState, then any previous informational TypeSpecificElementState is superceded.

enabled bool

Process element enable/disable state. Optional. By default processing elements are enabled. If the corresponding Element returned can_disable equals to false, then this field can't be set to false. If enabled is not included, then state must be included if and only if the processing element is currently enabled.

latency Latency

If included, how much latency is added to the pipeline if this processing element is enabled. This field must not be present in a SetElementState state since the latency can't be set by a client, it can only provided by the server in a WatchElementState reply.

Equalizer

Defined in fuchsia.hardware.audio.signalprocessing/equalizer.fidl

Parameters for a Element with type equal to EQUALIZER.

OrdinalFieldTypeDescription
bands vector<EqualizerBand>[64]

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

supported_controls EqualizerSupportedControls

The controls supported by this equalizer.

can_disable_bands bool

If included and true, individual bands can be disabled via ElementState. If not included or false, the bands are always enabled. For a band to be functional its enclosing equalizer processing element has to be enabled.

min_frequency uint32

Minimum frequency for the bands in Hz. Required.

max_frequency uint32

Maximum frequency for the bands in Hz. Required.

max_q float32

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

min_gain_db float32

Minimum gain in dB. Required if any EqualizerBand.EqualizerBandType is set to PEAK, LOW_SHELF, HIGH_SHELF.

max_gain_db float32

Maximum gain in dB. Required if any EqualizerBand.EqualizerBandType is set to PEAK, LOW_SHELF, HIGH_SHELF.

EqualizerBand

Defined in fuchsia.hardware.audio.signalprocessing/equalizer.fidl

Parameters for an equalizer Band.

OrdinalFieldTypeDescription
id uint64

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.

EqualizerBandState

Defined in fuchsia.hardware.audio.signalprocessing/equalizer.fidl

State for a single band within a Element with type equal to EQUALIZER.

OrdinalFieldTypeDescription
id uint64

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

type EqualizerBandType

Type of band. Optional.

frequency uint32

Center frequency for the band. Optional.

q float32

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

gain_db float32

Gain in dB. Required for EqualizerBandType PEAK, LOW_SHELF and HIGH_SHELF. May not be included for EqualizerBandType NOTCH, LOW_CUT or HIGH_CUT.

enabled bool

Enable/disable the band. Optional. By default all bands are enabled. Disabling the enclosing processing element by setting ElementState.enabled to false disables the whole equalizer and it does not change this field. For a band to be functional its enclosing equalizer processing element has to be enabled.

EqualizerElementState

Defined in fuchsia.hardware.audio.signalprocessing/equalizer.fidl

State for a Element with type equal to EQUALIZER.

OrdinalFieldTypeDescription
bands_state vector<EqualizerBandState>[64]

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

Gain

Defined in fuchsia.hardware.audio.signalprocessing/gain.fidl

Parameters for an Element with type equal to GAIN.

OrdinalFieldTypeDescription
type GainType

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

domain GainDomain

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

min_gain float32

Minimum gain in GainType format. Required.

max_gain float32

Maximum gain in GainType format. Required.

min_gain_step float32

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 WatchElement call. Required.

GainElementState

Defined in fuchsia.hardware.audio.signalprocessing/gain.fidl

State for an Element with type equal to GAIN.

OrdinalFieldTypeDescription
gain float32

Current gain in GainType format. Required.

Topology

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

A Topology specifies one way processing elements are arranged within the hardware.

OrdinalFieldTypeDescription
id uint64

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.

processing_elements_edge_pairs vector<EdgePair>[64]

Vector of processing elements edge pairs in this order. The ordering of processing elements with edge pairs form pipelines. To define multiple possible pipelines, return more Topology entries in GetTopologies. Required.

VendorSpecific

Defined in fuchsia.hardware.audio.signalprocessing/vendor_specific.fidl

Type specific parameters for an Element with type equal to VENDOR_SPECIFIC.

OrdinalFieldTypeDescription

VendorSpecificState

Defined in fuchsia.hardware.audio.signalprocessing/vendor_specific.fidl

State for an Element with type equal to VENDOR_SPECIFIC.

OrdinalFieldTypeDescription

UNIONS

Latency flexible

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

OrdinalVariantTypeDescription
latency_time zx/duration

Latency added to the pipeline as a zx.duration.

latency_frames uint32

Latency added to the pipeline as a number of frames.

Reader_GetElements_Result strict

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

OrdinalVariantTypeDescription
response Reader_GetElements_Response
err zx/status

Reader_GetTopologies_Result strict

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

OrdinalVariantTypeDescription
response Reader_GetTopologies_Response
err zx/status

SignalProcessing_SetElementState_Result strict

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

OrdinalVariantTypeDescription
response SignalProcessing_SetElementState_Response
err zx/status

SignalProcessing_SetTopology_Result strict

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

OrdinalVariantTypeDescription
response SignalProcessing_SetTopology_Response
err zx/status

TypeSpecificElement flexible

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

Type specific Parameters for an Element.

OrdinalVariantTypeDescription
vendor_specific VendorSpecific
gain Gain
equalizer Equalizer
dynamics Dynamics

TypeSpecificElementState flexible

Defined in fuchsia.hardware.audio.signalprocessing/signal_processing.fidl

Type specific processing element state. The type of processing element control is defined by the type of parameters provided in this union. Must match the type returned in the corresponding ElementType entry in the corresponding Element.

OrdinalVariantTypeDescription
vendor_specific VendorSpecificState
gain GainElementState
equalizer EqualizerElementState
dynamics DynamicsElementState

BITS

DynamicsSupportedControls flexible

Type: uint64

Defined in fuchsia.hardware.audio.signalprocessing/dynamics.fidl

Supported controls for Dynamics. If included, each bit representing a parameter of the dynamics processing bands can be changed with SetElement.

NameValueDescription
1

If included, the knee_width_db parameter can be changed.

2

If included, the attack parameter can be changed.

4

If included, the release parameter can be changed.

8

If included, the output_gain_db parameter can be changed.

16

If included, the input_gain_db parameter can be changed.

32

If included, the lookahead parameter can be changed.

64

If included, the level_type parameter can be changed.

128

If included, the linked_channels parameter can be changed.

256

If included, the threshold_type parameter can be changed.

EqualizerSupportedControls flexible

Type: uint64

Defined in fuchsia.hardware.audio.signalprocessing/equalizer.fidl

Equalizer supported controls specified in Equalizer.

NameValueDescription
1

If included, the frequency of the equalizer bands can be changed with SetElement.

2

If included, the q of the equalizer bands can be changed with SetElement.

4

If included, the type of the equalizer bands can be changed with SetElement to EqualizerBandType PEAK.

8

If included, the type of the equalizer bands can be changed with SetElement to EqualizerBandType NOTCH.

16

If included, the type of the equalizer bands can be changed with SetElement to EqualizerBandType LOW_CUT.

32

If included, the type of the equalizer bands can be changed with SetElement to EqualizerBandType HIGH_CUT.

64

If included, the type of the equalizer bands can be changed with SetElement to EqualizerBandType LOW_SHELF.

128

If included, the type of the equalizer bands can be changed with SetElement to EqualizerBandType HIGH_SHELF.

CONSTANTS

NameValueTypeDescription
MAX_COUNT_DYNAMICS_BANDS 64 uint32
MAX_COUNT_EQUALIZER_BANDS 64 uint32
MAX_COUNT_PROCESSING_ELEMENTS 64 uint32
MAX_COUNT_PROCESSING_ELEMENTS_EDGE_PAIRS 64 uint32
MAX_COUNT_TOPOLOGIES 64 uint32
MAX_STRING_SIZE 256 uint32