Merge pull request #176 from grota/feature/restore_clipboard

feat: Clipboard Restoration Feature

Author: peteonrails

docs/CONFIGURATION.md

@@ -1200,6 +1200,47 @@ paste_keys = "shift+insert"  # For Hyprland/Omarchy
 - Letters: `a-z`
 - Special: `insert`, `enter`
 
+### restore_clipboard
+
+**Type:** Boolean
+**Default:** `false`
+**Required:** No
+**Applies to:** Paste mode only
+
+When `true`, voxtype saves your clipboard content before transcription and restores it after the paste operation completes. This prevents your original clipboard content from being overwritten by the transcription.
+
+**How it works:**
+1. Before transcription: Save current clipboard content (including MIME type for binary data)
+2. Copy transcribed text to clipboard
+3. Simulate paste keystroke
+4. After brief delay: Restore original clipboard content
+
+**Example:**
+```toml
+[output]
+mode = "paste"
+restore_clipboard = true  # Preserve original clipboard content
+```
+
+**Note:** This only works in `mode = "paste"`. In `mode = "clipboard"`, the user manually pastes the content, so restoration would interfere with the intended workflow.
+
+### restore_clipboard_delay_ms
+
+**Type:** Integer
+**Default:** `200`
+**Required:** No
+**Applies to:** Paste mode only (when `restore_clipboard = true`)
+
+Delay in milliseconds after the paste keystroke before restoring the original clipboard content. Increase this if the restoration happens too quickly and interferes with the paste operation. The default of 200ms works well for most applications including Electron apps (Slack, Discord, VS Code).
+
+**Example:**
+```toml
+[output]
+mode = "paste"
+restore_clipboard = true
+restore_clipboard_delay_ms = 300  # Longer delay for slower systems
+```
+
 ### fallback_to_clipboard
 
 **Type:** Boolean

docs/TROUBLESHOOTING.md

@@ -805,6 +805,27 @@ echo "test" | wl-copy
 wl-paste
 ```
 
+### Clipboard not restored after paste
+
+**Cause:** The restore delay may be too short for your application, or `wl-paste` is not installed.
+
+**Solution:**
+
+1. Make sure `wl-clipboard` is installed (provides both `wl-copy` and `wl-paste`):
+```bash
+# Arch: sudo pacman -S wl-clipboard
+# Debian: sudo apt install wl-clipboard
+# Fedora: sudo dnf install wl-clipboard
+```
+
+2. If the clipboard is restored before the application reads it, increase the delay:
+```toml
+[output]
+restore_clipboard_delay_ms = 500  # Try 300-500ms for slow applications
+```
+
+3. On X11, make sure `xclip` is installed for clipboard restoration support.
+
 ### No desktop notification
 
 **Cause:** notify-send not installed or notifications disabled.

docs/USER_MANUAL.md

@@ -1350,9 +1350,19 @@ mode = "paste"
 **Cons**:
 - Requires both wl-copy and ydotool
 - Won't work in applications where Ctrl+V has a different meaning (e.g., Vim command mode)
-- Overwrites clipboard contents
+- Overwrites clipboard contents (unless clipboard restoration is enabled)
 - No fallback behavior
 
+**Clipboard Restoration**: By default, paste mode overwrites your clipboard with the transcribed text. If you want to preserve your clipboard contents, enable clipboard restoration:
+
+```toml
+[output]
+mode = "paste"
+restore_clipboard = true
+```
+
+When enabled, voxtype saves your clipboard content before pasting, then restores it after a brief delay. This works with both text and binary clipboard content (images, files) on Wayland via `wl-paste`, and with text content on X11 via `xclip`. You can also enable it from the command line with `--restore-clipboard` or the `VOXTYPE_RESTORE_CLIPBOARD=true` environment variable.
+
 ### Fallback Behavior
 
 Voxtype uses a fallback chain: wtype → eitype → dotool → ydotool → clipboard (wl-copy) → xclip

src/cli.rs

@@ -53,6 +53,15 @@ pub struct Cli {
     #[arg(long)]
     pub paste: bool,
 
+    /// Restore clipboard content after paste mode completes
+    /// Saves clipboard before transcription and restores it after paste
+    #[arg(long)]
+    pub restore_clipboard: bool,
+
+    /// Delay in milliseconds after paste before restoring clipboard (default: 200)
+    #[arg(long, value_name = "MS")]
+    pub restore_clipboard_delay_ms: Option<u32>,
+
     /// Override model for transcription.
     /// Whisper: tiny, base, small, medium, large-v3, large-v3-turbo (and .en variants).
     /// Parakeet: parakeet-tdt-0.6b-v3, parakeet-tdt-0.6b-v3-int8

src/config.rs

@@ -181,6 +181,16 @@ type_delay_ms = 0
 # Useful for applications where Enter submits (e.g., Cursor IDE, Slack, Discord)
 # shift_enter_newlines = false
 
+# Restore clipboard content after paste mode (default: false)
+# Saves clipboard before transcription, restores it after paste keystroke
+# Only applies to mode = "paste". Useful when you want to preserve your
+# existing clipboard content across dictation operations.
+# restore_clipboard = false
+
+# Delay after paste before restoring clipboard (milliseconds)
+# Allows time for the paste operation to complete (default: 200)
+# restore_clipboard_delay_ms = 200
+
 # Pre/post output hooks (optional)
 # Commands to run before and after typing output. Useful for compositor integration.
 # Example: Block modifier keys during typing with Hyprland submap:
@@ -1487,6 +1497,10 @@ fn default_post_process_timeout() -> u64 {
     30000 // 30 seconds - generous for LLM processing
 }
 
+fn default_restore_clipboard_delay() -> u32 {
+    200 // 200ms - delay for paste to complete before restoring clipboard
+}
+
 /// Text output configuration
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct OutputConfig {
@@ -1580,6 +1594,16 @@ pub struct OutputConfig {
     /// Applies to both config-based file output and --output-file CLI flag
     #[serde(default)]
     pub file_mode: FileMode,
+
+    /// Restore original clipboard content after paste mode completes
+    /// Saves clipboard before transcription, restores it after paste keystroke
+    #[serde(default)]
+    pub restore_clipboard: bool,
+
+    /// Delay after paste before restoring clipboard content (milliseconds)
+    /// Allows time for the paste operation to complete
+    #[serde(default = "default_restore_clipboard_delay")]
+    pub restore_clipboard_delay_ms: u32,
 }
 
 impl OutputConfig {
@@ -1746,6 +1770,8 @@ impl Default for Config {
                 dotool_xkb_variant: None,
                 file_path: None,
                 file_mode: FileMode::default(),
+                restore_clipboard: false,
+                restore_clipboard_delay_ms: default_restore_clipboard_delay(),
             },
             engine: TranscriptionEngine::default(),
             parakeet: None,
@@ -1953,6 +1979,14 @@ pub fn load_config(path: Option<&Path>) -> Result<Config, VoxtypeError> {
     if let Ok(append_text) = std::env::var("VOXTYPE_APPEND_TEXT") {
         config.output.append_text = Some(append_text);
     }
+    if let Ok(val) = std::env::var("VOXTYPE_RESTORE_CLIPBOARD") {
+        config.output.restore_clipboard = val == "1" || val.eq_ignore_ascii_case("true");
+    }
+    if let Ok(val) = std::env::var("VOXTYPE_RESTORE_CLIPBOARD_DELAY_MS") {
+        if let Ok(ms) = val.parse::<u32>() {
+            config.output.restore_clipboard_delay_ms = ms;
+        }
+    }
 
     Ok(config)
 }
@@ -3399,4 +3433,63 @@ mod tests {
         assert_eq!(config.meeting.diarization.backend, "simple");
         assert_eq!(config.meeting.summary.backend, "disabled");
     }
+
+    // =========================================================================
+    // Clipboard Restore Tests
+    // =========================================================================
+
+    #[test]
+    fn test_restore_clipboard_defaults() {
+        let config = Config::default();
+        assert!(!config.output.restore_clipboard);
+        assert_eq!(config.output.restore_clipboard_delay_ms, 200);
+    }
+
+    #[test]
+    fn test_restore_clipboard_deserialization() {
+        let toml_str = r#"
+            [hotkey]
+            key = "SCROLLLOCK"
+
+            [audio]
+            device = "default"
+            sample_rate = 16000
+            max_duration_secs = 30
+
+            [whisper]
+            model = "base.en"
+
+            [output]
+            mode = "paste"
+            restore_clipboard = true
+            restore_clipboard_delay_ms = 500
+        "#;
+
+        let config: Config = toml::from_str(toml_str).unwrap();
+        assert!(config.output.restore_clipboard);
+        assert_eq!(config.output.restore_clipboard_delay_ms, 500);
+    }
+
+    #[test]
+    fn test_restore_clipboard_missing_uses_defaults() {
+        let toml_str = r#"
+            [hotkey]
+            key = "SCROLLLOCK"
+
+            [audio]
+            device = "default"
+            sample_rate = 16000
+            max_duration_secs = 30
+
+            [whisper]
+            model = "base.en"
+
+            [output]
+            mode = "paste"
+        "#;
+
+        let config: Config = toml::from_str(toml_str).unwrap();
+        assert!(!config.output.restore_clipboard);
+        assert_eq!(config.output.restore_clipboard_delay_ms, 200);
+    }
 }

src/error.rs

@@ -130,6 +130,9 @@ pub enum OutputError {
     #[error("wl-copy not found in PATH. Install wl-clipboard via your package manager.")]
     WlCopyNotFound,
 
+    #[error("wl-paste not found in PATH. Install wl-clipboard via your package manager.")]
+    WlPasteNotFound,
+
     #[error("xclip not found in PATH. Install xclip via your package manager.")]
     XclipNotFound,
 

src/main.rs

@@ -99,6 +99,12 @@ async fn main() -> anyhow::Result<()> {
     if cli.paste {
         config.output.mode = config::OutputMode::Paste;
     }
+    if cli.restore_clipboard {
+        config.output.restore_clipboard = true;
+    }
+    if let Some(delay) = cli.restore_clipboard_delay_ms {
+        config.output.restore_clipboard_delay_ms = delay;
+    }
     let top_level_model = cli.model.clone();
     if let Some(model) = cli.model {
         if setup::model::is_valid_model(&model) {
@@ -1085,6 +1091,11 @@ async fn show_config(config: &config::Config) -> anyhow::Result<()> {
     }
     println!("  type_delay_ms = {}", config.output.type_delay_ms);
     println!("  pre_type_delay_ms = {}", config.output.pre_type_delay_ms);
+    println!("  restore_clipboard = {}", config.output.restore_clipboard);
+    println!(
+        "  restore_clipboard_delay_ms = {}",
+        config.output.restore_clipboard_delay_ms
+    );
 
     println!("\n[output.notification]");
     println!(

src/output/mod.rs

@@ -287,6 +287,8 @@ pub fn create_output_chain_with_override(
                 config.paste_keys.clone(),
                 config.type_delay_ms,
                 pre_type_delay_ms,
+                config.restore_clipboard,
+                config.restore_clipboard_delay_ms,
             )));
         }
         crate::config::OutputMode::File => {