amagi-clipper 0.1.0__tar.gz

amagi_clipper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

amagi_clipper-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: amagi-clipper
+Version: 0.1.0
+Summary: Turn a long podcast, webinar or stream VOD into vertical 9:16 clips with burned-in captions. Local faster-whisper + ffmpeg, no API key.
+Author-email: "AmagiLabs (Amagisolutionsgroup, Inc.)" <dev@amagisolutionsgroup.com>
+License: MIT
+Project-URL: Homepage, https://github.com/amagilabs/amagi-clipper
+Project-URL: Source, https://github.com/amagilabs/amagi-clipper
+Project-URL: Issues, https://github.com/amagilabs/amagi-clipper/issues
+Keywords: podcast,shorts,clips,whisper,ffmpeg,captions,reels,tiktok,cli,claude-code
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.0.0
+Requires-Dist: av<19,>=15.1.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# amagi-clipper
+
+Point it at a long podcast, webinar, or stream recording and get back vertical 9:16 clips with burned-in captions, ready for Shorts, Reels, and TikTok. It runs on your own computer with no API key and no subscription.
+
+![demo](assets/demo.gif)
+
+amagi-clipper transcribes the recording locally with [faster-whisper](https://github.com/SYSTRAN/faster-whisper). It then scores every 20 to 75 second run of whole sentences on how well it stands alone, and uses ffmpeg to cut the top picks into 1080x1920 mp4s. Captions appear up to three words at a time, with the word being spoken in yellow.
+
+It was built for solo podcasters and small agencies who record every week and never find the time to cut clips.
+
+![three clips from the demo episode](assets/clips.png)
+
+*Frames from the three clips it cut from the demo episode (audio-only input, so it used the waveform layout).*
+
+## Install
+
+```
+pipx install amagi-clipper
+```
+
+Or from a clone of this repo: `pipx install .`
+
+You also need [ffmpeg](https://ffmpeg.org/) on your PATH. Python 3.10 or newer. The first run downloads the Whisper model you pick. If you have an NVIDIA GPU, amagi-clipper uses it automatically. GPU transcription also needs NVIDIA's cuBLAS and cuDNN 9 libraries (see the [faster-whisper install notes](https://github.com/SYSTRAN/faster-whisper)). If they are missing, amagi-clipper says so and falls back to the CPU.
+
+## Usage
+
+```
+amagi-clipper <file> [-o OUTDIR] [-n 5] [--min 20] [--max 75] [--layout auto|crop|blur|audiogram] [--model small] [--dry-run]
+```
+
+| Option | What it does |
+|---|---|
+| `-o`, `--outdir` | Where run folders go (default `amagi_clipper_out`) |
+| `-n`, `--count` | How many clips to cut (default 5) |
+| `--min`, `--max` | Shortest and longest clip in seconds (default 20 and 75) |
+| `--layout` | `crop` fills the frame from the center, `blur` puts the whole picture over a blurred copy, `audiogram` draws a waveform. Default: `crop` for video, `audiogram` for audio-only |
+| `--model` | faster-whisper size: `tiny`, `base`, `small` (default), `medium`, `large-v3` |
+| `--device` | `auto` (default), `cpu`, or `cuda` |
+| `--language` | Spoken language code such as `en` (default: detect) |
+| `--size` | Output size (default `1080x1920`) |
+| `--font`, `--font-size`, `--highlight` | Caption font (default Arial), size in pixels (default 5% of frame height), and the color of the spoken word (default `#FFD400`) |
+| `--no-upper` | Keep caption case as spoken instead of UPPERCASE |
+| `--no-headline` | Audiogram clips: leave out the headline at the top |
+| `--transcript` | Reuse a `transcript.json` from an earlier run instead of transcribing |
+| `--dry-run` | Score and list the clips, render nothing |
+
+Examples:
+
+```
+# Five clips from a video podcast, center-cropped
+amagi-clipper episode42.mp4
+
+# A two-person or screen-share recording: keep the whole picture
+amagi-clipper webinar.mp4 --layout blur -n 3
+
+# See what it would cut before rendering anything
+amagi-clipper episode42.mp4 --dry-run
+```
+
+Transcription is the slow step, so the transcript is cached in the run folder. Run the same file again with a different `-n`, `--min`, `--max`, or `--layout` and Whisper is skipped.
+
+## Real output
+
+The demo episode in `tests/fixtures/demo_episode.m4a` is 144 seconds of two synthesized voices. We wrote the script with three self-contained monologues buried among intro, outro, and back-and-forth chatter, to see whether amagi-clipper would find them. Here is the run on an RTX 3090 with the default `small` model:
+
+```
+$ amagi-clipper tests/fixtures/demo_episode.m4a -o runs -n 3
+#1   97.0  01:13-01:41    28s  clip_01.mp4  "Why do most clips fail?"
+#2   91.0  00:27-00:56    30s  clip_02.mp4  "Here's the truth nobody tells you about growing a podcast."
+#3   91.0  01:49-02:15    26s  clip_03.mp4  "Stop paying $30 a month for clip software."
+runs/demo_episode
+```
+
+It picked the three monologues and skipped the intro. Transcription plus three 1080x1920 renders took 23.7 seconds of wall time.
+
+Each run writes `<outdir>/<name>/`:
+
+- `clip_01.mp4`, `clip_02.mp4`, ...: the vertical clips with captions burned in.
+- `clip_01.srt`, ...: plain caption files, for platforms that take them.
+- `clips.md`: every clip with its score, the reasons behind it, and the full text.
+- `clips.json`: the same data for scripts.
+- `transcript.json`: word-level timestamps, reused on the next run.
+
+The entry for clip 1 in `clips.md` (full file in [examples/demo_episode](examples/demo_episode/clips.md)):
+
+```markdown
+## 1. 97.0 - [01:13 - 01:41] 28s
+
+- File: `clip_01.mp4`
+- Hook: "Why do most clips fail?"
+- Score parts: hook 27, standalone 20, ending 15, length 10, boundaries 10, delivery 15
+- Why: hook: opens with a question (+); hook: 'why' framing (+); hook: short first sentence, 5 words (+); standalone: clean start and finished last sentence (+); ending: lands on a full statement (+); length: 27s sits in the 26-53s sweet spot (+)
+```
+
+## How scoring works
+
+amagi-clipper splits the transcript into sentences at end punctuation or at any pause of 1.2 seconds or more. Every run of whole sentences between `--min` and `--max` is a candidate. Each candidate gets up to 100 points:
+
+| Part | Points | What earns them |
+|---|---|---|
+| Hook | 30 | The first sentence works as an opener: a question, a number, "here's", "why", "stop", talking to "you", short. An opener like "and", "so", or "but", or an intro line such as "welcome back", scores zero |
+| Standalone | 20 | Starts clean, with no "it" or "that" pointing back at something the viewer never heard, and finishes its last sentence |
+| Ending | 15 | Ends on a statement. Stopping on a question, on a short reply like "It was.", or running into the sign-off costs points |
+| Length | 10 | Sits in the middle of your `--min`/`--max` range |
+| Boundaries | 10 | Has a half-second pause before and after, so the cut does not clip a word |
+| Delivery | 15 | Few filler words, 1.8 to 4.0 words per second, no dead air over 2.5 seconds |
+
+The best clips are picked first and never overlap. Every point gained or lost is written to `clips.md` in plain words, so you can see why a clip ranked where it did.
+
+## Use it as a Claude Code skill
+
+The repo includes a `SKILL.md`. Copy it into your skills folder:
+
+```
+mkdir -p ~/.claude/skills/amagi-clipper
+cp SKILL.md ~/.claude/skills/amagi-clipper/SKILL.md
+```
+
+Then ask Claude to "cut five clips from episode42.mp4". It runs `amagi-clipper` and reads `clips.md` back to you.
+
+## Limitations
+
+- Scoring is a heuristic, not an LLM. It finds clean, self-contained stretches with a strong first line. It cannot tell whether a joke lands. Watch the clips before you post them.
+- `crop` is a fixed center crop with no face tracking. If the speaker sits off-center, use `--layout blur`.
+- Whisper on a CPU is slow. On our busy test PC, `small` ran slower than real time. `--model base` or `tiny` is faster but less accurate, and an NVIDIA GPU is much faster.
+- The demo episode is synthesized speech written for the test. Real conversations are messier, so expect to see more picks you would skip.
+
+## Related AmagiLabs projects
+
+- [amagi-listen](https://github.com/amagilabs/amagi-listen): give Claude a podcast or meeting recording and get back a chaptered transcript.
+- [amagi-watch](https://github.com/amagilabs/amagi-watch): give Claude a video URL and get back a transcript and key frames.
+- More tools at [github.com/amagilabs](https://github.com/amagilabs).
+
+If amagi-clipper saved you an afternoon of scrubbing through a timeline, a star helps other podcasters find it.
+
+## License
+
+MIT. Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs). See [LICENSE](LICENSE).
+
+Built by [AmagiLabs](https://amagilabs.ai).

amagi_clipper-0.1.0/README.md

@@ -0,0 +1,140 @@
+# amagi-clipper
+
+Point it at a long podcast, webinar, or stream recording and get back vertical 9:16 clips with burned-in captions, ready for Shorts, Reels, and TikTok. It runs on your own computer with no API key and no subscription.
+
+![demo](assets/demo.gif)
+
+amagi-clipper transcribes the recording locally with [faster-whisper](https://github.com/SYSTRAN/faster-whisper). It then scores every 20 to 75 second run of whole sentences on how well it stands alone, and uses ffmpeg to cut the top picks into 1080x1920 mp4s. Captions appear up to three words at a time, with the word being spoken in yellow.
+
+It was built for solo podcasters and small agencies who record every week and never find the time to cut clips.
+
+![three clips from the demo episode](assets/clips.png)
+
+*Frames from the three clips it cut from the demo episode (audio-only input, so it used the waveform layout).*
+
+## Install
+
+```
+pipx install amagi-clipper
+```
+
+Or from a clone of this repo: `pipx install .`
+
+You also need [ffmpeg](https://ffmpeg.org/) on your PATH. Python 3.10 or newer. The first run downloads the Whisper model you pick. If you have an NVIDIA GPU, amagi-clipper uses it automatically. GPU transcription also needs NVIDIA's cuBLAS and cuDNN 9 libraries (see the [faster-whisper install notes](https://github.com/SYSTRAN/faster-whisper)). If they are missing, amagi-clipper says so and falls back to the CPU.
+
+## Usage
+
+```
+amagi-clipper <file> [-o OUTDIR] [-n 5] [--min 20] [--max 75] [--layout auto|crop|blur|audiogram] [--model small] [--dry-run]
+```
+
+| Option | What it does |
+|---|---|
+| `-o`, `--outdir` | Where run folders go (default `amagi_clipper_out`) |
+| `-n`, `--count` | How many clips to cut (default 5) |
+| `--min`, `--max` | Shortest and longest clip in seconds (default 20 and 75) |
+| `--layout` | `crop` fills the frame from the center, `blur` puts the whole picture over a blurred copy, `audiogram` draws a waveform. Default: `crop` for video, `audiogram` for audio-only |
+| `--model` | faster-whisper size: `tiny`, `base`, `small` (default), `medium`, `large-v3` |
+| `--device` | `auto` (default), `cpu`, or `cuda` |
+| `--language` | Spoken language code such as `en` (default: detect) |
+| `--size` | Output size (default `1080x1920`) |
+| `--font`, `--font-size`, `--highlight` | Caption font (default Arial), size in pixels (default 5% of frame height), and the color of the spoken word (default `#FFD400`) |
+| `--no-upper` | Keep caption case as spoken instead of UPPERCASE |
+| `--no-headline` | Audiogram clips: leave out the headline at the top |
+| `--transcript` | Reuse a `transcript.json` from an earlier run instead of transcribing |
+| `--dry-run` | Score and list the clips, render nothing |
+
+Examples:
+
+```
+# Five clips from a video podcast, center-cropped
+amagi-clipper episode42.mp4
+
+# A two-person or screen-share recording: keep the whole picture
+amagi-clipper webinar.mp4 --layout blur -n 3
+
+# See what it would cut before rendering anything
+amagi-clipper episode42.mp4 --dry-run
+```
+
+Transcription is the slow step, so the transcript is cached in the run folder. Run the same file again with a different `-n`, `--min`, `--max`, or `--layout` and Whisper is skipped.
+
+## Real output
+
+The demo episode in `tests/fixtures/demo_episode.m4a` is 144 seconds of two synthesized voices. We wrote the script with three self-contained monologues buried among intro, outro, and back-and-forth chatter, to see whether amagi-clipper would find them. Here is the run on an RTX 3090 with the default `small` model:
+
+```
+$ amagi-clipper tests/fixtures/demo_episode.m4a -o runs -n 3
+#1   97.0  01:13-01:41    28s  clip_01.mp4  "Why do most clips fail?"
+#2   91.0  00:27-00:56    30s  clip_02.mp4  "Here's the truth nobody tells you about growing a podcast."
+#3   91.0  01:49-02:15    26s  clip_03.mp4  "Stop paying $30 a month for clip software."
+runs/demo_episode
+```
+
+It picked the three monologues and skipped the intro. Transcription plus three 1080x1920 renders took 23.7 seconds of wall time.
+
+Each run writes `<outdir>/<name>/`:
+
+- `clip_01.mp4`, `clip_02.mp4`, ...: the vertical clips with captions burned in.
+- `clip_01.srt`, ...: plain caption files, for platforms that take them.
+- `clips.md`: every clip with its score, the reasons behind it, and the full text.
+- `clips.json`: the same data for scripts.
+- `transcript.json`: word-level timestamps, reused on the next run.
+
+The entry for clip 1 in `clips.md` (full file in [examples/demo_episode](examples/demo_episode/clips.md)):
+
+```markdown
+## 1. 97.0 - [01:13 - 01:41] 28s
+
+- File: `clip_01.mp4`
+- Hook: "Why do most clips fail?"
+- Score parts: hook 27, standalone 20, ending 15, length 10, boundaries 10, delivery 15
+- Why: hook: opens with a question (+); hook: 'why' framing (+); hook: short first sentence, 5 words (+); standalone: clean start and finished last sentence (+); ending: lands on a full statement (+); length: 27s sits in the 26-53s sweet spot (+)
+```
+
+## How scoring works
+
+amagi-clipper splits the transcript into sentences at end punctuation or at any pause of 1.2 seconds or more. Every run of whole sentences between `--min` and `--max` is a candidate. Each candidate gets up to 100 points:
+
+| Part | Points | What earns them |
+|---|---|---|
+| Hook | 30 | The first sentence works as an opener: a question, a number, "here's", "why", "stop", talking to "you", short. An opener like "and", "so", or "but", or an intro line such as "welcome back", scores zero |
+| Standalone | 20 | Starts clean, with no "it" or "that" pointing back at something the viewer never heard, and finishes its last sentence |
+| Ending | 15 | Ends on a statement. Stopping on a question, on a short reply like "It was.", or running into the sign-off costs points |
+| Length | 10 | Sits in the middle of your `--min`/`--max` range |
+| Boundaries | 10 | Has a half-second pause before and after, so the cut does not clip a word |
+| Delivery | 15 | Few filler words, 1.8 to 4.0 words per second, no dead air over 2.5 seconds |
+
+The best clips are picked first and never overlap. Every point gained or lost is written to `clips.md` in plain words, so you can see why a clip ranked where it did.
+
+## Use it as a Claude Code skill
+
+The repo includes a `SKILL.md`. Copy it into your skills folder:
+
+```
+mkdir -p ~/.claude/skills/amagi-clipper
+cp SKILL.md ~/.claude/skills/amagi-clipper/SKILL.md
+```
+
+Then ask Claude to "cut five clips from episode42.mp4". It runs `amagi-clipper` and reads `clips.md` back to you.
+
+## Limitations
+
+- Scoring is a heuristic, not an LLM. It finds clean, self-contained stretches with a strong first line. It cannot tell whether a joke lands. Watch the clips before you post them.
+- `crop` is a fixed center crop with no face tracking. If the speaker sits off-center, use `--layout blur`.
+- Whisper on a CPU is slow. On our busy test PC, `small` ran slower than real time. `--model base` or `tiny` is faster but less accurate, and an NVIDIA GPU is much faster.
+- The demo episode is synthesized speech written for the test. Real conversations are messier, so expect to see more picks you would skip.
+
+## Related AmagiLabs projects
+
+- [amagi-listen](https://github.com/amagilabs/amagi-listen): give Claude a podcast or meeting recording and get back a chaptered transcript.
+- [amagi-watch](https://github.com/amagilabs/amagi-watch): give Claude a video URL and get back a transcript and key frames.
+- More tools at [github.com/amagilabs](https://github.com/amagilabs).
+
+If amagi-clipper saved you an afternoon of scrubbing through a timeline, a star helps other podcasters find it.
+
+## License
+
+MIT. Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs). See [LICENSE](LICENSE).
+
+Built by [AmagiLabs](https://amagilabs.ai).

amagi_clipper-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "amagi-clipper"
+version = "0.1.0"
+description = "Turn a long podcast, webinar or stream VOD into vertical 9:16 clips with burned-in captions. Local faster-whisper + ffmpeg, no API key."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AmagiLabs (Amagisolutionsgroup, Inc.)", email = "dev@amagisolutionsgroup.com" }]
+keywords = ["podcast", "shorts", "clips", "whisper", "ffmpeg", "captions", "reels", "tiktok", "cli", "claude-code"]
+classifiers = [
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video :: Conversion",
+]
+dependencies = [
+    "faster-whisper>=1.0.0",
+    "av>=15.1.0,<19",
+    "numpy>=1.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/amagilabs/amagi-clipper"
+Source = "https://github.com/amagilabs/amagi-clipper"
+Issues = "https://github.com/amagilabs/amagi-clipper/issues"
+
+[project.scripts]
+amagi-clipper = "amagi_clipper.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

amagi_clipper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

amagi_clipper-0.1.0/src/amagi_clipper/__init__.py

@@ -0,0 +1,3 @@
+"""amagi-clipper: cut a long recording into vertical captioned clips, locally."""
+
+__version__ = "0.1.0"

amagi_clipper-0.1.0/src/amagi_clipper/captions.py

@@ -0,0 +1,126 @@
+"""Caption files for a clip: an .ass file to burn in (word-by-word highlight) and a plain .srt."""
+from __future__ import annotations
+
+import re
+
+STRIP_PUNCT = re.compile(r"^[\"'(\[]+|[\"')\],;:]+$")
+
+
+def chunk_words(words: list[dict], max_words: int = 3, max_chars: int = 14) -> list[list[dict]]:
+    """Split words into short on-screen chunks. A chunk also ends after sentence punctuation."""
+    chunks: list[list[dict]] = []
+    cur: list[dict] = []
+    for w in words:
+        text_len = len(" ".join(x["word"] for x in cur + [w]))
+        if cur and (len(cur) >= max_words or text_len > max_chars):
+            chunks.append(cur)
+            cur = []
+        cur.append(w)
+        if re.search(r"[.!?]$", w["word"]):
+            chunks.append(cur)
+            cur = []
+    if cur:
+        chunks.append(cur)
+    return chunks
+
+
+def shift(words: list[dict], offset: float) -> list[dict]:
+    return [{**w, "start": max(0.0, w["start"] - offset), "end": max(0.0, w["end"] - offset)} for w in words]
+
+
+def ass_time(t: float) -> str:
+    cs = int(round(max(0.0, t) * 100))
+    h, cs = divmod(cs, 360000)
+    m, cs = divmod(cs, 6000)
+    s, cs = divmod(cs, 100)
+    return f"{h:d}:{m:02d}:{s:02d}.{cs:02d}"
+
+
+def srt_time(t: float) -> str:
+    ms = int(round(max(0.0, t) * 1000))
+    h, ms = divmod(ms, 3600000)
+    m, ms = divmod(ms, 60000)
+    s, ms = divmod(ms, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def ass_escape(text: str) -> str:
+    return text.replace("\\", "\\\\").replace("{", "(").replace("}", ")").replace("\n", " ")
+
+
+def display(word: str, upper: bool) -> str:
+    word = STRIP_PUNCT.sub("", word) or word
+    return word.upper() if upper else word
+
+
+def hex_to_ass(color: str) -> str:
+    """'#FFD400' -> '&H00D4FF' (ASS override colors are BBGGRR)."""
+    c = color.lstrip("#")
+    if not re.fullmatch(r"[0-9A-Fa-f]{6}", c):
+        raise ValueError(f"color must look like #RRGGBB, got {color!r}")
+    r, g, b = c[0:2], c[2:4], c[4:6]
+    return f"&H{b}{g}{r}".upper()
+
+
+def build_ass(words: list[dict], width: int, height: int, font: str = "Arial", font_size: int | None = None,
+              highlight: str = "#FFD400", upper: bool = True, clip_end: float | None = None,
+              headline: str | None = None) -> str:
+    """ASS subtitles with times relative to the clip start. Each chunk shows whole; the spoken word is highlighted.
+
+    `headline`, if given, sits at the top of the frame for the whole clip (used for audiogram clips).
+    """
+    size = font_size or max(24, round(height * 0.05))
+    margin_v = round(height * 0.22)
+    outline = max(2, round(size * 0.08))
+    hl = hex_to_ass(highlight)
+    lines = [
+        "[Script Info]",
+        "ScriptType: v4.00+",
+        f"PlayResX: {width}",
+        f"PlayResY: {height}",
+        "WrapStyle: 0",
+        "ScaledBorderAndShadow: yes",
+        "",
+        "[V4+ Styles]",
+        "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, "
+        "Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, "
+        "MarginR, MarginV, Encoding",
+        f"Style: Caption,{font},{size},&H00FFFFFF,&H00FFFFFF,&H00000000,&H80000000,-1,0,0,0,100,100,0,0,1,"
+        f"{outline},0,2,60,60,{margin_v},1",
+        f"Style: Headline,{font},{round(size * 0.8)},&H00FFFFFF,&H00FFFFFF,&H00000000,&H00000000,-1,0,0,0,100,100,0,0,1,"
+        f"{max(1, outline // 2)},0,8,90,90,{round(height * 0.12)},1",
+        "",
+        "[Events]",
+        "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
+    ]
+    if headline:
+        end = clip_end if clip_end is not None else (words[-1]["end"] + 0.3 if words else 0.0)
+        lines.append(f"Dialogue: 1,{ass_time(0)},{ass_time(end)},Headline,,0,0,0,,{ass_escape(headline)}")
+    chunks = chunk_words(words)
+    for ci, chunk in enumerate(chunks):
+        nxt = chunks[ci + 1][0]["start"] if ci + 1 < len(chunks) else None
+        chunk_end = chunk[-1]["end"] + 0.3
+        if nxt is not None:
+            # Hold the chunk through short pauses so captions don't blink off between phrases.
+            chunk_end = nxt if nxt - chunk[-1]["end"] < 1.0 else min(chunk_end, nxt)
+        if clip_end is not None:
+            chunk_end = min(chunk_end, clip_end)
+        for wi, w in enumerate(chunk):
+            start = w["start"]
+            end = chunk[wi + 1]["start"] if wi + 1 < len(chunk) else chunk_end
+            if end <= start:
+                continue
+            parts = []
+            for k, x in enumerate(chunk):
+                t = ass_escape(display(x["word"], upper))
+                parts.append(f"{{\\c{hl}&}}{t}{{\\c&HFFFFFF&}}" if k == wi else t)
+            lines.append(f"Dialogue: 0,{ass_time(start)},{ass_time(end)},Caption,,0,0,0,,{' '.join(parts)}")
+    return "\n".join(lines) + "\n"
+
+
+def build_srt(words: list[dict]) -> str:
+    out = []
+    for i, chunk in enumerate(chunk_words(words, max_words=7, max_chars=42), 1):
+        text = " ".join(w["word"] for w in chunk)
+        out.append(f"{i}\n{srt_time(chunk[0]['start'])} --> {srt_time(chunk[-1]['end'])}\n{text}\n")
+    return "\n".join(out)