agentleFS
timelapsetechtimelapsetech/mediaskills/.agents/skills/captions-compliance/SKILL.md

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.

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
  1. Very specific:

    If your tools showed a filesystem path when loading this SKILL.md, strip SKILL.md and use that folder.

    line 71
  2. Very specific:

    If you already ran another mediaskills script (for example .../audio/scripts/extract.py), this skill is a sibling of that folder: same …

    line 72
  3. Very specific:

    Prefer absolute paths for --input / --output when cwd is uncertain.

    line 95
  4. Distinctive:

    Before running any script, treat these two failures differently:

    line 100
  5. Very specific:

    Only escalate sandbox permissions if the error is explicitly a permission denial (e.g.

    line 103

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

RuleTypical targetScript
Characters per line≤ 32 (608) / ≤ 42 (reading comfort)rules.py, validate.py, format.py
Lines on screen≤ 2rules.py, validate.py
On-screen duration~1–7 secondsrules.py, validate.py
Reading speed~15–20 chars/secrules.py
Safe areaTitle-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.py places 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.py emits 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.py flags overlapping cues; fix timing before SCC export.
  • Long lines in 608 — to-scc.py hard-wraps at 32 characters per row; run format.py first for cleaner breaks.
  • Busy lower thirds — apply-busy-zones.py is a heuristic flagger, not vision-based detection.
  • Whisper accuracy — to-captions-pipeline.py uses the tiny model 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):

  1. If your tools showed a filesystem path when loading this SKILL.md, strip SKILL.md and use that folder.
  2. If you already ran another mediaskills script (for example .../audio/scripts/extract.py), this skill is a sibling of that folder: same parent, directory name captions-compliance.
  3. 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.srt

Prefer 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) reports No such file or directory or command not found: this is a missing or unreachable binary, not a permissions issue. Escalating sandbox permissions will not fix it. Run command -v uv and command -v ffmpeg to see whether they resolve at all. If not, install or re-link them (install-media-tools doctor/install) rather than retrying with wider permissions. ffmpeg is required for to-captions-pipeline.py; other scripts only need uv.
  • 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.py

Validate an SRT file

uv run <skill_directory>/scripts/validate.py --input captions.srt

Normalize whitespace and wrap long lines

uv run <skill_directory>/scripts/format.py --input captions.srt

Export for broadcast (SCC / CEA-608)

uv run <skill_directory>/scripts/to-scc.py --input captions.srt --output deliverable.scc

Export SMPTE-TT / TTML

uv run <skill_directory>/scripts/to-smpte-tt.py --input captions.srt --output captions.xml

Flag cues that may hit lower-thirds

uv run <skill_directory>/scripts/apply-busy-zones.py --input captions.srt

Speech → SRT (full pipeline)

uv run <skill_directory>/scripts/to-captions-pipeline.py --input clip.mp4 --model tiny

Troubleshooting

SymptomCauseAction
valid: false with overlapsCues share time rangesEdit timing or re-run transcription
SCC import fails in NLEInvalid parity or timecodeRe-export; check validate_scc errors in stderr
? characters in SCCUnsupported Unicode in sourceReplace in SRT before export
Empty SCC / no cuesMalformed SRTRun validate.py first
ffmpeg not foundMissing binaryInstall via install-media-tools skill
Whisper slow or inaccurateModel sizeTry --model base or small

Available scripts

ScriptOpPurpose
scripts/rules.pycaption.rulesFCC-oriented compliance rule set
scripts/validate.pycaption.validateTiming, overlap, and readability checks
scripts/format.pycaption.formatNormalize and soft-wrap SRT
scripts/to-scc.pycaption.to_sccSRT → Scenarist SCC V1.0 (CEA-608)
scripts/to-smpte-tt.pycaption.to_smpte_ttSRT → SMPTE-TT / TTML XML
scripts/apply-busy-zones.pycaption.apply_busy_zonesFlag long/multiline lower-screen cues
scripts/to-captions-pipeline.pycaption.to_captions_pipelineMedia → SRT via faster-whisper

See references/BROADCAST_GUIDELINES.md for context.

Acceptance checks (agent must pass before delivery)

  1. Contract: exit 0, ok: true, every output_paths entry exists and is non-empty.
  2. Skill gate: run validate.py before SCC/SMPTE-TT export; resolve blocking overlaps and timing issues (or document intentional residuals).
  3. Spot-check: first/last cues readable; SCC/TTML open in target NLE or viewer when available.
  4. Distributor specs still override heuristics — never claim legal certification from this skill alone.
  5. 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 alignment
  • subtitles — burn-in, shift, and format conversion
  • install-media-tools — ffmpeg for the transcription pipeline

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.