sayclip

Push-to-talk: local speech transcription straight to your clipboard.

Читать по-русски: README_RU.md

About

Hold a hotkey, say something, release it — the text lands in your clipboard a moment later. No cloud, no API keys: transcription runs fully locally via whisper.cpp.

• Genuine push-to-talk — recording starts on key-down and stops on key-up, not a toggle
• Fully local transcription, nothing leaves your machine
• Runs in the foreground or as a background daemon, with autostart on login
• Optional auto-paste: paste automatically right after transcription, or double-tap the hotkey to paste on demand
• Escape cancels an in-progress recording
• Switchable model/language/prompt, no config file editing required
• Linux and Windows

[hold Right Ctrl] "remind me to deploy the staging branch after lunch"
                                    ↓
                    copied to clipboard, paste anywhere

System requirements

• a microphone
• Linux with an X11 session, or Windows 10/11 (macOS/Wayland are not supported yet)
• Node.js ≥ 18 — only if you install via npm; the Windows installer bundles its own Node runtime, no separate install needed

whisper.cpp is a required dependency but not something you set up yourself: on first run sayclip offers to download a small prebuilt runtime + model automatically. See Installation below.

Installation

Linux

npm install -g sayclip

Verify:

sayclip --version
sayclip --help

Dependencies (usually already installed on Ubuntu):

• arecord (package alsa-utils) — microphone recording. Check: which arecord
• xclip (or xsel / wl-copy) — clipboard access. Check: which xclip
• notify-send (package libnotify-bin) — result notifications. Check: which notify-send
• an X11 session — the global hotkey listener needs XRecord, not available on Wayland

The global hotkey listener (uiohook-napi) ships with prebuilt native binaries — no extra system package needed for it.

Windows

Two ways to install:

Option A — Installer (recommended)

Download sayclip-setup.exe from the latest release and run it. No Node.js/npm required — the installer bundles its own Node runtime. Setup asks for your microphone and model on first launch; change anything later from the tray icon → Settings....

Option B — npm (for developers)

npm install -g sayclip
sayclip

Same CLI as Linux (sayclip reconfig, start, stop, ...).

Either way, ffmpeg must be on PATH — it's used both for recording and for auto-detecting your microphone. Install it yourself:

winget install ffmpeg

or download a build from ffmpeg.org and add it to PATH. The installer checks for ffmpeg up front and stops with a clear message if it's missing.

Why isn't ffmpeg bundled? Most prebuilt Windows ffmpeg builds (including the one sayclip was tested with) include GPL-licensed components, which makes redistributing the binary as a sayclip asset a real compliance burden (license text, copyright notices, a source-code offer). Since ffmpeg is a required dependency either way, it's simpler to have you install it from an official source directly.

whisper.cpp: same as Linux — no manual build needed, auto-downloaded on first run (or point sayclip at your own build).

Configuration

Settings (whisper binary/model path, recognition language, initial prompt, microphone, notifications, auto-paste, autostart) live in ~/.sayclip/config.json (%USERPROFILE%\.sayclip\config.json on Windows). On first use, sayclip asks what it needs and saves it.

Change any setting later:

sayclip reconfig

On a Windows installer build these questions show as a small popup window instead of a terminal prompt — same settings, same file, different UI. Console/npm installs on both platforms always use the terminal.

Usage

sayclip

| Command | What it does | |---|---| | sayclip | run in the foreground, hold Right Ctrl to record | | sayclip start | run the same thing in the background | | sayclip stop | stop the background instance | | sayclip restart | restart the background instance | | sayclip transcribe <file.wav> | transcribe a .wav file and print the text | | sayclip reconfig | change whisper binary/model/language/prompt/microphone/autostart/etc. | | sayclip --version / -v | show version | | sayclip --help / -h | show help |

The hotkey is fixed to Right Ctrl for now (hold to record, release to stop) — no rebinding option yet.

• Escape while recording cancels it — nothing is transcribed or copied.
• Double-tap the hotkey (two quick taps) to paste the clipboard immediately — only if auto-paste is enabled in sayclip reconfig.
• With auto-paste enabled, the transcribed text is also pasted automatically right after transcription, unless you pressed another key in the meantime (e.g. switched windows) — that cancels the auto-paste.

Autostart on login

Run sayclip reconfig and choose to enable/disable autostart — this is fully automatic on both platforms (a systemd --user unit on Linux, a registry Run key on Windows), no manual setup needed.

License

MIT