Subtitle Toolkit

Convert subtitle text between formats. Reads SRT, WebVTT, ASS/SSA, YouTube SBV and TTML/DFXP; writes SRT, WebVTT, ASS, CSV or plain text. Format is auto-detected unless `from` is given.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The full subtitle file text."
    },
    "to": {
      "type": "string",
      "enum": [
        "srt",
        "vtt",
        "ass",
        "csv",
        "text"
      ],
      "description": "Target format. `text` = plain transcript, one line per cue, no timecodes."
    },
    "from": {
      "type": "string",
      "enum": [
        "auto",
        "srt",
        "vtt",
        "ass",
        "sbv",
        "ttml"
      ],
      "description": "Source format (default \"auto\" = detect)."
    },
    "dedupe": {
      "type": "boolean",
      "description": "Only for to=\"text\": collapse consecutive identical lines (rolling-caption transcripts repeat lines). Default false."
    }
  },
  "required": [
    "content",
    "to"
  ]
}

Strip noise from auto-generated subtitles: HTML/WebVTT tags, ASS override codes, music and sound-effect cues, speaker labels, empty cues and duplicate lines. Returns the subtitle file in SRT or WebVTT.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The full subtitle file text."
    },
    "remove_tags": {
      "type": "boolean",
      "description": "Strip HTML/WebVTT tags and ASS override codes. Default true."
    },
    "remove_sound_cues": {
      "type": "boolean",
      "description": "Strip [Music], [Applause], ♪ ... ♪ and similar. Default true."
    },
    "remove_speaker_labels": {
      "type": "boolean",
      "description": "Strip leading \"SPEAKER:\" prefixes. Default false — enable only if you want them gone."
    },
    "drop_empty": {
      "type": "boolean",
      "description": "Drop cues that become empty after cleaning. Default true."
    },
    "drop_duplicates": {
      "type": "boolean",
      "description": "Drop cues whose text was already seen. Default false."
    },
    "to": {
      "type": "string",
      "enum": [
        "srt",
        "vtt"
      ],
      "description": "Output format. Default: same as the input."
    }
  },
  "required": [
    "content"
  ]
}

Fix subtitle timing. Use offset_seconds for a uniform shift (whole track early/late). Use ratio, or from_fps/to_fps, for progressive drift caused by a frame-rate mismatch. Pass exactly one of the three.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The full subtitle file text."
    },
    "offset_seconds": {
      "type": "number",
      "description": "Shift every cue by this many seconds. Negative = earlier. e.g. -2.5"
    },
    "ratio": {
      "type": "number",
      "description": "Scale all timings by this factor (new = old x ratio). e.g. 1.0427 for a 25→23.976 fps fix."
    },
    "from_fps": {
      "type": "number",
      "description": "The frame rate the subtitles were authored for (used with to_fps)."
    },
    "to_fps": {
      "type": "number",
      "description": "The frame rate of the actual video (used with from_fps)."
    }
  },
  "required": [
    "content"
  ]
}

Audit subtitle readability and produce a report: reading speed (CPS), cue durations that are too short or too long, lines that are too wide, more than two lines, and overlapping cues. Returns a formatted report listing every flagged cue.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The full subtitle file text."
    },
    "max_cps": {
      "type": "number",
      "description": "Max characters per second. Default 20."
    },
    "min_duration_seconds": {
      "type": "number",
      "description": "Minimum cue duration in seconds. Default 0.833 (Netflix 5/6s)."
    },
    "max_duration_seconds": {
      "type": "number",
      "description": "Maximum cue duration in seconds. Default 7."
    },
    "max_line_length": {
      "type": "number",
      "description": "Max characters per line. Default 42."
    }
  },
  "required": [
    "content"
  ]
}

Append one subtitle track after another (CD1 + CD2, or a second language track). The second track is offset so it starts after the last cue of the first, plus an optional gap.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The first subtitle file text."
    },
    "append_content": {
      "type": "string",
      "description": "The subtitle file text to append."
    },
    "gap_seconds": {
      "type": "number",
      "description": "Extra gap between the two tracks, in seconds. Default 0."
    },
    "to": {
      "type": "string",
      "enum": [
        "srt",
        "vtt"
      ],
      "description": "Output format. Default: same as the input."
    }
  },
  "required": [
    "content",
    "append_content"
  ]
}

Split one subtitle track into two parts at a given timecode, keeping original timecodes. Use the `at` argument plus `part` to fetch either half.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The full subtitle file text."
    },
    "at": {
      "type": "string",
      "description": "Split point. Accepts \"45:00\", \"1:02:03\", \"90\" (seconds) or \"1:02:03.500\"."
    },
    "part": {
      "type": "string",
      "enum": [
        "a",
        "b"
      ],
      "description": "Which half to return. Default \"a\" (before the split point)."
    },
    "to": {
      "type": "string",
      "enum": [
        "srt",
        "vtt"
      ],
      "description": "Output format. Default: same as the input."
    }
  },
  "required": [
    "content",
    "at"
  ]
}

Repair mojibake — text where UTF-8 bytes were decoded as a single-byte encoding (cp1252/Latin-1 or cp1251). Symptoms: "é", "’", "привет". Returns the repaired text and how many passes were applied.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The garbled subtitle text."
    },
    "read_as": {
      "type": "string",
      "enum": [
        "auto",
        "cp1252",
        "cp1251"
      ],
      "description": "Which encoding the file was wrongly read as. Default \"auto\" (tries cp1252 then cp1251)."
    },
    "twice": {
      "type": "boolean",
      "description": "Set true when the text was mis-decoded twice (nested mojibake). Default false."
    }
  },
  "required": [
    "content"
  ]
}

Turn a plain transcript (one line per caption) into an SRT file with evenly spaced timecodes. Timing is a starting point, not a real transcription — say so when you present the result.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Plain text, one caption per line. Blank lines are skipped."
    },
    "duration_seconds": {
      "type": "number",
      "description": "Seconds each cue stays on screen. Default 2.5."
    },
    "start_seconds": {
      "type": "number",
      "description": "Timecode of the first cue, in seconds. Default 0."
    },
    "max_chars_per_cue": {
      "type": "number",
      "description": "Split longer lines into several cues at word boundaries. Default 0 = never split."
    }
  },
  "required": [
    "content"
  ]
}