Subtitle Extractslator

English | 中文

SubtitleExtractslator is a subtitle translation skill project.

The primary deliverable in this repository is the skill package (prompts, policy, runtime assets, and usage contract). The .NET CLI and MCP server are runtime implementations that exist to execute this skill reliably in local scripts and agent environments.

Runtime forms in this repository:

• CLI application for local automation
• MCP stdio server for agent-driven workflows

It is built for end-to-end subtitle processing: detect existing tracks, search candidates, extract source subtitles, translate with context-aware batching, and emit final SRT output while preserving subtitle timing and structure.

Downloads

Quick install skill command:

npx skills add waynebaby/SubtitleExtractslator

Primary runtime distribution now uses NuGet package + portable DLL entry.

Package indexes:

• Stable index: packages.released.md
• Stable index (zh-CN): packages.released.zh-CN.md
• Beta index: packages.beta.md
• Beta index (zh-CN): packages.beta.zh-CN.md

Install example:

dotnet add package SubtitleExtractslator.Cli --version <VERSION>

Guide-first entry:

dotnet SubtitleExtractslator.Cli.dll --guide

If the package feed is unavailable, use the GitHub fallback .nupkg links below.

• Latest releases: Releases
• Windows x64 package (v0.1.16): subtitle-extractslator-v0.1.16-win-x64.zip
• Windows ARM64 package (v0.1.16): subtitle-extractslator-v0.1.16-win-arm64.zip
• Linux x64 package (v0.1.16): subtitle-extractslator-v0.1.16-linux-x64.zip
• Linux musl x64 package (v0.1.16): subtitle-extractslator-v0.1.16-linux-musl-x64.zip
• Linux ARM64 package (v0.1.16): subtitle-extractslator-v0.1.16-linux-arm64.zip
• Linux musl ARM64 package (v0.1.16): subtitle-extractslator-v0.1.16-linux-musl-arm64.zip
• Linux ARM package (v0.1.16): subtitle-extractslator-v0.1.16-linux-arm.zip
• macOS ARM64 package (v0.1.16): subtitle-extractslator-v0.1.16-osx-arm64.zip
• macOS x64 package (v0.1.16): subtitle-extractslator-v0.1.16-osx-x64.zip

First: Guide-First Runtime Entry

If your goal is to run this as a skill in your own agent, keep npx skills add for discovery, and use NuGet package runtime as command source of truth.

1. Install package from stable/beta channel.
2. Run dotnet SubtitleExtractslator.Cli.dll --guide first.
3. Follow guide command entries for CLI or MCP mode.
4. If package feed is unavailable, download fallback .nupkg from the release links above.

Notes:

• This repository keeps subtitle-extractslator/ for skill routing and policy context.
• The SubtitleExtractslator.Cli/ project is the runtime host used by the skill (CLI + MCP server), delivered as portable DLL package.
• Build and packaging details are in docs/skill-installation-and-build.md.

Usage Scenarios (Short Prompts)

Use the skill name in your agent chat:

/subtitle-extractslator

Scenario 1: Translate one video to Chinese with local model endpoint

/subtitle-extractslator

Translate D:\\media\\xxx.mkv to zh.
Use local model endpoint http://127.0.0.1:1234/v1/chat/completions. model: qwen3.5-9b-uncensored-hauhaucs-aggressive
Output D:\\media\\xxx.zh.srt.

Scenario 2: Process one folder recursively

/subtitle-extractslator

Run in MCP mode.
Process D:\\tv\\Fallout\\S01 recursively to zh.
Skip files that already have .zh.srt.

Scenario 3: Resume interrupted folder run

/subtitle-extractslator

Continue previous D:\\tv\\Fallout run to zh.
Resume from centralized temp queue state.

Scenario 4: Translate one SRT to multiple languages

/subtitle-extractslator

Translate D:\\subs\\episode01.en.srt to zh, ja, es.
Keep timing and cue order unchanged.

Scenario 5: Probe-only check

/subtitle-extractslator

Probe D:\\media\\xxx.mkv for embedded zh subtitle track.
Return probe result only.

Scenario 6: Batch processing with supervisor/worker

/subtitle-extractslator

Run long folder translation to zh.
Use supervisor + worker model for this batch run.
If platform supports subagents, supervisor must delegate bounded batches to worker subagents.
If subagents are unavailable, keep the same supervisor/worker contract in a single-agent loop.

Operational note:

• MCP mode does not expose a single translate-batch tool. Batch behavior is achieved by your agent looping over files and invoking MCP tools file-by-file.
• Multi-language output is also an agent loop pattern: run translate once per target language.

Design note:

1. Long-running multi-file orchestration uses centralized queue state under the temp root.
2. Queue state is designed for resume-safe small-batch processing.
3. Typical completion behavior is run-to-completion until queue is empty or only blocked items remain.
4. Batch processing uses supervisor/worker model; when platform supports subagents, delegation is required.
5. Canonical term definitions are maintained in docs/README.md under Terminology Glossary.

What The Skill Solves

• Provides a reusable subtitle workflow skill contract for probe/search/extract/translate/merge.
• Keeps cue order and timestamps stable while translating text content.
• Standardizes agent-side execution through MCP tools.
• Provides CLI runtime knobs for grouping, batch sizing, retries, and model endpoint settings.

Current implementation scope

Execution modes:

• CLI mode (default)
• MCP stdio mode (--mode mcp)

Workflow steps:

1. Probe media subtitle tracks for target language.
2. Query OpenSubtitles candidates (real API when configured; mock fallback optional).
3. Extract local subtitle (prefer English, fallback nearest available).
4. Group cues by timeline rules.
5. Build rolling scene summary and historical context.
6. Translate by mode policy.
7. Merge and emit SRT.
8. Optional: remux generated AI subtitle into source media as a new subtitle language track.

Translation policy:

• MCP mode: sampling-only (sampling/createMessage). Sampling failures return errors.
• CLI mode: external provider only (including custom endpoint access).

Build

dotnet build SubtitleExtractslator.sln

dotnet build SubtitleExtractslator.sln

Project structure

• subtitle-extractslator/: skill package (primary)
• SubtitleExtractslator.Cli/: skill runtime host (CLI + MCP tools + workflow core)
• docs/: setup and operational notes
• samples/: sample SRT and trace files

CLI usage

dotnet run --project SubtitleExtractslator.Cli -- --mode cli probe --input "movie.mkv" --lang zh

dotnet run --project SubtitleExtractslator.Cli -- --mode cli subtitle-timing-check --input "movie.mkv" --subtitle "movie.zh.srt"

dotnet run --project SubtitleExtractslator.Cli -- --mode cli opensubtitles-search --input "movie.mkv" --lang zh --search-query-primary "movie" --search-query-normalized "movie s00e00"

dotnet run --project SubtitleExtractslator.Cli -- --mode cli extract --input "movie.mkv" --out "movie.en.srt" --prefer en

dotnet run --project SubtitleExtractslator.Cli -- --mode cli translate --input "movie.en.srt" --lang zh --output "movie.zh.srt"

dotnet run --project SubtitleExtractslator.Cli -- --mode cli translate-batch --input-list ".\\inputs.txt" --lang zh --output-dir ".\\out" --output-suffix ".zh.srt"

dotnet run --project SubtitleExtractslator.Cli -- --mode cli probe --input "movie.mkv" --lang zh

dotnet run --project SubtitleExtractslator.Cli -- --mode cli subtitle-timing-check --input "movie.mkv" --subtitle "movie.zh.srt"

dotnet run --project SubtitleExtractslator.Cli -- --mode cli opensubtitles-search --input "movie.mkv" --lang zh --search-query-primary "movie" --search-query-normalized "movie s00e00"

dotnet run --project SubtitleExtractslator.Cli -- --mode cli extract --input "movie.mkv" --out "movie.en.srt" --prefer en

dotnet run --project SubtitleExtractslator.Cli -- --mode cli translate --input "movie.en.srt" --lang zh --output "movie.zh.srt"

dotnet run --project SubtitleExtractslator.Cli -- --mode cli translate-batch --input-list "./inputs.txt" --lang zh --output-dir "./out" --output-suffix ".zh.srt"

Batch input file format (--input-list):

• UTF-8 text file.
• One media/subtitle path per line.
• Empty lines and lines starting with # are ignored.

Batch mode is CLI-only. MCP mode intentionally does not provide batch workflow due to common timeout constraints in MCP clients.

CLI common options:

• --env "KEY=VALUE;KEY2=VALUE2" injects temporary environment overrides for the current command only.
• --help prints complete command help.

MCP stdio mode

dotnet run --project SubtitleExtractslator.Cli -- --mode mcp

dotnet run --project SubtitleExtractslator.Cli -- --mode mcp

MCP transport and tool registration use the official ModelContextProtocol NuGet package (AddMcpServer().WithStdioServerTransport().WithTools<...>()).

The MCP server supports:

• probe
• subtitle_timing_check
• opensubtitles_search
• opensubtitles_download
• extract
• translate

MCP tool return contract:

• Tools return a structured object with ok, data, and error.
• On success: ok=true, data contains tool result.
• On failure: ok=false, error includes code, message, optional snapshotPath, and timeUtc.

Translation providers

• MCP sampling provider uses official MCP sampling (sampling/createMessage).
• MCP sampling retries follow LLM_RETRY_COUNT (or overrides).
• Oversized responses trigger a concise-reasoning warning in the next retry.
• MCP has no external fallback on translation errors.
• External/custom endpoint access is CLI route only.

OpenSubtitles

• Real API search/download requires local auth cache from subtitle auth login.
• subtitle auth login stores api key, username, and password in local cache for later aquire usage.
• Optional mock branch remains available via OPENSUBTITLES_MOCK=1 for offline testing.

Publish single-file examples

dotnet publish SubtitleExtractslator.Cli -c Release -r win-x64 -p:PublishSingleFile=true -p:SelfContained=true

dotnet publish SubtitleExtractslator.Cli -c Release -r linux-x64 -p:PublishSingleFile=true -p:SelfContained=true

dotnet publish SubtitleExtractslator.Cli -c Release -r osx-arm64 -p:PublishSingleFile=true -p:SelfContained=true

dotnet publish SubtitleExtractslator.Cli -c Release -r linux-x64 -p:PublishSingleFile=true -p:SelfContained=true
dotnet publish SubtitleExtractslator.Cli -c Release -r osx-arm64 -p:PublishSingleFile=true -p:SelfContained=true