A free, open source, and extensible speech-to-text application that works completely offline.
Add transcription hook (#930)
Alexander Yastrebov033c627cc5ea
diff --git a/README.md b/README.mdindex dd8a2b45..94b089b8 100644--- a/README.md+++ b/README.md@@ -122,6 +122,25 @@ handy --start-hidden --no-tray> /Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription> ```+### Transcription hook++Advanced users on macOS and Linux can rewrite text right before Handy pastes it. Put an executable at `hooks/transcription` in Handy's app data folder (`~/Library/Application Support/com.pais.handy/` on macOS, `~/.local/share/com.pais.handy/` on Linux). Handy writes the text to its stdin, after any LLM post-processing, and pastes its stdout. One trailing newline is removed, and empty output pastes nothing. If the hook fails or runs longer than 30 seconds, the original text is pasted.++The hook doesn't get your shell's `PATH`: on macOS, Handy started from the Dock or Finder only sees `/usr/bin:/bin:/usr/sbin:/sbin`. Use absolute paths for anything else, such as `/opt/homebrew/bin/opencc`.++Example that prefixes `#` when Terminal is the frontmost app (macOS):++```bash+mkdir -p ~/Library/Application\ Support/com.pais.handy/hooks+cd ~/Library/Application\ Support/com.pais.handy/hooks+cat > transcription << 'EOF'+#!/bin/bash+app=$(osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true')+if [ "$app" = "Terminal" ]; then echo "# $(cat)"; else cat; fi+EOF+chmod +x transcription+```+## Known Issues & Current LimitationsThis project is actively being developed and has some [known issues](https://github.com/cjpais/Handy/issues). We believe in transparency about the current state:diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lockindex bc166d43..3a122610 100644--- a/src-tauri/Cargo.lock+++ b/src-tauri/Cargo.lock@@ -7090,6 +7090,7 @@ dependencies = ["libc","mio 1.1.1","pin-project-lite",+ "signal-hook-registry","socket2","tokio-macros","windows-sys 0.61.2",diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.tomlindex 18e5c309..cbd0ebf7 100644--- a/src-tauri/Cargo.toml+++ b/src-tauri/Cargo.toml@@ -51,7 +51,7 @@ anyhow = "1.0.95"hound = "3.5.1"log = "0.4.25"env_filter = "0.1.0"-tokio = "1.43.0"+tokio = { version = "1.43.0", features = ["process"] }earshot = "1.2.2"enigo = "0.6.1"# Feedback sounds. No `recording`: microphone capture is handy-recorder's.diff --git a/src-tauri/src/actions.rs b/src-tauri/src/actions.rsindex 2c8b796c..748d17cd 100644--- a/src-tauri/src/actions.rs+++ b/src-tauri/src/actions.rs@@ -828,7 +828,21 @@ impl ShortcutAction for TranscribeAction {}}- if processed.final_text.is_empty() {+ // The user's hook only changes what gets pasted;+ // history above keeps the text as produced.+ let Some(final_text) = complete_unless_cancelled(+ crate::transcription_hook::apply(&ah, processed.final_text),+ || rm.was_cancelled_since(cancel_generation),+ )+ .await+ else {+ debug!("Transcription operation cancelled during hook");+ utils::hide_recording_overlay(&ah);+ set_tray_state(&ah, TrayIconState::Idle);+ return;+ };++ if final_text.is_empty() {utils::hide_recording_overlay(&ah);set_tray_state(&ah, TrayIconState::Idle);emit_transcription_complete(@@ -840,7 +854,6 @@ impl ShortcutAction for TranscribeAction {} else {let ah_clone = ah.clone();let paste_time = Instant::now();- let final_text = processed.final_text;let post_process_failed = processed.post_process_failed;let rm_for_paste = Arc::clone(&rm);// Taken before the paste thread exists, and sodiff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rsindex 5b666540..b0362ed3 100644--- a/src-tauri/src/lib.rs+++ b/src-tauri/src/lib.rs@@ -26,6 +26,7 @@ mod shortcut;mod signal_handle;mod system_languages;mod transcription_coordinator;+mod transcription_hook;mod tray;mod tray_i18n;mod utils;diff --git a/src-tauri/src/transcription_hook.rs b/src-tauri/src/transcription_hook.rsnew file mode 100644index 00000000..52bc23d6--- /dev/null+++ b/src-tauri/src/transcription_hook.rs@@ -0,0 +1,65 @@+//! Optional user hook: `<app data dir>/hooks/transcription` receives the text+//! about to be pasted on stdin, and its stdout is pasted instead.++use anyhow::Context;+use log::error;+use std::path::Path;+use std::process::Stdio;+use std::time::Duration;+use tauri::AppHandle;+use tokio::io::AsyncWriteExt;+use tokio::process::Command;++/// Hung hooks are killed so they can't leave the pipeline stuck in "transcribing".+const HOOK_TIMEOUT: Duration = Duration::from_secs(30);++/// Returns the hook's output, or `text` unchanged if there's no hook or it+/// fails. Dropping the future kills the hook, so callers can cancel it.+pub async fn apply(app: &AppHandle, text: String) -> String {+ let Ok(dir) = crate::portable::app_data_dir(app) else {+ return text;+ };+ let hook = dir.join("hooks").join("transcription");+ if text.is_empty() || !hook.is_file() {+ return text;+ }++ run(&hook, &text).await.unwrap_or_else(|e| {+ error!("Transcription hook failed, using original text: {:#}", e);+ text+ })+}++async fn run(hook: &Path, text: &str) -> anyhow::Result<String> {+ let mut child = Command::new(hook)+ .stdin(Stdio::piped())+ .stdout(Stdio::piped())+ .stderr(Stdio::piped())+ .kill_on_drop(true)+ .spawn()?;++ // Write input while reading output so neither side blocks on a full pipe.+ // Write errors are ignored: a hook may exit without reading its input.+ let mut stdin = child.stdin.take().context("stdin not piped")?;+ let write = async move {+ let _ = stdin.write_all(text.as_bytes()).await;+ };+ let (_, output) = tokio::time::timeout(HOOK_TIMEOUT, async {+ tokio::join!(write, child.wait_with_output())+ })+ .await+ .context("timed out")?;+ let output = output?;++ let stderr = String::from_utf8_lossy(&output.stderr);+ anyhow::ensure!(+ output.status.success(),+ "exited with {}: {}",+ output.status,+ stderr.trim()+ );++ // Drop one trailing newline so `echo` output doesn't submit a terminal line.+ let stdout = String::from_utf8_lossy(&output.stdout);+ Ok(stdout.strip_suffix('\n').unwrap_or(&stdout).to_string())+}