closed-caption-app/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a live transcription desktop application built with Electron that provides real-time speech-to-text transcription with OBS integration. The app supports multiple transcription backends including local/remote Whisper and ElevenLabs Scribe, with GPU acceleration support.

Architecture

Main Components

• Electron Main Process (src/main.js): Manages application windows, starts the Express server, handles IPC communication between main window and display window
• Express Server (src/server/index.js): REST API server with Socket.IO for real-time communication, handles transcription requests and settings management
• Frontend Client (public/js/app.js): Main UI for recording controls, settings, and transcription display
• Display Window (public/display.html): Transparent overlay window for OBS capture

Backend Architecture

• Transcription Backends (src/server/backends/):
  • whisper.js: Local and remote OpenAI Whisper integration with queue management
  • elevenlabs.js: ElevenLabs Scribe API integration
• Utilities (src/server/utils/):
  • settingsManager.js: Persistent settings storage and management
  • transcriptionQueue.js: Queue system for managing audio processing
  • audioUtils.js: Audio processing utilities

Key Technologies

• Electron: Desktop app framework
• Express + Socket.IO: Real-time server communication
• MediaRecorder API: Browser audio recording
• Web Audio API: Audio level monitoring and analysis
• Multiple AI APIs: OpenAI Whisper, ElevenLabs Scribe

Development Commands

# Start the application in development mode (opens DevTools)
npm run dev

# Start the application normally
npm start

# Build for distribution
npm run build

# Run server only (for testing backend)
npm run server

Environment Configuration

Copy .env.example to .env and configure:

• WHISPER_MODEL: Local Whisper model size (tiny/base/small/medium/large)
• OPENAI_API_KEY: For remote Whisper API
• ELEVENLABS_API_KEY: For ElevenLabs Scribe
• AUDIO_THRESHOLD: Silence detection sensitivity (0.001-0.1)
• SERVER_PORT: Server port (default: 3000)

Settings System

The app uses a persistent settings system (src/server/utils/settingsManager.js) that:

• Stores settings in ~/.live-transcription/settings.json
• Provides UI override of environment variables
• Handles secure API key storage
• Syncs settings between client and server

Audio Processing Flow

1. Audio Capture: MediaRecorder captures microphone input in configurable chunks (1-5 seconds)
2. Level Monitoring: Web Audio API provides real-time audio level feedback
3. Transcription: Audio chunks sent to selected backend (Whisper Local/Remote or ElevenLabs)
4. Queue Management: Transcription queue prevents overload and manages processing order
5. Display: Results broadcast via Socket.IO to main window and OBS display window

Display Window System

The app creates two windows:

• Main Window: Controls, settings, and transcription preview
• Display Window: Transparent, always-on-top overlay for OBS capture
• IPC communication synchronizes settings and transcription data between windows

GPU Acceleration

Supports hardware acceleration detection and configuration:

• NVIDIA CUDA: Detected via nvidia-smi
• AMD ROCm: Detected via rocm-smi (Linux only)
• Intel OpenVINO: Detected via lspci for Intel GPUs

Common Development Patterns

• Settings are managed centrally and applied to both UI and backend
• Audio processing uses queues to prevent overwhelming backends
• Real-time communication via Socket.IO for transcription updates
• IPC handles communication between Electron windows
• Error handling includes graceful fallbacks for missing dependencies

Server Deployment

The git directory on the servers are /root/whp and once you do a git pull, to sync web files you would run the rsync command for web-files/ to /docker/whp/web/