This release is a pre-release and may not be stable for production use.
AI Subtitle Translator
Built for Bazarr+. Ready for your own app.
Translate SRT files and subtitle lines through OpenRouter. Run the service on your own machine, choose a model, and follow each job from submission to translated output.
Get started · Models & costs · Web UI · Use the API · Configuration
- SRT in, SRT out. Subtitle files and right-to-left language support.
- Choose your model. OpenRouter models with per-request provider routing.
- Track your jobs. Immediate translation or queued jobs with progress and reported costs.
What could a season cost?
The latest full-file run translated 1,340 cues with Luna for $0.0466. Scaling that result to 24 forty-minute episodes at 15 cues/minute gives roughly $0.50 for one target language. This is a budgeting estimate, not a measured season bill. See the current results, formula and limits.
Quick start
With Bazarr+
For the published image, run this on your Docker host:
curl -sSL https://raw.githubusercontent.com/LavX/ai-subtitle-translator/main/install.sh | bash
The installer detects containers named bazarr or bazarr-ui-test, configures networking and prints the encryption key.
- Open AI Subtitle Translator settings in Bazarr+.
- Enter a translator URL reachable from Bazarr+, the printed encryption key, your OpenRouter API key and an explicit model such as
openai/gpt-5.6-luna:smartfastto match the benchmark routing. - Click Test, then Save.
On a shared custom Docker network, use http://ai-subtitle-translator:8765. Across separate bridge networks, use the Docker host's IP and published port. localhost works only when Bazarr+ shares the host network or runs directly on that host. See the Bazarr+ Setup Guide.
As a library
pip install lavx-ai-subtitle-translator # the core and the built-in back ends
pip install "lavx-ai-subtitle-translator[server]" # plus the HTTP service and GUI
The core never reads environment variables: build a CoreSettings and pass it in.
Docker
git clone https://github.com/LavX/ai-subtitle-translator.git
cd ai-subtitle-translator
# Set your OpenRouter API key and a recommended model
cat > .env <<'EOF'
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_DEFAULT_MODEL=openai/gpt-5.6-luna:smartfast
EOF
docker compose up -d
Service runs at http://localhost:8765. Interactive docs at /docs. The named translator-data volume preserves the database and encryption key. Follow Authentication before calling protected endpoints.
Manual
git clone https://github.com/LavX/ai-subtitle-translator.git
cd ai-subtitle-translator
python -m venv venv && source venv/bin/activate
pip install -e ".[server]"
export OPENROUTER_API_KEY=sk-or-...
export OPENROUTER_DEFAULT_MODEL=openai/gpt-5.6-luna:smartfast
mkdir -p data
export DB_PATH="$PWD/data/jobs.db"
export ENCRYPTION_KEY_FILE="$PWD/data/encryption.key"
ai-subtitle-translator serve --host 0.0.0.0 --port 8765
The source-build examples select Luna with local :smartfast routing. See model recommendations for quality, cost and compatibility notes.
Upgrading from 2.1.x
The package is now published as lavx-ai-subtitle-translator, and requirements.txt is gone: the
dependencies live in pyproject.toml, and the HTTP server is the server extra. For a manual
install, remove the old distribution first, because both own the same subtitle_translator files:
pip uninstall ai-subtitle-translator
pip install ".[server]" # from a checkout; or: pip install "lavx-ai-subtitle-translator[server]"
The ai-subtitle-translator command, the uvicorn subtitle_translator.main:app entry point and the
HTTP API are unchanged, so Docker users only need to pull the new image.
Data-collection handling is stricter than in 2.1.x. A request whose config pins backend to
Gemini or an OpenAI-compatible connection and also sets provider.dataCollection: "deny" is now
refused with a validation error, and a request that sets deny without a pin no longer fails over to
those back ends, because they cannot promise that no data is collected. provider.only and
provider.ignore on those pins are ignored and logged.
Admins who set OPENROUTER_DENY_DATA_COLLECTION=true and also keep a Gemini or OpenAI-compatible
back end in BACKEND_ORDER lose that fallback: the setting now limits failover to OpenRouter
connections, the same as a per-request deny. Remove the setting to keep the fallback, or accept
that those back ends cannot promise that no data is collected.
Optional web UI
Enable the standalone subtitle studio for single-file or batch SRT translation:
UI_ENABLED=true
Add that setting to .env for the supplied Compose setup, then run docker compose up -d --build. For a manual installation, export UI_ENABLED=true before starting the service. Open http://localhost:8765/ui/, or use your server's host name and port. The UI is disabled by default and adds no frontend build step or external CDN dependency.
- Enter your OpenRouter API key and click Connect. No service token or encryption key is needed in the GUI. Connection checks use OpenRouter's key endpoint, without making a translation request.
- Optionally select Remember on this device to save and reuse the validated key in this browser. Forget saved key removes it and disconnects. Unchecking Remember also removes the saved copy.
- Add UTF-8
.srtfiles, choose the source and target languages, and select a model or enter a custom ID. Luna is preselected, with the full OpenRouter catalog available. Choose Lowest price (:floor, the default), Fastest (:nitro), SmartFast (price + speed), or OpenRouter default routing. Service tier starts at Standard, which keeps that routing preference while disabling automatic Flex and priority tier selection. Follow routing allows discounted Flex with:flooror priority capacity with:nitro. SmartFast uses standard capacity unless you explicitly choose another tier through a provider restriction or the API. - Translate the batch, follow each file's progress and reported cost, then download individual SRTs or the ready results as a ZIP.
The preview supports side-by-side comparison, subtitle italics/bold/underline, cue search, direct cue entry and keyboard navigation. Partial downloads show translated-cue coverage separately from completed batches. Request options sets a provider deadline of 2, 5 or 10 minutes; the UI starts at 2 minutes, and a request that stalls is retried once at the same size before the batch is split. A longer deadline gives slow routes more time, but does not guarantee provider availability. Flex capacity can be much slower or unavailable. Standard capacity can cost more than the catalog price and the historical :floor estimates. See OpenRouter service tiers and service compatibility.
To select a specific provider, open Request options and enter its OpenRouter ID in Provider, for example azure. The request is restricted to that provider with fallbacks disabled, so it must serve the selected model. Leave it empty for automatic selection. Routing and tier settings still apply, but a tier-specific endpoint ID can change the eligible tier and price. This can help when one provider is slow, but does not guarantee availability.
SmartFast filters providers by price and estimated request time, then keeps each job with an eligible provider when possible. Selecting it reveals five controls in Request options: median premium (50%), speed tolerance (20%), sparse pool multiplier (3), maximum input price ($1 per million tokens), and maximum output price ($3 per million tokens). These are quoted rate limits, not a total bill budget. Cache hits and faster translations are not guaranteed. See SmartFast routing for selection rules, API examples and Bazarr+ model suffix usage. The full-file SmartFast benchmark below is separate from the historical routing comparisons.
Reasoning starts at Off, which explicitly disables reasoning for subtitle translation. Model default omits the setting, and catalog-supported effort levels are available when reported. A model that declares mandatory reasoning cannot use Off. Changing models keeps your explicit selection and explains incompatible choices before you submit. Custom model IDs remain usable with Off or Model default; the backend checks metadata when available.
The queue shows files awaiting submission, active jobs and downloadable outputs, with partial downloads counted separately. Job messages show the latest reported request, backoff and timeout recovery activity. Elapsed time and an accepted API key do not confirm translated output. If an older server has no activity detail, the UI says so. Terminal errors retain attempted and unattempted batch counts, including after restoring history.
GUI translations always use the OpenRouter key you entered. The GUI never falls back to the server's configured key. Its session shows only GUI jobs belonging to that key; people sharing a key share access to those jobs. Existing service-token API clients keep their authentication flow and do not list GUI jobs.
Remembering is opt-in and uses browser local storage, so save a key only on a trusted device. Without it, the browser keeps the key only for the current session. Disconnect clears the in-memory key; a saved key remains available until you forget it. Your key and subtitles pass through this self-hosted service to OpenRouter. Use HTTPS when accessing the service across an untrusted network.
Batch translation submits one job per file, not OpenRouter's asynchronous batch API. Queued and running jobs can be cancelled from the queue; a cancelled running job stops its provider requests and frees its worker. Forget removes a finished job and its result from the server. Partial results are marked and remain downloadable. The queue lists the newest event first: a job that just finished or a file you just added moves to the top. After a reload, the GUI restores retained jobs automatically when you connect with the same key. A remembered key reconnects automatically. Connection interruptions leave the last known progress visible while the GUI reconnects. Submissions are never automatically replayed.
The GUI is served by the application. Its Python controller calls the job manager directly, using one same-origin /ui/session WebSocket for browser commands and live updates. Browser state is plain JSON, with no custom encryption layer. Reverse proxies must forward WebSocket upgrades. Queued cancellation preserves results if a job finishes before the command arrives. Existing HTTP API clients remain supported. Per-job keys use the service's existing encryption at rest. If encryption is disabled, keys are not persisted, and interrupted GUI jobs fail after a restart instead of using the server's key.
Authentication
Encryption is enabled by default. Translation, job, configuration and status endpoints require an X-Auth-Token derived from the shared encryption key. Bazarr+ handles this automatically after you configure that key.
For the Docker setup, derive a token without copying the encryption key into your shell:
AUTH_TOKEN=$(docker exec ai-subtitle-translator python -c '
import hashlib, hmac, os
from pathlib import Path
key = os.environ.get("ENCRYPTION_KEY") or Path(
os.environ.get("ENCRYPTION_KEY_FILE", "/app/data/encryption.key")
).read_text().strip()
print(hmac.new(bytes.fromhex(key), b"subtitle-translator-auth-v1", hashlib.sha256).hexdigest())
')
curl -H "X-Auth-Token: $AUTH_TOKEN" http://localhost:8765/api/v1/status
For a manual installation, run the same Python command without docker exec ai-subtitle-translator, in the shell where you exported ENCRYPTION_KEY_FILE.
/health, /api/v1/models, /docs, /redoc and /openapi.json are public. PUT /api/v1/config also requires X-Admin-Key when ADMIN_API_KEY is set. Disabling encryption skips token authentication; a configured admin key still protects configuration writes.
Encrypted API keys, key rotation and disabling encryption
API key encryption
API keys sent between clients and the translator can be encrypted in transit using AES-256-GCM with a pre-shared key. This protects the API-key field only; subtitle text and the authentication token still need HTTPS when crossing an untrusted network.
How it works
- On first startup, the translator generates an encryption key and saves it to
/app/data/encryption.key - Read the key:
docker exec ai-subtitle-translator cat /app/data/encryption.key - Paste the 64-character hex key into Bazarr+'s AI Subtitle Translator settings
- Bazarr+ encrypts the OpenRouter API key before sending it in requests
- The translator decrypts it on receipt
- The same key is used to derive the auth token (see Authentication)
Encrypted API keys use the format enc:base64data. Plaintext keys are accepted by default. Set ENCRYPTION_STRICT=true to require encrypted per-request keys on translation endpoints. The current /test and PUT /config handlers do not enforce this check.
Test encryption
curl -X POST http://localhost:8765/api/v1/test \
-H "Content-Type: application/json" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-d '{"apiKey": "enc:your-encrypted-key-here"}'
Returns encryption status and OpenRouter API key validation in one call.
Regenerate key
# Via CLI (inside container)
docker exec ai-subtitle-translator python -m subtitle_translator.cli regenerate-key
# Or set via environment variable (overrides key file)
docker run -e ENCRYPTION_KEY=your64charhexkey... ...
Restart the service after changing the key file and update clients to use the new key. Existing persisted per-request keys encrypted with the old key cannot be decrypted with the new one.
Disable encryption
docker run -e ENCRYPTION_ENABLED=false ...
Subtitle translation leaderboard
Start with Mercury 2.5 if cost matters, Gemini 2.5 Flash Lite if speed does, Luna if quality does. In the September 15, 2026 run, twelve models delivered a file and eight of those had no mechanical defect at all. Mercury finished a feature film for $0.0142, Gemini 2.5 Flash Lite in under 40 seconds, and Luna read best of anything tested, at three times Mercury's price.
11 of 24 models returned a complete file inside ten minutes. Every model below translated the same 1,338-cue English subtitle into Hungarian through the queued API, with SmartFast routing at its defaults and a 600-second cap.
| Model ID | Result | Seconds | Requests | Observed cost, USD | Defect cues | Reading |
|---|---|---|---|---|---|---|
inception/mercury-2.5 |
Complete | 70.7 | 17 | $0.0142 | 0 | Usable |
deepseek/deepseek-v4-flash |
Complete | 142.8 | 21 | $0.0145 | 0 | Reliable |
tencent/hy-mt2-30b-a3b |
Complete | 93.2 | 41 | $0.0165 | 234 | Usable |
tencent/hy-mt2-7b |
Complete | 103.1 | 42 | $0.0167 | 3 | Weak |
meta/muse-spark-1.2-contributor |
Complete | 114.2 | 17 | $0.0176 | 0 | Reliable |
tencent/hy-mt2-1.8b |
Partial, 1333 | 113.0 | 202 | $0.0178 | 22 | Unusable |
google/gemma-4-26b-a4b-it |
Complete | 290.1 | 23 | $0.0182 | 15 | Weak |
meta/muse-spark-1.3-contributor |
Complete | 192.0 | 17 | $0.0184 | 0 | Reliable |
inclusionai/ling-3.0-flash-vl |
Complete | 577.2 | 19 | $0.0201 | 0 | Usable |
google/gemini-2.5-flash-lite |
Complete | 39.7 | 18 | $0.0212 | 0 | Usable |
openai/gpt-5.6-luna |
Complete | 85.4 | 17 | $0.0446 | 0 | Reliable |
deepseek/deepseek-v4.1-flash |
Complete | 256.3 | 21 | $0.1893 | 0 | Reliable |
Defect cues counts cues carrying a foreign writing system, invented markup, or untranslated English, over the whole delivered file. tencent/hy-mt2-30b-a3b writes good Hungarian but inserted 234 <i> and <br> tags into a file that has none. google/gemma-4-26b-a4b-it dropped Chinese, Korean and Sinhala into nine cues. Reading is a grouping from a fixed 14-cue sample chosen for difficulty before any output existed; it is not a score.
Twelve models did not finish inside the cap, led by deepseek/deepseek-v4-flash-0731 at 94% and tencent/hy3 at 88%, down to nvidia/nemotron-3.5-lightning:free at 0%. Not one free model finished the film, in this run or in September 10's. A capped job reports no usage, so its cost is unknown rather than zero.
Timing above roughly 200 seconds is a range rather than a measurement: deepseek/deepseek-v4-flash-0731 completed in 483 seconds on one run and capped at 94% on the next. google/gemini-2.5-flash-lite is the steadiest, landing within a few seconds and a fraction of a cent across four runs.
Worth knowing: the three Tencent Hy-MT2 models top OpenRouter's usage ranking for the translation task. On this workload they produced the three weakest results of everything that finished.
How this was measured
Jobs went through POST /api/v1/jobs/translate/content with an encrypted per-request key, the wire format Bazarr+ uses, in waves of five against a container started fresh for each wave. 100-cue batches, four parallel batches, temperature 0.3 where supported, reasoning unspecified, a 600-second provider timeout and a 600-second cap per job. SmartFast ran at its defaults: median +50%, sparse-pool 3x, a 20% estimated-speed band, and $1 input / $3 output per million token ceilings.
SmartFast is worth having on. Routing deepseek/deepseek-v4-flash-0731 by throughput instead sent it to an endpoint charging $0.44/$1.32 per million against the $0.04/$0.10 available elsewhere for the same model, and the same film cost $0.3369 instead of $0.0597.
Six models could not be benchmarked for reasons outside the model: three free Ling variants are refused by an account data-policy setting, both Inkling variants are restricted to agentic harnesses, and nex-agi/nex-n2.5-mini:free has a single endpoint OpenRouter reports as unhealthy.
Episode, movie and season cost estimates
For a rough Mercury budget, scale its measured $0.0142 per 1,338 cues by your file's cue count. At an illustrative 15 cues/minute, a 20-minute episode is about $0.0032, a two-hour movie $0.0191, and 24 forty-minute episodes $0.1529. For Luna, multiply by about 3.1. These are extrapolations from one run, not measured bills. Text density, reasoning, provider prices, retries and cache usage all move them, and time does not scale linearly because batches run in parallel.
estimated Mercury cost = 0.0142 × your cue count / 1338
Raw results and earlier runs
- September 15 cohort report, with the full results, the defect counts and the sampled reading, plus its CSV and defect CSV.
- September 10 run report and CSV, on the build that became v2.0.0, with its own quality findings.
- Historical benchmarks: September 7 smoke tests and September 9 routing/retry runs, with their original settings and limitations.
- Translated subtitle text and the raw provider captures are not kept in the repository. The figures taken from them are in the reports and CSVs.
How it fits together
flowchart LR
A["Bazarr+ or your HTTP client"] --> B["AI Subtitle Translator"]
B --> C["OpenRouter · selected model"]
C --> B
B --> D["Translated subtitles"]
The service handles batching, retries and queued-job progress. OpenRouter routes model inference. Job history lives in SQLite; review the restart and recovery limits before relying on unattended workloads.
API endpoints
Full interactive docs at /docs (Swagger) or /redoc when running. File endpoints accept JSON with a content string containing SRT text, not multipart uploads. Content endpoints accept a lines array.
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET |
/health |
Health check | |
GET |
/api/v1/models |
List recommended translation models and metadata | |
GET |
/api/v1/status |
token | Service status and queue stats |
GET |
/api/v1/config |
token | Current configuration |
PUT |
/api/v1/config |
token | Update config at runtime |
POST |
/api/v1/translate/content |
token | Translate subtitle lines (synchronous) |
POST |
/api/v1/translate/file |
token | Translate SRT file (synchronous) |
POST |
/api/v1/jobs/translate/content |
token | Submit async translation job |
POST |
/api/v1/jobs/translate/file |
token | Submit async SRT translation job |
GET |
/api/v1/jobs |
token | List all jobs (filter by status) |
GET |
/api/v1/jobs/{id} |
token | Job status, progress, metrics, and result |
DELETE |
/api/v1/jobs/{id} |
token | Cancel a queued job or delete a finished job |
POST |
/api/v1/test |
token | Test encryption and API key validity |
Endpoints marked token require an X-Auth-Token header when encryption is enabled (see Authentication).
Translate subtitle content
curl -X POST http://localhost:8765/api/v1/translate/content \
-H "Content-Type: application/json" \
-H "X-Auth-Token: $AUTH_TOKEN" \
-d '{
"sourceLanguage": "en",
"targetLanguage": "hu",
"title": "Breaking Bad",
"lines": [
{"position": 1, "line": "Say my name."},
{"position": 2, "line": "You are goddamn right."}
]
}'
Submit async translation job
curl -X POST http://localhost:8765/api/v1/jobs/translate/content \
-H "Content-Type: application/json" \
-H "X-Auth-Token: $AUTH_TOKEN" \
-d '{
"sourceLanguage": "en",
"targetLanguage": "hu",
"title": "Breaking Bad S05E07",
"mediaType": "Episode",
"fileName": "breaking.bad.s05e07.srt",
"jobName": "bb-s05e07-hungarian",
"lines": [
{"position": 1, "line": "Say my name."}
],
"config": {
"model": "openai/gpt-5.6-luna:smartfast",
"temperature": 0.3,
"reasoning": {"effort": "low"},
"parallelBatches": 4
}
}'
Example job status and cancellation behavior
Job status response
Poll GET /api/v1/jobs/{id} for live progress and metrics:
{
"jobId": "3f1318c0-...",
"status": "processing",
"progress": 66,
"message": "Translated 400/600 lines (4/6 batches)",
"jobName": "bb-s05e07-hungarian",
"fileName": "breaking.bad.s05e07.srt",
"sourceLanguage": "en",
"targetLanguage": "hu",
"title": "Breaking Bad S05E07",
"mediaType": "Episode",
"model": "openai/gpt-5.6-luna:smartfast",
"totalLines": 600,
"totalBatches": 6,
"completedBatches": 4,
"completedLines": 400,
"tokensUsed": 25000,
"totalCost": 0.0084,
"elapsedSeconds": 12.5
}
Job statuses: queued | processing | completed | partial | failed | cancelled
Processing jobs cannot currently be cancelled. Deleting a processing job returns its current status without stopping translation. A partial result includes translated lines and original text for lines that could not be translated.
Per-request config override
Every translate endpoint accepts an optional config block to override defaults:
{
"config": {
"apiKey": "sk-or-different-key",
"model": "deepseek/deepseek-v4-flash-0731:floor",
"temperature": 0.5,
"parallelBatches": 2,
"reasoning": {"effort": "low"},
"provider": {"sort": "floor"}
}
}
Reasoning effort levels: xhigh, high, medium, low, minimal, none. The none value explicitly disables reasoning. Omitting reasoning settings retains model defaults.
Provider routing (provider.sort) decides which OpenRouter provider serves the model:
| Value | What is sent | Effect |
|---|---|---|
throughput (default when nothing is sent) |
provider.sort: throughput |
Fastest provider first |
price |
provider.sort: price |
Cheapest provider first |
latency |
provider.sort: latency |
Lowest latency first |
nitro |
model:nitro slug shortcut |
Fastest, and priority-tier endpoints become eligible |
floor |
model:floor slug shortcut |
Cheapest, and flex-tier endpoints become eligible |
smartfast |
Filtered provider.only, mandatory max_price, and session_id |
Price limits, estimated speed and affinity for each job; see SmartFast |
default |
nothing | OpenRouter's own load balancing |
nitro and floor are supersets of the matching sort. OpenRouter does not stack slug variants, so on a slug that already carries one (:thinking, :free, ...) they fall back to the plain throughput/price sort. A :nitro or :floor typed straight into the model id is honoured as-is and no competing sort is sent. For these existing routes, provider.order, only, ignore and allowFallbacks are passed through unchanged.
SmartFast accepts config.provider.sort: "smartfast" or a trailing :smartfast on the model ID. The translator removes that local suffix before calling OpenRouter and preserves underlying variants, including model:free:smartfast and model:thinking:smartfast. Tune it with config.provider.smartFast; the SmartFast guide lists all fields and bounds. Manual provider order, stacked routing shortcuts and a competing sort are rejected. Explicit only, ignore and allowFallbacks: false restrictions remain effective within SmartFast's limits.
Per-request config.serviceTier accepts default (standard capacity), flex, or priority. It is forwarded as OpenRouter's top-level service_tier. Setting default prevents route shortcuts from admitting Flex and priority tiers, while retaining their price or throughput sorting. Outside SmartFast, omitting it preserves OpenRouter's routing-based tier selection. SmartFast uses standard endpoints when it is omitted, unless an explicit only restriction selects another tier. The GUI explicitly selects standard capacity for new submissions; existing API clients retain their current behavior.
When a library caller gives a job a cost budget, ordinary OpenRouter routing (not only SmartFast) sends the catalog prices the budget reserved, and a zero per-request fee, as provider.max_price, so no endpoint or service tier above them can serve the request and spend what the budget never held. A lower cap the request already carries stays; a model whose prices the catalog does not list is sent no cap and is held by reported cost only.
Configuration
The table lists application defaults. For manual runs, most settings load from environment variables or a .env file in the working directory. LOG_LEVEL and CORS_ALLOWED_ORIGINS read the process environment directly: export them for manual runs. Docker Compose only forwards the variables explicitly listed in docker-compose.yml. That covers the ones in .env.example except JOB_QUEUE_MAX_CONCURRENT, JOB_QUEUE_MAX_JOBS and JOB_QUEUE_TTL_HOURS, which Compose does not pass on: add them to the environment section to change the job queue limits. Add the <TYPE>_<FIELD> variables of an installed extension back end to that section as well. The Compose default model is google/gemini-2.5-flash-lite, which differs from the application default below. Set a model ID available to your OpenRouter account explicitly.
| Variable | Default | Description |
|---|---|---|
OPENROUTER_API_KEY |
(empty) | Default OpenRouter API key; required for translation unless supplied in request config |
OPENROUTER_DEFAULT_MODEL |
amazon/nova-2-lite-v1:free |
Default translation model |
OPENROUTER_TEMPERATURE |
0.3 |
Sampling temperature |
OPENROUTER_MAX_TOKENS |
8000 |
Room the reply gets for the translation itself, sent as max_tokens. Reasoning is paid for out of the same allowance, so a reasoning request raises what is sent: a declared reasoning budget is added on top, and an effort level (or a model that always reasons) multiplies it, because effort buys a share of the total. The result is held under the output ceiling the catalog publishes for the model's top provider, and a model that accepts no budget parameter is sent none. 0 or any non-positive value sends no budget, which lets OpenRouter reserve the model's full output ceiling against your balance: a free account rarely has the credit for that |
BACKEND_ORDER |
openrouter,gemini |
Back ends to try, in order. A back end with no key or sign-in is skipped; add openai_compatible or the type id of an installed back-end package to use it |
OPENROUTER_DENY_DATA_COLLECTION |
false |
Send provider.data_collection: deny, so OpenRouter uses only providers that do not collect user data. It also limits failover: only OpenRouter connections are tried, so a Gemini or OpenAI-compatible fallback in BACKEND_ORDER is never used. A request that pins one of those back ends is refused with a validation error, and so is every request when the server has no OpenRouter connection. A request can state its own dataCollection (allow) to override it |
GEMINI_API_KEYS |
(empty) | Comma-separated Google Gemini API keys |
GEMINI_KEY_PROJECTS |
(empty) | The Google Cloud project of each key, in the same order, so keys from one project share its limits |
GEMINI_MODEL |
gemini-3.6-flash |
Gemini model |
GEMINI_BATCH_SIZE |
300 |
Max subtitle lines per Gemini batch |
GEMINI_REASONING |
disabled |
Gemini reasoning mode |
GEMINI_PRICE_INPUT |
0 |
USD per million input tokens; 0 reports usage with no cost and holds nothing |
GEMINI_PRICE_OUTPUT |
0 |
USD per million output tokens |
OPENAI_COMPATIBLE_PRESET |
(empty) | openai, lmstudio, ollama or custom |
OPENAI_COMPATIBLE_BASE_URL |
(preset) | Server address, for example http://192.168.1.10:1234/v1 |
OPENAI_COMPATIBLE_MODEL |
(empty) | Model name the server serves |
OPENAI_COMPATIBLE_API_KEY |
(empty) | Only if the server asks for one |
OPENAI_COMPATIBLE_PRICE_INPUT, OPENAI_COMPATIBLE_PRICE_OUTPUT |
0 |
USD per million input and output tokens; required for the OpenAI preset. OPENAI_COMPATIBLE_PRICE_INPUT_PER_MILLION and ..._OUTPUT_PER_MILLION are the same settings under the names Bazarr+ uses, and win when both are set |
OPENAI_COMPATIBLE_TEMPERATURE, OPENAI_COMPATIBLE_BATCH_SIZE, OPENAI_COMPATIBLE_PARALLEL_BATCHES, OPENAI_COMPATIBLE_MAX_TOKENS |
(back-end defaults) | Request tuning for the OpenAI-compatible back end |
BACKENDS_DATA_DIR |
/app/data/backends |
Folder for per-back-end data, such as the sign-ins of installed back-end packages |
BATCH_SIZE |
100 |
Max subtitle lines per batch (auto-adjusted per model) |
PARALLEL_BATCHES_PER_JOB |
4 |
Concurrent batches per translation job |
JOB_QUEUE_MAX_CONCURRENT |
15 |
Concurrent translation job workers at startup |
JOB_QUEUE_MAX_JOBS |
500 |
Maximum queued and processing jobs accepted; existing active jobs are retained after a lower limit is configured |
RETRY_DELAY |
1.0 |
Base delay in seconds for ordinary retries |
MAX_RETRIES |
3 |
Ordinary retry setting; repeated 429s use up to MAX_RETRIES + 3 attempts |
REQUEST_TIMEOUT |
120.0 |
Provider request timeout in seconds; each root batch has a budget of three times this value including one same-size retry and recovery |
LOG_LEVEL |
INFO |
Log level (DEBUG for full request/response logging) |
CORS_ALLOWED_ORIGINS |
* |
Comma-separated allowed CORS origins |
ADMIN_API_KEY |
(empty) | Required as X-Admin-Key header for PUT /config when set |
UI_ENABLED |
false |
Serve the optional web UI at /ui/ |
HOST |
0.0.0.0 |
Bind address when launched with ai-subtitle-translator serve or python -m subtitle_translator.main |
PORT |
8765 |
Port when launched with ai-subtitle-translator serve or python -m subtitle_translator.main |
ENCRYPTION_ENABLED |
true |
Enable AES-256-GCM API key encryption |
ENCRYPTION_STRICT |
false |
When true, reject plaintext API keys (require enc: prefix) |
ENCRYPTION_KEY |
(auto-generated) | 64-char hex AES-256 key. Overrides key file when set |
ENCRYPTION_KEY_FILE |
/app/data/encryption.key |
Path to persistent encryption key file |
DB_PATH |
/app/data/jobs.db |
SQLite database path for job persistence |
JOB_RETENTION_HOURS |
24 |
Hours to keep completed/failed jobs before cleanup |
Inside a container localhost is the container itself, so an OpenAI-compatible server on the
host takes the host's LAN address or host.docker.internal.
Requests that carry their own OpenRouter key (the Bazarr+ 2.7 integration and the web GUI) run only
on that key. Other requests use the back ends in BACKEND_ORDER; when one is rate limited, out of
quota, rejects its key or cannot be reached, the next one continues where it stopped. Put backend
in a request's config to use one back end only.
What a request's options do on each kind of connection:
| Option | OpenRouter | Gemini / OpenAI-compatible, pinned with backend |
Gemini / OpenAI-compatible, reached by failover |
|---|---|---|---|
requestTimeout |
applied | applied to the call and the batch | applied |
model, temperature (config first, then the top-level fields) |
applied | applied | ignored: the connection keeps its own, because a model name means nothing to another back end |
parallelBatches |
applied | applied by OpenAI-compatible; Gemini always runs one batch at a time | ignored |
provider routing (only, ignore, order, sort, smartFast, allowFallbacks), reasoning, useThinkingVariant, serviceTier |
applied | ignored, with a warning in the log | ignored |
provider.dataCollection: "deny" |
applied | the request is refused with a validation error | never reached: only OpenRouter connections are tried |
provider.dataCollection: "allow" |
applied | ignored | ignored |
A request that brings its own OpenRouter key runs on that key alone, with every option applied.
provider.dataCollection: "deny" is different from the other routing options because Gemini and
OpenAI-compatible back ends cannot promise that no data is collected: a request pinned to one is
refused with a validation error, and an unpinned request that says deny only ever tries OpenRouter
connections, and is refused when there is none. OPENROUTER_DENY_DATA_COLLECTION does the same for
every request that does not state its own dataCollection.
OPENROUTER_MAX_TOKENS and BATCH_SIZE have to fit each other. A batch that cannot
answer inside the budget comes back cut short, and the adaptive sizer then halves the
batch size for that model and re-sends, so the reply arrives complete but the truncated
attempt is still billed. Measured on a 1355-cue film at the defaults, a verbose model
spent 6200 to 8000 completion tokens per 100-cue batch, so two batches were cut short
and the run took 27 requests instead of 14. Either raise the budget or lower
BATCH_SIZE; the log names which limit stopped a reply when it happens.
The Docker image and manual Uvicorn command above explicitly bind to 0.0.0.0:8765. Change the Uvicorn arguments to use another bind address or port.
PUT /api/v1/config changes are held in memory and lost on restart. Running jobs keep the model, temperature, parallel batch count and API key defaults captured when they started. Queued jobs use current defaults when they start; explicit request overrides retain priority. API key rotation updates subsequent requests without closing connections used by running jobs. See the interactive schema for accepted fields.
A provider timeout is retried once at the same size, because a stalled request usually means a slow provider rather than an oversized batch, and a stall does not teach the model a smaller batch size. If the retry also times out, the batch is split once above the five-line floor. A timed-out floor batch or recovery request is not repeated. The root batch, including the retry and recovery, has a budget of three times the configured request timeout. Up to PARALLEL_BATCHES_PER_JOB batches are in flight at once, and a batch that finishes frees its slot for the next one immediately, so one stalled request no longer holds back the other slots. A parallel group that produces no usable output and only timeout failures stops later groups; earlier translations and reported usage remain available. Ordinary invalid-response, network and rate-limit errors keep their distinct retry handling within the batch budget. Per-request config.requestTimeout overrides the timeout (30-900 seconds).
Small models are loose with JSON. A trailing comma is repaired, and a reply cut off by the token limit keeps the complete translations before the break, and only the cues it left out are requested again. One malformed line no longer costs the lines behind it: when a batch is split, every smaller batch is still attempted after one of them fails, and the result names the cues that stayed in the source language and why.
OpenRouter can return HTTP 200 with an error inside the response body. The service handles those errors by their embedded code: rate limits wait before retrying and do not reduce batch size; transient server errors use bounded retries; authentication and credit errors fail the batch. Reported usage from failed attempts remains included. A provider error marker cannot count as a completed translation.
Job messages publish request, retry, backoff and recovery activity while work is pending. Activity does not advance completed line/batch counts or invent usage. Partial adaptive output retains translated indices while missing positions use source-text fallbacks in downloadable results. Every request line carrying a translated position counts as completed; a reply that repeats an index or answers one nobody asked for adds nothing.
Job persistence
Jobs are stored in SQLite and survive container restarts. On startup, queued or in-progress jobs from the previous session are recovered and re-queued from the beginning; completed batches are not checkpointed for resumption. Per-request API keys are encrypted at rest when encryption is enabled. With encryption disabled, those keys are not persisted, so recovery requires a configured default API key.
Startup recovers every stored queued or processing job independently of recent terminal history. History loaded into memory is bounded by JOB_QUEUE_MAX_JOBS. If that limit has decreased below the accepted active count, existing work is retained and new submissions wait until the active count falls below the limit.
Mount a volume to /app/data to persist across container recreations:
docker run -d --name ai-subtitle-translator \
-p 8765:8765 \
-v translator-data:/app/data \
-e OPENROUTER_API_KEY=sk-or-... \
-e OPENROUTER_DEFAULT_MODEL=openai/gpt-5.6-luna:floor \
ghcr.io/lavx/ai-subtitle-translator:latest
The data directory contains:
jobs.db- SQLite database with all job historyencryption.key- auto-generated encryption key (chmod 600)
Adaptive batch sizing, rate limits and reasoning controls
Adaptive batch sizing
Batch size depends on the model and its output limits. The translator adjusts it using:
- Known limits - small-context models get smaller default batches
- Context-length heuristic - estimates safe batch size from the model's context window
- Adaptive retry - if a batch fails, halves the size and retries, down to five lines. Remembers the learned size for future requests to the same model. After three consecutive qualifying successes, doubles it toward the size that originally failed. This state is in memory and resets on restart.
Batch sizing helps with incomplete responses and context limits, but does not guarantee a model will produce valid translations.
Rate limit handling
When OpenRouter returns 429 Too Many Requests:
- Makes up to six attempts for repeated 429s with default settings. Honors
Retry-Afterwhen provided; otherwise backoff starts at five seconds and caps at 30 seconds - Serializes retries across parallel batches so they don't all hit the API at once
- Staggers initial parallel requests by 0.5s to spread the load
- Reports
partialstatus if some batches completed before retries ran out
Reasoning support
Reasoning configuration uses explicit catalog effort metadata when available, then falls back to built-in model overrides and recommended-model metadata. Other model IDs use the OpenRouter /models API. When reasoning is requested:
- For effort-based models, the service forwards the requested effort, for example
{"reasoning": {"effort": "low"}} - When the catalog declares supported efforts, an explicit effort is forwarded unchanged or rejected before a translation request if unsupported. This metadata takes priority over older token-budget model overrides. Without effort metadata, token-budget models accept
{"reasoning": {"maxTokens": N}}; aneffortvalue alone keeps the existing fallback behavior effort: "none"orenabled: falsesendsreasoning: {"effort": "none"}to OpenRouter. Omitted reasoning settings retain model defaults. Models declaring mandatory reasoning in/modelsmetadata reject explicit disable before a translation request is sent. Disable also conflicts with an explicitly selected thinking variant.response_format: json_objectis sent when reasoning is omitted or explicitly disabled. SmartFast also requires every endpoint allowed for that request to support this optional field, otherwise it omits the field and keeps the same JSON instructions, cue validation and bounded recovery. JSON mode only allows an object at the top level, so the prompt asks for{"translations": [...]}; asking for a bare array under JSON mode made some models (DeepSeek V4 Flash among them) answer with a single translated line per batch. The parser also accepts a wrapper under any single list-valued key.response_format: json_objectis skipped when reasoning is enabled (some models misbehave with reasoning and JSON mode together)
Development
Open feature and fix pull requests against development, the pre-release branch. main is the stable branch.
pip install -e ".[dev]"
pytest tests/ -v --tb=short # unit and integration tests
ruff check src/ tests/ # lint
ruff format src/ tests/ # format
The optional UI has dependency-free JavaScript checks:
node --test tests/ui/*.test.mjs
For browser acceptance checks, install Playwright in your development environment:
pip install playwright
playwright install chromium
PYTHONPATH=src python tests/ui_browser.py
This starts a temporary local service using the real API and job worker with synthetic translations and dummy OpenRouter key validation. It makes no paid model calls. The checks cover key saving and reuse, job ownership, batch downloads, partial results, cancellation races and interrupted submissions. Set CHROMIUM_PATH to use a particular Chromium executable.
Project structure
src/subtitle_translator/
main.py, cli.py # shims for the documented entry points
_vendor/srt.py # vendored srt 3.5.3 (MIT)
core/ # importable without the server: models, settings, errors,
# batch processing, the back-end interface, the engine
backends/ # built-in back ends: OpenRouter, the OpenAI-compatible client, Gemini
server/ # the standalone service: FastAPI app, config, crypto, CLI,
api/ queue/ static/ # job queue, browser GUI
License
MIT. See LICENSE.
Built alongside Bazarr+
- LavX - Enterprise AI solutions
- Bazarr+ - Subtitle management, translation and the wider media workflow
- OpenRouter - Multi-model LLM routing API
If this service makes your library more accessible, support its development.
Metadata
Release files for lavx-ai-subtitle-translator 2.2.0rc2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lavx_ai_subtitle_translator-2.2.0rc2.tar.gz | 283.7 kB | With provenance | Details for lavx_ai_subtitle_translator-2.2.0rc2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lavx_ai_subtitle_translator-2.2.0rc2-py3-none-any.whl | Python 3 | none | any | Details for lavx_ai_subtitle_translator-2.2.0rc2-py3-none-any.whl |
Total release size: 561.7 kB
Release files / lavx_ai_subtitle_translator-2.2.0rc2.tar.gz
| Download URL | lavx_ai_subtitle_translator-2.2.0rc2.tar.gz |
|---|---|
| Size | 283.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b8a1e03a5b3d9064ff2a69321c820b4e32cc30fd653efc5e066ab6cb9648207d
|
|
BLAKE2b-256 checksum How to use checksums |
c506d45621477d71d2839f91f05e5fc66ad21e89315764651f4fded4a39d4eb7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / lavx_ai_subtitle_translator-2.2.0rc2-py3-none-any.whl
| Download URL | lavx_ai_subtitle_translator-2.2.0rc2-py3-none-any.whl |
|---|---|
| Size | 278.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e15835357a6bf56357244d50efc8830e0ac9fcc7c158f34570be4ecac2de867a
|
|
BLAKE2b-256 checksum How to use checksums |
9b9293ba82a34001aa9ab09e07a87a43c3479b5721dbf1b61833dbfa195dd617
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for lavx-ai-subtitle-translator 2.2.0rc2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for lavx_ai_subtitle_translator-2.2.0rc2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.