Voice Transcriber Documentation¶

Overview¶

Voice Transcriber is a lightweight desktop application that provides seamless voice-to-text conversion with system tray integration. Record audio with a single click, and transcribed text is automatically copied to your clipboard.

Key Features¶

• 🎯 System Tray Integration: Click to record, visual state feedback
• 🎙️ High-Quality Recording: Audio capture using arecord on Linux
• 🌍 Multilingual Support: French, English, Spanish, German, Italian
• ✍️ Text Formatting: Optional GPT-based grammar improvement
• 📋 Clipboard Integration: Automatic result copying
• 🏠 Self-Hosted Option: Run 100% offline with Speaches
• 🔒 Privacy-Focused: No persistent audio storage, local processing

Quick Start¶

Get started in under 5 minutes:

# Clone the repository
git clone https://github.com/Nouuu/voice-transcriber.git
cd voice-transcriber

# One-command setup (checks deps, installs, creates config)
make setup

# Configure your OpenAI API key
nano ~/.config/voice-transcriber/config.json

# Run the application
make run

# Clone the repository
git clone https://github.com/Nouuu/voice-transcriber.git
cd voice-transcriber

# Check system dependencies (Bun, arecord, xsel)
make check-system-deps

# Install Bun dependencies
make install

# Initialize configuration file
make init-config

# Configure your OpenAI API key
nano ~/.config/voice-transcriber/config.json

# Run the application
make run

How It Works¶

sequenceDiagram
    participant User
    participant SystemTray
    participant AudioRecorder
    participant MP3Encoder
    participant Backend as Whisper API<br/>(OpenAI or Speaches)
    participant GPT as ChatGPT<br/>(optional)
    participant Clipboard

    User->>SystemTray: Click tray icon
    SystemTray->>SystemTray: State: RECORDING (🔴)
    SystemTray->>AudioRecorder: Start recording
    AudioRecorder->>AudioRecorder: Capture audio (arecord)
    User->>SystemTray: Click again to stop
    SystemTray->>SystemTray: State: PROCESSING (🟣)
    AudioRecorder->>AudioRecorder: Save WAV file
    AudioRecorder->>MP3Encoder: Convert to MP3
    Note over MP3Encoder: Compress audio<br/>~75% size reduction<br/>(mono 16kHz 64kbps)
    MP3Encoder-->>AudioRecorder: MP3 file
    AudioRecorder->>Backend: Upload MP3
    Backend->>Backend: Transcribe audio
    Backend-->>AudioRecorder: Return text
    opt Formatting Enabled
        AudioRecorder->>GPT: Format text
        GPT-->>AudioRecorder: Formatted text
    end
    AudioRecorder->>Clipboard: Copy text
    Clipboard-->>User: Paste transcription
    SystemTray->>SystemTray: State: IDLE (🟢)

Key Steps:

1. Audio Capture - Records in WAV format (CD quality: 44.1kHz, 16-bit)
2. MP3 Compression - Converts to mono 16kHz 64kbps MP3 (~75% size reduction)
3. Transcription - Sends to OpenAI Whisper or self-hosted Speaches
4. Optional Formatting - Improves grammar/punctuation with ChatGPT (if enabled)
5. Clipboard - Automatically copies result for instant pasting

Popular Use Cases¶

Documentation Structure¶

Community and Support¶

• GitHub Repository: nouuu/voice-transcriber
• npm Package: voice-transcriber
• Issues: Report a bug or request a feature
• Discussions: GitHub Discussions

License¶

This project is licensed under the MIT License.