audio-driver-ctl

Play, record, and configure audio streams.

Important

audio-driver-ctl is deprecated. Please use ffx audio device tool instead. For more information, run ffx audio device --help from your host machine and see README for ffx audio: //src/developer/ffx/plugins/audio/README.md

Usage

audio-driver-ctl [-d <device>] [-t {input|output}] agc {on|off}

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] [-r <hertz>] duplex <playpath> <recordpath>

audio-driver-ctl [-d <device>] [-t {input|output}] gain <decibels>

audio-driver-ctl [-d <device>] [-t {input|output}] info

audio-driver-ctl list

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] loop <playpath>

audio-driver-ctl [-d <device>] [-t {input|output}] mute

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] [-r <hertz>] noise [<seconds>] [<amplitude>]

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] play <playpath>

audio-driver-ctl [-d <device>] [-t {input|output}] pmon [<seconds>]

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] [-r <hertz>] record <recordpath> [<seconds>]

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] [-r <hertz>] tone [<frequency>] [<seconds>] [<amplitude>]

audio-driver-ctl [-d <device>] [-t {input|output}] unmute

Options

-a <mask> option

Active channel mask. For example 0xf or 15 for channels 0, 1, 2, and 3. Defaults to all channels.

-b {8|16|20|24|32} option

Bits per sample. Defaults to 16.

-c <channels> option

Number of channels to use when recording or generating tones/noises. Does not affect WAV file playback because WAV files specify how many channels to use in their headers. Defaults to the first driver-reported value. Run info to see how many channels your target Fuchsia device has. The number of channels must match what the audio driver expects because audio-driver-ctl does not do any mixing.

-d <device> option

The device path or service instance name. If unspecified, the tool picks the first device found. If it does not contain /, the tool treats it as a service instance name (for example, default -> /svc/.../default/stream_config_connector).

-t {input|output} option

The device type. Defaults to output. This option is ignored for commands like play that only make sense for one of the types.

-r <hertz> option

The frame rate in hertz. Defaults to 48000.

Commands

agc command

audio-driver-ctl [-d <device>] [-t {input|output}] agc {on|off}

Enables or disables automatic gain control for the stream.

duplex command

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] [-r <hertz>] duplex <playpath> <recordpath>

Simultaneously plays the WAV file located at <playpath> and records another WAV file into <recordpath> to analyze delays in the system. If provided, the -c option applies to the recording side, because the WAV file header determines the number of channels for playback. For duplex mode, the -d parameter must be an instance name and cannot be a full path.

gain command

audio-driver-ctl [-d <device>] [-t {input|output}] gain <decibels>

Sets the gain of the stream in decibels.

info command

audio-driver-ctl [-d <device>] [-t {input|output}] info

Gets capability and status info for a stream.

list command

audio-driver-ctl list

Lists all available input and output devices.

loop command

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] loop <playpath>

Repeatedly plays the WAV file at <playpath> on the selected output until a key is pressed.

mute command

audio-driver-ctl [-d <device>] [-t {input|output}] mute

Mutes a stream.

noise command

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] [-r <hertz>] noise [<seconds>] [<amplitude>]

Plays pseudo-white noise. <seconds> controls how long the noise plays and must be at least 0.001 seconds. If <seconds> is not provided the noise plays until a key is pressed.

play command

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] play <playpath>

Plays a WAV file.

pmon command

audio-driver-ctl [-d <device>] [-t {input|output}] pmon [<seconds>]

Monitors the plug state of a stream. <seconds> must be above 0.5 seconds (default: 10.0 seconds).

record command

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] [-r <hertz>] record <recordpath> [<seconds>]

Records to the specified WAV file from the selected input. If <seconds> is not provided the input is recorded until a key is pressed.

tone command

audio-driver-ctl [-a <mask>] [-b {8|16|20|24|32}] [-c <channels>] \
    [-d <device>] [-r <hertz>] tone [<frequency>] [<seconds>] [<amplitude>]

Plays a sinusoidal tone. <frequency> must be between 15.0 and 96000.0 hertz (default: 440.0 hertz). <seconds> must be above 0.001 seconds. If is not provided the tone plays until a key is pressed. <amplitude> scales the output if provided and must be an increment of 0.1 between 0.1 and 1.0.

unmute command

audio-driver-ctl [-d <device>] [-t {input|output}] unmute

Unmutes a stream. Note that the gain of the stream will be reset to its default value.

Examples

Enable automatic gain control on a stream

audio-driver-ctl agc on

Get stream info

This command is equivalent to audio-driver-ctl -t output -d default info:

audio-driver-ctl info

Info for audio output at "/svc/fuchsia.hardware.audio.StreamConfigConnectorOutputService/default/stream_config_connector"
  Unique ID    : 0100000000000000-0000000000000000
  Manufacturer : Spacely Sprockets
  Product      : acme
  Current Gain : 0.00 dB (unmuted, AGC on)
  Gain Caps    : gain range [-103.00, 24.00] in 0.50 dB steps; can mute; can AGC
  Plug State   : plugged
  Plug Time    : 12297829382473034410
  PD Caps      : hardwired
Number of channels      : 1
Frame rate              : 8000Hz
Bits per channel        : 16
Valid bits per channel  : 16
...

List all available input and output devices

audio-driver-ctl list

Input Devices:
  default
Output Devices:
  default

Set gain of a stream to -40 decibels

This command is equivalent to audio-driver-ctl -t output -d default gain -40:

audio-driver-ctl gain -40

Mute a stream

This command is equivalent to audio-driver-ctl -t output -d default mute:

audio-driver-ctl mute

Repeatedly play (loop) a WAV file on a stream

This command is equivalent to audio-driver-ctl -t output -d default loop /tmp/test.wav:

audio-driver-ctl loop /tmp/test.wav

Looping /tmp/test.wav until a key is pressed

Play a WAV file once on a stream

This command is equivalent to audio-driver-ctl -t output -d default play /tmp/test.wav:

audio-driver-ctl play /tmp/test.wav

Play a 450 hertz tone for 1 second at 50% amplitude on a stream

This command is equivalent to audio-driver-ctl -t output -d default tone 450 1 0.5:

audio-driver-ctl tone 450 1 0.5

Playing 450.00 Hz tone for 1.00 seconds at 0.50 amplitude

Unmute a stream

This command is equivalent to audio-driver-ctl -t output -d default unmute:

audio-driver-ctl unmute

Notes

Accessing this command

This command is only available on certain diagnostic and testing Fuchsia builds.

This is a device-side command, not a host-side command like fx or ffx. In other words before calling this command you must first access the shell of the Fuchsia device.

To interactively access the Fuchsia device's shell:

ffx component explore <component>

Replace <component> with the name of the component that has access to the command documented on this page.

To call a single command and return the output to the host:

ffx component explore <component> -c "<command>"

Replace <command> with one of the commands documented on this page.

Supported builds for commands that exercise streams

Commands that exercise audio streams such as play are only supported in diagnostic product bundles like core. In other builds only the informational commands like info are supported.

Copying WAV files between a host and a target Fuchsia device

To copy WAV files from your host to your target Fuchsia device or vice versa, run fx cp (--to-target|--to-host) <source> <destination> on your host. <source> is the file you want to copy and <destination> is where you want to put the copied file.

Example of copying from host to target Fuchsia device:

fx cp --to-target /path/on/host/source.wav /path/on/target/destination.wav

Example of copying from target Fuchsia device to host:

fx cp --to-host /path/on/target/source.wav /path/on/host/destination.wav

Both commands should be run from your host, not the target Fuchsia device.

Source code

Source code for audio-driver-ctl: //src/media/audio/tools/audio-driver-ctl/