Files

T

trav e39bbaaddb Download translation models at deploy time instead of committing them

Removes the 664 MB models/ tree (history keeps it; no rewrite). The download
script now pins version 0.3.4, verifies every file against the registry's
SHA-256, writes latest.txt last so partial downloads are never served, and
accepts MODEL_PAIRS to fetch a subset.

2026-10-13 14:29:57 -07:00

3.3 KiB

Raw Permalink Blame History

CLAUDE.md

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

Project Overview

CAPTION.Ninja is a free browser-based captioning, transcription, and real-time translation tool for live streams and presentations. It runs entirely client-side with no build process - pure static HTML/CSS/JavaScript.

Development

No build, test, or lint commands - this is a static web project. Serve files directly via any HTTP server or open HTML files in a browser.

For local development:

# Any simple HTTP server works
python -m http.server 8000
# or
npx serve .

Architecture

Communication Pattern

All pages communicate via WebSocket (wss://api.caption.ninja:443) using room IDs:

Capture pages (input): Capture speech/text and broadcast to a room
Overlay pages (output): Subscribe to a room and display/translate/speak captions
Room ID: 16-char alphanumeric string stored in localStorage['cn_room_id']

Message format:

Final: {"msg": true, "final": "text", "id": counter, "label": label}
Interim: {"msg": true, "interm": "partial", "id": counter}

Key Files

Capture Pages (text producers):

index.html - Main capture, minimal UI, browser speech recognition
capture-pro.html - Enhanced capture with SRT/WebVTT export, keyboard shortcuts, autosave
manual.html - Manual text entry instead of speech
translate.html / translate_premium.html - Capture with translation

Overlay Pages (text display):

overlay.html - Main display overlay with optional translation/TTS
overlay_enhanced.html - Enhanced overlay with local translation, context, and styling options
overlay_roll.html - Credits-style scrolling overlay
transcript.html - Playlist controller for pre-written scripts

Workers & Utilities:

worker.js - Web Worker for Mozilla Bergamot translation
bergamot-translator-worker.js - WASM translation module (167KB)
tts-integration.js - TTS via tts.rocks (Kokoro, Piper, ElevenLabs, etc.)
security-utils.js - Room ID validation and security warnings

Translation System

Translation is local-only:

Mozilla Bergamot (free, local): 17 languages, runs in a Web Worker via WASM, uses models served from /models. Models are not committed: deployments fetch them with scripts/download-bergamot-models.sh (SHA-256 verified).
Remote translation providers (Google Cloud Translation, OpenAI-compatible, Anthropic) are not part of this fork.

URL Parameter Configuration

All functionality is configured via URL parameters - no build-time config needed. Key parameters:

?room=ID - Connect to specific room
?lang=en-US - Speech recognition language
?translate=es - Target translation language
?tts=en-US - Enable text-to-speech
?label=name - Speaker label
?clear - Clear on each message
?showtime=5000 - Auto-hide delay (ms)
?maxlines=N - Keep only N most recent lines
?dual=1 - Show translation + original together

External Dependencies

No npm packages. The static UI uses Mozilla Bergamot models served from /models (downloaded at deploy time, not committed) and native browser speech recognition/TTS. Optional third-party TTS services are opt-in via URL parameters.

Self-Hosting

Fork repo and use GitHub Pages. For private WebSocket server: https://github.com/steveseguin/websocket_server/

3.3 KiB Raw Permalink Blame History