1
---
2
name: srt-subtitle-quality-checker
3
description: Checks SRT and WebVTT subtitle files for broken or overlapping timings, numbering gaps, empty cues, reading speed above a characters-per-second limit, long or extra lines, cues that flash by or linger, unbalanced tags, and sound labels, then rewrites and retimes the problem cues and can shift the whole file. Use when a user shares subtitles or captions and asks "check my subtitles", "why are these captions hard to read?", "fix the timing", or "make these subtitles follow the guidelines".
4
---
5
6
# SRT Subtitle Quality Checker
7
8
You help video makers, translators, and accessibility teams ship subtitles that people can actually read. You find timing errors that break players, cues that appear too briefly or carry too much text, and lines that are too long, and you fix them by rewriting the text more concisely and adjusting times, without changing the meaning.
9
10
## Files in this skill
11
12
- `scripts/check_subtitles.py` - parses SRT and WebVTT, checks timing, numbering, reading speed, line length, line count, duration, gaps, tags, and sound labels, and can shift every timestamp (Python 3 standard library only)
13
- `references/subtitle-guidelines.md` - common limits for reading speed, line length, duration, gaps, line breaks, and when to use SDH labels
14
- `references/condensing-techniques.md` - how to shorten subtitle text without losing meaning, and how to retime cues
15
- `templates/subtitle-review.md` - the review report to return
16
- `examples/example-workshop-video.md` - a worked review of a short tutorial video
17
18
## Workflow
19
20
### 1. Collect the facts
21
Ask, or assume and say so:
22
- The file (SRT or VTT) and the video length; frame rate if known (24, 25, or 30 fps).
23
- Audience and style guide: general adult viewers, children, a platform guide, or the client's own limits.
24
- Subtitle type: same-language captions, translation, or SDH (for deaf and hard-of-hearing viewers, with sound labels).
25
- Whether you may rewrite text or only retime it.
26
27
### 2. Run the checker
28
```bash
29
python3 scripts/check_subtitles.py movie.srt
30
python3 scripts/check_subtitles.py movie.srt --max-cps 15 --max-line 37 # children or stricter guides
31
python3 scripts/check_subtitles.py movie.vtt --json
32
python3 scripts/check_subtitles.py movie.srt --shift -1200 > movie-synced.srt # whole file 1.2 s earlier
33
```
34
Defaults: 17 characters per second, 42 characters per line, 2 lines, 0.833 to 7 seconds on screen, 83 ms minimum gap. Pick limits from `references/subtitle-guidelines.md` to match the audience. If you cannot run the script, check the cues by hand: duration, characters divided by seconds, longest line, and overlaps with the next cue.
35
36
### 3. Fix in this order
37
1. HIGH findings first: overlaps, out-of-order cues, end before start, bad timestamps, empty cues. These break players or hide text.
38
2. Reading speed: extend the cue into free time before or after it (respect the minimum gap and shot changes the user mentions), otherwise condense the text with `references/condensing-techniques.md`, otherwise split the cue in two at a natural pause.
39
3. Line length and line count: rebreak at natural phrase boundaries; keep the top line shorter when possible; never break between an article and its noun.
40
4. Too short or too long on screen: merge very short cues with a neighbor, split long ones.
41
5. INFO items: renumber, balance tags, remove sound labels from non-SDH files, chain cues (0 ms gap) or leave a visible gap.
42
Rerun the checker on the corrected file until there are no HIGH findings and every WARN is fixed or explained.
43
44
### 4. Deliver
45
Fill in `templates/subtitle-review.md`: summary with counts before and after, the limits used, a table of changed cues (old and new times and text), and the full corrected file in the same format as the input. Follow the style of `examples/example-workshop-video.md`.
46
47
## Rules
48
- Never change the meaning, tone, or speaker of a line; condense filler, not content.
49
- Keep names, numbers, and technical terms exactly; if a term is wrong, flag it instead of guessing.
50
- Timing changes must stay in sync with the speech: extend a cue only into silence, by at most about 0.5 s before speech starts or 1 s after it ends, unless the user allows more.
51
- Keep the input format (SRT stays SRT, VTT stays VTT) and the original encoding (UTF-8).
52
- Say clearly which findings you could not fix without hearing the audio or seeing the video.
53