DeepSeek Harness (DSH) core philosophy is “Everything is a plugin”. When performing automated video processing or multilingual content distribution, subtitle parsing, translation, and merging are common but cumbersome steps. subtitle-studio is a multilingual subtitle translation workflow plugin for DSH. It is maintained by JohnXu22786 and open-sourced under the MIT license. The plugin implements subtitle parsers from scratch, without relying on heavy libraries, and provides SRT/VTT parsing, sentence-level LLM translation, bilingual subtitle merging, alignment validation, and batch processing capabilities.

Core Features

  1. Parsing and Writing: Supports SRT and WebVTT formats. The parser uses a fault-tolerant state machine and can handle missing indices, blank separators, CRLF, and UTF BOM (UTF-8/UTF-16LE/UTF-16BE). Output is forced to UTF-8, and millisecond-level timestamps can round-trip losslessly.
  2. Sentence-level Translation: Based on LLM batch requests, supports character budget control, JSON mode, retry mechanisms, and glossary injection. Defaults to DeepSeek (OpenAI-compatible interface), and can also connect to other OpenAI-compatible endpoints via configuration.
  3. Bilingual Merging: Supports two layouts: stacked (original text at the bottom) and interleaved (original and translated text alternating), with customizable separators and labels.
  4. Alignment Validation: Checks translated entry count, missing/extra entries, empty translations, and timeline overlaps.
  5. Batch Processing: Supports directory-level processing, including concurrency control, file-level retries, fallback mechanisms, and atomic checkpoint files, with pause/resume support.
  6. Dual Entry Points: Provides five DSH tools (sub_parse, sub_translate, sub_merge, sub_export, sub_glossary) and a dependency-free CLI tool.

Installation and Configuration

Prerequisites: Node.js >= 18.18. The plugin itself has zero runtime dependencies.

Installation: Add the plugin to a DSH profile:

dsh plugin --profile <name> add subtitle-studio

After installation, the plugin registers configuration lines in the profile and injects the corresponding tools and services.

Key Configuration Items: The plugin injects configuration through cordis.patch.yml. The following are descriptions of some core configuration items:

  • LLM Configuration:
    • llm.provider: HTTP backend or harness ctx.llm seam, defaults to openai.
    • llm.baseUrl: OpenAI-compatible endpoint URL, defaults to https://api.deepseek.com/v1.
    • llm.apiKey: API key, supports environment variable expansion.
    • llm.model: Model name, defaults to deepseek-chat.
    • llm.chunkChars: Character budget per request, defaults to 3500.
  • Language Configuration:
    • sourceLanguage: Source language label, defaults to empty (auto).
    • targetLanguages: List of target languages, defaults to empty.
  • Output Configuration:
    • output.layout: Bilingual merge layout, options stacked or interleaved, defaults to stacked.
    • output.format: Output format, options srt or vtt, defaults to retaining the source format.
  • Batch and Validation:
    • batch.concurrency: Concurrency level for batch processing, defaults to 2.
    • validation.maxChars: Threshold for overly long CJK subtitles, defaults to 160.
    • validation.maxWords: Threshold for overly long Latin-script subtitles, defaults to 40.

Usage

The plugin provides two ways to use it: a CLI tool and the DSH tool set.

CLI Usage: After installation, you can directly run the global command:

subtitle-studio --help

DSH Tool Usage: The plugin registers five tools, which can be called via DSH’s ctx.tools:

  1. sub_parse: Parses a subtitle file into a JSON structure.
  2. sub_translate: Calls an LLM to perform translation.
  3. sub_merge: Merges the source subtitles with the translation.
  4. sub_export: Exports to SRT or VTT.
  5. sub_glossary: Manages the JSON glossary.

Example command (must be executed in a DSH environment):

# 调用翻译工具
dsh tools sub_translate --file input.srt --lang zh

Use Cases and Notes

Use Cases: Video projects that require automated multilingual subtitle processing, or developers who need to integrate subtitle translation into larger DSH workflows.

Notes: The plugin runs with the permissions of the current DSH process and involves API calls and file read/write operations. Ensure the configured API key is secure. It is recommended to review the source code before installation to confirm the license and dependency status.

Summary

subtitle-studio provides a complete subtitle processing pipeline from parsing to translation, merging, and validation. For developers who need to integrate subtitle functionality into the DSH ecosystem, this is a ready-to-use solution. The plugin source code and directory page are available at the links below.