A free, open source, and extensible speech-to-text application that works completely offline.
debug + perf transcribe cli (#1541)
CJ Paisbff4db7e7571
diff --git a/src-tauri/src/cli.rs b/src-tauri/src/cli.rsindex 24a8a541..122b33e9 100644--- a/src-tauri/src/cli.rs+++ b/src-tauri/src/cli.rs@@ -1,4 +1,5 @@use clap::Parser;+use std::path::PathBuf;#[derive(Parser, Debug, Clone, Default)]#[command(name = "handy", about = "Handy - Speech to Text")]@@ -26,4 +27,32 @@ pub struct CliArgs {/// Enable debug mode with verbose logging#[arg(long)]pub debug: bool,++ /// Transcribe this WAV (16 kHz mono) headlessly and exit. Runs the same+ /// batch transcription path as the app — no mic, no VAD, no download+ /// (the model must already be installed).+ #[arg(short = 'f', long, value_name = "WAV")]+ pub transcribe_file: Option<PathBuf>,++ /// Model id to load for --transcribe-file (default: the selected model).+ #[arg(long)]+ pub model: Option<String>,++ /// Hard-select the compute device for --transcribe-file by its --list-devices+ /// index (0 = CPU, 1.. = a specific GPU). Omit to use the persisted+ /// accelerator setting. whisper.cpp models only.+ #[arg(long, value_name = "N")]+ pub device_index: Option<usize>,++ /// List the selectable whisper compute devices (with indices) and exit.+ #[arg(long)]+ pub list_devices: bool,++ /// Repeat the transcription N times (best_ms reports the fastest run).+ #[arg(long, value_name = "N")]+ pub repeat: Option<usize>,++ /// Emit --transcribe-file results as JSON.+ #[arg(long)]+ pub json: bool,}diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rsindex 5f6836f1..24922240 100644--- a/src-tauri/src/lib.rs+++ b/src-tauri/src/lib.rs@@ -321,6 +321,165 @@ fn show_main_window_command(app: AppHandle) -> Result<(), String> {Ok(())}+/// Headless one-shot transcription for the `--transcribe-file` / `--list-devices`+/// path. Drives the same `TranscriptionManager::transcribe` the app uses; no+/// mic, no VAD, no download. Returns a process exit code (0 ok, 1 runtime+/// failure, 2 bad input/usage).+fn run_headless_transcription(app: &AppHandle, args: &CliArgs) -> i32 {+ use managers::model::EngineType;+ use std::time::Instant;++ // --list-devices: print the selectable whisper compute devices (index 0 is+ // CPU; 1.. are GPUs) and exit. Pass an index here to --device-index.+ if args.list_devices {+ println!("whisper compute devices:");+ for d in managers::transcription::describe_compute_devices() {+ println!(" {}", d);+ }+ if args.transcribe_file.is_none() {+ return 0;+ }+ }++ let Some(wav) = args.transcribe_file.clone() else {+ return 0;+ };++ // read_wav_samples reads 16-bit int samples and does no validation; the app+ // only ever saves 16 kHz mono 16-bit PCM, so reject anything else rather than+ // transcribe garbage / mis-time / mis-decode.+ match hound::WavReader::open(&wav) {+ Ok(reader) => {+ let spec = reader.spec();+ if spec.sample_rate != 16_000+ || spec.channels != 1+ || spec.bits_per_sample != 16+ || spec.sample_format != hound::SampleFormat::Int+ {+ eprintln!(+ "error: expected 16 kHz mono 16-bit PCM WAV, got {} Hz / {} ch / {}-bit {:?}",+ spec.sample_rate, spec.channels, spec.bits_per_sample, spec.sample_format+ );+ return 2;+ }+ }+ Err(e) => {+ eprintln!("error: cannot open {}: {}", wav.display(), e);+ return 2;+ }+ }++ let samples = match crate::audio_toolkit::read_wav_samples(&wav) {+ Ok(s) => s,+ Err(e) => {+ eprintln!("error: failed to read {}: {}", wav.display(), e);+ return 2;+ }+ };+ let audio_secs = samples.len() as f64 / 16_000.0;++ let tm = app.state::<Arc<TranscriptionManager>>();+ let mm = app.state::<Arc<ModelManager>>();++ let model_id = args+ .model+ .clone()+ .unwrap_or_else(|| get_settings(app).selected_model);+ if model_id.is_empty() {+ eprintln!("error: no model selected (pass --model or pick one in the app)");+ return 2;+ }++ // --device-index hard-selects the compute device for this load by its+ // --list-devices index (whisper.cpp models only; not persisted). Omit it to+ // use the persisted accelerator setting.+ let device_index = args.device_index;+ let requested_device = match device_index {+ Some(idx) => format!("index {}", idx),+ None => "settings".to_string(),+ };++ let is_whisper = mm+ .get_model_info(&model_id)+ .map(|i| matches!(i.engine_type, EngineType::Whisper))+ .unwrap_or(false);+ if device_index.is_some() && !is_whisper {+ eprintln!(+ "warning: --device-index applies to whisper.cpp models only; ignored for '{}'",+ model_id+ );+ }++ // Cold load (timed).+ let load_start = Instant::now();+ if let Err(e) = tm.load_model_with_device(&model_id, device_index) {+ eprintln!("error: load_model('{}') failed: {}", model_id, e);+ return 1;+ }+ let load_ms = load_start.elapsed().as_millis() as u64;+ // transcribe-rs doesn't expose the engine's bound backend post-load, so for+ // whisper report the device the load resolved to; ONNX engines report "onnx".+ let bound_backend = if is_whisper {+ managers::transcription::describe_effective_whisper_device(device_index)+ } else {+ "onnx".to_string()+ };++ let runs = args.repeat.unwrap_or(1).max(1);+ let mut times_ms: Vec<u64> = Vec::new();+ let mut text = String::new();+ for i in 0..runs {+ // If the model's unload-timeout is "Immediately", transcribe() unloads+ // the engine after each run; reload (untimed) so repeats keep working+ // and the inference timing below stays clean.+ if !tm.is_model_loaded() {+ if let Err(e) = tm.load_model_with_device(&model_id, device_index) {+ eprintln!("error: reload before run {} failed: {}", i + 1, e);+ return 1;+ }+ }+ let t = Instant::now();+ match tm.transcribe(samples.clone()) {+ Ok(out) => text = out,+ Err(e) => {+ eprintln!("error: transcribe failed: {}", e);+ return 1;+ }+ }+ times_ms.push(t.elapsed().as_millis() as u64);+ }+ let best_ms = times_ms.iter().copied().min().unwrap_or(0);+ let rtf = if best_ms > 0 {+ audio_secs / (best_ms as f64 / 1000.0)+ } else {+ 0.0+ };++ if args.json {+ println!(+ "{}",+ serde_json::json!({+ "model": model_id,+ "requested_device": requested_device,+ "bound_backend": bound_backend,+ "audio_secs": audio_secs,+ "load_ms": load_ms,+ "transcribe_ms": times_ms,+ "best_ms": best_ms,+ "rtf": rtf,+ "text": text,+ })+ );+ } else {+ println!(+ "model={} device={} backend={} audio={:.2}s load={}ms best={}ms rtf={:.2}x",+ model_id, requested_device, bound_backend, audio_secs, load_ms, best_ms, rtf,+ );+ println!("text: {}", text);+ }+ 0+}+#[cfg_attr(mobile, tauri::mobile_entry_point)]pub fn run(cli_args: CliArgs) {// Detect portable mode before anything else@@ -447,6 +606,10 @@ pub fn run(cli_args: CliArgs) {let invoke_handler = specta_builder.invoke_handler();+ // The headless path must run as its own instance (see the single-instance+ // note below), not forward to an already-running app.+ let headless_mode = cli_args.transcribe_file.is_some() || cli_args.list_devices;+#[allow(unused_mut)]let mut builder = tauri::Builder::default().device_event_filter(tauri::DeviceEventFilter::Always)@@ -458,8 +621,16 @@ pub fn run(cli_args: CliArgs) {.rotation_strategy(RotationStrategy::KeepOne).clear_targets().targets([- // Console output respects RUST_LOG environment variable- Target::new(TargetKind::Stdout).filter({+ // Console output respects RUST_LOG environment variable. In+ // headless mode (--transcribe-file/--list-devices) stdout+ // carries only the result (JSON or plain), so send console+ // logs to stderr instead to keep stdout clean for parsing.+ Target::new(if headless_mode {+ TargetKind::Stderr+ } else {+ TargetKind::Stdout+ })+ .filter({let console_filter = console_filter.clone();move |metadata| console_filter.enabled(metadata)}),@@ -496,8 +667,12 @@ pub fn run(cli_args: CliArgs) {builder = builder.plugin(tauri_nspanel::init());}- builder- .plugin(tauri_plugin_single_instance::init(|app, args, _cwd| {+ // Single-instance forwards CLI args to an already-running Handy and exits.+ // That would make the headless path (--transcribe-file/--list-devices) a+ // silent no-op whenever the app is already open, so skip it in headless mode+ // and run a standalone instance instead.+ if !headless_mode {+ builder = builder.plugin(tauri_plugin_single_instance::init(|app, args, _cwd| {if args.iter().any(|a| a == "--toggle-transcription") {signal_handle::send_transcription_input(app, "transcribe", "CLI");} else if args.iter().any(|a| a == "--toggle-post-process") {@@ -507,7 +682,10 @@ pub fn run(cli_args: CliArgs) {} else {show_main_window(app);}- }))+ }));+ }++ builder.plugin(tauri_plugin_fs::init()).plugin(tauri_plugin_process::init()).plugin(tauri_plugin_updater::Builder::new().build())@@ -525,6 +703,48 @@ pub fn run(cli_args: CliArgs) {.setup(move |app| {specta_builder.mount_events(app);+ // Headless one-shot path (`--transcribe-file` / `--list-devices`):+ // initialize only what transcription needs — store/paths (via the+ // registered plugins), the model + transcription managers, and the+ // accelerator settings — then run on a worker thread and exit. This+ // deliberately skips the window, tray, overlay, audio recorder (so it+ // never opens the mic, even with always_on_microphone set), signal+ // handlers, and autostart that the normal UI path+ // (initialize_core_logic) sets up.+ if headless_mode {+ let app_handle = app.handle().clone();+ let model_manager = Arc::new(+ ModelManager::new(&app_handle).expect("Failed to initialize model manager"),+ );+ let transcription_manager = Arc::new(+ TranscriptionManager::new(&app_handle, model_manager.clone())+ .expect("Failed to initialize transcription manager"),+ );+ app_handle.manage(model_manager);+ app_handle.manage(transcription_manager);+ managers::transcription::apply_accelerator_settings(&app_handle);++ let handle = app_handle.clone();+ let args = cli_args.clone();+ std::thread::spawn(move || {+ let code = run_headless_transcription(&handle, &args);+ // Drop the loaded engine before teardown: ggml-metal's global+ // device free asserts (SIGABRT) if a model's Metal resources+ // are still alive at C++ static-destructor time.+ if let Some(tm) = handle.try_state::<Arc<TranscriptionManager>>() {+ let _ = tm.unload_model();+ }+ // process::exit (not app.exit, which exits 0 regardless) so the+ // exit code propagates to the shell. Flush first since+ // process::exit runs no destructors / buffer flushes.+ use std::io::Write;+ let _ = std::io::stdout().flush();+ let _ = std::io::stderr().flush();+ std::process::exit(code);+ });+ return Ok(());+ }+// Create main window programmatically so we can set data_directory// for portable mode (redirects WebView2 cache to portable Data dir)let mut win_builder =diff --git a/src-tauri/src/managers/transcription.rs b/src-tauri/src/managers/transcription.rsindex 2ccd6af4..1f7412f7 100644--- a/src-tauri/src/managers/transcription.rs+++ b/src-tauri/src/managers/transcription.rs@@ -24,7 +24,7 @@ use transcribe_rs::{sense_voice::{SenseVoiceModel, SenseVoiceParams},Quantization,},- whisper_cpp::{WhisperEngine, WhisperInferenceParams},+ whisper_cpp::{WhisperEngine, WhisperInferenceParams, WhisperLoadParams},SpeechModel, TranscribeOptions,};@@ -251,6 +251,19 @@ impl TranscriptionManager {}pub fn load_model(&self, model_id: &str) -> Result<()> {+ self.load_model_with_device(model_id, None)+ }++ /// Like [`load_model`](Self::load_model), but lets a caller hard-select the+ /// compute device for this one load by its `--list-devices` index (0 = CPU,+ /// 1.. = a specific GPU). `None` keeps the persisted accelerator setting+ /// (which may be Auto). Only affects whisper.cpp models; the selection is+ /// not persisted.+ pub fn load_model_with_device(+ &self,+ model_id: &str,+ device_index: Option<usize>,+ ) -> Result<()> {let load_start = std::time::Instant::now();debug!("Starting to load model: {}", model_id);@@ -301,7 +314,27 @@ impl TranscriptionManager {let loaded_engine = match model_info.engine_type {EngineType::Whisper => {- let engine = WhisperEngine::load(&model_path).map_err(|e| {+ // With an explicit `device_index` (the --device-index flag),+ // hard-select that device for this load via load_with_params;+ // otherwise WhisperEngine::load reads the persisted accelerator+ // preference from the global atomics (set by+ // apply_accelerator_settings). The selection is not persisted.+ let engine = match device_index {+ Some(idx) => {+ let (use_gpu, gpu_device) = resolve_device_index(idx)+ .inspect_err(|e| emit_loading_failed(&e.to_string()))?;+ WhisperEngine::load_with_params(+ &model_path,+ WhisperLoadParams {+ use_gpu,+ gpu_device,+ ..Default::default()+ },+ )+ }+ None => WhisperEngine::load(&model_path),+ }+ .map_err(|e| {let error_msg = format!("Failed to load whisper model {}: {}", model_id, e);emit_loading_failed(&error_msg);anyhow::anyhow!(error_msg)@@ -477,12 +510,19 @@ impl TranscriptionManager {// Validate selected language against the model's supported languages.// If the language isn't supported, fall back to "auto" to prevent errors.+ // Validate against the model that's actually loaded (which can differ+ // from settings.selected_model when a caller loaded a specific model —+ // e.g. the --transcribe-file path's --model), not the persisted+ // selection.+ let active_model = self+ .get_current_model()+ .unwrap_or_else(|| settings.selected_model.clone());let validated_language = if settings.selected_language == "auto" {"auto".to_string()} else {let is_supported = self.model_manager- .get_model_info(&settings.selected_model)+ .get_model_info(&active_model).map(|info| {info.supported_languages.is_empty()|| info@@ -768,6 +808,68 @@ pub fn apply_accelerator_settings(app: &tauri::AppHandle) {info!("ORT accelerator set to: {}", ort_pref);}+/// Human-readable list of the whisper compute devices selectable via+/// `--device-index`, for the `--list-devices` flag. Index 0 is always CPU;+/// indices 1.. are the GPUs enumerated by transcribe-rs (whisper.cpp), in+/// order. The reported `index` is the value to pass to `--device-index`.+pub fn describe_compute_devices() -> Vec<String> {+ let mut out = vec!["index=0 kind=cpu name=CPU".to_string()];+ for (i, d) in cached_gpu_devices().iter().enumerate() {+ out.push(format!(+ "index={} kind=gpu name={} vram={}MB",+ i + 1,+ d.name,+ d.total_vram_mb+ ));+ }+ out+}++/// Resolve a `--list-devices` index to the (use_gpu, gpu_device) pair for a+/// whisper.cpp model load (the `--device-index` flag). Index 0 selects the CPU+/// (use_gpu = false); indices 1.. select the Nth GPU by its backend id. Errors+/// if the index isn't a registered device.+fn resolve_device_index(index: usize) -> Result<(bool, i32)> {+ if index == 0 {+ return Ok((false, 0));+ }+ let gpus = cached_gpu_devices();+ let gpu = gpus.get(index - 1).ok_or_else(|| {+ anyhow::anyhow!("No compute device with index {index} (see --list-devices)")+ })?;+ Ok((true, gpu.id))+}++/// Human-readable description of the whisper compute device that a load with the+/// given `--device-index` will actually bind, for headless diagnostics (e.g.+/// confirming `--device-index` bound a GPU rather than falling back to CPU).+/// Mirrors transcribe-rs's resolution: an explicit index, else the persisted+/// accelerator setting (whose Auto reports as "gpu:auto"). whisper.cpp only.+pub fn describe_effective_whisper_device(device_index: Option<usize>) -> String {+ use transcribe_rs::accel::{get_whisper_accelerator, get_whisper_gpu_device, GPU_DEVICE_AUTO};++ let (use_gpu, gpu_device) = match device_index {+ Some(idx) => match resolve_device_index(idx) {+ Ok(pair) => pair,+ Err(_) => return format!("index {idx} (invalid)"),+ },+ None => (+ get_whisper_accelerator().use_gpu(),+ get_whisper_gpu_device(),+ ),+ };+ if !use_gpu {+ return "cpu".to_string();+ }+ if gpu_device == GPU_DEVICE_AUTO {+ return "gpu:auto".to_string();+ }+ match cached_gpu_devices().iter().find(|d| d.id == gpu_device) {+ Some(d) => format!("gpu:{} ({})", gpu_device, d.name),+ None => format!("gpu:{}", gpu_device),+ }+}+#[derive(Serialize, Clone, Debug, Type)]pub struct GpuDeviceOption {pub id: i32,diff --git a/src-tauri/src/managers/transcription_mock.rs b/src-tauri/src/managers/transcription_mock.rsindex 9e1f0511..a0879a28 100644--- a/src-tauri/src/managers/transcription_mock.rs+++ b/src-tauri/src/managers/transcription_mock.rs@@ -51,6 +51,14 @@ impl TranscriptionManager {Ok(())}+ pub fn load_model_with_device(+ &self,+ _model_id: &str,+ _device_index: Option<usize>,+ ) -> Result<()> {+ Ok(())+ }+pub fn initiate_model_load(&self) {}pub fn get_current_model(&self) -> Option<String> {@@ -65,6 +73,16 @@ impl TranscriptionManager {/// No-op in CI mock.pub fn apply_accelerator_settings(_app: &tauri::AppHandle) {}+/// Empty in CI mock (no compute devices enumerated).+pub fn describe_compute_devices() -> Vec<String> {+ Vec::new()+}++/// CPU placeholder in CI mock.+pub fn describe_effective_whisper_device(_device_index: Option<usize>) -> String {+ "cpu".to_string()+}+#[derive(Serialize, Clone, Debug, Type)]pub struct GpuDeviceOption {pub id: i32,