CLI API

decibri-cli is a cross-platform command-line tool for audio capture, playback, and device enumeration. Single statically-linked binary, no runtime dependencies to install on Windows and macOS, built on the same Rust audio backend as the decibri Python and Node.js packages (the browser package shares the same API through a JavaScript implementation). This page covers installation and first commands, then the full command-line reference.

Quickstart

Install

decibri-cli is a single binary. Pick the method that suits your platform.

brew tap decibri/decibri
brew install decibri-cli

brew tap decibri/decibri
brew install decibri-cli

# Only if Scoop is not already installed
irm get.scoop.sh | iex

scoop bucket add decibri https://github.com/decibri/scoop-decibri
scoop install decibri-cli

Homebrew covers macOS on Intel and Apple Silicon, and Linux on x86_64 and arm64. The formula downloads the pre-built release archive and installs the decibri binary, so nothing is compiled.

Scoop is Windows, 64-bit only. The first command installs Scoop itself, once, in PowerShell, and needs no administrator rights.

Any platform

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.

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 <version>
decibri <version>
Audio backend: WASAPI
Platform: x86_64-pc-windows-msvc
Rust: <rust-version>

For machine-readable output, add --json:

decibri version --json

{
  "decibri_cli": "<version>",
  "decibri": "<version>",
  "audio_backend": "WASAPI",
  "target": "x86_64-pc-windows-msvc",
  "rust_version": "<rust-version>"
}

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. 24-bit and float output formats are not supported.

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 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 <version>
decibri <version>
Audio backend: WASAPI
Platform: x86_64-pc-windows-msvc
Rust: <rust-version>

JSON output (stable schema)

{
  "decibri_cli": "<version>",
  "decibri": "<version>",
  "audio_backend": "WASAPI",
  "target": "x86_64-pc-windows-msvc",
  "rust_version": "<rust-version>"
}

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

{
  "input_devices": [
    { "index": 0, "name": "MacBook Pro Microphone", "kind": "input", "default": true, "channels": 1, "sample_rate": 48000 },
    { "index": 1, "name": "Blue Yeti",              "kind": "input", "default": false, "channels": 2, "sample_rate": 48000 }
  ],
  "output_devices": [
    { "index": 0, "name": "MacBook Pro Speakers",   "kind": "output", "default": true, "channels": 2, "sample_rate": 48000 }
  ]
}

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.
• 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

{
  "file": "speech.wav",
  "duration_seconds": 30.0,
  "sample_rate": 16000,
  "channels": 1,
  "samples": 480000,
  "bytes": 960000,
  "device": "MacBook Pro Microphone",
  "dropped_chunks": 0
}

If the recording was stopped by Ctrl+C, the truncated WAV is finalised normally and the JSON summary is emitted with duration_seconds reflecting the actual recorded length. If a watchdog trip or IO error occurs mid-capture, the partial WAV is preserved on disk but the CLI exits with code 4 and emits no JSON summary, so the JSON output is success-only.

decibri play

Plays a WAV file through an output device.

Usage

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

Flags

Supported formats

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 without a major version bump.

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

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: libasound error

Which ALSA package you need depends on how you installed decibri-cli. A pre-built binary (Homebrew, npm, or direct download) needs the ALSA runtime library:

sudo apt install libasound2        # Debian / Ubuntu
sudo dnf install alsa-lib          # Fedora
sudo pacman -S alsa-lib            # Arch

Building from source with cargo install needs the ALSA development headers instead:

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

"Unsupported WAV format" on decibri play

Only 16-bit PCM integer and 32-bit float WAV are supported. Convert the file to 16-bit PCM WAV (16 kHz mono is the common target for speech pipelines), then play the converted file.