Basic Usage Guide¶

Learn how to use Voice Transcriber effectively for everyday voice-to-text transcription.

System Tray Interface¶

Voice Transcriber operates through a system tray icon with three visual states:

Recording Audio¶

Start Recording¶

Method 1: Click tray icon

1. Left-click the system tray icon (green circle)
2. Icon changes to red
3. Start speaking into your microphone

Method 2: Context menu

1. Right-click the system tray icon
2. Select "Start Recording"
3. Icon changes to red
4. Start speaking

Stop Recording¶

Method 1: Click tray icon again

1. Left-click the system tray icon (red circle)
2. Icon changes to purple (processing)
3. Wait for transcription

Method 2: Context menu

1. Right-click the system tray icon
2. Select "Stop Recording"
3. Icon changes to purple (processing)

Automatic Clipboard Copy¶

Once processing completes:

1. Icon returns to green (idle)
2. Transcribed text is automatically copied to your clipboard
3. Paste anywhere with Ctrl+V (Linux) or Cmd+V (macOS)

Example Workflow¶

1. Click tray icon (🟢 → 🔴)
2. "Make a note to follow up with the client tomorrow"
3. Click again (🔴 → 🟣)
4. Wait 2-3 seconds
5. Paste in your notes app: "Make a note to follow up with the client tomorrow."

1. Click tray icon
2. "Hi team, I wanted to share an update on the project..."
3. Click again
4. Wait for processing
5. Paste in email client: "Hi team, I wanted to share an update on the project..."

1. Start recording at beginning of meeting
2. Let meeting proceed naturally
3. Stop recording at end
4. Paste transcription in notes document
5. Review and edit as needed

Context Menu Options¶

Right-click the tray icon for available actions:

🎤 Voice Transcriber
├── 🎙️ Start Recording
├── ⏹️ Stop Recording
├── ⚙️ Open Config
├── 🔄 Reload Config
└── ❌ Exit

Menu Actions¶

Start Recording

Begin audio capture (disabled while recording)

Same as left-click when idle

Stop Recording

End recording and transcribe (enabled only while recording)

Same as left-click when recording

Open Config

Opens configuration file in your default text editor

Always available

Reload Config

Reloads configuration without restarting the application

Only available when idle (not recording or processing)

Exit

Exit the application gracefully

Configuration Management¶

You can now manage configuration directly from the system tray menu without restarting the application.

Quick Configuration Workflow¶

1. Open Config: Right-click tray icon → "Open Config"
2. Edit: Make your changes in the text editor
3. Save: Save the configuration file
4. Reload: Right-click tray icon → "Reload Config" (when idle)

When to Use Reload Config¶

Reload Config is useful when you want to:

• Switch between transcription backends (OpenAI ↔ Speaches)
• Test different language settings
• Update API keys
• Change transcription or formatting prompts
• Enable/disable the formatter

Configuration Reload Safety¶

The reload process includes automatic safety checks:

• Validation: Configuration is validated before applying
• Rollback: Previous configuration is restored if reload fails
• Service reinitialization: All services are properly restarted with new settings

If reload fails, you'll see an error message and the previous configuration will be restored automatically.

Debug Mode¶

Enable debug mode for detailed logging and performance metrics:

voice-transcriber --debug

What Debug Mode Shows¶

Debug mode provides detailed information about:

• File sizes: WAV and MP3 file sizes with compression ratios
• Audio format: Sample rate, channels, conversion details
• Processing times: Breakdown of upload, processing, and response times
• Transcription details: Character count, duration metrics

Example Debug Output¶

2025-10-11T10:30:15.123Z [DEBUG] WAV file size: 2.45 MB (2569216 bytes)
2025-10-11T10:30:15.125Z [DEBUG] WAV format: 2 channel(s), 44100 Hz sample rate
2025-10-11T10:30:15.234Z [DEBUG] MP3 file size: 0.62 MB (650240 bytes)
2025-10-11T10:30:15.234Z [DEBUG] Compression ratio: 74.7% size reduction
2025-10-11T10:30:15.234Z [DEBUG] WAV to MP3 conversion completed in 0.11 seconds
2025-10-11T10:30:16.789Z [INFO] OpenAI transcription completed in 1.55s
2025-10-11T10:30:16.789Z [DEBUG]   └─ Estimated breakdown: upload ~0.47s, processing ~0.93s, receive ~0.16s
2025-10-11T10:30:16.789Z [DEBUG]   └─ Transcription length: 142 characters

When to Use Debug Mode¶

Disabling Debug Mode¶

Simply run without the --debug flag:

voice-transcriber

Best Practices¶

For Accuracy¶

For Efficiency¶

For Multilingual Use¶

Common Use Cases¶

Note Taking¶

Perfect for: Meeting notes, lecture notes, brainstorming sessions

Tips: - Record entire meeting or lecture - Transcribe in segments for easier review - Edit transcription afterward for clarity

Message Dictation¶

Perfect for: Emails, chat messages, social media posts

Tips: - Speak naturally but with clear punctuation - Enable formatter for proper capitalization - Review before sending

Content Creation¶

Perfect for: Blog posts, articles, scripts

Tips: - Outline first, then dictate sections - Use short recordings for easier editing - Transcribe ideas quickly without typing

Accessibility¶

Perfect for: Users with typing difficulties, RSI, or mobility issues

Tips: - Configure comfortable microphone position - Use voice commands in conjunction with transcription - Combine with accessibility tools in your OS

Performance Expectations¶

Transcription Speed¶

Accuracy Expectations¶

Keyboard Shortcuts (Future Feature)¶

Next Steps¶

• Language Support - Multilingual transcription
• Transcription Backends - OpenAI vs Speaches
• Troubleshooting - Common issues and solutions