captions-compliance
Skill1 starsChanged 3 months agoMITView on GitHub
Broadcast caption compliance — validate and format SRT, export CEA-608 SCC and SMPTE-TT, flag busy-zone collisions, and transcribe speech to captions. Use when delivering FCC-aligned captions or handoff to linear/broadcast workflows.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- site/AGENTS.mdAGENTS.md
- site/CLAUDE.mdCLAUDE.md
- audioSkill
- downloadSkill
- forced-narrative-exactSkill
- imageSkill
- inspectSkill
- install-media-toolsSkill
- program-masterSkill
- shotsSkill
- speech-captionsSkill
- subtitlesSkill
- timecodeSkill
- video-transformationSkill
- vision-analysisSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 71
If your tools showed a filesystem path when loading this SKILL.md, strip SKILL.md and use that folder.
- Very specific: line 72
If you already ran another mediaskills script (for example .../audio/scripts/extract.py), this skill is a sibling of that folder: same …
- Very specific: line 95
Prefer absolute paths for --input / --output when cwd is uncertain.
- Distinctive: line 100
Before running any script, treat these two failures differently:
- Very specific: line 103
Only escalate sandbox permissions if the error is explicitly a permission denial (e.g.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Captions Compliance
Validate, normalize, and export captions for broadcast and streaming delivery. Scripts follow FCC-oriented readability heuristics (line length, duration, overlap) and produce CEA-608 SCC (Scenarist V1.0) and SMPTE-TT / TTML for downstream systems.
When to use
- This skill — compliance checks, SRT cleanup, SCC/SMPTE-TT export, busy-zone review, speech → SRT pipeline.
timecode— frame-accurate timecode math when aligning captions to 29.97/30fps sequences.subtitles— burn-in, shift timing, or convert between subtitle formats after you have a compliant SRT.
Broadcast context
FCC (U.S. closed captioning)
The FCC requires accurate, synchronous, and readable captions for most television and IP-delivered video. Practical heuristics used here:
| Rule | Typical target | Script |
| Characters per line | ≤ 32 (608) / ≤ 42 (reading comfort) | rules.py, validate.py, format.py |
| Lines on screen | ≤ 2 | rules.py, validate.py |
| On-screen duration | ~1–7 seconds | rules.py, validate.py |
| Reading speed | ~15–20 chars/sec | rules.py |
| Safe area | Title-safe (~10% margin) | rules.py, apply-busy-zones.py |
These are guidelines, not legal certification. Always verify against your distributor's spec (e.g. Netflix, PBS, local station).
CEA-608 / Scenarist SCC
- SCC (Scenarist Closed Caption V1.0) encodes CEA-608 line-21 captions as hex word pairs with odd parity.
- Pop-on style: load to non-displayed memory (RCL/ENM), position with PAC codes, display (EOC), clear (EDM).
- Character set is limited to basic North American ASCII; unsupported glyphs are replaced.
to-scc.pyplaces captions on rows 14–15 (bottom of the 15-row 608 grid).
SMPTE-TT (TTML)
- SMPTE ST 2052 / TTML is the common interchange for file-based and OTT caption delivery.
to-smpte-tt.pyemits a minimal TTML document with<p begin="…" end="…">cues.- Timestamps use VTT-style
HH:MM:SS.mmm(comma in SRT is normalized).
Gotchas
- 608 vs 708 — SCC export is CEA-608 only. CEA-708 (DTVCC) requires a different encoder.
- 29.97 SCC timebase — SCC output uses a 30-frame grid (non-drop) common in Scenarist files; verify against your NLE's import settings.
- Overlap detection —
validate.pyflags overlapping cues; fix timing before SCC export. - Long lines in 608 —
to-scc.pyhard-wraps at 32 characters per row; runformat.pyfirst for cleaner breaks. - Busy lower thirds —
apply-busy-zones.pyis a heuristic flagger, not vision-based detection. - Whisper accuracy —
to-captions-pipeline.pyuses thetinymodel by default; use larger models for accuracy at the cost of speed.
Running scripts
This skill's scripts live in scripts/ alongside this file. Before running any script, resolve its absolute path from this skill's own directory — do not assume the shell cwd is the skill folder, the repo root, or the workspace. Stay in the workspace (so media paths resolve) and pass the absolute script path to uv run:
uv run <skill_directory>/scripts/validate.py --input captions.srt<skill_directory> is a placeholder. Never pass those angle brackets to the shell — the command will fail. Replace it with a real absolute directory before invoking uv run.
How to get that directory (do this yourself; do not ask the user first; do not skip the skill):
- If your tools showed a filesystem path when loading this
SKILL.md, stripSKILL.mdand use that folder. - If you already ran another mediaskills script (for example
.../audio/scripts/extract.py), this skill is a sibling of that folder: same parent, directory namecaptions-compliance. - Otherwise search standard install locations and confirm the script exists:
NAME=captions-compliance
for d in \
"$HOME/.agents/skills/$NAME" \
"$HOME/.cursor/skills/$NAME" \
"$HOME/.codex/skills/$NAME" \
"$HOME/.claude/skills/$NAME" \
"$PWD/.agents/skills/$NAME" \
"$PWD/.cursor/skills/$NAME" \
"$PWD/skills/$NAME"
do
if [ -f "$d/SKILL.md" ] && [ -e "$d/scripts/validate.py" ]; then
SKILL_DIR=$(cd "$d" && pwd)
break
fi
done
[ -n "$SKILL_DIR" ] || { echo "mediaskills: $NAME not found" >&2; exit 1; }
uv run "$SKILL_DIR/scripts/validate.py" --input captions.srtPrefer absolute paths for --input / --output when cwd is uncertain.
Missing binaries vs permissions
Before running any script, treat these two failures differently:
- If a required binary (
uv,ffmpeg) reportsNo such file or directoryorcommand not found: this is a missing or unreachable binary, not a permissions issue. Escalating sandbox permissions will not fix it. Runcommand -v uvandcommand -v ffmpegto see whether they resolve at all. If not, install or re-link them (install-media-toolsdoctor/install) rather than retrying with wider permissions.ffmpegis required forto-captions-pipeline.py; other scripts only needuv. - Only escalate sandbox permissions if the error is explicitly a permission denial (e.g.
Operation not permitted,Permission denied).
Recipes
Check compliance rules
uv run <skill_directory>/scripts/rules.pyValidate an SRT file
uv run <skill_directory>/scripts/validate.py --input captions.srtNormalize whitespace and wrap long lines
uv run <skill_directory>/scripts/format.py --input captions.srtExport for broadcast (SCC / CEA-608)
uv run <skill_directory>/scripts/to-scc.py --input captions.srt --output deliverable.sccExport SMPTE-TT / TTML
uv run <skill_directory>/scripts/to-smpte-tt.py --input captions.srt --output captions.xmlFlag cues that may hit lower-thirds
uv run <skill_directory>/scripts/apply-busy-zones.py --input captions.srtSpeech → SRT (full pipeline)
uv run <skill_directory>/scripts/to-captions-pipeline.py --input clip.mp4 --model tinyTroubleshooting
| Symptom | Cause | Action |
valid: false with overlaps | Cues share time ranges | Edit timing or re-run transcription |
| SCC import fails in NLE | Invalid parity or timecode | Re-export; check validate_scc errors in stderr |
? characters in SCC | Unsupported Unicode in source | Replace in SRT before export |
| Empty SCC / no cues | Malformed SRT | Run validate.py first |
ffmpeg not found | Missing binary | Install via install-media-tools skill |
| Whisper slow or inaccurate | Model size | Try --model base or small |
Available scripts
| Script | Op | Purpose |
scripts/rules.py | caption.rules | FCC-oriented compliance rule set |
scripts/validate.py | caption.validate | Timing, overlap, and readability checks |
scripts/format.py | caption.format | Normalize and soft-wrap SRT |
scripts/to-scc.py | caption.to_scc | SRT → Scenarist SCC V1.0 (CEA-608) |
scripts/to-smpte-tt.py | caption.to_smpte_tt | SRT → SMPTE-TT / TTML XML |
scripts/apply-busy-zones.py | caption.apply_busy_zones | Flag long/multiline lower-screen cues |
scripts/to-captions-pipeline.py | caption.to_captions_pipeline | Media → SRT via faster-whisper |
See references/BROADCAST_GUIDELINES.md for context.
Acceptance checks (agent must pass before delivery)
- Contract: exit 0,
ok: true, everyoutput_pathsentry exists and is non-empty. - Skill gate: run
validate.pybefore SCC/SMPTE-TT export; resolve blocking overlaps and timing issues (or document intentional residuals). - Spot-check: first/last cues readable; SCC/TTML open in target NLE or viewer when available.
- Distributor specs still override heuristics — never claim legal certification from this skill alone.
- On failure: fix or escalate; do not export SCC from invalid timing.
Do not use for
- Legal caption certification
- Burning subtitles (use
subtitles/burn.py) - General video editing (use
video-transformation)
Related skills
timecode— timecode conversion for frame-accurate alignmentsubtitles— burn-in, shift, and format conversioninstall-media-tools— ffmpeg for the transcription pipeline
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

