Subtitle Tools by langbot-team

# Subtitle Tools

Convert and re-time subtitle/caption files (SRT ↔ VTT). Pure Python stdlib.

## What it does

- Convert between SRT and VTT.
- Shift timings by milliseconds (fix late/early subtitles).
- Scale timings by a factor (fix frame-rate mismatches).
- Extract plain text from a subtitle file.

## Files

| File | Purpose |
|------|---------|
| `SKILL.md` | Instructions the agent receives on activation |
| `scripts/subs.py` | Convert/shift/scale/extract on SRT and VTT |
| `references/formats.md` | SRT vs VTT notes and timing-fix math |

## Requirements

None — uses only the Python standard library.

## License

Apache-2.0.


---
name: subtitle-tools
display_name: Subtitle Tools
description: "Work with subtitle files: convert between SRT and VTT, shift/scale timings, strip to plain text, and renumber. Use when the user has a .srt or .vtt subtitle/caption file and wants to convert, re-time, or extract the text. Do NOT use for transcribing audio (that needs a speech-to-text tool)."
license: Apache-2.0
---

# Subtitle Tools

Convert and manipulate subtitle/caption files (SRT ↔ VTT) without external services.

## When to use

The user has a `.srt` or `.vtt` file and wants to convert format, shift/scale the
timing (e.g. subtitles are 2s late), or pull out just the spoken text.

## Execution steps

1. **Identify the file** under `/workspace` and what they want done.
2. Run `python scripts/subs.py <command> ...` (pure stdlib, no installs):
   - Convert: `subs.py convert in.srt out.vtt` (direction inferred from extensions)
   - Shift: `subs.py shift in.srt out.srt --ms 2000` (positive = later, negative = earlier)
   - Scale: `subs.py scale in.srt out.srt --factor 1.0427` (e.g. 23.976→25 fps)
   - Text: `subs.py text in.srt out.txt` (strip timings/indices to plain text)
3. **Report** the output path and a one-line summary (e.g. "shifted +2.0s, 412 cues").

## Rules

- Preserve cue order and text exactly; only change what was asked.
- For timing fixes, confirm the direction (late vs early) before shifting.
- Keep multi-line cue text intact.

## Available resources

- `scripts/subs.py` — convert/shift/scale/extract on SRT and VTT files (stdlib only).
- `references/formats.md` — SRT vs VTT format notes and common timing-fix math.