Table of Contents
AI Subtitles
The subtitles capability translates existing UTF-8 SRT/VTT tracks to configurable languages. Configure Queue, an existing mounted library root, backend URL, model, source/target languages, lowercase output language code, batch size (1–20), optional glossary and optional notification provider. The default language pair is English → Czech; it is not hard-coded into the translation engine.
Ollama uses its generate API with non-streaming JSON generation. OpenAI uses the Responses API with JSON-object output, store: false, and output-text item parsing. The endpoint/model/key are explicitly configured by the administrator. No model is silently selected and no live paid requests run during tests. External subtitle dialogue is treated as data in the prompt.
Methods
| Method | Behavior |
|---|---|
config() |
Checks root/model/languages/code/backend endpoint, OpenAI key when needed and batch-size bounds. |
scan() |
Searches at most 10,000 paths and returns up to 500 original SRT/VTT files, excluding symlinks and generated .ai. outputs. |
source(relative, settings) |
Confines the source to the library, checks suffix/10 MiB bound/UTF-8/document validity, reads bytes and derives an input/config fingerprint. |
submit(relative) |
Validates without contacting an AI service; reuses matching recorded outputs or queues a path/fingerprint job. Credentials never enter the job payload. |
translate(sources, context, settings) |
Protects formatting, requests a JSON translations array, bounds HTTP response to 2 MiB and timeout to 180 seconds, parses the backend response, rejects truncated/count/markup/empty/invalid-dialogue output and restores original tags. |
process(payload, progress) |
Rejects changed inputs/config, resumes completed batches from encrypted checkpoints, validates all cues, checks source unchanged, writes a new atomic fingerprint-named output without overwriting existing files, records output hash/metadata and clears checkpoint. |
Formatting and outputs
SubtitleDocument and formatting helpers are adapted from Kaizoku revision b20ac193. Cue IDs, timestamps, BOM, newline style, VTT NOTE/STYLE/REGION blocks, timestamp settings and markup are preserved. protect_markup() masks inline tags; restore_markup() rejects changed tag markers; validate_text() rejects missing dialogue, altered formatting, timestamps inside dialogue and malformed blank-line boundaries; quality checks reject obvious instruction echoes/repeated unrelated output. render() changes only cue text.
Outputs are <original-stem>.ai.<language-code>.<fingerprint>.srt/vtt. Originals are never overwritten or deleted. Existing matching outputs are reused, including queued duplicates processed later. Checkpoints are encrypted in control settings and allow Queue retry after a later batch fails. At-least-once job execution can repeat the most recent external request if a process dies before checkpoint persistence. Generated translation quality still depends on the selected model; outputs remain separate for review.
GET /plugins/ai-subtitles/ scans/list files and prior outputs. POST / requires content.write and CSRF, validates the selected original and queues translation. GET /outputs/<fingerprint> serves a registered output only within the configured root, with normal authentication/plugin gates. service(), index(), submit() and download() implement these adapters. Completion emits subtitles.completed through the optional notification provider.
This plugin translates text tracks. It does not extract audio, transcribe video, download missing subtitles or overwrite tracks embedded inside media files.