Skip to content

armgit / Handy

Public Imported from GitHub
0

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.md
index 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 Limitations
This 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.lock
index 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.toml
index 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.rs
index 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 so
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 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.rs
new file mode 100644
index 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())
+}