PROTOCOLS
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.
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
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
SetClockDomain
Request
| Name | Type |
|---|
clock_domain |
int32
|
SetClockProperties
Set properties for this virtual device's clock. These include the clock
domain and the initial rate difference (in ppm) between its clock and
the local monotonic clock. The clock domain is an int32 provided by the
clock tree to an audio driver; special values for CLOCK_DOMAIN_MONOTONIC
[0], and CLOCK_DOMAIN_EXTERNAL [-1] (not locally controllable) are
defined in fuchsia.hardware.audio/stream.fidl. Other than -1, any
negative value for clock_domain is invalid and will be ignored. A
non-zero value for 'initial_rate_adjustment_ppm' is only valid (and will
only be accepted) if the clock_domain is NOT equal to 0. This method
must be called before calling Add(), or after Remove(). Once the
device is activated, the clock_domain value is returned by the driver in
response to an AUDIO_STREAM_CMD_GET_CLOCK_DOMAIN command, and the
clock rate is expressed in the timing, and values, of position
notifications. Neither clock domain nor position notifications are
directly exposed to clients by public APIs, but these are both used in
AudioCore's device (or more accurately, domain) clock recovery.
Request
| Name | Type |
|---|
clock_domain |
int32
|
initial_rate_adjustment_ppm |
int32
|
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
|
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
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
|
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
|
SetManufacturer
Set the virtual audio device's manufacturer name. Must be called before
Add() or after Remove(). After device activation, the driver returns
this value in response to an AUDIO_STREAM_CMD_GET_STRING command of ID
AUDIO_STREAM_STR_ID_MANUFACTURER. This is exposed to clients via the
fuchsia.media.AudioDeviceEnumerator protocol, in an AudioDeviceInfo
struct returned from GetDevices() and the ->OnDeviceAdded() event.
Request
| Name | Type |
|---|
manufacturer_name |
string[256]
|
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
|
SetProduct
Set the virtual audio device's product name. This must be called before
Add() or after Remove(). After device activation, the driver returns
this value in response to an AUDIO_STREAM_CMD_GET_STRING command of ID
AUDIO_STREAM_STR_ID_PRODUCT. This name is exposed to clients via the
fuchsia.media.AudioDeviceEnumerator protocol, in an AudioDeviceInfo
struct returned from GetDevices() and the ->OnDeviceAdded() event.
Request
| Name | Type |
|---|
product_name |
string[256]
|
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
|
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]
|
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().
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
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
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
|
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.
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
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
|
AdjustClockRate
Immediately change the virtual device's clock rate, as expressed in the
timing and content of position notifications the driver emits.
'ppm_monotonic' cannot exceed [-1000,+1000]. Each rate change in rate is
standalone; i.e. successive rate changes are not cumulative.
Request
| Name | Type |
|---|
ppm_from_monotonic |
int32
|
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
|
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
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
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
SetClockDomain
Request
| Name | Type |
|---|
clock_domain |
int32
|
SetClockProperties
Set properties for this virtual device's clock. These include the clock
domain and the initial rate difference (in ppm) between its clock and
the local monotonic clock. The clock domain is an int32 provided by the
clock tree to an audio driver; special values for CLOCK_DOMAIN_MONOTONIC
[0], and CLOCK_DOMAIN_EXTERNAL [-1] (not locally controllable) are
defined in fuchsia.hardware.audio/stream.fidl. Other than -1, any
negative value for clock_domain is invalid and will be ignored. A
non-zero value for 'initial_rate_adjustment_ppm' is only valid (and will
only be accepted) if the clock_domain is NOT equal to 0. This method
must be called before calling Add(), or after Remove(). Once the
device is activated, the clock_domain value is returned by the driver in
response to an AUDIO_STREAM_CMD_GET_CLOCK_DOMAIN command, and the
clock rate is expressed in the timing, and values, of position
notifications. Neither clock domain nor position notifications are
directly exposed to clients by public APIs, but these are both used in
AudioCore's device (or more accurately, domain) clock recovery.
Request
| Name | Type |
|---|
clock_domain |
int32
|
initial_rate_adjustment_ppm |
int32
|
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
|
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
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
|
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
|
SetManufacturer
Set the virtual audio device's manufacturer name. Must be called before
Add() or after Remove(). After device activation, the driver returns
this value in response to an AUDIO_STREAM_CMD_GET_STRING command of ID
AUDIO_STREAM_STR_ID_MANUFACTURER. This is exposed to clients via the
fuchsia.media.AudioDeviceEnumerator protocol, in an AudioDeviceInfo
struct returned from GetDevices() and the ->OnDeviceAdded() event.
Request
| Name | Type |
|---|
manufacturer_name |
string[256]
|
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
|
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
|
SetProduct
Set the virtual audio device's product name. This must be called before
Add() or after Remove(). After device activation, the driver returns
this value in response to an AUDIO_STREAM_CMD_GET_STRING command of ID
AUDIO_STREAM_STR_ID_PRODUCT. This name is exposed to clients via the
fuchsia.media.AudioDeviceEnumerator protocol, in an AudioDeviceInfo
struct returned from GetDevices() and the ->OnDeviceAdded() event.
Request
| Name | Type |
|---|
product_name |
string[256]
|
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
|
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]
|
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>
|
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.
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
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
|
Immediately change the virtual device's clock rate, as expressed in the
timing and content of position notifications the driver emits.
'ppm_monotonic' cannot exceed [-1000,+1000]. Each rate change in rate is
standalone; i.e. successive rate changes are not cumulative.
Request
| Name | Type |
|---|
ppm_from_monotonic |
int32
|
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
|
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
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
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
|
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 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
SetClockDomain
Request
| Name | Type |
|---|
clock_domain |
int32
|
Set properties for this virtual device's clock. These include the clock
domain and the initial rate difference (in ppm) between its clock and
the local monotonic clock. The clock domain is an int32 provided by the
clock tree to an audio driver; special values for CLOCK_DOMAIN_MONOTONIC
[0], and CLOCK_DOMAIN_EXTERNAL [-1] (not locally controllable) are
defined in fuchsia.hardware.audio/stream.fidl. Other than -1, any
negative value for clock_domain is invalid and will be ignored. A
non-zero value for 'initial_rate_adjustment_ppm' is only valid (and will
only be accepted) if the clock_domain is NOT equal to 0. This method
must be called before calling Add(), or after Remove(). Once the
device is activated, the clock_domain value is returned by the driver in
response to an AUDIO_STREAM_CMD_GET_CLOCK_DOMAIN command, and the
clock rate is expressed in the timing, and values, of position
notifications. Neither clock domain nor position notifications are
directly exposed to clients by public APIs, but these are both used in
AudioCore's device (or more accurately, domain) clock recovery.
Request
| Name | Type |
|---|
clock_domain |
int32
|
initial_rate_adjustment_ppm |
int32
|
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
|
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
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
|
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
|
Set the virtual audio device's manufacturer name. Must be called before
Add() or after Remove(). After device activation, the driver returns
this value in response to an AUDIO_STREAM_CMD_GET_STRING command of ID
AUDIO_STREAM_STR_ID_MANUFACTURER. This is exposed to clients via the
fuchsia.media.AudioDeviceEnumerator protocol, in an AudioDeviceInfo
struct returned from GetDevices() and the ->OnDeviceAdded() event.
Request
| Name | Type |
|---|
manufacturer_name |
string[256]
|
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
|
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
|
Set the virtual audio device's product name. This must be called before
Add() or after Remove(). After device activation, the driver returns
this value in response to an AUDIO_STREAM_CMD_GET_STRING command of ID
AUDIO_STREAM_STR_ID_PRODUCT. This name is exposed to clients via the
fuchsia.media.AudioDeviceEnumerator protocol, in an AudioDeviceInfo
struct returned from GetDevices() and the ->OnDeviceAdded() event.
Request
| Name | Type |
|---|
product_name |
string[256]
|
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
|
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]
|
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.
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
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
|
AdjustClockRate
Immediately change the virtual device's clock rate, as expressed in the
timing and content of position notifications the driver emits.
'ppm_monotonic' cannot exceed [-1000,+1000]. Each rate change in rate is
standalone; i.e. successive rate changes are not cumulative.
Request
| Name | Type |
|---|
ppm_from_monotonic |
int32
|
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
|
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
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
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
SetClockDomain
Request
| Name | Type |
|---|
clock_domain |
int32
|
SetClockProperties
Set properties for this virtual device's clock. These include the clock
domain and the initial rate difference (in ppm) between its clock and
the local monotonic clock. The clock domain is an int32 provided by the
clock tree to an audio driver; special values for CLOCK_DOMAIN_MONOTONIC
[0], and CLOCK_DOMAIN_EXTERNAL [-1] (not locally controllable) are
defined in fuchsia.hardware.audio/stream.fidl. Other than -1, any
negative value for clock_domain is invalid and will be ignored. A
non-zero value for 'initial_rate_adjustment_ppm' is only valid (and will
only be accepted) if the clock_domain is NOT equal to 0. This method
must be called before calling Add(), or after Remove(). Once the
device is activated, the clock_domain value is returned by the driver in
response to an AUDIO_STREAM_CMD_GET_CLOCK_DOMAIN command, and the
clock rate is expressed in the timing, and values, of position
notifications. Neither clock domain nor position notifications are
directly exposed to clients by public APIs, but these are both used in
AudioCore's device (or more accurately, domain) clock recovery.
Request
| Name | Type |
|---|
clock_domain |
int32
|
initial_rate_adjustment_ppm |
int32
|
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
|
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
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
|
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
|
SetManufacturer
Set the virtual audio device's manufacturer name. Must be called before
Add() or after Remove(). After device activation, the driver returns
this value in response to an AUDIO_STREAM_CMD_GET_STRING command of ID
AUDIO_STREAM_STR_ID_MANUFACTURER. This is exposed to clients via the
fuchsia.media.AudioDeviceEnumerator protocol, in an AudioDeviceInfo
struct returned from GetDevices() and the ->OnDeviceAdded() event.
Request
| Name | Type |
|---|
manufacturer_name |
string[256]
|
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
|
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
|
SetProduct
Set the virtual audio device's product name. This must be called before
Add() or after Remove(). After device activation, the driver returns
this value in response to an AUDIO_STREAM_CMD_GET_STRING command of ID
AUDIO_STREAM_STR_ID_PRODUCT. This name is exposed to clients via the
fuchsia.media.AudioDeviceEnumerator protocol, in an AudioDeviceInfo
struct returned from GetDevices() and the ->OnDeviceAdded() event.
Request
| Name | Type |
|---|
product_name |
string[256]
|
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
|
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]
|
STRUCTS
CONSTANTS
