About this project

## What it is ChatGPT Subtitle Translator is a translation utility built around the OpenAI ChatGPT API (or any OpenAI-compatible chat completion endpoint, including a local Ollama instance). Its focus is line-based translation, especially SRT subtitles, where preserving the correspondence between input and output lines matters for keeping subtitle timing intact. ## How it works SRT indices and timestamps are stripped or simplified before being sent to the model to reduce token usage. Lines are grouped into batches inside a single prompt, removing repeated per-entry overhead and allowing arbitrarily long files to be translated without excessive token consumption. The default system instruction is a minimal `Translate to <language>`. Five structured modes are selectable via `--structured`: - `array` (default): lines are sent as a JSON array and the model returns a matching array. - `object`: source lines become keys in the response schema, so no explicit user message is sent. - `timestamp`: timings are preserved alongside text using a compact Toon format with batch offset plus per-entry offset/length in milliseconds; the model may merge adjacent entries. Retries only occur when output time-span boundaries mismatch the input. - `agent`: alias for the agent subcommand with default options. - `none`: legacy mode without structured output. ## Features - Web UI (hosted on GitHub Pages) and CLI - Structured Output support, enabled by default in both interfaces - Prompt Caching support, controlled with `-c, --context` (CLI only) - Works with any OpenAI API compatible provider, e.g. local Ollama - Line-based batching with automatic batch sizing derived from the context token budget - Optional OpenAI Moderation check (`--use-moderator`, CLI only) to avoid wasting tokens on likely refusals - Streaming process output - Request-per-minute rate limiting - Progress resumption (CLI only) - Repetition-loop detection during streaming (`--guard-repetition`) ## Agent mode The `agent` subcommand runs multiple passes before translating: an overview pass samples the file to identify content, duration, genre/tone and character names and to detect the source language; a planning pass scans the file in token-bounded windows, producing batch summaries that are consolidated into a refined translation instruction; the translation pass then uses that enriched instruction and verifies the target language after the first batch. Options include `--no-refine`, `--no-fitting` and `--context-summary`. ## Setup and usage Node.js >= 20 is required. After cloning, run `npm install`, make `cli/translator.mjs` executable, copy `.env.example` to `.env` and add an API key. Typical invocations include `cli/translator.mjs --input subtitles.srt --from Japanese --to English`, plain-text input via `--plain-text`, and custom instructions via `--system-instruction`. Model, temperature, top_p, penalties and logit bias can be configured through standard OpenAI parameters.