closed-caption-app/README.md

Live Transcription App

A desktop application for live speech-to-text transcription with OBS compatibility. Supports multiple transcription backends including local/remote Whisper and ElevenLabs Scribe, with GPU acceleration for NVIDIA, AMD, and Intel GPUs.

Features

• Multiple Transcription Backends:

  • Whisper (Local) - Run OpenAI's Whisper model locally
  • Whisper (Remote) - Use OpenAI's Whisper API
  • ElevenLabs (Scribe) - Use ElevenLabs' Scribe v1 speech-to-text API

• OBS Integration:

  • Transparent/frameless window mode
  • Always-on-top option
  • Customizable text display

• Customization Options:

  • Text duration control (1-60 seconds)
  • Text and background colors
  • Font selection (system fonts + Google Fonts)
  • Adjustable font size (16-72px)

• Advanced Features:

  • GPU acceleration (NVIDIA CUDA, AMD ROCm, Intel OpenVINO)
  • Ambient noise calibration
  • Persistent settings storage
  • Real-time audio level monitoring
  • Queue management for optimal performance
  • Configurable transcription speed (1-5 second chunks)

Installation

1. Clone the repository:

git clone <repository-url>
cd closed-caption-app

2. Install dependencies:

npm install

3. Install Whisper (for local transcription):

   • See INSTALL_WHISPER.md for detailed instructions

4. Configure environment:

cp .env.example .env
# Edit .env with your API keys

Configuration

Settings Page

Access the settings page by clicking the ⚙️ Settings button in the main interface. The settings page allows you to:

• Configure API keys for OpenAI and ElevenLabs
• Select Whisper model size (tiny to large)
• Enable GPU acceleration (auto-detects NVIDIA/AMD/Intel)
• Calibrate ambient noise levels
• Customize display settings (fonts, colors, duration)
• Test API connections
• Save settings persistently

Environment Variables (Optional)

You can also edit .env file for initial configuration:

# For local Whisper
WHISPER_MODEL=base

# For remote Whisper (OpenAI API)
OPENAI_API_KEY=your_api_key_here

# For ElevenLabs speech-to-text
ELEVENLABS_API_KEY=your_api_key_here

# Audio threshold for silence detection
AUDIO_THRESHOLD=0.01

Note: Settings configured through the UI will override environment variables.

Usage

1. Start the application:

npm start

2. Click ⚙️ Settings to configure:

   • API keys for remote services
   • GPU acceleration (if available)
   • Audio threshold and ambient noise calibration
   • Display preferences

3. Select your preferred transcription backend

4. Configure display settings (color, font, duration)

5. Click "Start Recording" to begin transcription

6. Use "Open Display Window" for OBS capture

Ambient Noise Calibration

1. Go to Settings → Audio Processing
2. Click "Start Calibration"
3. Stay quiet for 10 seconds
4. The app will learn your room's ambient noise level
5. Threshold will be automatically adjusted

OBS Setup

1. Add a "Window Capture" source in OBS
2. Select "Live Transcription" window
3. Enable "Allow Transparency" in the source properties
4. Position and scale as needed

Keyboard Shortcuts

• ESC - Exit display mode (when in fullscreen)

Development

Run in development mode:

npm run dev

Build

Build for distribution:

npm run build

System Requirements

• Node.js 16+
• Python 3.8+ (for local Whisper)
• ffmpeg (for audio processing)
• Microphone access

Documentation

• Settings Guide - Detailed guide for all settings and configuration options
• Whisper Installation - Complete guide for installing Whisper with GPU support

Troubleshooting

No transcription appearing

• Check microphone permissions
• Verify selected backend is configured (use Settings page)
• Check audio level meter is responding to sound
• Verify audio threshold isn't too high

Whisper local not working

• Ensure Whisper is installed: whisper --help
• Check Python and ffmpeg are in PATH
• Try a smaller model (tiny/base) for testing
• Check GPU detection in Settings if using acceleration

Window not transparent in OBS

• Enable "Allow Transparency" in OBS source settings
• Use the separate display window (Open Display Window button)

High CPU/GPU usage

• Use Settings to select smaller Whisper model
• Increase transcription chunk size (3-5 seconds)
• Calibrate ambient noise to reduce unnecessary processing
• Check queue status for backlog