KadeHeyborne/dictation-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dictation-service/README.md
Kade Heyborne 71c305a201
Major refactoring: v0.2.0 - Simplify to core dictation & read-aloud features 
This is a comprehensive refactoring that transforms the dictation service from a
complex multi-mode application into two clean, focused features:
1. Voice dictation with system tray icon
2. On-demand read-aloud via Ctrl+middle-click

## Key Changes

### Dictation Service Enhancements
- Add GTK/AppIndicator3 system tray icon for visual status
- Remove all notification spam (dictation start/stop/status)
- Icon states: microphone-muted (OFF) → microphone-high (ON)
- Click tray icon to toggle dictation (same as Alt+D)
- Simplify ai_dictation_simple.py by removing conversation mode

### Read-Aloud Service Redesign
- Replace automatic clipboard reader with on-demand Ctrl+middle-click
- New middle_click_reader.py service
- Works anywhere: highlight text, Ctrl+middle-click to read
- Uses Edge-TTS (Christopher voice) with mpv playback
- Lock file prevents feedback with dictation service

### Conversation Mode Removed
- Delete all VLLM/conversation code (VLLMClient, ConversationManager, TTS)
- Archive 5 old implementations to archive/old_implementations/
- Remove conversation-related scripts and services
- Clean separation of concerns for future reintegration if needed

### Dependencies Cleanup
- Remove: openai, aiohttp, pyttsx3, requests (conversation deps)
- Keep: PyGObject, pynput, sounddevice, vosk, numpy, edge-tts
- Net reduction: 4 packages removed, 6 core packages retained

### Testing Improvements
- Add test_dictation_service.py (8 tests) ✅
- Add test_middle_click.py (11 tests) ✅
- Fix test_run.py to use correct model path
- Total: 19 unit tests passing
- Delete obsolete test files (test_suite, test_vllm_integration, etc.)

### Documentation
- Add CHANGES.md with complete changelog
- Add docs/MIGRATION_GUIDE.md for upgrading
- Add README.md with quick start guide
- Update docs/README.md with current features only
- Add justfile for common tasks

### New Services & Scripts
- Add middle-click-reader.service (systemd)
- Add scripts/setup-middle-click-reader.sh
- Add desktop files for autostart
- Remove toggle-conversation.sh (obsolete)

## Impact

**Code Quality**
- Net change: -6,007 lines (596 added, 6,603 deleted)
- Simpler architecture, easier maintenance
- Better test coverage (19 tests vs mixed before)
- Cleaner separation of concerns

**User Experience**
- No notification spam during dictation
- Clean visual status via tray icon
- Full control over read-aloud (no unwanted readings)
- Better performance (fewer background processes)

**Privacy**
- No conversation data stored
- No VLLM connection needed
- All processing local except Edge-TTS text

## Migration Notes

Users upgrading should:
1. Run `uv sync` to update dependencies
2. Restart dictation.service to get tray icon
3. Run scripts/setup-middle-click-reader.sh for new read-aloud
4. Remove old read-aloud.service if present

See docs/MIGRATION_GUIDE.md for details.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-10 19:11:06 -07:00

1.2 KiB
Raw Permalink Blame History

Dictation Service

A Linux voice dictation service with system tray icon and on-demand text-to-speech.

Features

🎤 Dictation Mode (Alt+D)

  • Real-time voice-to-text transcription
  • Text automatically typed into focused application
  • System tray icon for visual status (no notifications)
  • Toggle on/off via Alt+D or tray icon click
  • High accuracy using Vosk speech recognition

🔊 Read-Aloud (Middle-Click)

  • Highlight text anywhere
  • Middle-click (scroll wheel press) to read it aloud
  • High-quality Microsoft Edge Neural TTS voice
  • Works in all applications
  • On-demand only (no automatic reading)

Quick Start

# 1. Install dependencies
uv sync

# 2. Setup dictation service
./scripts/setup-keybindings.sh
systemctl --user enable --now dictation.service

# 3. Setup read-aloud (optional)
./scripts/setup-middle-click-reader.sh

# 4. Use dictation
# Press Alt+D, speak, press Alt+D again

# 5. Use read-aloud
# Highlight text, middle-click

See docs/README.md for detailed documentation.

Requirements

  • Linux (GNOME/Wayland tested)
  • Python 3.12+
  • Microphone
  • System packages: portaudio19-dev, ydotool, xclip, mpv, GTK libraries

License

[Your License]