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

<<./_access.md>>

Supported builds for commands that exercise streams

Commands that exercise audio streams such as play are only supported in diagnostic [product bundles][glossary.product-bundle] 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/