[Versão em Português Brasileiro](COOKBOOK.pt-BR.md)
# Cookbook
> Every recipe here is a real problem followed by a command you can paste.
## Latency Note
- The first result of an invocation pays the model load, and it reports `cold_load` true.
- Every later result in the same invocation reports `cold_load` false, because the process is still alive.
- Nothing is cached between invocations, since the process dies and releases its VRAM.
- Amortise the load by passing several `--file` values to one invocation instead of spawning one process per file.
- Measure, never guess, by reading `processing_time_ms` from the envelope of each result.
- Reduce wall time on a card with spare VRAM by raising `--concurrency`, which the VRAM gate will refuse if it does not fit.
## Default Values Reference
- `model` is `large-v3`.
- `language` is `auto`.
- `device` is `0`.
- `timeout` is `0`, meaning no deadline.
- `timeout-grace` is `5` seconds, the slack a batch gets to finish its summary.
- `max-duration` is `86400` seconds.
- `beam` is `5`, accepted in the range 1 to 16.
- `vad` is `0.0`, accepted in the range 0 to 1.
- `concurrency` is `1`, accepted in the range 1 to 32.
- `helper` is empty.
- `helper-fallback` is `true`, so a hard decode is retried through the helper.
- `max-memory` is `0`, meaning no cap.
- `locale` is empty, so the operating system decides.
- `origin-base` is `https://huggingface.co/ggerganov/whisper.cpp/resolve/main`.
- `download-retries` is `2`.
- `retry-max-elapsed` is `120` seconds.
- `download-timeout` is `600` seconds.
- `download-backoff-ms` is `200`, accepted in the range 0 to 60000.
- `http-proxy` is empty, so downloads go direct.
- `hallucination-filter` is `true`.
- `hallucination-patterns` is empty, so the seeded caption patterns apply.
- `log-level` is `warn`, and `-q` and `-v` still win over it.
- `log-format` is `text`, accepting `text` or `json`.
- `log-timestamps` is `false`.
- `vad-frame-ms` is `30`, accepted in the range 10 to 100.
- `vad-rms-min` is `0.002`, accepted in the range 0 to 1.
- `vad-rms-max` is `0.1`, accepted in the range 0 to 1.
- `resample-taps` is `31`, odd, accepted in the range 3 to 511.
- `io-chunk-bytes` is `65536`, accepted in the range 4096 to 16777216.
- `probe-poll-ms` is `25`, accepted in the range 1 to 1000.
- `helper-args` is empty.
- `nvidia-smi-path` is empty, so `PATH` is searched.
- `audio-extensions` is `ogg,mp3,wav,flac`.
- `video-extensions` is `mp4,mov,m4v,mkv,webm,avi`.
- `content-keys` is `text`.
## Model Reference
- `tiny` is roughly 75 MB on disk and budgeted at 400 MiB of VRAM.
- `base` is roughly 142 MB on disk and budgeted at 600 MiB of VRAM.
- `small` is roughly 466 MB on disk and budgeted at 1200 MiB of VRAM.
- `medium` is roughly 1.5 GB on disk and budgeted at 2500 MiB of VRAM.
- `large-v3` is roughly 3.1 GB on disk and budgeted at 3500 MiB of VRAM.
## How To Check Whether This Machine Can Transcribe At All
- You inherited a host and you do not know whether it has a usable card.
```bash
whisper-nvidia-cli doctor
```
## How To Read Only the Failing Checks
- The doctor envelope is long and you only care about what is broken.
```bash
whisper-nvidia-cli doctor --select name,detail --filter ok=false
```
## How To Learn Which Model Fits This Card
- You want the largest model the free VRAM can host, without guessing.
```bash
whisper-nvidia-cli doctor --select name,detail --filter name=suggested_model
```
- The same value is also a top-level `suggested_model` field of the plain `doctor` envelope.
## How To Download the Model Before Any Real Work
- You want the network cost paid up front, not in the middle of a batch.
```bash
whisper-nvidia-cli models download small
```
## How To Transcribe One File
- You have one recording and you want its text.
```bash
whisper-nvidia-cli transcribe interview.wav
```
## How To Get Only the Transcript Text
- The surrounding envelope is noise for this particular step.
```bash
whisper-nvidia-cli transcribe interview.wav --select text
```
## How To Write the Transcript Straight to a .txt File
- `--output` writes the plain text to the path you name, and leaves the JSON on stdout untouched, so a pipeline reading stdout keeps working while a human gets a file.
```bash
whisper-nvidia-cli transcribe interview.wav --output interview.txt
```
- Combine it with `--select text` when the file is all you want and the envelope is noise.
- Over a batch the flag names ONE file, so the transcripts of every input arrive in it in the order the batch ran.
## How To Transcribe From a Pipe
- The audio never touches the filesystem and arrives as bytes.
```bash
## How To Transcribe a Headerless Stream
- The bytes carry no container header the decoder can sniff.
```bash
## How To Transcribe a Whole Batch in One Process
- You have many files and you refuse to pay the model load for each one.
```bash
whisper-nvidia-cli transcribe --file a.wav --file b.wav --file c.wav
```
## How To Force NDJSON For a Single File
- Your consumer parses one JSON object per line and does not want a special case.
```bash
whisper-nvidia-cli transcribe a.wav --ndjson
```
## How To Reconcile a Batch That Partly Failed
- You need to know how many targets succeeded without counting lines yourself.
```bash
whisper-nvidia-cli transcribe --file a.wav --file broken.bin --select file,text
```
- Read the final object, which carries `summary`, `ok`, `failed`, and `total`.
## How To Speed Up a Batch on a Roomy Card
- You have free VRAM and a queue of files waiting.
```bash
whisper-nvidia-cli transcribe --file a.wav --file b.wav --file c.wav --file d.wav --concurrency 4
```
## How To Force the Speech Language
- Auto-detection keeps picking the wrong language on short clips.
```bash
whisper-nvidia-cli transcribe aula.wav --language pt
```
## How To Learn Where the Language Came From
- You want to know whether the code was forced or detected.
```bash
whisper-nvidia-cli transcribe aula.wav --select language,language_source
```
## How To Get Timestamped Segments
- You are building subtitles and need start and end times.
```bash
whisper-nvidia-cli transcribe lecture.wav --timestamps
```
## How To Trade Accuracy for Speed
- The transcript only needs to be searchable, not publishable.
```bash
whisper-nvidia-cli transcribe long.wav --model tiny --beam 1
```
## How To Keep Silence From Being Transcribed
- The recording has long silent stretches you do not want the model to hallucinate over.
```bash
whisper-nvidia-cli transcribe meeting.wav --vad 0.7
```
- Read `vad_chunks`, and know that `0` means no chunk was found so the whole file was used.
## How To Validate a Plan Without Touching the GPU
- You want to know the command is well formed before you commit to a long run.
```bash
whisper-nvidia-cli transcribe long.wav --dry-run --model medium --beam 8 --concurrency 2
```
## How To Bound a Run That Might Never End
- A corrupt file has hung your pipeline before.
```bash
whisper-nvidia-cli transcribe suspect.wav --timeout 300
```
- Expect exit code 124 when the deadline is reached.
## How To Refuse a Model That Is Too Big
- A machine with a small card must never pull a large model file.
```bash
whisper-nvidia-cli transcribe talk.wav --max-memory 600000000
```
- Expect exit code 70 when the chosen model file exceeds the cap.
## How To Pick a Specific GPU
- The host has several cards and only one is yours to use.
```bash
whisper-nvidia-cli transcribe talk.wav --device 1
```
- Expect exit code 78 for an index the host does not have.
## How To Persist a Card Choice
- You are tired of repeating `--device` on every call.
```bash
whisper-nvidia-cli config set device 1
```
## How To Transcribe a Video
- The source is a recording of a call and there is no separate audio track.
```bash
whisper-nvidia-cli config set helper /usr/bin/ffmpeg
whisper-nvidia-cli transcribe standup.mp4
```
- Expect exit code 69 for a video target when the helper is not configured.
## How To Rescue an Audio File the Decoder Rejects
- The container is nominally supported but the file is malformed.
```bash
whisper-nvidia-cli config set helper /usr/bin/ffmpeg
whisper-nvidia-cli config set helper-fallback true
whisper-nvidia-cli transcribe stubborn.mp3
```
## How To Measure a File Without Loading a Model
- You want duration and format on a host that has no GPU at all.
```bash
whisper-nvidia-cli inspect recording.mp4
```
## How To Filter a Directory Down to Long Recordings
- You only want to spend GPU time on files above a threshold.
```bash
## How To List Only the Models You Already Have
- The catalog has five rows and you care about the cached ones.
```bash
whisper-nvidia-cli models list --select name,size_bytes --filter present=true
```
## How To Detect a Corrupted Model File
- A download was interrupted and you suspect the cached file.
```bash
whisper-nvidia-cli models verify small
```
- Expect exit code 78 on a digest mismatch, and download again after deleting.
## How To Find Where a Model Lives on Disk
- Another tool needs the absolute path of the weights.
```bash
whisper-nvidia-cli models path small
```
## How To Reclaim Disk
- The large model is cached and you no longer need it.
```bash
whisper-nvidia-cli models remove large-v3 --yes
```
- Expect exit code 78 when `--yes` is omitted, because removal is never implicit.
## How To Count the Catalog Without Reading It
- You only need a number for a report.
```bash
whisper-nvidia-cli models list --count-only
```
## How To Sort the Catalog by Size
- You want to see the models ordered from smallest to largest.
```bash
whisper-nvidia-cli models list --select name,size_bytes --sort size_bytes
```
## How To Cap the Bytes You Emit
- Your consumer has a hard payload limit and drops anything larger.
```bash
whisper-nvidia-cli models list --max-output-bytes 512
```
## How To Shorten a Long Transcript for a Model Context
- The full text will not fit and a preview is enough.
```bash
whisper-nvidia-cli transcribe podcast.wav --truncate-content 800
```
- Read `content_truncated` to know that a cut happened.
## How To Cap How Many Rows a Batch Emits
- A long batch floods a context window, and only the first rows are being read anyway.
```bash
whisper-nvidia-cli transcribe recordings/ --limit 20
```
- `--limit` trims the emitted array rows, and leaves the summary line intact.
## How To Drop Repeated Rows From a Batch
- The same audio reached the batch twice under two names, and the duplicate is noise.
```bash
whisper-nvidia-cli transcribe recordings/ --dedupe-by text
```
- `--dedupe-by` keeps the first row for each key and drops every later row with the same value.
## How To List the Contracts Without Leaving transcribe
- The caller wants the contract names in the same invocation, without a second process.
```bash
whisper-nvidia-cli transcribe interview.wav --print-schema
```
- `--print-schema` lists every published JSON contract by name, which is the same set the `schema` verb serves.
## How To See What the Run Is Doing on Stderr
- A run is slow and stdout stays deliberately silent until it is done.
```bash
whisper-nvidia-cli transcribe interview.wav -vv
```
- `--verbose` raises stderr verbosity and repeats, and it NEVER changes stdout, which stays contract-shaped.
## How To Inherit an Orchestrator's Active Target
- A supervisor already decided which file this one-shot run is about.
```bash
whisper-nvidia-cli transcribe --use-active
```
- `--use-active` is opt-in and inherits the active-target marker, which no verb here ever writes: the marker belongs to whatever orchestrates these runs.
## How To Work Entirely Offline
- The machine has no network and must never attempt one.
```bash
whisper-nvidia-cli --offline transcribe talk.wav
```
- Expect exit code 78 when the model is absent and the download is forbidden.
## How To Point the Catalog at an Internal Mirror
- Your network blocks the public origin and you host the weights yourself.
```bash
whisper-nvidia-cli config set origin-base https://mirror.internal/whisper
```
- Expect exit code 78 for any origin that does not start with `https://`.
## How To Make Downloads More Patient
- The link is slow and the default retry window gives up too soon.
```bash
whisper-nvidia-cli config set download-retries 5
whisper-nvidia-cli config set retry-max-elapsed 600
whisper-nvidia-cli config set download-timeout 1800
```
## How To Isolate a Test Run From Your Real Cache
- A test must never write into the directories your daily work depends on.
```bash
whisper-nvidia-cli --config-dir /tmp/wcfg --cache-dir /tmp/wcache config list
```
## How To Audit Every Persisted Knob
- Someone changed a setting and you need to see the effective values.
```bash
whisper-nvidia-cli config list --select key,value
```
## How To Undo One Setting
- A knob was set experimentally and must return to the compiled seed.
```bash
whisper-nvidia-cli config unset beam
```
## How To Find the Configuration File
- You want to back it up or inspect it by hand.
```bash
whisper-nvidia-cli config path
```
## How To Switch the Interface Language
- The operator reads Portuguese and the stderr prose should follow.
```bash
whisper-nvidia-cli locale set pt-BR
```
- Know that JSON keys stay English no matter which locale is active.
## How To Read the Locale Actually in Effect
- The persisted locale, the operating system and `--lang` can each decide it, and only one wins.
```bash
whisper-nvidia-cli locale show
```
- Read `locale` from the envelope rather than inferring it from the prose you happen to see.
## How To Go Back to Automatic Language Detection
- A locale was pinned for one job and should not outlive it.
```bash
whisper-nvidia-cli locale clear
```
- Know that clearing removes the persisted value, so detection decides again on the next run.
## How To Read One Setting Without Listing Them All
- A script needs a single value and `config list` would make it search the envelope for it.
```bash
whisper-nvidia-cli config get model
```
- Expect exit code 78 for a key that is not one of the thirty-five writable names.
## How To Pin the Contract Version Your Integration Expects
- An integration should refuse to parse an envelope shaped by a contract it was not written against.
```bash
whisper-nvidia-cli version --select contract,engine
```
- Compare `contract` against the version you built for, and read `engine` to learn which backend was compiled in.
## How To Silence Everything Except the Contract
- The pipeline is headless and stderr is pure noise there.
```bash
whisper-nvidia-cli --quiet transcribe talk.wav
```
## How To Fail Fast When No Human Is Present
- A missing pipe must not block a scheduled job forever.
```bash
whisper-nvidia-cli --no-input transcribe --stdin
```
- Expect exit code 64 instead of a blocked process.
## How To Discover the Surface From Inside a Script
- Your integration must adapt instead of hardcoding a verb list.
```bash
whisper-nvidia-cli commands
whisper-nvidia-cli schema --name transcribe
```
## How To Install Shell Completions
- You use the CLI by hand and want tab completion.
```bash
whisper-nvidia-cli completions bash > ~/.local/share/bash-completion/completions/whisper-nvidia-cli
```
## How To Report Third-Party Attribution
- A compliance review asks what the binary bundles.
```bash
whisper-nvidia-cli licenses
```
## How To Tie a Run to Your Own Trace
- An incident review needs to match a log line to one invocation.
```bash
whisper-nvidia-cli transcribe talk.wav --select correlation_id,file,model
```
## See Also
- [HOW_TO_USE.md](HOW_TO_USE.md) for the guided walkthrough.
- [AGENTS.md](AGENTS.md) for the machine contract.
- [CROSS_PLATFORM.md](CROSS_PLATFORM.md) for the platform matrix.
- [TESTING.md](TESTING.md) for the test suite.