subtitle-studio

A self-contained multilingual subtitle translation workflow plugin for dsh (DeepSeek Harness), built around the "everything is a plugin" idea. It parses and writes SRT/VTT subtitles, translates them sentence-by-sentence through a configurable LLM, merges bilingual outputs, validates alignment, and processes whole directories — exposed both as dsh tools (ctx.tools) and as a dependency-free CLI.

subtitle-studio is a new, self-contained implementation. Its subtitle parsers are written from scratch (no heavy subtitle libraries), its LLM layer speaks OpenAI-compatible HTTP out of the box (DeepSeek by default) and can plug into the harness's ctx.llm seam, and everything is UTF-8 on both ends.

---

Table of contents

• Features
• Installation
• Using subtitle-studio as a dsh bundle
• CLI
• Configuration
• Glossary format
• Library & service API
• Testing
• Limitations
• License

Features

1. Parsing & writing — SRT and WebVTT with a tolerant state machine:

   • accepts missing sequence numbers, missing blank separators, CRLF, and a UTF BOM (UTF-8 / UTF-16LE / UTF-16BE);
   • keeps multi-line cue text and VTT identifiers/settings verbatim;
   • skips junk lines and malformed timecode lines, reporting them as issues instead of aborting;
   • output is always UTF-8 and round-trips preserve timing to the millisecond.

2. Sentence-by-sentence translation — batched requests over a character budget, JSON payloads keyed by cue index for reliable alignment, bounded retries (with a corrective nudge on malformed JSON), timeouts, and glossary injection. Works with any OpenAI-compatible endpoint (DeepSeek is default) or the dsh ctx.llm seam.

3. Bilingual subtitles — merge original + translation either stacked (translation lines under the original) or interleaved (alternating cues), with optional per-line tags and a separator. The timeline is copied verbatim from the source, so it is preserved by construction.

4. Alignment validation — checks translation count vs. source, missing and extra cues, empty translations, overlong cues that should be split, and timeline overlaps.

5. Batch processing — translate whole directories with a bounded concurrency pool, per-file retry with backoff, an atomic checkpoint file for pause/resume, and token/cost estimation (with approximate per-model rates that can be overridden).

6. Two entry points — five dsh tools (sub_parse, sub_translate, sub_merge, sub_export, sub_glossary) plus a full CLI.

Installation

Requirements: Node.js ≥ 18.18.

# 1. install dev dependencies and build
npm install
npm run build

# 2. run the CLI directly
node bin/subtitle-studio.js --help

# or install the bin globally (makes `subtitle-studio` available)
npm link

The package ships zero runtime dependencies. TypeScript is only a dev dependency (build to lib/ with tsc).

Using subtitle-studio as a dsh bundle

The package is a valid dsh bundle: package.json declares the bundle manifest, cordis.patch.yml inserts the plugin row into a profile, and lib/index.js exports the Cordis-style entry (name + apply(ctx, config)).

1. Add the bundle to a profile

…