fuchsia.virtualaudio

PROTOCOLS

Forwarder

Defined in fuchsia.virtualaudio/virtual_audio.fidl

Using this Simple Layout (C-bound) protocol, an intermediary (such as the virtual audio service) forwards FIDL protocol requests to the virtual audio driver, which enables clients to use more full-featured (C++ based) bindings with this driver -- specifically the Control, Input and Output protocols.

SendControl

Request

NameType
control request<Control>

SendInput

Request

NameType
input request<Input>

SendOutput

Request

NameType
output request<Output>

Control

Defined in fuchsia.virtualaudio/virtual_audio.fidl

This protocol provides the caller a high-level ON/OFF switch for overall virtual audio functionality at the system level. When virtualaudio is disabled, device configurations can be created and changed, but no devices can be added. When virtualaudio is enabled, device configurations can again be converted into devices by calling Add().

Enable

Allow inputs and outputs to be activated, but do not automatically reactivate those previously deactivated by Disable(). Does not affect existing Configs. By default, virtualaudio is enabled on system startup. This method's callback can be used as a mechanism to synchronize with other asynchronous in-flight virtualaudio FIDL operations.

Request

NameType

Response

NameType

Disable

Deactivate all active inputs/outputs; disallow subsequent activations. This method's callback can be used as a mechanism to synchronize with other asynchronous in-flight virtualaudio FIDL operations.

Request

NameType

Response

NameType

GetNumDevices

Return the number of active input and output virtual devices. This method's callback can be used as a mechanism to synchronize with other asynchronous in-flight virtualaudio FIDL operations.

Request

NameType

Response

NameType
num_input_devices uint32
num_output_devices uint32

Input

Defined in fuchsia.virtualaudio/virtual_audio.fidl

This protocol represents an active virtual audio input device. It inherits the parent protocols Device and Configuration. This protocol, as well as the contents of Device, represent actions that can be taken by an active input device -- actions that should be immediately detected and reacted upon by the audio subsystem.

SetDeviceName

Set the virtual audio device's name. This corresponds to the value associated with the device node for this virtual device. This must be called before calling Add(), or after Remove().

Request

NameType
device_name string

SetManufacturer

Set the virtual audio device's manufacturer name. This must be called before calling Add(), or after Remove(). Once a device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_STRING command of string ID AUDIO_STREAM_STR_ID_MANUFACTURER. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() and the ->OnDeviceAdded() event.

Request

NameType
manufacturer_name string

SetProduct

Set the virtual audio device's product name. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_STRING command of string ID AUDIO_STREAM_STR_ID_PRODUCT. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() and the ->OnDeviceAdded() event.

Request

NameType
product_name string

SetUniqueId

Set the virtual audio device's unique ID, a 16-character string. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_UNIQUE_ID command. This value is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() or ->OnDeviceAdded().

Request

NameType
unique_id uint8[16]

AddFormatRange

Add a supported format range for this audio device. This must be called before calling Add(), or after Remove(). Once the device is activated, format ranges are returned by the driver in response to an AUDIO_STREAM_CMD_GET_FORMATS command. sample_format_flags is of type audio_sample_format_t, and rate_family_flags is a bit field of possible constants beginning with ASF_RANGE_FLAG_FPS_. See audio.h for details.

Request

NameType
sample_format_flags uint32
min_frame_rate uint32
max_frame_rate uint32
min_channels uint8
max_channels uint8
rate_family_flags uint16

ClearFormatRanges

Remove the minimal format range that is added by default to all configurations. As with AddFormatRange(), this method must be called before calling Add(), or after Remove().

Request

NameType

SetFifoDepth

Set the virtual audio device's fifo depth, in bytes. This must be called before calling Add(), or after Remove(). Once the device is activated, the depth of its FIFO is returned by the driver in response to an AUDIO_RB_CMD_GET_FIFO_DEPTH command on the ring buffer channel.

Request

NameType
fifo_depth_bytes uint32

SetExternalDelay

Set the virtual audio device's external delay, in nanoseconds. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_SET_FORMAT command.

Request

NameType
external_delay zx/duration

SetRingBufferRestrictions

Set restrictions for the device ring buffer. This must be called before calling Add(), or after Remove(). Once the device is activated, the ring buffer and its size are returned by the driver in response to an AUDIO_RB_CMD_GET_BUFFER command on the ring buffer channel. Note: both min_frames and max_frames must be multiples of modulo_frames.

Request

NameType
min_frames uint32
max_frames uint32
modulo_frames uint32

SetGainProperties

Set gain properties for this virtual device. This must be called before calling Add(), or after Remove(). Once the device is activated, gain information is returned by the driver in an audio_stream_cmd_get_gain_resp struct, in response to an AUDIO_STREAM_CMD_GET_GAIN command. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioGainInfo struct by GetDeviceGain() and the ->OnDeviceGainChanged() event.

Request

NameType
min_gain_db float32
max_gain_db float32
gain_step_db float32
current_gain_db float32
can_mute bool
current_mute bool
can_agc bool
current_agc bool

SetPlugProperties

Set plug properties for this virtual device. This must be called before calling Add(), or after Remove(). Once the device is activated, plug information is returned by the driver in response to an AUDIO_STREAM_CMD_PLUG_DETECT command. This information is used by the system when determining which device is default. This in turn is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: in GetDevices(), GetDefaultInputDevice()/GetDefaultOutputDevice() and the ->OnDefaultDeviceChanged() event.

Request

NameType
plug_change_time zx/time
plugged bool
hardwired bool
can_notify bool

ResetConfiguration

Return a configuration to its default settings. This call has no effect on active devices. In other words, it must be called before calling Add(), or after Remove().

Request

NameType

Add

Activate (DdkAdd) the virtual audio device as currently configured. A device node will be published and detected by the AudioDeviceManager, and a driver for the virtual device will be loaded and queried. Device arrivals are exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol, in GetDevices() and the ->OnDeviceAdded() event.

Request

NameType

Remove

Deactivate (DdkRemove) the active virtual audio device, but retain its configuration for future activation. The driver for the virtual device will be unloaded, and the device node closed. Device removals are exposed to clients by fuchsia.media.AudioDeviceEnumerator, in GetDevices() and ->OnDeviceRemoved().

Request

NameType

GetFormat

Return the format selected by the client, when that client issued an AUDIO_STREAM_CMD_SET_FORMAT command. This can only occur after a device has been added, and is only allowed to occur before the device's ring buffer has been returned (i.e., before an AUDIO_RB_CMD_GET_BUFFER command).

Request

NameType

Response

NameType
frames_per_second uint32
sample_format uint32
num_channels uint32
external_delay zx/duration

OnSetFormat

Notify all subscribed listeners when the above format is set or changed.

Response

NameType
frames_per_second uint32
sample_format uint32
num_channels uint32
external_delay zx/duration

GetGain

Return the current gain state for this device. After a device has been added, a client can call this at any time -- even before the ring buffer has been established, or before the format has been set.

Request

NameType

Response

NameType
current_mute bool
current_agc bool
current_gain_db float32

OnSetGain

Notify all subscribed listeners when the above gain is set or changed.

Response

NameType
current_mute bool
current_agc bool
current_gain_db float32

GetBuffer

Return details about the ring buffer that was established in response to a client AUDIO_RB_CMD_GET_BUFFER command. This will only occur after the client sets the format and retrieves other driver information.

Request

NameType

Response

NameType
ring_buffer handle<vmo>
num_ring_buffer_frames uint32
notifications_per_ring uint32

OnBufferCreated

Notify all subscribed listeners when the above buffer has been created.

Response

NameType
ring_buffer handle<vmo>
num_ring_buffer_frames uint32
notifications_per_ring uint32

SetNotificationFrequency

Override the position notification frequency set by AudioCore for this stream, with the given value. Although this method can be called at any time (including before this Input|Output is added, or after it is started), logically it makes most sense to call this immediately after receiving details about the just-created ring buffer, via GetBuffer or the ->OnBufferCreated event.

Request

NameType
notifications_per_ring uint32

OnStart

Notify all subscribed listeners when the device is commanded to Start streaming. This can only occur after a device is fully configured (format is set; ring buffer is established and fetched).

Response

NameType
start_time zx/time

OnStop

Notify all subscribed listeners when the device is commanded to Stop streaming. This can only occur when the device is already Started. Stop returns the device to a fully-configured state. Upon this command, the already-set format and ring buffer are retained without change, but position will re-begin at 0, if the device is again Started.

Response

NameType
stop_time zx/time
ring_position uint32

GetPosition

Return the current position (in bytes) within the ring buffer, along with the time (per MONOTONIC clock) that corresponds with that position. This can only be called after the ring buffer is established. If the device has not yet Started streaming, then zero will always be returned.

Request

NameType

Response

NameType
monotonic_time zx/time
ring_position uint32

OnPositionNotify

Notify all subscribed listeners, when any AUDIO_RB_POSITION_NOTIFY position notification is issued by the driver. The frequency of these per-stream notifications is set by AudioCore, reported to VAD clients via GetBuffer or the ->OnBufferCreated event. VirtualAudioDevice clients can enable an alternate notification frequency for a given stream by calling SetNotificationFrequency. As with a direct call to GetPosition, the returned parameters are the current position (in bytes) in the ring buffer, as well as the time (per MONOTONIC clock) that corresponds with that ring buffer position.

Response

NameType
monotonic_time zx/time
ring_position uint32

ChangePlugState

Hot-plug or hot-unplug an active virtual device, at the specified time. For devices marked as capable of asynchronously notifying the system of plug changes, the driver will now send the values using AUDIO_STREAM_PLUG_DETECT_NOTIFY. Else, values will be reflected when the driver is next sent an AUDIO_STREAM_CMD_PLUG_DETECT command. This information is used by the system when determining which device is default. This, in turn, is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: in GetDevices(), GetDefaultInputDevice()/GetDefaultOutputDevice() and the ->OnDefaultDeviceChanged() event.

Request

NameType
plug_change_time zx/time
plugged bool

Output

Defined in fuchsia.virtualaudio/virtual_audio.fidl

This protocol represents an active virtual audio output device. It inherits the parent protocols Device and Configuration. This protocol, as well as the contents of Device, represent actions that can be taken by an active output device -- actions that should be immediately detected and reacted upon by the audio subsystem.

SetDeviceName

Set the virtual audio device's name. This corresponds to the value associated with the device node for this virtual device. This must be called before calling Add(), or after Remove().

Request

NameType
device_name string

SetManufacturer

Set the virtual audio device's manufacturer name. This must be called before calling Add(), or after Remove(). Once a device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_STRING command of string ID AUDIO_STREAM_STR_ID_MANUFACTURER. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() and the ->OnDeviceAdded() event.

Request

NameType
manufacturer_name string

SetProduct

Set the virtual audio device's product name. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_STRING command of string ID AUDIO_STREAM_STR_ID_PRODUCT. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() and the ->OnDeviceAdded() event.

Request

NameType
product_name string

SetUniqueId

Set the virtual audio device's unique ID, a 16-character string. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_UNIQUE_ID command. This value is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() or ->OnDeviceAdded().

Request

NameType
unique_id uint8[16]

AddFormatRange

Add a supported format range for this audio device. This must be called before calling Add(), or after Remove(). Once the device is activated, format ranges are returned by the driver in response to an AUDIO_STREAM_CMD_GET_FORMATS command. sample_format_flags is of type audio_sample_format_t, and rate_family_flags is a bit field of possible constants beginning with ASF_RANGE_FLAG_FPS_. See audio.h for details.

Request

NameType
sample_format_flags uint32
min_frame_rate uint32
max_frame_rate uint32
min_channels uint8
max_channels uint8
rate_family_flags uint16

ClearFormatRanges

Remove the minimal format range that is added by default to all configurations. As with AddFormatRange(), this method must be called before calling Add(), or after Remove().

Request

NameType

SetFifoDepth

Set the virtual audio device's fifo depth, in bytes. This must be called before calling Add(), or after Remove(). Once the device is activated, the depth of its FIFO is returned by the driver in response to an AUDIO_RB_CMD_GET_FIFO_DEPTH command on the ring buffer channel.

Request

NameType
fifo_depth_bytes uint32

SetExternalDelay

Set the virtual audio device's external delay, in nanoseconds. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_SET_FORMAT command.

Request

NameType
external_delay zx/duration

SetRingBufferRestrictions

Set restrictions for the device ring buffer. This must be called before calling Add(), or after Remove(). Once the device is activated, the ring buffer and its size are returned by the driver in response to an AUDIO_RB_CMD_GET_BUFFER command on the ring buffer channel. Note: both min_frames and max_frames must be multiples of modulo_frames.

Request

NameType
min_frames uint32
max_frames uint32
modulo_frames uint32

SetGainProperties

Set gain properties for this virtual device. This must be called before calling Add(), or after Remove(). Once the device is activated, gain information is returned by the driver in an audio_stream_cmd_get_gain_resp struct, in response to an AUDIO_STREAM_CMD_GET_GAIN command. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioGainInfo struct by GetDeviceGain() and the ->OnDeviceGainChanged() event.

Request

NameType
min_gain_db float32
max_gain_db float32
gain_step_db float32
current_gain_db float32
can_mute bool
current_mute bool
can_agc bool
current_agc bool

SetPlugProperties

Set plug properties for this virtual device. This must be called before calling Add(), or after Remove(). Once the device is activated, plug information is returned by the driver in response to an AUDIO_STREAM_CMD_PLUG_DETECT command. This information is used by the system when determining which device is default. This in turn is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: in GetDevices(), GetDefaultInputDevice()/GetDefaultOutputDevice() and the ->OnDefaultDeviceChanged() event.

Request

NameType
plug_change_time zx/time
plugged bool
hardwired bool
can_notify bool

ResetConfiguration

Return a configuration to its default settings. This call has no effect on active devices. In other words, it must be called before calling Add(), or after Remove().

Request

NameType

Add

Activate (DdkAdd) the virtual audio device as currently configured. A device node will be published and detected by the AudioDeviceManager, and a driver for the virtual device will be loaded and queried. Device arrivals are exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol, in GetDevices() and the ->OnDeviceAdded() event.

Request

NameType

Remove

Deactivate (DdkRemove) the active virtual audio device, but retain its configuration for future activation. The driver for the virtual device will be unloaded, and the device node closed. Device removals are exposed to clients by fuchsia.media.AudioDeviceEnumerator, in GetDevices() and ->OnDeviceRemoved().

Request

NameType

GetFormat

Return the format selected by the client, when that client issued an AUDIO_STREAM_CMD_SET_FORMAT command. This can only occur after a device has been added, and is only allowed to occur before the device's ring buffer has been returned (i.e., before an AUDIO_RB_CMD_GET_BUFFER command).

Request

NameType

Response

NameType
frames_per_second uint32
sample_format uint32
num_channels uint32
external_delay zx/duration

OnSetFormat

Notify all subscribed listeners when the above format is set or changed.

Response

NameType
frames_per_second uint32
sample_format uint32
num_channels uint32
external_delay zx/duration

GetGain

Return the current gain state for this device. After a device has been added, a client can call this at any time -- even before the ring buffer has been established, or before the format has been set.

Request

NameType

Response

NameType
current_mute bool
current_agc bool
current_gain_db float32

OnSetGain

Notify all subscribed listeners when the above gain is set or changed.

Response

NameType
current_mute bool
current_agc bool
current_gain_db float32

GetBuffer

Return details about the ring buffer that was established in response to a client AUDIO_RB_CMD_GET_BUFFER command. This will only occur after the client sets the format and retrieves other driver information.

Request

NameType

Response

NameType
ring_buffer handle<vmo>
num_ring_buffer_frames uint32
notifications_per_ring uint32

OnBufferCreated

Notify all subscribed listeners when the above buffer has been created.

Response

NameType
ring_buffer handle<vmo>
num_ring_buffer_frames uint32
notifications_per_ring uint32

SetNotificationFrequency

Override the position notification frequency set by AudioCore for this stream, with the given value. Although this method can be called at any time (including before this Input|Output is added, or after it is started), logically it makes most sense to call this immediately after receiving details about the just-created ring buffer, via GetBuffer or the ->OnBufferCreated event.

Request

NameType
notifications_per_ring uint32

OnStart

Notify all subscribed listeners when the device is commanded to Start streaming. This can only occur after a device is fully configured (format is set; ring buffer is established and fetched).

Response

NameType
start_time zx/time

OnStop

Notify all subscribed listeners when the device is commanded to Stop streaming. This can only occur when the device is already Started. Stop returns the device to a fully-configured state. Upon this command, the already-set format and ring buffer are retained without change, but position will re-begin at 0, if the device is again Started.

Response

NameType
stop_time zx/time
ring_position uint32

GetPosition

Return the current position (in bytes) within the ring buffer, along with the time (per MONOTONIC clock) that corresponds with that position. This can only be called after the ring buffer is established. If the device has not yet Started streaming, then zero will always be returned.

Request

NameType

Response

NameType
monotonic_time zx/time
ring_position uint32

OnPositionNotify

Notify all subscribed listeners, when any AUDIO_RB_POSITION_NOTIFY position notification is issued by the driver. The frequency of these per-stream notifications is set by AudioCore, reported to VAD clients via GetBuffer or the ->OnBufferCreated event. VirtualAudioDevice clients can enable an alternate notification frequency for a given stream by calling SetNotificationFrequency. As with a direct call to GetPosition, the returned parameters are the current position (in bytes) in the ring buffer, as well as the time (per MONOTONIC clock) that corresponds with that ring buffer position.

Response

NameType
monotonic_time zx/time
ring_position uint32

ChangePlugState

Hot-plug or hot-unplug an active virtual device, at the specified time. For devices marked as capable of asynchronously notifying the system of plug changes, the driver will now send the values using AUDIO_STREAM_PLUG_DETECT_NOTIFY. Else, values will be reflected when the driver is next sent an AUDIO_STREAM_CMD_PLUG_DETECT command. This information is used by the system when determining which device is default. This, in turn, is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: in GetDevices(), GetDefaultInputDevice()/GetDefaultOutputDevice() and the ->OnDefaultDeviceChanged() event.

Request

NameType
plug_change_time zx/time
plugged bool

Device

Defined in fuchsia.virtualaudio/virtual_audio.fidl

This protocol represents the base functionality of active Input and Output audio devices -- methods that are common to both protocols. This protocol, as well as the contents of Output and Input, represent actions that can be taken by an active device -- actions that should be immediately detected and reacted upon by the audio subsystem.

SetDeviceName

Set the virtual audio device's name. This corresponds to the value associated with the device node for this virtual device. This must be called before calling Add(), or after Remove().

Request

NameType
device_name string

SetManufacturer

Set the virtual audio device's manufacturer name. This must be called before calling Add(), or after Remove(). Once a device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_STRING command of string ID AUDIO_STREAM_STR_ID_MANUFACTURER. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() and the ->OnDeviceAdded() event.

Request

NameType
manufacturer_name string

SetProduct

Set the virtual audio device's product name. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_STRING command of string ID AUDIO_STREAM_STR_ID_PRODUCT. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() and the ->OnDeviceAdded() event.

Request

NameType
product_name string

SetUniqueId

Set the virtual audio device's unique ID, a 16-character string. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_UNIQUE_ID command. This value is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() or ->OnDeviceAdded().

Request

NameType
unique_id uint8[16]

AddFormatRange

Add a supported format range for this audio device. This must be called before calling Add(), or after Remove(). Once the device is activated, format ranges are returned by the driver in response to an AUDIO_STREAM_CMD_GET_FORMATS command. sample_format_flags is of type audio_sample_format_t, and rate_family_flags is a bit field of possible constants beginning with ASF_RANGE_FLAG_FPS_. See audio.h for details.

Request

NameType
sample_format_flags uint32
min_frame_rate uint32
max_frame_rate uint32
min_channels uint8
max_channels uint8
rate_family_flags uint16

ClearFormatRanges

Remove the minimal format range that is added by default to all configurations. As with AddFormatRange(), this method must be called before calling Add(), or after Remove().

Request

NameType

SetFifoDepth

Set the virtual audio device's fifo depth, in bytes. This must be called before calling Add(), or after Remove(). Once the device is activated, the depth of its FIFO is returned by the driver in response to an AUDIO_RB_CMD_GET_FIFO_DEPTH command on the ring buffer channel.

Request

NameType
fifo_depth_bytes uint32

SetExternalDelay

Set the virtual audio device's external delay, in nanoseconds. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_SET_FORMAT command.

Request

NameType
external_delay zx/duration

SetRingBufferRestrictions

Set restrictions for the device ring buffer. This must be called before calling Add(), or after Remove(). Once the device is activated, the ring buffer and its size are returned by the driver in response to an AUDIO_RB_CMD_GET_BUFFER command on the ring buffer channel. Note: both min_frames and max_frames must be multiples of modulo_frames.

Request

NameType
min_frames uint32
max_frames uint32
modulo_frames uint32

SetGainProperties

Set gain properties for this virtual device. This must be called before calling Add(), or after Remove(). Once the device is activated, gain information is returned by the driver in an audio_stream_cmd_get_gain_resp struct, in response to an AUDIO_STREAM_CMD_GET_GAIN command. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioGainInfo struct by GetDeviceGain() and the ->OnDeviceGainChanged() event.

Request

NameType
min_gain_db float32
max_gain_db float32
gain_step_db float32
current_gain_db float32
can_mute bool
current_mute bool
can_agc bool
current_agc bool

SetPlugProperties

Set plug properties for this virtual device. This must be called before calling Add(), or after Remove(). Once the device is activated, plug information is returned by the driver in response to an AUDIO_STREAM_CMD_PLUG_DETECT command. This information is used by the system when determining which device is default. This in turn is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: in GetDevices(), GetDefaultInputDevice()/GetDefaultOutputDevice() and the ->OnDefaultDeviceChanged() event.

Request

NameType
plug_change_time zx/time
plugged bool
hardwired bool
can_notify bool

ResetConfiguration

Return a configuration to its default settings. This call has no effect on active devices. In other words, it must be called before calling Add(), or after Remove().

Request

NameType

Add

Activate (DdkAdd) the virtual audio device as currently configured. A device node will be published and detected by the AudioDeviceManager, and a driver for the virtual device will be loaded and queried. Device arrivals are exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol, in GetDevices() and the ->OnDeviceAdded() event.

Request

NameType

Remove

Deactivate (DdkRemove) the active virtual audio device, but retain its configuration for future activation. The driver for the virtual device will be unloaded, and the device node closed. Device removals are exposed to clients by fuchsia.media.AudioDeviceEnumerator, in GetDevices() and ->OnDeviceRemoved().

Request

NameType

GetFormat

Return the format selected by the client, when that client issued an AUDIO_STREAM_CMD_SET_FORMAT command. This can only occur after a device has been added, and is only allowed to occur before the device's ring buffer has been returned (i.e., before an AUDIO_RB_CMD_GET_BUFFER command).

Request

NameType

Response

NameType
frames_per_second uint32
sample_format uint32
num_channels uint32
external_delay zx/duration

OnSetFormat

Notify all subscribed listeners when the above format is set or changed.

Response

NameType
frames_per_second uint32
sample_format uint32
num_channels uint32
external_delay zx/duration

GetGain

Return the current gain state for this device. After a device has been added, a client can call this at any time -- even before the ring buffer has been established, or before the format has been set.

Request

NameType

Response

NameType
current_mute bool
current_agc bool
current_gain_db float32

OnSetGain

Notify all subscribed listeners when the above gain is set or changed.

Response

NameType
current_mute bool
current_agc bool
current_gain_db float32

GetBuffer

Return details about the ring buffer that was established in response to a client AUDIO_RB_CMD_GET_BUFFER command. This will only occur after the client sets the format and retrieves other driver information.

Request

NameType

Response

NameType
ring_buffer handle<vmo>
num_ring_buffer_frames uint32
notifications_per_ring uint32

OnBufferCreated

Notify all subscribed listeners when the above buffer has been created.

Response

NameType
ring_buffer handle<vmo>
num_ring_buffer_frames uint32
notifications_per_ring uint32

SetNotificationFrequency

Override the position notification frequency set by AudioCore for this stream, with the given value. Although this method can be called at any time (including before this Input|Output is added, or after it is started), logically it makes most sense to call this immediately after receiving details about the just-created ring buffer, via GetBuffer or the ->OnBufferCreated event.

Request

NameType
notifications_per_ring uint32

OnStart

Notify all subscribed listeners when the device is commanded to Start streaming. This can only occur after a device is fully configured (format is set; ring buffer is established and fetched).

Response

NameType
start_time zx/time

OnStop

Notify all subscribed listeners when the device is commanded to Stop streaming. This can only occur when the device is already Started. Stop returns the device to a fully-configured state. Upon this command, the already-set format and ring buffer are retained without change, but position will re-begin at 0, if the device is again Started.

Response

NameType
stop_time zx/time
ring_position uint32

GetPosition

Return the current position (in bytes) within the ring buffer, along with the time (per MONOTONIC clock) that corresponds with that position. This can only be called after the ring buffer is established. If the device has not yet Started streaming, then zero will always be returned.

Request

NameType

Response

NameType
monotonic_time zx/time
ring_position uint32

OnPositionNotify

Notify all subscribed listeners, when any AUDIO_RB_POSITION_NOTIFY position notification is issued by the driver. The frequency of these per-stream notifications is set by AudioCore, reported to VAD clients via GetBuffer or the ->OnBufferCreated event. VirtualAudioDevice clients can enable an alternate notification frequency for a given stream by calling SetNotificationFrequency. As with a direct call to GetPosition, the returned parameters are the current position (in bytes) in the ring buffer, as well as the time (per MONOTONIC clock) that corresponds with that ring buffer position.

Response

NameType
monotonic_time zx/time
ring_position uint32

ChangePlugState

Hot-plug or hot-unplug an active virtual device, at the specified time. For devices marked as capable of asynchronously notifying the system of plug changes, the driver will now send the values using AUDIO_STREAM_PLUG_DETECT_NOTIFY. Else, values will be reflected when the driver is next sent an AUDIO_STREAM_CMD_PLUG_DETECT command. This information is used by the system when determining which device is default. This, in turn, is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: in GetDevices(), GetDefaultInputDevice()/GetDefaultOutputDevice() and the ->OnDefaultDeviceChanged() event.

Request

NameType
plug_change_time zx/time
plugged bool

Configuration

Defined in fuchsia.virtualaudio/virtual_audio.fidl

This protocol is conceptually a base protocol to Device. It exposes the methods used to specify the properties of a virtual audio device (its configuration), before the virtual device is instantiated by the call to Add(). Although the non-Add methods on this protocol can be called after calling Add() (i.e., after Configuration has been converted into active Device), this only changes how future Devices will be created; it has no effect on already-created Devices.

SetDeviceName

Set the virtual audio device's name. This corresponds to the value associated with the device node for this virtual device. This must be called before calling Add(), or after Remove().

Request

NameType
device_name string

SetManufacturer

Set the virtual audio device's manufacturer name. This must be called before calling Add(), or after Remove(). Once a device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_STRING command of string ID AUDIO_STREAM_STR_ID_MANUFACTURER. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() and the ->OnDeviceAdded() event.

Request

NameType
manufacturer_name string

SetProduct

Set the virtual audio device's product name. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_STRING command of string ID AUDIO_STREAM_STR_ID_PRODUCT. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() and the ->OnDeviceAdded() event.

Request

NameType
product_name string

SetUniqueId

Set the virtual audio device's unique ID, a 16-character string. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_GET_UNIQUE_ID command. This value is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioDeviceInfo struct by GetDevices() or ->OnDeviceAdded().

Request

NameType
unique_id uint8[16]

AddFormatRange

Add a supported format range for this audio device. This must be called before calling Add(), or after Remove(). Once the device is activated, format ranges are returned by the driver in response to an AUDIO_STREAM_CMD_GET_FORMATS command. sample_format_flags is of type audio_sample_format_t, and rate_family_flags is a bit field of possible constants beginning with ASF_RANGE_FLAG_FPS_. See audio.h for details.

Request

NameType
sample_format_flags uint32
min_frame_rate uint32
max_frame_rate uint32
min_channels uint8
max_channels uint8
rate_family_flags uint16

ClearFormatRanges

Remove the minimal format range that is added by default to all configurations. As with AddFormatRange(), this method must be called before calling Add(), or after Remove().

Request

NameType

SetFifoDepth

Set the virtual audio device's fifo depth, in bytes. This must be called before calling Add(), or after Remove(). Once the device is activated, the depth of its FIFO is returned by the driver in response to an AUDIO_RB_CMD_GET_FIFO_DEPTH command on the ring buffer channel.

Request

NameType
fifo_depth_bytes uint32

SetExternalDelay

Set the virtual audio device's external delay, in nanoseconds. This must be called before calling Add(), or after Remove(). Once the device is activated, this value is returned by the driver in response to an AUDIO_STREAM_CMD_SET_FORMAT command.

Request

NameType
external_delay zx/duration

SetRingBufferRestrictions

Set restrictions for the device ring buffer. This must be called before calling Add(), or after Remove(). Once the device is activated, the ring buffer and its size are returned by the driver in response to an AUDIO_RB_CMD_GET_BUFFER command on the ring buffer channel. Note: both min_frames and max_frames must be multiples of modulo_frames.

Request

NameType
min_frames uint32
max_frames uint32
modulo_frames uint32

SetGainProperties

Set gain properties for this virtual device. This must be called before calling Add(), or after Remove(). Once the device is activated, gain information is returned by the driver in an audio_stream_cmd_get_gain_resp struct, in response to an AUDIO_STREAM_CMD_GET_GAIN command. This information is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: returned in an AudioGainInfo struct by GetDeviceGain() and the ->OnDeviceGainChanged() event.

Request

NameType
min_gain_db float32
max_gain_db float32
gain_step_db float32
current_gain_db float32
can_mute bool
current_mute bool
can_agc bool
current_agc bool

SetPlugProperties

Set plug properties for this virtual device. This must be called before calling Add(), or after Remove(). Once the device is activated, plug information is returned by the driver in response to an AUDIO_STREAM_CMD_PLUG_DETECT command. This information is used by the system when determining which device is default. This in turn is exposed to clients by the fuchsia.media.AudioDeviceEnumerator protocol: in GetDevices(), GetDefaultInputDevice()/GetDefaultOutputDevice() and the ->OnDefaultDeviceChanged() event.

Request

NameType
plug_change_time zx/time
plugged bool
hardwired bool
can_notify bool

ResetConfiguration

Return a configuration to its default settings. This call has no effect on active devices. In other words, it must be called before calling Add(), or after Remove().

Request

NameType