CLI API

decibri-cli is a cross-platform command-line tool for audio capture, playback, and device enumeration. Single statically-linked binary, zero runtime dependencies, built on the same Rust audio backend as the decibri Node.js and browser packages. This page covers installation and first commands, then the full command-line reference.

Quickstart

Install

Three ways to install. Pick whichever fits your workflow best.

npm (recommended)

Downloads the platform-specific binary from GitHub Releases, verifies its SHA256, and adds it to your PATH. No Node.js runtime is required after installation, because npm is used only as a delivery channel.

Cargo

Builds from source. Requires Rust stable. On Linux, you'll also need the ALSA development headers: sudo apt install libasound2-dev on Debian/Ubuntu, or sudo dnf install alsa-lib-devel on Fedora.

Direct download

Pre-built archives for every supported platform are available on the releases page, along with SHA256SUMS and SLSA provenance attestations for supply-chain verification.

Your first commands

Check the version

decibri version

Prints the CLI version, the decibri library version it was built against, the audio backend for your platform, the Rust target triple, and the Rust compiler version:

decibri-cli 0.1.0
decibri 3.0.0
Audio backend: WASAPI
Platform: x86_64-pc-windows-msvc
Rust: 1.82.0

For machine-readable output, add --json:

decibri version --json

{
  "decibri_cli": "0.1.0",
  "decibri": "3.0.0",
  "audio_backend": "WASAPI",
  "target": "x86_64-pc-windows-msvc",
  "rust_version": "1.82.0"
}

List audio devices

decibri devices

Prints a human-readable table of all input and output devices on the system. Use --input or --output to filter, and --json for machine-readable output.

decibri devices --input
decibri devices --output
decibri devices --input --json

Record a WAV file

decibri capture -o recording.wav -d 10

Records 10 seconds of audio from your default input device to recording.wav. The default format is 16-bit PCM at 16 kHz mono, which is the format expected by most speech recognition engines. Press Ctrl+C at any time to stop early; decibri-cli writes a valid (truncated) WAV file, never a corrupted one.

Play a WAV file

decibri play recording.wav

Plays the file through your default output device. Supports 16-bit PCM integer and 32-bit float WAV inputs. Other WAV formats (24-bit, 8-bit, non-PCM codecs) produce a clear error rather than garbled output. Ctrl+C stops playback cleanly with exit code 0.

Common workflows

Record from a specific microphone

decibri devices --input
decibri capture -o out.wav -d 10 --device "Blue Yeti"

--device accepts either a case-insensitive name substring or a numeric device index from the devices listing. Name substrings are usually the more stable choice across runs.

Higher-quality stereo recording

decibri capture -o song.wav -d 60 -r 44100 -c 2

CD-quality 44.1 kHz stereo, 60 seconds. The encoding remains 16-bit PCM WAV, since v0.1.0 does not output 24-bit or float formats.

Round-trip check

decibri capture -o test.wav -d 5 && decibri play test.wav

Useful for verifying that input and output devices both work end-to-end. A simple audio loopback test for CI or new machine setup.

CI-friendly recording

decibri capture -o /tmp/ci-test.wav -d 2 --quiet --json

--quiet suppresses progress bars and status messages. Combined with --json, this is the pattern for shell scripts and CI pipelines. Exit code 0 on success, with a JSON summary on stdout describing the output file.

See Exit codes and Platform support in the API reference below.

API reference

Overview

decibri-cli exposes four subcommands: version, devices, capture, and play. All commands support --json for machine-readable output and --quiet to suppress progress indicators. Exit codes are stable across the 0.x series and documented below.

Global flags

decibri version

Displays version information and build metadata for decibri-cli and its underlying library.

Usage

decibri version [--json]

Human output

decibri-cli 0.1.0
decibri 3.0.0
Audio backend: WASAPI
Platform: x86_64-pc-windows-msvc
Rust: 1.82.0

JSON output (stable schema)

{
  "decibri_cli": "0.1.0",
  "decibri": "3.0.0",
  "audio_backend": "WASAPI",
  "target": "x86_64-pc-windows-msvc",
  "rust_version": "1.82.0"
}

decibri devices

Lists audio input and output devices available on the system.

Usage

decibri devices [--input] [--output] [--json]

Flags

Default behavior (no --input/--output flag) lists both inputs and outputs.

Human output

INPUT DEVICES
  #  Name                     Channels  Sample rate  Default
  0  MacBook Pro Microphone      1        48000        yes
  1  Blue Yeti                   2        48000

OUTPUT DEVICES
  #  Name                     Channels  Sample rate  Default
  0  MacBook Pro Speakers        2        48000        yes
  1  External Headphones         2        48000

JSON output

{
  "inputs": [
    { "index": 0, "name": "MacBook Pro Microphone", "channels": 1, "sample_rate": 48000, "is_default": true },
    { "index": 1, "name": "Blue Yeti",               "channels": 2, "sample_rate": 48000, "is_default": false }
  ],
  "outputs": [
    { "index": 0, "name": "MacBook Pro Speakers",    "channels": 2, "sample_rate": 48000, "is_default": true }
  ]
}

decibri capture

Records audio from an input device to a 16-bit PCM WAV file.

Usage

decibri capture -o <FILE> [-d <DURATION>] [-r <RATE>] [-c <CHANNELS>] [--device <NAME_OR_INDEX>] [--json] [--quiet]

Flags

Behavior

• Always writes 16-bit signed integer PCM WAV. Other sample formats are not supported in v0.1.0.
• Ctrl+C (SIGINT) produces a valid truncated WAV file. The header is rewritten with the actual sample count before exit, so files are never left in a corrupt state.
• Memory usage is bounded and stable during long recordings (verified at 60+ minutes).
• Watchdog protection aborts cleanly if the output disk stalls, preventing unbounded memory growth.
• If --duration is omitted, capture runs until Ctrl+C.

Examples

# ASR-ready recording (16 kHz mono, 30 seconds)
decibri capture -o speech.wav -d 30

# Stereo music recording at CD quality
decibri capture -o song.wav -d 60 -r 44100 -c 2

# Record from a specific microphone by name substring
decibri capture -o out.wav -d 10 --device "Yeti"

# Record until Ctrl+C, JSON summary on exit
decibri capture -o clip.wav --json

JSON output

{
  "command": "capture",
  "output": "speech.wav",
  "duration": 30.0,
  "sample_rate": 16000,
  "channels": 1,
  "format": "int16",
  "bytes_written": 960044,
  "device": "MacBook Pro Microphone",
  "interrupted": false
}

If the recording was stopped by Ctrl+C, "interrupted": true and duration reflects the actual recorded length.

decibri play

Plays a WAV file through an output device.

Usage

decibri play <FILE> [--device <NAME_OR_INDEX>] [--json] [--quiet]

Flags

Supported formats

Use ffmpeg or sox to convert unsupported files to 16-bit PCM WAV before playback.

Behavior

• Ctrl+C stops playback cleanly with exit code 0.
• In --json mode, an interrupted playback reports "interrupted": true.

Examples

decibri play recording.wav
decibri play recording.wav --device "External Headphones"

Exit codes

Exit codes are stable and will not change across v0.x releases.

Platform support

Troubleshooting

Device not found (exit 3)

Verify the device name with decibri devices first. The --device value is matched case-insensitively against the device name substring, or parsed as a numeric index. Name substrings are generally more stable across runs than indices, which can shift if devices are plugged in or unplugged.

Windows SmartScreen warning on first run

v0.1.x binaries are unsigned. If you installed via npm, you shouldn't see the prompt because the binary is fetched to your user directory rather than executed from an untrusted download location. Direct downloads from GitHub Releases may trigger the warning; verify the SHA256 against SHA256SUMS on the release page and run it anyway if it matches.

macOS Gatekeeper "cannot be verified" on direct download

Unquarantine the file manually:

xattr -d com.apple.quarantine /path/to/decibri

Or use npm install -g decibri-cli / cargo install decibri-cli, which avoid the issue entirely.

Linux: libasound2 error after cargo install

Install the ALSA development headers:

sudo apt install libasound2-dev    # Debian / Ubuntu
sudo dnf install alsa-lib-devel    # Fedora

"Unsupported WAV format" on decibri play

v0.1.0 only supports 16-bit PCM integer and 32-bit float WAV. Convert with ffmpeg:

ffmpeg -i input.wav -acodec pcm_s16le -ar 16000 -ac 1 output.wav
decibri play output.wav