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:
```bash
git clone <repository-url>
cd closed-caption-app
```

2. Install dependencies:
```bash
npm install
```

3. Install Whisper (for local transcription):
   - See [INSTALL_WHISPER.md](INSTALL_WHISPER.md) for detailed instructions

4. Configure environment:
```bash
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:

```env
# 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:
```bash
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:
```bash
npm run dev
```

## Build

Build for distribution:
```bash
npm run build
```

## System Requirements

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

## Documentation

- [Settings Guide](SETTINGS.md) - Detailed guide for all settings and configuration options
- [Whisper Installation](INSTALL_WHISPER.md) - 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