# Usage
Audio processing requires an ONNX model through `--model-path` and exactly one of `--process-audio` and `--process-folder`.
## Download models and ONNX Runtime
The `download` subcommand caches revision-pinned, checksum-verified assets and prints the path to each downloaded model graph:
```bash
extract-speech download silero
extract-speech download fsmn-int8 --cache-dir ./model-cache
extract-speech download all
```
Download the compatible CPU ONNX Runtime distribution separately. The printed path can be passed directly to `--dylib-path`:
```bash
extract-speech download onnxruntime
```
Run `extract-speech download --help` for the full model-variant list. Existing valid cache files are reused. The default cache honors `EXTRACT_SPEECH_CACHE_DIR`, then uses the platform cache directory described in [Models and runtimes](models-and-runtimes.md).
## Process one file
Write one WAV file per detected speech region:
```bash
extract-speech \
--vad-model silero \
--model-path models/silero-vad-v6.onnx \
--process-audio recording.wav \
--output clips
```
The `clips` directory will contain names such as `1730135784123_0.wav`. Names contain the creation timestamp and segment index.
Write all detected regions into one output file:
```bash
extract-speech \
--vad-model silero \
--model-path models/silero-vad-v6.onnx \
--process-audio recording.wav \
--output-type concatenated \
--output speech.wav
```
With `--output-type concatenated`, `--output` is the complete destination filename for a single input.
## Process a directory
```bash
extract-speech \
--vad-model silero \
--model-path models/silero-vad-v6.onnx \
--process-folder recordings \
--output output
```
Directory processing is non-recursive and processes supported files in parallel. Recognized extensions are `wav`, `mp3`, `flac`, `ogg`, `opus`, `m4a`, and `aac`.
With the default `--output-type files`, each input gets its own output directory:
```text
output/
├── interview-1/
│ ├── 1730135784123_0.wav
│ └── 1730135784124_1.wav
└── interview-2/
└── 1730135785123_0.wav
```
With `--output-type concatenated`, `--output` remains a directory and each input produces a file named after its input stem, such as `output/interview-1.wav`.
## Output formats and sample rates
Select the format with `--output-format wav`, `opus`, or `ogg`.
- `wav` writes mono, 16-bit PCM WAV data.
- `opus` and `ogg` both write mono Opus audio in an Ogg container; the selected value determines the filename extension.
- `--sample-rate` controls the final output rate and defaults to `16000` Hz.
Input is decoded, mixed down to mono when necessary, and converted to 16 kHz for VAD. Detected samples are then converted to the requested output rate. Opus is encoded internally at 48 kHz while preserving the requested rate in its identification header.
## Tune detection
`--threshold` accepts a value from `0.0` to `1.0` and defaults to `0.7`:
- lower values detect quieter speech but may include more noise
- higher values are more selective but may miss quiet speech
For example:
```bash
extract-speech \
--vad-model silero \
--model-path models/silero-vad-v6.onnx \
--process-audio recording.wav \
--threshold 0.5 \
--output clips
```
PulseVAD, TEN VAD, and MarbleNet use a recommended starting threshold of `0.5`, so specify `--threshold 0.5` when selecting these models. See [Models and runtimes](models-and-runtimes.md) for model downloads and runtime compatibility.
## Use separate detection and source audio
`--source-audio` lets the model detect speech in one file while extracting the matching regions from another. This is useful when detection works better on a denoised copy but output should come from the original recording.
```bash
extract-speech \
--vad-model silero \
--model-path models/silero-vad-v6.onnx \
--process-audio denoised.wav \
--source-audio original.wav \
--output clips
```
Both files must have the same sample count after decoding, mono conversion, and conversion to 16 kHz. This mode is available only for single-file processing.
## Write metadata
Use `--metadata` to write a JSON summary:
```bash
extract-speech \
--vad-model silero \
--model-path models/silero-vad-v6.onnx \
--process-audio recording.wav \
--output clips \
--metadata metadata.json
```
Example:
```json
{
"intervals": [
{
"filename": "1730135784123_0.wav",
"duration": "2.500000"
}
],
"total_seconds": "2.500000",
"compute_seconds": "0.123456"
}
```
For directory processing, metadata is written once per input under the output directory. The supplied metadata stem is combined with the input stem, for example `metadata_interview-1.json`.
## Inspect a model
Model inspection does not require an audio input:
```bash
extract-speech \
--model-path model.onnx \
--print-model-info io
```
Accepted values are `graph`, `nodes`, and `io`.
## Logging
All runtime diagnostics use the `log` facade. Set `RUST_LOG` to control the CLI's
filter; model-specific details are emitted at the `debug` level. `--debug` is a
convenience shorthand that selects the `debug` filter only when `RUST_LOG` is
not set.
```bash
RUST_LOG=extract_speech=debug extract-speech \
--vad-model silero \
--model-path models/silero-vad-v6.onnx \
--process-audio recording.wav
```
## CLI reference
The processing interface remains available as top-level options. Downloads use `extract-speech download <ASSET> [--cache-dir <PATH>]`.
| `--model-path <PATH>` | ONNX model path; required for processing and inspection | — |
| `--runtime <RUNTIME>` | `candle` or `onnxruntime` | `candle` |
| `--vad-model <MODEL>` | `silero`, `pulsevad`, `pyannote`, `fsmn`, `ten`, or `marblenet` | `pulsevad` |
| `--dylib-path <PATH>` | ONNX Runtime dynamic library; required for `onnxruntime` | — |
| `--process-audio <PATH>` | Single audio file used for VAD | — |
| `--process-folder <PATH>` | Directory of audio files used for VAD | — |
| `--source-audio <PATH>` | Alternate source for extracted samples | — |
| `--output <PATH>` | Output directory or concatenated file | `output` |
| `--metadata <PATH>` | Metadata JSON path or naming template | — |
| `--output-type <TYPE>` | `files` or `concatenated` | `files` |
| `--output-format <FORMAT>` | `wav`, `opus`, or `ogg` | `wav` |
| `--threshold <NUMBER>` | Detection threshold from `0.0` through `1.0` | `0.7` |
| `--sample-rate <HZ>` | Final output sample rate | `16000` |
| `--cuda` | Prefer the CUDA execution provider | off |
| `--trt` | Prefer the TensorRT execution provider | off |
| `--coreml` | Prefer the CoreML execution provider | off |
| `--debug` | Use debug-level logging when `RUST_LOG` is unset | off |
| `--print-model-info <KIND>` | Print `graph`, `nodes`, or `io` model details | — |
Run `extract-speech --help` to view the reference generated by the installed version.