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
Request
| Name | Type |
|---|
input |
request<Input>
|
SendOutput
Request
| Name | Type |
|---|
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
Response
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
Response
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
Response
| Name | Type |
|---|
num_input_devices |
uint32
|
num_output_devices |
uint32
|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
unique_id |
uint8[16]
|
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
| Name | Type |
|---|
sample_format_flags |
uint32
|
min_frame_rate |
uint32
|
max_frame_rate |
uint32
|
min_channels |
uint8
|
max_channels |
uint8
|
rate_family_flags |
uint16
|
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
SetClockDomain
Set the virtual audio device's clock domain, an int32 provided by the
clock tree, with special values 0 for the MONOTONIC clock domain and
-1 for EXTERNAL domains that are not controllable locally. This method
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_CLOCK_DOMAIN command. This is not exposed
to clients by public APIs but is used in AudioCore's clock recovery for
this device (or more accurately, for this domain).
Request
| Name | Type |
|---|
clock_domain |
int32
|
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
| Name | Type |
|---|
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
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
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
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
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
Response
| Name | Type |
|---|
frames_per_second |
uint32
|
sample_format |
uint32
|
num_channels |
uint32
|
external_delay |
zx/duration
|
Notify all subscribed listeners when the above format is set or changed.
Response
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
current_mute |
bool
|
current_agc |
bool
|
current_gain_db |
float32
|
OnSetGain
Notify all subscribed listeners when the above gain is set or changed.
Response
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
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
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
unique_id |
uint8[16]
|
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
| Name | Type |
|---|
sample_format_flags |
uint32
|
min_frame_rate |
uint32
|
max_frame_rate |
uint32
|
min_channels |
uint8
|
max_channels |
uint8
|
rate_family_flags |
uint16
|
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
SetClockDomain
Set the virtual audio device's clock domain, an int32 provided by the
clock tree, with special values 0 for the MONOTONIC clock domain and
-1 for EXTERNAL domains that are not controllable locally. This method
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_CLOCK_DOMAIN command. This is not exposed
to clients by public APIs but is used in AudioCore's clock recovery for
this device (or more accurately, for this domain).
Request
| Name | Type |
|---|
clock_domain |
int32
|
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
| Name | Type |
|---|
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
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
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
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
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
Response
| Name | Type |
|---|
frames_per_second |
uint32
|
sample_format |
uint32
|
num_channels |
uint32
|
external_delay |
zx/duration
|
Notify all subscribed listeners when the above format is set or changed.
Response
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
current_mute |
bool
|
current_agc |
bool
|
current_gain_db |
float32
|
OnSetGain
Notify all subscribed listeners when the above gain is set or changed.
Response
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
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
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
unique_id |
uint8[16]
|
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
| Name | Type |
|---|
sample_format_flags |
uint32
|
min_frame_rate |
uint32
|
max_frame_rate |
uint32
|
min_channels |
uint8
|
max_channels |
uint8
|
rate_family_flags |
uint16
|
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
SetClockDomain
Set the virtual audio device's clock domain, an int32 provided by the
clock tree, with special values 0 for the MONOTONIC clock domain and
-1 for EXTERNAL domains that are not controllable locally. This method
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_CLOCK_DOMAIN command. This is not exposed
to clients by public APIs but is used in AudioCore's clock recovery for
this device (or more accurately, for this domain).
Request
| Name | Type |
|---|
clock_domain |
int32
|
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
| Name | Type |
|---|
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
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
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
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
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
Response
| Name | Type |
|---|
frames_per_second |
uint32
|
sample_format |
uint32
|
num_channels |
uint32
|
external_delay |
zx/duration
|
Notify all subscribed listeners when the above format is set or changed.
Response
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
current_mute |
bool
|
current_agc |
bool
|
current_gain_db |
float32
|
OnSetGain
Notify all subscribed listeners when the above gain is set or changed.
Response
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
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
| Name | Type |
|---|
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
Response
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
unique_id |
uint8[16]
|
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
| Name | Type |
|---|
sample_format_flags |
uint32
|
min_frame_rate |
uint32
|
max_frame_rate |
uint32
|
min_channels |
uint8
|
max_channels |
uint8
|
rate_family_flags |
uint16
|
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
SetClockDomain
Set the virtual audio device's clock domain, an int32 provided by the
clock tree, with special values 0 for the MONOTONIC clock domain and
-1 for EXTERNAL domains that are not controllable locally. This method
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_CLOCK_DOMAIN command. This is not exposed
to clients by public APIs but is used in AudioCore's clock recovery for
this device (or more accurately, for this domain).
Request
| Name | Type |
|---|
clock_domain |
int32
|
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
| Name | Type |
|---|
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
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
STRUCTS
