SpeechShift
A fully local, offline first speech-to-text application made for desktop environments running Wayland compositor (DE's like hyprland etc...).
Records audio when a hotkey is pressed, transcribes it using faster-whisper, and automatically types the transcribed text.
Demo
Demo done on omarchy running hyprland
Roadmap
- Support for even faster transcription local methods like nvidia parakeet
- Custom vocabulary support
- Use LLM's like ChatGPT to auto format text before pasting
System Requirements
We'll expand compatibility in the coming days.
- Window manager: Wayland
- Python: 3.8+
- Package manager: UV
Installation
1. Automatic Installation (Recommended)
uv tool install speechshift
Run test to make sure pipewire, wl clipboard is present. It also downloads the whisper (small - ~80mb) model for transcription.
speechshift --test
Add these lines to your ~/.config/hypr/hyprland.conf:
The recommended default is Super+Shift+R, but you can set it to anything you like
# SpeechShift POC Keybinds
bind = SUPER_SHIFT, R, exec, /path/to/speechshift --toggle
and setup speechshift daemon to startup on default by adding these lines to ~/.config/hypr/hyprland.conf
exec-once = /path/to/speechshift --deamon
Then either restart, so that the deamon is automatically run. Or start running the speechshift deamon manually for this session by running
speechshift --deamon
Usage
- Start recording (Super+Shift+R): You'll see a notification: "🎤 Recording started..."
- Stop recording (Super+Shift+R): Audio is automatically transcribed using faster-whisper or AssemblyAI. Transcribed text is typed into the focused window. Notifications show: "🔄 Transcribing audio..." → "✅ Transcribed: [preview]"
Configuration
SpeechShift can be configured by creating a config.json file in ~/.config/speechshift/. If the file doesn't exist, it will be created with default settings upon first run.
Here's an example configuration to override the default whisper model and language:
{
"transcription": {
"engine": "whisper"
},
"whisper": {
"model": "medium",
"language": "en"
},
"audio": {
"recording_device": null,
"notification_timeout": 3000
}
}
to use Assembly AI, make sure to set the ASSEMBLYAI_API_KEY environment variable and set the transcription engine to assemblyai.
Assembly AI is highly recommended since its much better on accuracy & speed.
How It Works
Architecture Overview
Keybind (Super+Shift+R)
↓
Main Python Script
├── PipeWire Audio Recording (sounddevice)
├── AI Transcription (faster-whisper)
├── Temporary File Management
├── Wayland Text Input (wl-clipboard + hyprctl simulate control+V)
├── Smart Notifications (notify-send)
Workflow
- Keybind Press: Hyprland detects Super+Shift+R press
- Recording Start:
- Python script starts PipeWire audio capture
- Notification: "🎤 Recording started..."
- Audio streams to temporary WAV file in /tmp
- Keybind Release: Hyprland detects key release
- Recording Stop & Transcription:
- Audio capture stops
- Notification: "🔄 Transcribing audio..."
- faster-whisper transcribes the audio
- Transcribed text pasted into active window
- Temporary file automatically deleted
- Success notification: "✅ Transcribed: [preview]"
Technical Details
- Audio Format: 16-bit WAV, 44.1kHz, mono
- Transcription Model: faster-whisper "base" model (configurable)
- File Handling: Temporary files in
/tmp, auto-cleanup after transcription - Text Insertion: Direct typing via wtype, fallback to clipboard paste
- Notifications: Smart status updates via notify-send
- Error Handling: Graceful fallback with error notifications
Troubleshooting
Common Issues
-
"sounddevice not available":
# Install manually: pip install --user sounddevice numpy -
"Audio recording failed":
- Check PipeWire is running:
systemctl --user status pipewire - Test microphone:
pw-record --list-targets - Verify permissions: ensure user is in
audiogroup
- Check PipeWire is running:
-
"Hyprland socket not found":
- Ensure running under Hyprland
- Check environment variables:
echo $HYPRLAND_INSTANCE_SIGNATURE
-
"Text insertion not working":
- Verify wtype is installed:
wtype --version - Test manually:
wtype "test" - Check focused window accepts text input
- Verify wtype is installed:
-
"Notifications not showing":
- Test manually:
notify-send "test" "message"
- Test manually:
Debug Mode
Enable detailed logging by checking ~/.speechshift.log:
tail -f ~/.speechshift.log
Metadata
Release files for speechshift 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| speechshift-0.1.4.tar.gz | 16.3 kB | Without provenance | Details for speechshift-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| speechshift-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for speechshift-0.1.4-py3-none-any.whl |
Total release size: 35.0 kB
Release files / speechshift-0.1.4.tar.gz
| Download URL | speechshift-0.1.4.tar.gz |
|---|---|
| Size | 16.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c40307d9b403879b9c2b496b6c28704d39f664b6c02b0174f69168c6216b2286
|
|
BLAKE2b-256 checksum How to use checksums |
c1cd3b18c153079d0ed2a3341872839bcc02ffed1e962eec040039ef5a126732
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.19
|
Release files / speechshift-0.1.4-py3-none-any.whl
| Download URL | speechshift-0.1.4-py3-none-any.whl |
|---|---|
| Size | 18.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dc6ad1a86d82a9902a52afd4ef611b097c0127fc600bc0705856424f46893c82
|
|
BLAKE2b-256 checksum How to use checksums |
557be5fdfd218ea9b5c0f9d393c675779a342e888d77de190e1f2f25f249a416
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.19
|
Security for speechshift 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.