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
//! Clap surface. Side-effect verbs take a named target. No product env.

use std::path::PathBuf;

use clap::{Args, Parser, Subcommand, ValueEnum, ValueHint};

use crate::surface::Surface;

/// One-shot NVIDIA Whisper CLI for agents.
#[derive(Debug, Parser)]
#[command(
    name = "whisper-nvidia-cli",
    version,
    propagate_version = true,
    arg_required_else_help = true
)]
pub struct Cli {
    /// Verb to run
    #[command(subcommand)]
    pub command: Option<Commands>,
    /// Suppress stderr
    #[arg(short = 'q', long, global = true)]
    pub quiet: bool,
    /// Increase stderr verbosity
    #[arg(short, long, global = true, action = clap::ArgAction::Count)]
    pub verbose: u8,
    /// Refuse stdin
    #[arg(long, global = true)]
    pub no_input: bool,
    /// Refuse every network call, including model download
    #[arg(long, global = true)]
    pub offline: bool,
    /// List every published JSON contract by name
    #[arg(long, global = true)]
    pub print_schema: bool,
    /// Isolate config on this directory
    #[arg(long, global = true, value_hint = ValueHint::DirPath)]
    pub config_dir: Option<PathBuf>,
    /// Isolate model cache on this directory
    #[arg(long, global = true, value_hint = ValueHint::DirPath)]
    pub cache_dir: Option<PathBuf>,
    /// UI locale override (en or pt-BR)
    #[arg(long, global = true)]
    pub lang: Option<String>,
    /// Filter rows `key=value`, `key!=value`, `key~sub`
    #[arg(long, global = true)]
    pub filter: Vec<String>,
    /// Project keys
    #[arg(long, global = true, alias = "fields")]
    pub select: Option<String>,
    /// Limit emitted array rows
    #[arg(long, short = 'n', global = true)]
    pub limit: Option<usize>,
    /// Sort rows by key
    #[arg(long, global = true)]
    pub sort: Option<String>,
    /// Drop later rows with the same key
    #[arg(long, global = true)]
    pub dedupe_by: Option<String>,
    /// Emit only a count
    #[arg(long, global = true)]
    pub count_only: bool,
    /// Truncate long strings by character count
    #[arg(long, global = true)]
    pub truncate_content: Option<usize>,
    /// Drop trailing array rows to fit this byte cap
    #[arg(long, global = true)]
    pub max_output_bytes: Option<usize>,
    /// Deadline in seconds for the whole invocation
    ///
    /// FR-034 is named "Timeout global" and says the deadline ends the
    /// invocation, not one stage of it. The flag used to live on `transcribe`
    /// alone, so `models download` — the verb that opens a socket and is most
    /// able to hang — had no way to be bounded at all. Declaring it here puts
    /// it on every verb, which is what the requirement asked for.
    #[arg(long, global = true)]
    pub timeout: Option<u64>,
}

impl Cli {
    /// Build the reduction knobs.
    pub fn surface(&self) -> Surface {
        Surface {
            filter: self.filter.clone(),
            select: self
                .select
                .as_deref()
                .map(|s| {
                    s.split(',')
                        .map(|p| p.trim().to_string())
                        .filter(|p| !p.is_empty())
                        .collect()
                })
                .unwrap_or_default(),
            limit: self.limit,
            sort: self.sort.clone(),
            dedupe_by: self.dedupe_by.clone(),
            count_only: self.count_only,
            truncate_content: self.truncate_content,
            max_output_bytes: self.max_output_bytes,
        }
    }
}

impl Commands {
    /// The argv target this verb was aimed at, plus where it came from.
    ///
    /// The success envelopes already echo this pair, but a failure used to
    /// drop it: an agent that fired several named targets got back a bare
    /// `code` and could not tell which slot had failed. Deriving the pair
    /// here, from the parsed verb rather than from each handler, means a verb
    /// added later cannot forget to carry it.
    ///
    /// Verbs with no target — `list`, `version`, `doctor` — return `None`, and
    /// the envelope then omits both keys rather than emitting nulls.
    ///
    /// `None` also covers the cases where naming one target would be a lie:
    ///
    /// * A batch. `transcribe a.wav --file b.wav` has two targets, and a
    ///   whole-invocation failure belongs to neither in particular. Echoing the
    ///   first made `b.wav` vanish from the envelope, so a caller retried one
    ///   file and dropped the other in silence. Each NDJSON line still names
    ///   its own target, which is where per-target attribution belongs.
    /// * `--use-active`. The marker is read later, by the verb that owns the
    ///   paths; here only the flag is known. A placeholder would satisfy the
    ///   key while telling the caller nothing it can check.
    ///
    /// Omitting is the honest answer in both: absence says "no single target",
    /// where a placeholder would have said something false.
    pub fn target(&self) -> Option<(String, &'static str)> {
        let named = |t: &str| Some((t.to_string(), "argv"));
        match self {
            Self::Transcribe(args) => {
                // Arity carries no meaning for the slot itself, but a envelope
                // that names one of several targets is worse than one that
                // names none.
                let count = usize::from(args.target.is_some()) + args.files.len();
                if count > 1 {
                    return None;
                }
                if let Some(path) = args.target.as_ref().or_else(|| args.files.first()) {
                    return named(&path.display().to_string());
                }
                if args.use_active {
                    return None;
                }
                // `--stdin` is explicit, but a piped run without it reaches the
                // same reader. Both are the same slot and must answer alike;
                // otherwise an absent pair means "no target" in one case and
                // "the target is stdin" in the other.
                if args.stdin || !std::io::IsTerminal::is_terminal(&std::io::stdin()) {
                    return Some(("-".to_string(), "stdin"));
                }
                None
            }
            Self::Inspect(args) => named(&args.target.display().to_string()),
            Self::Models { action } => match action {
                ModelsAction::List => None,
                ModelsAction::Download { target }
                | ModelsAction::Path { target }
                | ModelsAction::Remove { target, .. }
                | ModelsAction::Verify { target } => named(target),
            },
            Self::Config { action } => match action {
                ConfigAction::Path | ConfigAction::List => None,
                ConfigAction::Get { target }
                | ConfigAction::Set { target, .. }
                | ConfigAction::Unset { target } => named(target),
            },
            Self::Locale { action } => match action {
                LocaleAction::Show | LocaleAction::Clear => None,
                LocaleAction::Set { target } => named(target),
            },
            Self::Schema { name } => name.as_deref().map(|n| (n.to_string(), "argv")),
            Self::Doctor { .. }
            | Self::Commands
            | Self::Version
            | Self::Completions { .. }
            | Self::Licenses => None,
        }
    }
}

/// Top-level verbs.
#[derive(Debug, Subcommand)]
pub enum Commands {
    /// Transcribe one file, stdin, or a batch of --file values
    Transcribe(TranscribeArgs),
    /// Measure media without loading a model
    Inspect(InspectArgs),
    /// Manage cached models
    Models {
        /// Model verb to run
        #[command(subcommand)]
        action: ModelsAction,
    },
    /// Diagnose GPU, kit, helper, and suggested model
    Doctor {
        /// GPU index to diagnose
        #[arg(long)]
        device: Option<u32>,
    },
    /// Persist knobs
    Config {
        /// Config verb to run
        #[command(subcommand)]
        action: ConfigAction,
    },
    /// Emit JSON schemas
    Schema {
        /// Emit only the contract with this name
        #[arg(long)]
        name: Option<String>,
    },
    /// Emit the command tree
    Commands,
    /// Product and contract identity
    Version,
    /// Shell completions
    Completions {
        /// Shell to emit the script for
        shell: clap_complete::Shell,
    },
    /// Third-party attribution
    Licenses,
    /// UI locale
    Locale {
        /// Locale verb to run
        #[command(subcommand)]
        action: LocaleAction,
    },
}

/// Transcribe arguments. Target is named; arity does not carry meaning.
#[derive(Debug, Args)]
pub struct TranscribeArgs {
    /// Named audio or video target
    #[arg(conflicts_with_all = ["stdin", "use_active"])]
    pub target: Option<PathBuf>,
    /// Additional files (each is a named target)
    #[arg(long = "file", value_name = "PATH", value_hint = ValueHint::FilePath)]
    pub files: Vec<PathBuf>,
    /// Read audio bytes from stdin
    #[arg(long, conflicts_with_all = ["target", "use_active"])]
    pub stdin: bool,
    /// Inherit the active-target marker, which a caller writes (opt-in only)
    ///
    /// No verb here sets the marker: it belongs to whatever orchestrates these
    /// one-shot runs. The failure names the file so the caller knows where.
    #[arg(long, conflicts_with_all = ["target", "stdin"])]
    pub use_active: bool,
    /// Speech language or auto
    #[arg(long)]
    pub language: Option<String>,
    /// Catalog model name
    #[arg(long)]
    pub model: Option<String>,
    /// Beam size 1..=16
    #[arg(long)]
    pub beam: Option<i32>,
    /// Include timestamp segments
    #[arg(long)]
    pub timestamps: bool,
    /// Emit one JSON object per file plus a summary
    #[arg(long)]
    pub ndjson: bool,
    /// Speech-cut sensitivity 0..=1; 0 disables the cut entirely
    #[arg(long)]
    pub vad: Option<f32>,
    /// Parallel copies; refused when VRAM cannot fit
    #[arg(long)]
    pub concurrency: Option<usize>,
    /// Force decoder format
    #[arg(long, value_enum)]
    pub input_format: Option<InputFormat>,
    /// GPU index
    #[arg(long)]
    pub device: Option<u32>,
    /// Validate and exit
    #[arg(long)]
    pub dry_run: bool,

    /// Also write the transcript text to this file; stdout keeps the JSON
    #[arg(long, value_name = "PATH")]
    pub output: Option<PathBuf>,

    /// Process RSS cap in bytes
    #[arg(long)]
    pub max_memory: Option<u64>,
}

impl TranscribeArgs {
    /// Collect argv targets. Never reads the active marker here.
    pub fn argv_targets(&self) -> Vec<PathBuf> {
        let mut out = Vec::new();
        if let Some(t) = &self.target {
            out.push(t.clone());
        }
        out.extend(self.files.iter().cloned());
        out
    }
}

/// Inspect one media file.
#[derive(Debug, Args)]
pub struct InspectArgs {
    /// Media path
    pub target: PathBuf,
}

/// Model verbs. Mutating leaves take a target name.
#[derive(Debug, Subcommand)]
pub enum ModelsAction {
    /// List cached models
    List,
    /// Fetch a catalog model into the cache
    Download {
        /// Catalog model name
        target: String,
    },
    /// Print where a model is cached
    Path {
        /// Catalog model name
        target: String,
    },
    /// Drop a model from the cache
    Remove {
        /// Catalog model name
        target: String,
        /// Confirm the removal
        #[arg(long)]
        yes: bool,
    },
    /// Check a cached model against its checksum
    Verify {
        /// Catalog model name
        target: String,
    },
}

/// Config verbs. Writes take the key as the target.
#[derive(Debug, Subcommand)]
pub enum ConfigAction {
    /// Print where the config file lives
    Path,
    /// List every persisted key
    List,
    /// Read one persisted key
    Get {
        /// Config key name
        target: String,
    },
    /// Persist one key
    Set {
        /// Config key name
        target: String,
        /// Value to persist
        value: String,
    },
    /// Drop one persisted key
    Unset {
        /// Config key name
        target: String,
    },
}

/// Locale verbs.
#[derive(Debug, Subcommand)]
pub enum LocaleAction {
    /// Print the locale in effect
    Show,
    /// Persist the UI locale
    Set {
        /// Locale tag (en or pt-BR)
        target: String,
    },
    /// Drop the persisted locale
    Clear,
}

/// Forced input formats.
///
/// A closed enum makes `--input-format banana` an argv error (exit 2) at the
/// clap layer instead of a silently accepted string.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum InputFormat {
    /// Ogg container
    Ogg,
    /// MP3 container
    Mp3,
    /// WAV container
    Wav,
    /// FLAC container
    Flac,
}

impl InputFormat {
    /// Lowercase container name used as the decoder hint.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Ogg => "ogg",
            Self::Mp3 => "mp3",
            Self::Wav => "wav",
            Self::Flac => "flac",
        }
    }
}