Subtitle File Fixer

---
name: subtitle-file-fixer
description: Cleans up SRT and WebVTT subtitle and caption files. It removes overlaps and empty captions, sorts and renumbers, splits captions that are too long, re-wraps lines (42 characters, 2 lines by default), gives short or fast captions more time where there's room, shifts all timing, strips formatting tags and converts between SRT and VTT. It reports captions that still read too fast, so their wording can be shortened. Use when the user says things like "fix my subtitles", "my captions overlap", "clean up this SRT", "convert SRT to VTT", "captions are out of sync by 2 seconds", "make my captions readable for Reels", or uploads a .srt or .vtt file.
---

# Subtitle File Fixer

Run the automatic fixes, shorten what still reads too fast, and check again.

Rules you never break:

1. **Never change the meaning.** Wording edits only shorten (fillers, repeats). Never add words that weren't said, and never change names, numbers or claims.
2. **Wording changes need the user's OK.** List each one. Timing and layout fixes are automatic.
3. **Never overwrite the user's file.** Always write a new file with `--out`.

## Bundled files

| File | When to use it |
|---|---|
| `scripts/subs.mjs` | Steps 1, 2 and 4. Reports without `--out`. With `--out`, writes a new SRT or VTT (never overwrites). Needs Node.js 18+. |
| `references/subtitle-guidelines.md` | The reasons behind the defaults, what's automatic and what's left, and vertical video tips. Read it when choosing settings. |
| `examples/` | `messy.srt`, the fixed outputs, the report, a walkthrough and test runs. |

## Step 1: Report first

```
node <skill-folder>/scripts/subs.mjs <file.srt|file.vtt> [settings]
```

Settings to consider:
- **Vertical video** (TikTok, Reels, Shorts): `--max-chars 32`.
- **Children's content:** `--max-cps 14`.
- **Out of sync:** `--shift 1.5` (later) or `--shift -0.5` (earlier). Ask the user which direction, or compare a known line's time with the video.
- **Tags that platforms don't show:** `--strip-tags`.

## Step 2: Apply the automatic fixes

```
node <skill-folder>/scripts/subs.mjs <file> --out <name>-fixed.srt   (or .vtt to convert)
```

## Step 3: Fix what's left

For each "Still to look at" item:
- **Too fast:** shorten the wording, keeping names, numbers and meaning. Aim for the reading-speed limit.
- **Too short with no room:** merge it into the next caption, or drop a pure filler ("Okay.", "Um").
- **Long line with tags:** strip the tags (`--strip-tags`), or edit the line.

Edit the fixed file (a copy, never the original) and keep a list of changes for the user.

## Step 4: Check again

Run the report on the edited file until "Still to look at" is 0, or only items the user chose to keep remain.

## Step 5: Report back

1. What was fixed automatically (the counts from the report).
2. Every wording change, with old and new text.
3. The output file names. Offer a VTT copy or vertical-video settings if relevant.

**No Node.js?** For short files (under about 50 captions), fix overlaps and line lengths by hand. Say the script wasn't run.