Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

remove sigusr1 on linux (#1824)

CJ Pais2266b29b798b
diff --git a/README.md b/README.md
index f1890809..cf22a0c5 100644
--- a/README.md
+++ b/README.md
@@ -194,22 +194,24 @@ Without these tools, Handy falls back to enigo which may have limited compatibil
bind = $mainMod, O, exec, handy --toggle-transcription
```
-- You can also manage global shortcuts outside of Handy via Unix signals, which lets Wayland window managers or other hotkey daemons keep ownership of keybindings:
+- You can also trigger Handy externally via Unix signals or the CLI flags, which lets Wayland window managers or other hotkey daemons keep ownership of keybindings:
- | Signal | Action | Example |
- | --------- | ----------------------------------------- | ---------------------- |
- | `SIGUSR2` | Toggle transcription | `pkill -USR2 -n handy` |
- | `SIGUSR1` | Toggle transcription with post-processing | `pkill -USR1 -n handy` |
+ | Action | Trigger |
+ | ----------------------------------------- | -------------------------------------------------------- |
+ | Toggle transcription | `pkill -USR2 -n handy` or `handy --toggle-transcription` |
+ | Toggle transcription with post-processing | `handy --toggle-post-process` |
Example Sway config:
```ini
bindsym $mod+o exec pkill -USR2 -n handy
- bindsym $mod+p exec pkill -USR1 -n handy
+ bindsym $mod+p exec handy --toggle-post-process
```
`pkill` here simply delivers the signal—it does not terminate the process.
+ > **Behavior change:** older releases also accepted `SIGUSR1` for toggling transcription with post-processing. WebKitGTK — the webview engine embedded in Handy on Linux — uses SIGUSR1 internally to coordinate JavaScript garbage collection, so listening for it caused phantom recordings and interrupted dictations every few minutes ([#1660](https://github.com/cjpais/Handy/issues/1660)). Handy no longer listens for SIGUSR1 on Linux; the post-processing toggle is still available via `handy --toggle-post-process`. **Remove any `pkill -USR1` bindings**: the signal is now delivered straight to WebKit's internal handler and can crash the app.
+
**Overlay & Pasting Issues (Linux):**
- The recording overlay window can interfere with pasting transcribed text into target applications on Linux (X11)
@@ -468,6 +470,12 @@ Exec=env HANDY_NO_GTK_LAYER_SHELL=1 handy
If a workaround helps you, please [open an issue](https://github.com/cjpais/Handy/issues) describing your distro, desktop environment, and session type — that information helps us narrow down the underlying bug.
+### Handy Starts or Stops Recording on Its Own (Linux)
+
+Handy 0.9.4 and earlier listened for `SIGUSR1` as a remote-control trigger. WebKitGTK — the webview engine embedded in Handy on Linux — uses that same signal internally to coordinate JavaScript garbage collection, so GC cycles were misread as hotkey presses: recordings started on their own, or real dictations were cut off mid-sentence (typically ~2 minutes in). See [#1660](https://github.com/cjpais/Handy/issues/1660).
+
+Update to a newer release, and replace any `pkill -USR1 -n handy` keybindings with `handy --toggle-post-process`.
+
### How to Contribute
1. **Check existing issues** at [github.com/cjpais/Handy/issues](https://github.com/cjpais/Handy/issues)
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 621b6a02..5bfcfbeb 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -33,10 +33,6 @@ use managers::audio::AudioRecordingManager;
use managers::history::HistoryManager;
use managers::model::ModelManager;
use managers::transcription::TranscriptionManager;
-#[cfg(unix)]
-use signal_hook::consts::{SIGUSR1, SIGUSR2};
-#[cfg(unix)]
-use signal_hook::iterator::Signals;
use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
use std::sync::Arc;
use tauri::image::Image;
@@ -189,11 +185,11 @@ fn initialize_core_logic(app_handle: &AppHandle) {
// after permissions are confirmed (on macOS) or after onboarding completes.
// This matches the pattern used for Enigo initialization.
+ // Set up signal handlers for toggling transcription. On Linux, SIGUSR1 is
+ // deliberately not handled — it belongs to WebKitGTK's garbage collector
+ // (#1660) — see signal_handle.rs.
#[cfg(unix)]
- let signals = Signals::new([SIGUSR1, SIGUSR2]).unwrap();
- // Set up signal handlers for toggling transcription
- #[cfg(unix)]
- signal_handle::setup_signal_handler(app_handle.clone(), signals);
+ signal_handle::setup_signal_handler(app_handle.clone());
// Apply macOS Accessory policy if starting hidden and tray is available.
// If the tray icon is disabled, keep the dock icon so the user can reopen.
diff --git a/src-tauri/src/signal_handle.rs b/src-tauri/src/signal_handle.rs
index 1f54c0d9..efe01e8a 100644
--- a/src-tauri/src/signal_handle.rs
+++ b/src-tauri/src/signal_handle.rs
@@ -4,8 +4,10 @@ use log::debug;
use log::warn;
use tauri::{AppHandle, Manager};
+#[cfg(target_os = "macos")]
+use signal_hook::consts::SIGUSR1;
#[cfg(unix)]
-use signal_hook::consts::{SIGUSR1, SIGUSR2};
+use signal_hook::consts::SIGUSR2;
#[cfg(unix)]
use signal_hook::iterator::Signals;
#[cfg(unix)]
@@ -21,12 +23,30 @@ pub fn send_transcription_input(app: &AppHandle, binding_id: &str, source: &str)
}
}
+/// Listen for Unix signals that remotely toggle transcription.
+///
+/// SIGUSR2 toggles plain transcription on all Unix platforms. SIGUSR1
+/// (transcription with post-processing) is only handled on macOS: on Linux,
+/// WebKitGTK's JavaScriptCore garbage collector sends SIGUSR1 to its own
+/// threads to suspend them, so handling it caused phantom recordings on every
+/// GC cycle (#1660). Linux users should use `handy --toggle-post-process`
+/// instead.
#[cfg(unix)]
-pub fn setup_signal_handler(app_handle: AppHandle, mut signals: Signals) {
+pub fn setup_signal_handler(app_handle: AppHandle) {
+ #[cfg(target_os = "macos")]
+ let mut signals =
+ Signals::new([SIGUSR1, SIGUSR2]).expect("failed to register transcription signal handlers");
+ #[cfg(not(target_os = "macos"))]
+ let mut signals =
+ Signals::new([SIGUSR2]).expect("failed to register transcription signal handlers");
+ #[cfg(target_os = "macos")]
debug!("Signal handlers registered (SIGUSR1, SIGUSR2)");
+ #[cfg(not(target_os = "macos"))]
+ debug!("Signal handler registered (SIGUSR2; SIGUSR1 is left to WebKitGTK)");
thread::spawn(move || {
for sig in signals.forever() {
let (binding_id, signal_name) = match sig {
+ #[cfg(target_os = "macos")]
SIGUSR1 => ("transcribe_with_post_process", "SIGUSR1"),
SIGUSR2 => ("transcribe", "SIGUSR2"),
_ => continue,
diff --git a/src/content/release-notes/0.9.5.md b/src/content/release-notes/0.9.5.md
new file mode 100644
index 00000000..8e38d236
--- /dev/null
+++ b/src/content/release-notes/0.9.5.md
@@ -0,0 +1,18 @@
+## Linux: Phantom Recording Fix
+
+If Handy on Linux sometimes started recording on its own, or cut off a real
+dictation mid-sentence (typically about 2 minutes in), that was a signal
+conflict: Handy listened for `SIGUSR1` as a remote-control trigger, but
+WebKitGTK — the webview engine embedded in Handy — uses the same signal
+internally for JavaScript garbage collection. Every GC cycle looked like a
+hotkey press ([#1660](https://github.com/cjpais/Handy/issues/1660)).
+
+Handy no longer listens for `SIGUSR1` on Linux.
+
+**If you bound `pkill -USR1 -n handy` to a hotkey, replace it with:**
+
+```bash
+handy --toggle-post-process
+```
+
+`SIGUSR2` (plain transcription toggle) is unchanged and keeps working.