Whisper-fast dictation under a starry sky.

OSWispa doesn't start on login

The most common cause is a missing or unreachable model file. Check your config at ~/.config/oswispa/config.json and verify the model_path exists. Models should be stored locally at ~/.local/share/oswispa/models/.

For reliable autostart, use a systemd user service instead of the desktop file:

# Create the service
cat > ~/.config/systemd/user/oswispa.service <<EOF
[Unit]
Description=OSWispa Voice-to-Text
After=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/local/bin/oswispa
Restart=on-failure

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable oswispa
systemctl --user start oswispa

Model not found error

OSWispa exits immediately if the configured model file is missing. If your models are on a network drive or external mount, they may not be available at login time.

Fix: Copy models to local storage:

mkdir -p ~/.local/share/oswispa/models
cp /path/to/your/model.bin ~/.local/share/oswispa/models/

Then update ~/.config/oswispa/config.json to point to the local path.

App closes when terminal closes

If you're running oswispa from a terminal, closing that terminal kills the app. Use the systemd service approach above, or launch with nohup:

nohup oswispa & disown

The systemd service is recommended for production use.

Text doesn't paste automatically

OSWispa types text directly via ydotool. For best reliability, enable the service:

sudo systemctl enable ydotool
sudo systemctl start ydotool

Text is also copied to the clipboard as backup. Use Ctrl + V if needed.

How do I change the hotkey?

Open Settings from the tray icon, then configure modifiers and an optional trigger key. You can still edit ~/.config/oswispa/config.json directly:

"hotkey": {
  "ctrl": true,
  "alt": false,
  "shift": true,
  "super_key": false,
  "trigger_key": "space"
}

Changes apply immediately.

How do I check if OSWispa is running?

Check the systemd service status or look for the process:

systemctl --user status oswispa
# or
pgrep -f oswispa

The system tray icon also indicates active status.

Can I use a VPS instead of local models?

Yes. In Settings, switch Backend mode to Remote VPS, set your endpoint, and optionally store an API key securely. HTTPS is required by default.

OSWispa remains local-first and can fall back to local models when available.