Professional transcription with proofreading & custom vocabulary.

Quick install

Clone the repo, create virtual environment, install dependencies, then run. First launch fetches models automatically (can take 10–30 minutes depending on connection).

# 1) Clone
git clone https://github.com/travisgerrard/openscribe.git
cd openscribe

# 2) Check Python version (MUST be 3.11+)
python3 --version

# 3) Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 4) Upgrade pip and install Python deps
pip install --upgrade pip
pip install -r requirements.txt

# 5) Node deps
npm install

# 6) Start app (auto-downloads models on first run)
npm start

⚠️ Important: Always activate your virtual environment before running the app: source venv/bin/activate

Need help? See Troubleshooting section below.

Manual model setup (optional)

# Create folders
mkdir -p models vosk

# Parakeet speech model (~1.5GB)
# Place at: models/mlx-community/parakeet-tdt-0.6b-v2/

# LLM for proofreading (choose one)
# • models/mlx-community/Qwen3-14B-4bit-AWQ  (~8GB)
# • models/mlx-community/Qwen3-8B-4bit       (~4GB)

# Wake‑word (Vosk, ~100MB)
# Download from: https://alphacephei.com/vosk/models
# Extract under: vosk/vosk-model-small-en-us-0.15/

System requirements

• OS: macOS (primary), Windows, or Linux
• CPU: Modern 4‑core or better. Apple Silicon M1/M2+ or Intel/AMD ≥2.5 GHz recommended.
• Memory (RAM): Minimum 8 GB. Recommended 16 GB for smooth proofreading models; 24–32 GB if using larger 14B LLMs.
• Python: 3.11 or newer (required for MLX compatibility)
• Node.js: 16 or newer
• ffmpeg: Required for audio processing
• Disk space: 5–15 GB for models (recommend ≥20 GB free)
• Internet: Required on first run for auto‑downloaded models
• Microphone: Any input supported by your OS

Notes: the default Parakeet speech model is ~1.5 GB and runs well on 8–16 GB RAM. For optional proofreading LLMs, 8B‑class 4‑bit models are comfortable on 16 GB; 14B‑class 4‑bit may require 24 GB+.

🔧 Virtual Environment Setup

Virtual environments are required to manage Python dependencies properly.

# Create virtual environment
python3 -m venv venv

# Activate (run this EVERY time you open terminal)
source venv/bin/activate  # macOS/Linux
# OR
venv\Scripts\activate     # Windows

# Verify activation (should show venv path)
which python  # macOS/Linux
# OR
where python  # Windows

# Install/upgrade dependencies
pip install --upgrade pip
pip install -r requirements.txt

Remember: You must activate the virtual environment every time you open a new terminal window.

Hotkeys & wake‑words

• ⌘⇧A — Toggle active
• ⌘⇧D — Start dictation
• ⌘⇧S — Stop dictation
• ⌘⇧P — Proofread selection
• Say "note" / "dictate" — start dictation
• Say "proof" — start proofreading

Customize hotkeys and wake‑words in Settings → Shortcuts.

Models & Downloads

• Auto-download: Models download automatically on first run to models/ directory
• Download time: 10-30 minutes depending on internet speed
• Storage: Ensure ≥20GB free space for all models
• Cache location: Models stored in models/mlx-community/ and models/nightmedia/
• Manual override: See "Manual model setup" section above

Note: If you see "model not found" errors, the app will automatically re-download missing models.

Common Issues & Solutions

• Solution A: Switch to Whisper model in Settings → ASR Model
• Solution B: Ensure parakeet-mlx is installed: pip install parakeet-mlx
• Solution C: Delete corrupted models and let app re-download

• macOS: brew install python@3.11 or download from python.org
• Windows: Download Python 3.11+ from python.org
• Linux: sudo apt install python3.11 or use pyenv

• Check: Terminal prompt should show (venv)
• Activate: source venv/bin/activate
• Verify: which python should show venv path

• macOS: brew install ffmpeg (requires Homebrew)
• Windows: Download from ffmpeg.org or use winget install ffmpeg
• Linux: sudo apt install ffmpeg (Ubuntu/Debian) or sudo yum install ffmpeg (CentOS/RHEL)
• Verify: ffmpeg -version should show version info

Quick Fix Checklist

1. Python Version: python3 --version (must be 3.11+)
2. Virtual Environment: source venv/bin/activate
3. ffmpeg: ffmpeg -version (required for audio processing)
4. Dependencies: pip install -r requirements.txt
5. Node Modules: npm install
6. Model Directory: Check if models/ exists
7. Permissions: Ensure write access to project directory

Still stuck? Check the detailed troubleshooting guide on GitHub.

For developers

# Run tests
pytest

# Build (dev)
npm run build:python
npm run build:electron

# Build (dist)
npm run dist

See CONTRIBUTING.md for guidelines.

Privacy

OpenScribe processes audio locally. No recordings are sent to external servers, and this build includes no cloud model integrations.