whisper-nvidia-cli 0.1.0

One-shot agent-native local NVIDIA GPU speech-to-text CLI powered by whisper.cpp
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
[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
cat interview.ogg | whisper-nvidia-cli transcribe --stdin
```


## How To Transcribe a Headerless Stream
- The bytes carry no container header the decoder can sniff.

```bash
cat raw.pcmwav | whisper-nvidia-cli transcribe --stdin --input-format wav
```


## 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
fd -e wav . ./audio | while read -r f; do whisper-nvidia-cli inspect "$f" --select file,duration_seconds; done
```


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