videobeaux/docs/programs/utilities/subs_convert.md

subs_convert

Description

Converts subtitle files between formats (e.g., SRT, VTT, ASS) while preserving timing, text, and (where possible) style metadata.

Purpose

The subs_convert program standardizes subtitle workflows by:

• Listing available subtitle tracks in a media file.
• Extracting specific subtitle tracks by index or language.
• Converting them to a desired output format.
• Optionally cleaning or shifting them in time.

It is especially helpful when preparing subtitles for caption-burning, translations, or multi-version deliverables.

How It Works

1. Input Inspection
   Reads subtitle streams from the input media file (or compatible subtitle sources).
2. Track Selection
   • list shows all available subtitle tracks with indices and metadata.
   • indexes selects specific tracks by index.
   • langs filters tracks by language codes (e.g., eng, spa).
   • all overrides filters and selects every subtitle track.
3. Filtering & Cleaning
   • forced_only restricts output to forced subtitles only (e.g., foreign-language dialogue).
   • exclude_hi strips hearing-impaired (HI) descriptors like sound effects or music tags.
4. Format Conversion
   Converts the selected tracks into the requested output format (SRT, VTT, ASS, etc.).
5. Timing Adjustment
   Applies an optional time_shift so subtitles can be nudged earlier or later to stay in sync.
6. Output Writing
   Writes one or more subtitle files to an output directory or a specific outputfile path.

Program Template

videobeaux -P subs_convert \
  -i input.mp4 \
  -o output.mp4 \
  --list VALUE \
  --indexes VALUE \
  --langs VALUE \
  --all VALUE \
  --forced_only VALUE \
  --exclude_hi VALUE \
  --format VALUE \
  --outdir VALUE \
  --outputfile VALUE \
  --time_shift VALUE

Arguments

• list — List all subtitle tracks in the input with indexes, languages, and basic metadata. Useful as a first step to see what is available.
• indexes — One or more subtitle track indexes to extract/convert (e.g., 0, 1,2). Accepts a comma-separated list.
• langs — Filter tracks by language codes (e.g., eng, spa). Accepts one or more languages, usually as a comma-separated list, depending on implementation.
• all — Select all subtitle tracks, ignoring indexes and langs filters.
• forced_only — Restrict output to subtitle events marked as “forced” (e.g., foreign-language dialogue or plot-critical on-screen text).
• exclude_hi — Attempt to remove hearing-impaired (HI) descriptors such as [MUSIC], (LAUGHTER), and other non-dialogue notes.
• format — Output format for converted subtitles, such as srt, vtt, or ass. The exact set of valid formats depends on the underlying subtitle tooling.
• outdir — Directory where the converted subtitle files should be written. Filenames are usually derived from the input and track metadata.
• outputfile — Explicit path and filename for the converted subtitle file when you only want a single, known output file location.
• time_shift — Apply a timing offset to all subtitle cues. Positive values delay subtitles; negative values make them appear earlier (e.g., -0.25 shifts cues 250ms earlier).

Real World Example

videobeaux -P subs_convert \
  -i documentary.mp4 \
  -o documentary_fixed.mp4 \
  --langs eng \
  --exclude_hi \
  --format vtt \
  --time_shift -0.25 \
  --outdir subs_output

Technical Notes

• list is often used alone to inspect subtitle tracks before running a full conversion.
• If both indexes and langs are provided, explicit indexes typically take priority.
• all supersedes both indexes and langs, ensuring every subtitle track is processed.
• time_shift expects a value in seconds and can be fractional for fine-grained adjustment.
• Some formats (like ASS) support styling; preservation depends on how much style data exists in the source.

Recommended Usage

• Start with list to discover track indices and language tags.
• Use langs when targeting a specific language for translation or distribution.
• Use exclude_hi for clean, dialogue-only subtitle deliveries.
• Use format ass when preparing styled subtitles for tools like captburn.
• Use time_shift after trimming or re-cutting your video to quickly re-align subtitles without manual editing.