Windy Word

Switch the active sound pack. Pack ids come from list_sound_effect_packs — typical built-ins are "_silent", "classic-beep", "soft-chime". Affects all 6 hook stages unless individually overridden via custom-sound assignments. Persisted via EffectsEngine _saveSettings.

Set which voice clone is the active TTS default. Pass id=null to deactivate (no clone — falls back to built-in TTS). The id must match an existing clone (use list_voice_clones to discover ids).

Enable or disable Windy Word's auto-launch on user login. Linux writes/removes a .desktop autostart entry; macOS/Windows toggle via Electron's setLoginItemSettings. Returns the resulting state (enabled boolean) so agents can verify the change took.

Patch the config store. Pass EITHER {path, value} for a single dotted-path write (e.g. path="engine.model", value="small"), OR {patch: {...}} for a flat object of dotted-path → value pairs applied in order. Changes persist immediately.

Rebind a keyboard shortcut. Action keys: toggleRecording, pasteTranscript, pasteClipboard, showHide, quickTranslate. Accelerator format is Electron-style (e.g. "CommandOrControl+Shift+Space", "Alt+W"). Triggers an immediate re-registration.

Set the master SFX volume (0-100). Affects every hook stage as a multiplier on per-stage volumes. Persists immediately to localStorage windy_sfxVolume and applies to the live EffectsEngine.sound master.

Switch the active transcription model. Hot-reloads the running Python engine over WebSocket if it is currently active — no app restart needed. Model must be in the WindyTune ladder (see list_models).

Select a paste strategy. Pass "auto" to use the platform default chain, or a specific strategy name (e.g. "wtype", "ydotool_type", "osascript_cmdv"). Optionally override the fallback chain. Strategy names come from list_paste_strategies.

Validate and apply a setting change against the catalog. Rejects unknown paths, type mismatches, out-of-range numbers, invalid enum values, malformed accelerators, and attempts to write read-only settings (e.g. license.*). On success, returns the previous + new value, any side effects that fired (e.g. "global shortcuts re-registered", "python engine hot-reload sent"), and whether a restart is required for the change to take full effect. Use set_config to bypass the catalog (low-level, no validation — for paths outside the catalog).

Switch the EffectsEngine mode: "silent" (no sounds), "classic" (built-in beeps), "surprise" (random selection from a category), "custom" (per-hook user-assigned sounds), "pack" (active pack drives everything). Persisted via _saveSettings.

Configure a single sound-effect hook stage. Hooks are the 6 lifecycle points where Windy Word plays sounds: start (🎬 begin recording), during (🎤 mid-recording chirps), stop (⏹️ end recording), process (⏳ Whisper transcribing), warning (⚠️ approaching session limit), paste (📋 transcript injected). Each hook has enabled (boolean) + volume (0-100 int). Pass any combo of those args — omitted ones are unchanged. Routes through the renderer EffectsEngine and persists via _saveSettings to localStorage.

Install or remove the Linux polkit auto-approve rule that lets install_dependency run without prompts. CRITICAL ONE-TIME SETUP for the agent-native install flow on a fresh machine: triggers a single pkexec password prompt for THIS call (the user types their password once); thereafter every install_dependency call for a whitelisted tool (wtype/ydotool/wl-clipboard/xdotool/ffmpeg) runs prompt-free. Uses subject.active so the rule applies to any logged-in user on the machine (not hardcoded to a single account). Linux only — returns 501 on macOS/Windows. Recommended flow: 1. run_diagnostics — see if install_polkit_rule check is warning 2. setup_install_polkit_rule({enable: true}) — user types password once 3. install_dependency({tool: "wtype"}) — silent install, no prompt Pass enable=false to remove the rule (also triggers a polkit prompt).

Cycle the Windy Word window through its three states: full → mini tornado → hidden → full.

WARNING: injects test text ("wtest") into whatever window currently has focus. Use to verify a specific strategy works on this machine. Returns timing + success flag. Have the user focus a known-safe target (e.g. a text editor) before calling.

Toggle voice recording on or off (same effect as the global hotkey). If currently idle, starts listening. If currently recording, stops and triggers the transcription + paste pipeline against whatever window had focus when recording started.

Transcribe an audio file at a given path. Accepts any format ffmpeg can read (wav, mp3, m4a, ogg, flac, webm, etc. — auto-detected). Routes through the same Python Whisper engine the Windy Word desktop app uses for live transcripts (no cold start when the engine is warm — WebSocket-routed for sub-second hand-off). Returns transcript text + timing diagnostics (transcribeMs, audioDurationSec, ratio = transcribe/audio, modelUsed). 500MB file cap; 60s ffmpeg ceiling; 120s WS ceiling. Designed for individual files — agents wanting bulk processing should iterate over a directory and call this per file.

Translate text to a target language. Tries the local translation-memory cache first (instant + free); on miss, calls Groq (preferred) or OpenAI via Windy Word's configured key. The TM cache auto-populates from successful calls so repeat translations are free. Source language defaults to "auto" (model detects); only concrete source-lang calls hit the TM. Returns {ok, translation, fromCache, sourceLang, targetLang, engine}.