fuchsia.audio.effects

Added: 7

PROTOCOLS

Processor

Defined in fuchsia.audio.effects/processor.fidl

An audio effect processor. Consumes one or more input streams, producing one or more output streams. On creation, this protocol must be tied to a fuchsia.audio.effects.Processor/ProcessorConfiguration, which defines the processor's input and output streams.

Process

Processes the given number of frames. This will consume num_frames from each ProcessorConfiguration.inputs[i] and produce an equivalent number of frames in each ProcessorConfiguration.outputs[i].

Execution model

All inputs and outputs must have identical frame rates. This simplifies the problem of matching input and output frames, as described below.

At each call to Process, the effect collects audio from a set of input buffers and produces a set of output buffers. The input buffers should be aligned by time. That means: the first frame in each input buffer, input[i].buffer[0], should have the same presentation time as all other frames input[j].buffer[0].

Output buffers with non-zero latency may be shifted relative to input buffers. For each output k, input frame 0 has the same presentation time as the frame at output[k].buffer[output[k].latency_frames].

  • request num_frames The number of frames to process.
  • request options Extra options.
  • response per_stage_metrics Metrics about this process call, possibly subdivided into multiple stages.
  • error A zx.Status value indicating success or failure.

Request

NameType
num_frames uint64
options ProcessOptions

Response

NameType
payload Processor_Process_Result

ProcessorCreator

Defined in fuchsia.audio.effects/creator.fidl

A factory for creating processors.

Create

Create a new Processor and return it's ProcessorConfiguration.

  • request name A string naming the processor to create. The meaning of this name is up to the implementor.
  • response processor_configuration Description of the new processor.
  • error A zx.Status value indicating success or failure.

Request

NameType
name string[1024]

Response

NameType
payload ProcessorCreator_Create_Result

STRUCTS

ProcessorCreator_Create_Response resource

Defined in fuchsia.audio.effects/creator.fidl

FieldTypeDescriptionDefault
processor_configuration ProcessorConfiguration No default

Processor_Process_Response

Defined in fuchsia.audio.effects/processor.fidl

FieldTypeDescriptionDefault
per_stage_metrics vector<ProcessMetrics>[8] No default

TABLES

InputConfiguration resource

Defined in fuchsia.audio.effects/processor.fidl

Configures a single input stream.

OrdinalFieldTypeDescription
format fuchsia.mediastreams/AudioFormat

Format of this input stream. Required.

buffer fuchsia.mem/Range

Buffer for this input stream. Must provide write access and must have enough space for ProcessorConfiguration.max_frames_per_call.

Required.

OutputConfiguration resource

Defined in fuchsia.audio.effects/processor.fidl

Configures a single output stream.

OrdinalFieldTypeDescription
format fuchsia.mediastreams/AudioFormat

Format of this output stream. Required.

buffer fuchsia.mem/Range

Buffer for this output stream. Must provide write access and must have enough space for ProcessorConfiguration.max_frames_per_call. Write access is needed so the audio system can write to the output buffer in error cases, such as when the Processor disconnects.

If the effect supports in-place updates, this may refer to the same memory range as an input buffer.

Required.

latency_frames uint64

If specified, the output signal is shifted by this many frames. If not specified, this is zero. See the explanation at [fuchsia.audio.effects/Processor.Process].

ring_out_frames uint64

If specified, then input frame F will affect the output stream up through frame F + ring_out_frames. If not specified, this is zero.

Put differently, if the effect is given an input stream with N non-silent frames followed by infinite silence, the effect will produce up to N + ring_out_frames non-silent frames before emitting silence.

ProcessMetrics

Defined in fuchsia.audio.effects/processor.fidl

An extensible container of metrics about a single Processor.Process call. All fields are optional.

OrdinalFieldTypeDescription
name string[64]

Each process call may be (optionally) divided into multiple stages, each with their own ProcessMetrics. This field names the stage described by this table.

wall_time zx/Duration

Total wall-clock time from the moment the Process call is received to the moment a response is returned.

cpu_time zx/Duration

Total amount of time spent running on the CPU. See zx_info_task_runtime.cpu_time.

queue_time zx/Duration

Total amount of time spent waiting to run. Only counts "ready" time. See zx_info_task_runtime.queue_time.

page_fault_time zx/Duration

Total amount of time spent handling page faults. See zx_info_task_runtime.page_fault_time.

kernel_lock_contention_time zx/Duration

Total amount of time spent waiting on contended kernel locks. See zx_info_task_runtime.lock_contention_time.

ProcessOptions

Defined in fuchsia.audio.effects/processor.fidl

An extensible container of options for Processor.Process.

OrdinalFieldTypeDescription
total_applied_gain_db_per_input vector<float32>[8]

The total gain that has been applied to each input stream by prior processing steps. For example, given an audio pipeline of the form input -> ProcessorA -> ProcessorB, if input is a sine wave with unity amplitude and ProcessorA applies a gain of -5.0dB, then ProcessorB should be called with total_applied_gain_db_per_input[0] = -5.0dB and ProcessorB's input buffer should contain a sine wave with amplitude -5.0dB.

If not specified, the applied gain is 0 dB for each input.

usage_mask_per_input vector<uint32>[8]

All fuchsia.media.AudioRenderUsages that contribute to each input stream. This is a bitmask of (1 << r), for each AudioRenderUsage that contributes. For example, if an input stream contains BACKGROUND (== 0) and INTERRUPTION (== 2), the bitmask is ((1<<0)|(1<<2)) = 0x5.

Note: this field may be removed once we have transitions to the new Fuchsia media APIs.

ProcessorConfiguration resource

Defined in fuchsia.audio.effects/processor.fidl

Configures a Processor.

OrdinalFieldTypeDescription
processor Processor

Dedicated FIDL channel for this processor. Required.

inputs vector<InputConfiguration>[8]

A description of all input streams for this processor. Must have at least one input.

Each input stream can have a different sample format or channel count, but all inputs must have the same frame rate.

outputs vector<OutputConfiguration>[8]

A description of all output streams for this processor. Must have at least one output.

Each output stream can have a different sample format or channel count, but all outputs must have the same frame rate as the input(s) -- effects are allowed to perform sample format conversion and rechannelization as long as the frame rate does not change.

max_frames_per_call uint64

The maximum number of frames that may be processed per call to fuchsia.audio.effects/Processor.Process. The default limit is the number of frames that can fit in the smallest input buffer. If specified, this must be smaller than the default limit.

block_size_frames uint64

If specified, all calls to fuchsia.audio.effects/Processor.Process. must set num_frames to a multiple of this number. Must be less than or equal to max_frames_per_call. If not specified, then any block size is allowed.

UNIONS

ProcessorCreator_Create_Result strict resource

Defined in fuchsia.audio.effects/creator.fidl

OrdinalVariantTypeDescription
response ProcessorCreator_Create_Response
err zx/Status

Processor_Process_Result strict

Defined in fuchsia.audio.effects/processor.fidl

OrdinalVariantTypeDescription
response Processor_Process_Response
err zx/Status

CONSTANTS

NameValueTypeDescription
MAX_INPUT_STREAMS 8 uint32

The maximum number of input and output streams. These bounds are somewhat arbitrary; in practice we don't expect more than 1 or 2 inputs and outputs in the vast majority of cases.

MAX_OUTPUT_STREAMS 8 uint32
MAX_PROCESS_STAGES 8 uint32

The maximum size of the per_stage_metrics array.

MAX_PROCESS_STAGE_NAME_LENGTH 64 uint32

The maximum length of the name of a process stage.