Command Line (seconv)

seconv is Subtitle Edit's headless command-line converter. It reuses the same core libraries as the desktop app (libse, libuilogic), so it supports the same formats, operations, and OCR engines — without any GUI dependency. Useful for scripts, CI pipelines, server-side workflows, and bulk conversion.

seconv lives in the main Subtitle Edit repository and ships in lockstep with the desktop app — no separately maintained fork, no version drift.

Highlights

• 380+ subtitle formats — text, binary, and image-based.
• Container input — Matroska (.mkv / .mks), MP4, MCC, transport stream teletext, Blu-Ray .sup.
• OCR for image-based sources via five engines (Tesseract subprocess, nOCR built-in, BinaryOCR built-in, Ollama HTTP, PaddleOCR subprocess).
• Auto-translate via local LLMs (llama.cpp with automatic server start, Ollama, LM Studio) or self-hosted services (LibreTranslate, NLLB).
• Image-based output — Blu-Ray sup, BDN-XML, DOST, FCP (Final Cut Pro + image), D-Cinema interop / SMPTE 2014, images-with-time-code.
• Operations pipeline — offset, fps change, change-speed, renumber, adjust-duration, fix-common-errors, merge/split, balance, redo casing, RTL fixes, multiple-replace, custom-text format, plain text.
• Cross-platform — Windows, Linux, macOS. Only requires the .NET runtime; no display or GUI needed.

Installation

Pre-built binaries are distributed alongside Subtitle Edit. To build from source:

dotnet build src/seconv/SeConv.csproj -c Release

The executable is seconv (or seconv.exe on Windows).

Usage

seconv <pattern> <format> [options]
seconv <pattern> --format <name> [options]   # alternative syntax

The format may be passed as the second positional argument or via --format <name>. Multiple input patterns can be passed as separate quoted arguments or comma-separated:

seconv "file1.srt" "file2.srt" subrip --overwrite
seconv "*.srt,*.ass" subrip --input-folder:./in

Options accept either --option:value, --option=value, or --option value. The colon form is shown throughout this page.

Quick examples

seconv *.srt sami                                                  # SRT → SAMI
seconv movie.srt subrip --encoding:windows-1252                    # encoding override
seconv movie.srt subrip --encoding:source                          # keep input's encoding on output
seconv *.sub subrip --fps:25 --output-folder:./out                 # frame-based → time-based

seconv movie.mkv subrip --track-number:3                           # extract MKV text track #3
seconv movie.sup subrip --ocr-engine:tesseract --ocr-language:eng  # OCR a Blu-Ray .sup
seconv movie.sup subrip --ocr-engine:nocr --ocr-db:Latin.nocr      # OCR via nOCR
seconv movie.sup subrip --ocr-engine:binaryocr --ocr-db:Latin.db   # OCR via BinaryOCR
seconv movie.sup subrip --ocr-engine:ollama --ollama-model:llama3.2-vision
seconv movie.sup subrip --ocr-engine:llamacpp                      # OCR via llama.cpp (auto-starts llama-server)

seconv subs.srt bluraysup --resolution:1920x1080                   # render text → Blu-Ray sup
seconv subs.srt bdnxml --resolution:1920x1080                      # render text → BDN-XML
seconv subs.srt bluraysup --background-color:"#B4000000"           # ... with a black background box

seconv subs.srt customtext --custom-format:my-template.xml         # custom template
seconv *.srt subrip --multiple-replace:rules.csv                   # search-and-replace pass (GUI export: .csv/.template/.xml)

seconv subs.srt subrip --offset:-2000 --renumber:1 --overwrite     # offset 2s back, renumber from 1

Subcommands

seconv formats              # list all supported formats
seconv list-encodings       # list text encodings
seconv list-pac-codepages   # list PAC code pages
seconv list-ocr-engines     # list OCR engines + installation status
seconv list-fce-rules       # list FixCommonErrors rule IDs
seconv dump-settings        # print a full --settings JSON with libse defaults
seconv info <file>          # print format/encoding/duration/language for a file
seconv lint <pattern>       # validate subtitle(s); exit 1 if issues found
seconv --help               # show help
seconv --version            # print version and exit

Inspect & validate

seconv info movie.srt                # human-readable table
seconv info movie.srt --json         # machine-parseable

seconv lint *.srt                    # check overlaps, line lengths, tags, ...
seconv lint *.srt --json             # CI-friendly: exit 1 on any issue

Options

File / I/O

Time / frame

Format-specific

Image output styling

When rendering a text subtitle to an image-based target (Blu-Ray sup, VobSub, BDN-XML, DOST, FCP / Final Cut Pro + image, D-Cinema, images-with-time-code, WebVTT thumbnails), these options control how the text is drawn. <i>, <b>, and <font color=...> tags in the subtitle text are honored. The same values can be set in a --settings JSON file's exportImages section (see Settings JSON); CLI flags win over the JSON.

Colours accept hex (#AARRGGBB, #RRGGBB, with or without #) or a colour name (white, black, yellow, ...).

# SRT → UHD Blu-Ray sup with a semi-transparent black background box (SE4-style)
seconv movie.srt bluraysup --resolution:3840x2160 --background-color:"#B4000000"

# Custom font, bold, box per line
seconv movie.srt bluraysup --font-name:Verdana --font-size:60 --font-bold --box-type:box-per-line

Containers / tracks

seconv automatically extracts subtitle tracks from container files:

When a container has multiple usable tracks, one output file is written per track with the track's language code as a suffix:

movie.mkv → movie.eng.srt
            movie.deu.srt
            movie.fra.srt

If two tracks share a language, the track number is added: movie.#3.eng.srt.

OCR

OCR database files are not bundled with seconv. The nocr and binaryocr engines need a .nocr or .db file passed via --ocr-db. Sources:

• If you have the desktop UI installed: %AppData%\Subtitle Edit\OCR\ (Windows) or ~/.config/Subtitle Edit/OCR/ (Linux/macOS).
• From the repo: Ocr/Latin.nocr and Ocr/Latin.db.
• Other languages: download from the SE UI (Tools → "OCR with nOCR" / BinaryOCR → download).

Run seconv list-ocr-engines for the per-engine installation-status table.

# Tesseract
seconv movie.sup subrip --ocr-engine:tesseract --ocr-language:eng

# nOCR (no external dependency)
seconv movie.sup subrip --ocr-engine:nocr --ocr-db:"C:\Users\me\AppData\Roaming\Subtitle Edit\Ocr\Latin.nocr"

# BinaryOCR
seconv movie.sup subrip --ocr-engine:binaryocr --ocr-db:"C:\Users\me\AppData\Roaming\Subtitle Edit\Ocr\Latin.db"

# llama.cpp — auto-starts a local llama-server with a downloaded OCR model
seconv movie.sup subrip --ocr-engine:llamacpp
seconv movie.sup subrip --ocr-engine:llamacpp --ocr-model:GLM-OCR-Q8_0.gguf
seconv movie.sup subrip --ocr-engine:llamacpp --ocr-url:http://127.0.0.1:8080

# MKV with image (PGS or VobSub) tracks — OCR runs automatically
seconv movie.mkv subrip --ocr-engine:tesseract --ocr-language:eng

# VobSub .sub + .idx pair — the .idx companion is auto-detected
seconv movie.sub subrip --ocr-engine:tesseract --ocr-language:eng

# Transport-stream teletext (no OCR needed)
seconv broadcast.ts subrip

# Time codes only — extract timing with no OCR (empty text); works for any image source
seconv movie.sup subrip --time-codes-only
seconv movie.sub subrip --time-codes-only

Auto-translate

--translate-to:<language> machine-translates each file as part of the conversion (after OCR for image sources, before the cleanup operations). Languages are given as a code or English name (de, German, da, Danish, …); the source language is auto-detected per file unless --translate-from is set.

llama.cpp (default engine). With no --translate-url, seconv runs a local llama-server for you: it looks for the binary in Subtitle Edit's data folder (llama.cpp next to seconv, then %AppData%\Subtitle Edit\llama.cpp / ~/Library/Application Support/Subtitle Edit/llama.cpp / ~/.config/Subtitle Edit/llama.cpp) and falls back to llama-server on PATH. The server is started on a free localhost port with the model's correct chat-template flags and stopped again when seconv exits. Models resolve against the data folder's models subfolder.

seconv never downloads engines or models (same policy as Tesseract/PaddleOCR). Get llama.cpp + a translation model in one of these ways:

• Run auto-translate with llama.cpp once in the Subtitle Edit UI (Tools → Auto-translate → llama.cpp) — it downloads both into the data folder that seconv probes.
• Install llama.cpp yourself (brew install llama.cpp, winget install ggml.llamacpp, or a GitHub release) and drop a .gguf translation model (e.g. TranslateGemma) into the models folder, or pass it via --translate-model:<path.gguf>.
• Point --translate-url at any llama-server you already have running.

# Translate to German via a local llama.cpp server (started and stopped automatically)
seconv movie.srt subrip --translate-to:de

# Specific source language and model
seconv movie.srt subrip --translate-from:en --translate-to:da --translate-model:translategemma-4b_Q4_K_M.gguf

# Already-running llama-server (local or remote)
seconv movie.srt subrip --translate-to:de --translate-url:http://192.168.1.10:8080

# Ollama
seconv movie.srt subrip --translate-to:da --translate-engine:ollama --translate-model:gemma2

# OCR a Blu-Ray sup and translate the result in one pass
seconv movie.sup subrip --ocr-engine:tesseract --ocr-language:eng --translate-to:de

Templates / replacements

Multiple-replace rule files

The quickest way to share rules between the GUI and seconv: in Subtitle Edit open Tools → Multiple replace, then export the rules as .template (JSON) or .csv, and pass that file to --multiple-replace. Both are read directly — no conversion needed.

seconv *.srt subrip --multiple-replace:my-rules.csv       # exported from the GUI
seconv *.srt subrip --multiple-replace:my-rules.template  # JSON export
seconv *.srt subrip --multiple-replace:fixes.xml          # legacy SE4 XML

CSV columns (a header row is recognised; Type is CaseInsensitive / CaseSensitive / RegularExpression):

Category,Find,ReplaceWith,Description,Active,Type
Demo,colour,color,,true,CaseInsensitive
Demo,"\bteh\b",the,,true,RegularExpression

The legacy XML shape is still accepted (its SearchType value Normal = the GUI's CaseInsensitive):

<?xml version="1.0" encoding="utf-8"?>
<MultipleSearchAndReplaceGroups>
  <Group>
    <Name>Demo</Name>
    <IsActive>true</IsActive>
    <Rules>
      <Rule>
        <Active>true</Active>
        <FindWhat>colour</FindWhat>
        <ReplaceWith>color</ReplaceWith>
        <SearchType>Normal</SearchType>
      </Rule>
      <Rule>
        <Active>true</Active>
        <FindWhat>\bteh\b</FindWhat>
        <ReplaceWith>the</ReplaceWith>
        <SearchType>RegularExpression</SearchType>
      </Rule>
    </Rules>
  </Group>
</MultipleSearchAndReplaceGroups>

Custom text format XML

<?xml version="1.0" encoding="utf-8"?>
<CustomFormatItem>
  <Name>JSON-ish</Name>
  <Extension>.json</Extension>
  <FormatHeader>{
  "lines": [</FormatHeader>
  <FormatParagraph>    {"start": "{start}", "end": "{end}", "text": "{text}"},</FormatParagraph>
  <FormatFooter>  ]
}</FormatFooter>
  <FormatTimeCode>hh:mm:ss.zzz</FormatTimeCode>
</CustomFormatItem>

seconv subs.srt customtext --custom-format:lines.xml

Available template tokens: {title}, {number}, {start}, {end}, {duration}, {gap}, {text}, {text-line-1}, {text-line-2}, {actor}, {cps-comma}, {cps-period}, {text-length}, {bookmark}, {media-file-name}, {media-file-name-full}, {#lines}, {#total-words}, {#total-characters}, {tab}. Time-code tokens accept hh/h, mm/m, ss/s, and zzz/zz/z for milliseconds (or zzzzzzz... for total milliseconds without breakdown).

Settings JSON

This is seconv's own schema — not the Subtitle Edit GUI's Settings.json. The desktop app's settings file uses different key names (e.g. the GUI's IsRemoveTextUppercaseLineOn is removeIfAllUppercase here) and a different structure; feeding it to --settings won't do what you expect (unrecognized keys are ignored with a warning). To get a correct starter file, run seconv dump-settings — it prints this whole schema populated with the current libse defaults:

bashCopy

seconv dump-settings > my-settings.json   # edit, then: --settings:my-settings.json

The keys and defaults below are exactly what dump-settings emits:

{
  "general": {
    "subtitleLineMaximumLength": 43,
    "subtitleMinimumDisplayMilliseconds": 1000,
    "subtitleMaximumDisplayMilliseconds": 8000,
    "currentFrameRate": 23.976,
    "defaultFrameRate": 23.976,
    "minimumMillisecondsBetweenLines": 24,
    "maxNumberOfLines": 2,
    "mergeLinesShorterThan": 33,
    "subtitleMaximumCharactersPerSeconds": 25.0,
    "subtitleOptimalCharactersPerSeconds": 15.0,
    "subtitleMaximumWordsPerMinute": 400.0,
    "dialogStyle": "DashBothLinesWithSpace",
    "continuationStyle": "None"
  },
  "removeTextForHearingImpaired": {
    "removeTextBeforeColon": true,
    "removeInterjections": false
  },
  "exportImages": {
    "fontName": "Arial",
    "fontSize": 50,
    "fontColor": "#FFFFFF",
    "isBold": false,
    "outlineColor": "black",
    "outlineWidth": 2.5,
    "shadowColor": "black",
    "shadowWidth": 0,
    "backgroundColor": "#B4000000",
    "backgroundCornerRadius": 0,
    "boxType": "one-box",
    "boxPaddingLeft": 5,
    "boxPaddingRight": 5,
    "boxPaddingTop": 3,
    "boxPaddingBottom": 3,
    "lineSpacingPercent": 0,
    "alignment": "bottom-center",
    "contentAlignment": "center",
    "bottomTopMargin": 54,
    "leftRightMargin": 96
  },
  "profiles": {
    "broadcast": {
      "general": { "subtitleMaximumDisplayMilliseconds": 6000 },
      "removeTextForHearingImpaired": { "removeInterjections": true }
    },
    "uhd": {
      "exportImages": { "fontSize": 100 }
    }
  }
}

The exportImages section styles text → image rendering (see Image output styling for the semantics); the equivalent CLI flags override it. The general section mirrors Configuration.Settings.General; any key left out keeps the libse default. The profile-shaping values (minimumMillisecondsBetweenLines, maxNumberOfLines, mergeLinesShorterThan, subtitleMaximumCharactersPerSeconds, subtitleOptimalCharactersPerSeconds, subtitleMaximumWordsPerMinute, dialogStyle, continuationStyle) feed Fix common errors and the split/merge operations, so set them to reproduce an SE4 profile. dialogStyle and continuationStyle take the enum names (case-insensitive): dialogStyle ∈ DashBothLinesWithSpace, DashBothLinesWithoutSpace, DashSecondLineWithSpace, DashSecondLineWithoutSpace; continuationStyle ∈ None, NoneTrailingDots, NoneTrailingEllipsis, OnlyTrailingDots, LeadingTrailingDots, LeadingTrailingEllipsis, LeadingTrailingDash, … (see the Fix common errors continuation styles).

Keys that seconv does not recognize are ignored, so a settings file written for a newer version still applies everything this one understands — but they are listed in a warning, so a typo (or a key your seconv is too old to know) does not silently give you default output.

seconv *.srt subrip --settings:my.json --profile:broadcast --remove-text-for-hi

Verbosity

Operations

Operations run after the structural transforms (offset, fps, renumber, adjust-duration, change-speed) in a fixed, sensible order regardless of where they appear on the command line:

# Common cleanup pass
seconv *.srt subrip --remove-text-for-hi --merge-same-texts --split-long-lines --overwrite

--apply-min-gap vs --fix-common-errors-rules:FixOverlappingDisplayTimes

Both touch boundary timings but solve different problems:

• --apply-min-gap[:<ms>] walks every pair of adjacent paragraphs and, when the gap is shorter than <ms>, shortens the previous cue's end time to open it up. It does not move the next cue's start. Pairs are also skipped when shortening would drop the previous cue below General.SubtitleMinimumDisplayMilliseconds — so this is best-effort, not a hard guarantee. Use it for delivery specs (e.g. broadcast standards that ask for 2 frames between cues) while accepting that minimum-display-duration collisions are left alone.
• FixOverlappingDisplayTimes is one rule inside Fix Common Errors and only resolves cases where a paragraph's end > the next paragraph's start (a true overlap). It does not enforce a non-zero minimum gap once overlaps are gone.

In most batch pipelines --apply-min-gap is the better choice; reach for the FCE rule when you specifically want to keep the tight gaps the source already has and only repair true overlaps.

FixCommonErrors rule selection

--fix-common-errors (no value) runs all 39 rules. Pass --fix-common-errors-rules:<list> to pick a subset — supplying that option implies --fix-common-errors.

seconv movie.srt subrip --fix-common-errors                                  # all rules
seconv movie.srt subrip --fix-common-errors-rules:FixCommas,FixMissingSpaces
seconv movie.srt subrip --fix-common-errors-rules:all,-FixDanishLetterI      # all except one
seconv movie.srt subrip --fix-common-errors --fce-language:es                # force the Spanish gate
seconv list-fce-rules                                                        # show rule IDs (marks language gates)

Language-specific rules. A few rules only make sense for one language and mirror the GUI's Fix Common Errors window, which only offers them when the detected language matches: FixAloneLowercaseIToUppercaseI (English), FixDanishLetterI (Danish), FixSpanishInvertedQuestionAndExclamationMarks (Spanish), and FixTurkishAnsiToUnicode (Turkish). seconv list-fce-rules marks each gated rule with its language in a Language gate column. These run only when the language matches — so e.g. the Spanish inverted-¿ fix never lands on English content (issue #11037). This holds however the rule was selected: naming it in --fix-common-errors-rules picks it into the run but does not bypass the gate, which makes mixed-language batches safe (a Spanish rule in your rule set self-skips on the English and French files).

The language is auto-detected from the content. To force it:

• --fce-language:<code> forces the language used for all gated rules (and the OCR-fix pass). Use it when a genuinely Spanish/Danish/Turkish file mis-detects (e.g. it's too short), or to run a named language rule on content that would auto-detect as something else. Accepts a two-letter code, three-letter code, or English name (es, spa, Spanish); an unrecognized value warns and falls back to auto-detection.

Rule selection is CLI-only. The set of rules is chosen with --fix-common-errors-rules, not through the --settings JSON. The settings file shapes how the rules behave (line length, min gap, dialog/continuation style, CPS — see Settings JSON); it does not select which rules run.

FixCommonOcrErrors runs only when a dictionary folder is available — bundled for English, or supplied via --dictionary-folder for other languages (see OCR options). Without one, that rule is skipped and every other rule still runs.

Rule ID ↔ GUI equivalent

The CLI rule IDs match the check-box rules in the desktop app's Fix Common Errors window. If you prototyped a fix set in the GUI, use this table (or seconv list-fce-rules, which prints the same three columns) to find the matching --fix-common-errors-rules IDs. Language gate marks rules that only run for one detected language (override with --fce-language, or by naming the rule).

Output format aliases

Run seconv formats for the full catalog (380+ entries, including input-only formats like Matroska, MP4, and MCC).

Exit codes

Legacy syntax

• Old SE 4.x /parameter:value syntax is auto-translated to --parameter:value.
• Older smashed-together long options (--inputfolder, --ocrengine, --FixCommonErrors, …) are kept as hidden aliases for the new POSIX-style names (--input-folder, --ocr-engine, --fix-common-errors, …), so existing scripts keep working.

More examples

Bulk format conversion

seconv "*.srt" assa --input-folder:./input --output-folder:./output --overwrite

MKV → SRT extraction

seconv movie.mkv subrip --overwrite                       # one SRT per language
seconv movie.mkv subrip --track-number:3 --overwrite      # only track 3
seconv movie.mkv subrip --forced-only --overwrite         # forced only

Blu-Ray sup OCR with cleanup

seconv subs.sup subrip \
  --ocr-engine:tesseract \
  --ocr-language:eng \
  --remove-text-for-hi \
  --split-long-lines \
  --overwrite

Round-trip via image-based output

seconv subs.srt bluraysup --resolution:1920x1080 --overwrite
seconv subs.srt bdnxml --overwrite

Styled Blu-Ray sup (SE4 /convert parity)

# SE4: SubtitleEdit.exe /convert movie.srt blu-raysup /Resolution:3840x2160 (+ styling from Settings.xml)
seconv movie.srt bluraysup \
  --resolution:3840x2160 \
  --font-name:Arial --font-size:100 \
  --background-color:"#B4000000" \
  --overwrite

EBU STL with reused header

seconv new.srt ebustl --ebu-header-file:original.stl --overwrite

Time shift + frame-rate conversion

seconv subs.srt subrip --fps:24 --target-fps:25 --offset:500 --overwrite

Plain text export

seconv movie.srt plaintext --overwrite

Custom JSON output via template

seconv movie.srt customtext --custom-format:lines-template.xml --output-filename:movie.json --overwrite

Architecture

seconv depends only on Subtitle Edit's core libraries — no Avalonia / GUI runtime:

src/
├── libse/        Core subtitle library (NuGet-shippable, netstandard2.1;net10.0)
├── libuilogic/   Shared headless logic (BatchConverter pipeline, OCR matchers, image renderer)
├── seconv/       This CLI
└── ui/           Avalonia desktop UI (not referenced by seconv)

This means seconv can run on systems without a display (CI, headless servers, Docker) without bundling Avalonia or any X server.

See also

• Supported Formats — full format catalog
• Batch Convert — GUI equivalent
• OCR — engine details and language packs