Skip to content

armgit / Handy

Public Imported from GitHub
0

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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,