Virtual audio drivers

Virtual audio drivers provide flexibly configurable audio devices on Fuchsia systems for testing, validation, and development. They allow automated test suites and developer tools to exercise the full audio subsystem without requiring physical audio hardware.

Virtual audio devices are dynamically created, configured, and controlled at runtime via the fuchsia.virtualaudio FIDL protocols.

Architecture and driver versions

Fuchsia provides two virtual audio driver implementations in the source tree: the modern virtual-audio driver and the virtual-audio-legacy driver.

Modern virtual audio driver (virtual-audio)

The modern virtual audio driver implements the fuchsia.hardware.audio.Composite protocol in Driver Framework v2.

Key capabilities include: * Composite topologies: Exposes combinations of ring buffer endpoints, DAI interconnects, and packet stream endpoints within a single virtual device. * Signal processing: Implements the fuchsia.hardware.audio.signalprocessing APIs, allowing tests to configure custom processing topologies, gain stages, mutes, and equalizer elements. * Clock domain configuration: Supports configuring monotonic or external clock domains, as well as dynamic clock rate adjustments to test drift compensation and position notifications. * Audio Device Registry integration: Serves as the primary mock and test driver for the Audio Device Registry service.

Legacy virtual audio driver (virtual-audio-legacy)

The legacy virtual audio driver is implemented using the legacy DDK (DFv1) and provides virtual devices implementing deprecated audio protocols:

• StreamConfig: Exposes fuchsia.hardware.audio.StreamConfigConnector to create virtual audio input and output streams (/dev/class/audio-input and /dev/class/audio-output).
• DAI: Exposes fuchsia.hardware.audio.DaiConnector (/dev/class/dai), supporting multiple concurrent client connections.
• Codec: Exposes fuchsia.hardware.audio.CodecConnector (/dev/class/codec).

This driver is retained to validate legacy audio components (such as audio_core and audio-driver-ctl) and to verify backward compatibility across deprecated FIDL protocols.

Control and configuration API

Virtual audio devices are controlled via two primary FIDL protocols defined in //sdk/fidl/fuchsia.virtualaudio:

1. fuchsia.virtualaudio.Control:

   • GetDefaultConfiguration: Retrieves the default template Configuration for a given device type (Composite, StreamConfig, Dai, or Codec).
   • AddDevice: Creates and activates a virtual device instance using a specified Configuration and binds a fuchsia.virtualaudio.Device control channel.
   • Enable / Disable: Globally enables or disables virtual audio device creation on the system.

2. fuchsia.virtualaudio.Device:

   • Manages the lifecycle of an active virtual device instance.
   • Receives notifications of format changes, buffer allocations, and position updates.
   • Allows tests to dynamically simulate hardware events such as hotplugging, unplugging, or adjusting clock rates.
   • Closing the Device channel automatically shuts down and removes the corresponding virtual device from the system.

Configurable device properties

Before activating a virtual device via Control.AddDevice, clients can customize properties in the Configuration table, including:

• Device metadata: device_name, manufacturer_name, product_name, and unique_id.
• Format support: Supported sample formats (e.g. PCM linear 16/24/32-bit, float 32-bit), channel counts, and frame rate ranges.
• Buffer properties: Minimum and maximum ring buffer sizes, FIFO depth, and external delay metrics.
• Clock settings: Clock domain specification and rate adjustment parameters.
• Plug properties: Hardwired vs. removable state, initial plug state, and plug time.

Testing workflows

Driver test integration

Test suites (such as audio_driver_basic_tests and audio_driver_admin_tests) can use virtual audio drivers to run self-contained device tests without requiring physical hardware or pre-installed platform bus nodes in system images.

Tests can either: * Connect to pre-existing virtual audio controller nodes in devfs (/dev/sys/platform/virtual-audio), or * Dynamically register ephemeral virtual audio drivers with Driver Runner during test fixture setup and unregister them upon completion.

Golden enumeration considerations

Because virtual audio devices can be created dynamically by test suites running on a target, board driver host enumeration tests (such as driver-host-enumeration-test-*) specify virtual audio drivers as optional (prefixed with ?) in their golden.json definitions:

{
    "drivers": [
        "?fuchsia-pkg://fuchsia.com/virtual-audio#meta/virtual-audio-driver.cm"
    ]
}

This ensures that enumeration tests succeed both on minimal/clean boots where virtual audio is absent, and during test runs where virtual audio components are dynamically active.