Skip to main content

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

Demo

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

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

  1. Start recording (Super+Shift+R): You'll see a notification: "🎤 Recording started..."
  2. 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

  1. Keybind Press: Hyprland detects Super+Shift+R press
  2. Recording Start:
    • Python script starts PipeWire audio capture
    • Notification: "🎤 Recording started..."
    • Audio streams to temporary WAV file in /tmp
  3. Keybind Release: Hyprland detects key release
  4. 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

  1. "sounddevice not available":

    # Install manually: pip install --user sounddevice numpy
    
  2. "Audio recording failed":

    • Check PipeWire is running: systemctl --user status pipewire
    • Test microphone: pw-record --list-targets
    • Verify permissions: ensure user is in audio group
  3. "Hyprland socket not found":

    • Ensure running under Hyprland
    • Check environment variables: echo $HYPRLAND_INSTANCE_SIGNATURE
  4. "Text insertion not working":

    • Verify wtype is installed: wtype --version
    • Test manually: wtype "test"
    • Check focused window accepts text input
  5. "Notifications not showing":

    • Test manually: notify-send "test" "message"

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)

Source distribution for speechshift 0.1.4
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)

Table of built distributions (wheels) for speechshift 0.1.4
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page