lumi-ai 0.1.2

Speech-to-text utility with hotkey activation

Lumi

Lumi is a speech-to-text utility that lets you instantly transcribe your speech with a simple keyboard shortcut.

Quick Start

# Install Lumi
pip install lumi-ai

# Start Lumi
lumi

Then:

1. Double-tap Option key → Start recording
2. Speak clearly
3. Single-tap Option key → Stop recording
4. Your transcription appears instantly where your cursor is! As well as in your clipboard, so you can paste it.

That's it! No complicated setup or configuration needed.

NOTE! First time you run it, if using MLX it will need to download models, so might take a bit, when you see Speech-to-text service started. it means all is ready.

Features

• Easy activation with double-tap Option key hotkey
• Single-tap to stop recording (more intuitive)
• Automatically transcribes speech when recording stops using Groq, ElevenLabs APIs, or local MLX Whisper
• Copies transcription to clipboard and automatically pastes it
• Plays lightweight notification sounds when recording starts/stops
• Command-line interface with configuration options
• Primarily tested on macOS (may work on other platforms but not fully tested)

Requirements

• Python 3.12+
• PortAudio library (brew install portaudio on macOS)
• For local transcription (default):
  • MLX (Apple Silicon Macs only) - no API key needed
• For cloud transcription (optional):
  • Groq API key or
  • ElevenLabs API key

Installation

From PyPI

pip install lumi-ai

Or with uv:

uv pip install lumi-ai

After installation, you can use the lumi command directly from your terminal.

From Source

1. Clone this repository
2. Install dependencies with uv sync
3. Run with uv run -m src.lumi.s2t

Development Installation

For development:

uv pip install -e .

Advanced Configuration

Command-line Options

# Choose transcription service
lumi --service mlx            # Use local MLX Whisper (default, no API key needed)
lumi --service groq           # Use Groq API
lumi --service elevenlabs     # Use ElevenLabs API

# API keys
lumi --api-key YOUR_GROQ_API_KEY
lumi --service elevenlabs --elevenlabs-api-key YOUR_ELEVENLABS_API_KEY

# Specify models
lumi --service groq --model whisper-large-v3-turbo
lumi --service elevenlabs --model scribe_v1
lumi --service mlx --model mlx-community/whisper-large-v3-turbo

# Other options
lumi --no-auto-paste          # Disable auto-pasting
lumi --debug                  # Enable debug logging

Keyboard Controls

• Double-tap Option: Start recording
• Single-tap Option: Stop recording
• Ctrl+C: Exit application

Advanced Features

• Automatic fallback to alternative audio input devices
• Temporary recordings stored in system temp directory
• Sound notifications for recording start/stop
• Auto-paste functionality (can be disabled with --no-auto-paste)
• Platform-aware keyboard shortcuts (Cmd+V on macOS, Ctrl+V elsewhere)
• Debug mode for troubleshooting with detailed logging

Platform Support

• macOS: Fully supported and tested
• Linux/Windows: Basic functionality may work but not extensively tested
• MLX Whisper: Only works on Apple Silicon Macs

Development

• Install dependencies: uv sync
• Add dependency: uv add package_name
• Lint: ruff check .
• Format: ruff format .
• Test: pytest
• Test specific file: pytest path/to/test_file.py