CLI API Reference

Complete reference for decibri-cli. For installation and a quick start, see Getting Started. For the underlying library, see the Node.js and Browser docs.

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

Related