explainer-studio 0.1.5__tar.gz → 0.1.6__tar.gz

explainer_studio-0.1.6/.claude/skills/make-explainer-video/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: make-explainer-video
+description: Make a narrated explainer video (YouTube landscape or 9:16 reel) with this studio. Use when asked to create, script, narrate, design scenes for, preview, check, render or thumbnail an episode under episodes/, or to fix a failing `studio check` or render.
+---
+
+# Make an explainer video with the studio
+
+Pipeline: `script.md` → local TTS → word timings → one HyperFrames scene per script section → cached renders → mastered MP4, `.srt` and chapters in `out/`. All commands run from the workspace (the folder holding `episodes/`) as `studio <cmd> <slug>`; in a clone of the repository, run it as `uv run studio <cmd> <slug>`.
+
+The full reference (script settings, TTS engines, gotchas) is `AGENTS.md` in a clone, or `references/agents.md` beside this file when the skill was installed with `studio install-skill`. The design spec is `brand/frame.md` or `references/frame.md`, and the starter script is `templates/script.md` or `references/script-template.md`. (In a pip-installed workspace there is no `brand/` or `templates/` folder unless you copied one in; the house style then ships with the package.) Read the design spec before designing any scene, and load the `hyperframes-core` and `hyperframes-animation` skills for the composition contract and motion. Don't restate them from memory.
+
+## Workflow
+
+1. **Scaffold**: `studio new <slug> "Title"` creates `episodes/<slug>/`. Read the starter script and, if present, the worked example `episodes/demo-paris-commune/`.
+2. **Write `script.md`** (the only source of truth for words, scene order and chapters):
+   - Front matter: `title`, `voice`, `speed`; `format: reel` and `burn_captions: true` for 9:16.
+   - One `## <id>: <chapter title>` per scene, then `> template: title|blank|stat|quote|points|outro`, optional `> duration: n` (required if a scene has no narration), then narration. Other `>` lines are visual notes and are never spoken.
+   - `{name}` marks a cue the visuals can hit; `{pause n}` adds a beat.
+   - Open on a question, contrast or striking fact in the first 5–10s. About 150–165 wpm: 5 min ≈ 700–750 words. Three main sections beat seven, and each needs a re-hook. Aim for 30–60s for a reel.
+   - Write numbers and abbreviations as they should be spoken, or add a respelling to `pronounce:`.
+   - YouTube chapters need at least 3, each 10s or longer. Consecutive scenes with the same title merge.
+3. **Sync**: `studio sync <slug>` narrates, aligns, stubs `scenes/<id>.html` from the templates and writes `index.html` and `timing.json`. `studio status <slug>` shows words, estimated and actual length, and cues per scene. Fix length and pacing in the script, then re-sync. Only changed paragraphs are re-narrated.
+4. **Design each scene** in `episodes/<slug>/scenes/<id>.html`. Rules:
+   - Keep the `/* <studio:timing> */` block; `sync` rewrites it. Time animation with `cue("name", fallback)` and `T.*`, never hard-coded seconds.
+   - Prefix every id and class with the scene id. The root is `#root`. Keep the script in its IIFE.
+   - Use `gsap.fromTo` for entrances, and no CSS `transform` on anything GSAP moves.
+   - Start with `<div class="paper">`, put content in `.stage` (or `.stage-reel`), and keep the final 0.5s exit fade (not on the outro).
+   - Put images in `assets/media/` and reference them as `assets/media/x.jpg`. Every figure, quote and photo gets a `.byline` source line.
+   - One idea on screen at a time, triggered by the narration. Use brand classes from `brand/brand.css`, with red on a single focal element.
+   - Changing `> template:` on an existing scene does nothing. Delete the scene file to re-stub it.
+   - Edit `brand/` for house-style changes, never `episodes/<slug>/assets/brand/` (a synced copy).
+5. **Review**: `studio preview <slug>` opens HyperFrames Studio with narration. For a look without a browser, run `npx hyperframes snapshot episodes/<slug> --at 12.5,40` and view the frames.
+6. **Check**: `studio check <slug>` must pass with 0 errors (lint, layout, contrast) before any render.
+7. **Render**: `studio render <slug> --draft` for a review copy, then `studio render <slug>` for `out/<slug>.mp4`, `.srt` and `.chapters.txt`. Only changed scenes re-render, and `--force [ids]` forces them. A full render takes about real time. Optionally run `studio thumbnail <slug>` after editing `thumbnail/thumbnail.html`.
+
+## Voice
+
+Default is Kokoro (local, free). `studio voices <slug>` writes loudness-matched samples to `out/voice-samples/` for choosing a voice or blend. Kokoro ignores SSML, so punctuation is the only delivery control. `tts: chatterbox` (voice cloning) and `tts: elevenlabs` (billed per character, key in `.env`; never read or print `.env`) are described in `AGENTS.md`. Ask before switching to a paid engine. Changing any voice setting re-narrates everything.
+
+## Gotchas
+
+- `index.html` and `timing.json` are generated; never hand-edit them.
+- Add `audio/recorded/<id>.wav|flac|m4a|mp3` to replace TTS for one scene.
+- A crashed render can leave `_render_*.html` in the episode; delete it.
+- DNS errors on downloads: `resolvectl flush-caches`.
+- Commit `audio/vo/`, `timing.json` and `index.html` after `sync`, because CI never narrates. Commit messages use `episode:` for episode content and `brand:` for the house style.
+
+## Music
+
+After `sync`, generate the bed yourself: `studio music <slug> --prompt "<genre, mood, tempo, instruments>" --variants 2`. It makes an instrumental ElevenLabs Music track as long as the episode (about $0.0083 a second, so tell the user the cost for long episodes) and prints the `music:` line. Match the prompt to the episode's tone, name no artists or songs, then set `music:` in `script.md`, listen or spot-check with a draft render, and log the track in `brand/music/CREDITS.md`. If it fails with a 401 naming `music_generation`, the API key lacks that permission: tell the user to enable it in ElevenLabs. If music is unavailable, fall back to writing a Suno-style song description (genre, mood, tempo, instrumentation, "instrumental, no vocals") for the user.
+
+## Done means
+
+`studio check` passes, a draft render has been made and its frames spot-checked, and the final render and `out/` files exist. Report the paths.

{explainer_studio-0.1.5 → explainer_studio-0.1.6}/.gitignore

@@ -229,3 +229,7 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Licensed (non-OFL) fonts: keep out of the public repo and the wheel
+brand/fonts-licensed/*
+!brand/fonts-licensed/README.md

explainer_studio-0.1.6/AGENTS.md

@@ -0,0 +1,117 @@
+# Explainer video studio
+
+Command-line studio for narrated explainer videos (~5 min, 1920x1080 30fps, for YouTube),
+with a clean editorial house style. Pipeline: `script.md` → local TTS narration → word-aligned timing →
+one HyperFrames sub-composition per scene → cached per-scene renders → mastered MP4, captions
+and chapters in `out/`.
+
+## Quick start
+
+```bash
+uv run studio new <slug> "Title"     # scaffold episodes/<slug>/
+$EDITOR episodes/<slug>/script.md    # write the script (format below)
+uv run studio sync <slug>            # narrate + align + stub scenes + write index.html
+uv run studio status <slug>          # word counts, est vs actual length, cues per scene
+# design each scenes/<id>.html (see "Authoring scenes")
+uv run studio preview <slug>         # HyperFrames Studio in the browser (with narration)
+uv run studio check <slug>           # lint + layout + contrast audits; must pass
+uv run studio render <slug> --draft  # fast review copy -> out/<slug>-draft.mp4
+uv run studio render <slug>          # final -> out/<slug>.mp4 + .srt + .chapters.txt
+uv run studio music <slug> --prompt "..."  # ElevenLabs Music bed sized to the synced episode (after sync)
+uv run studio thumbnail <slug>       # out/<slug>-thumbnail.jpg (edit thumbnail/thumbnail.html)
+```
+
+`episodes/demo-paris-commune/` is a complete worked example (38s, 4 scenes).
+
+## Layout
+
+- `brand/`: the house style, shared by every episode. **Edit here, never in an episode's copy.**
+  - `frame.md`: design spec (tokens in front matter, rules in prose). Read before designing a scene.
+  - `brand.css`: fonts, colour tokens and page furniture classes (`.section-head`, `.tag`, `.headline`, `.standfirst`, `.quote`, `.byline`, `.hl`…).
+  - `fonts/`: PT Serif + Source Sans 3 and JetBrains Mono, all OFL. `vendor/gsap.min.js` (no CDN at render time).
+  - `pronunciations.yaml`: studio-wide TTS respellings (acronyms, names).
+  - `music/`: optional music beds (`studio music --out brand/music/<name>.mp3` generates one with ElevenLabs Music).
+- `templates/scenes/*.html`: scene patterns: `title`, `blank`, `stat`, `quote`, `points`, `outro`. `templates/script.md` is the starter script and `templates/thumbnail.html` the thumbnail.
+- `tools/studio/`: the Python CLI (`uv run studio …`).
+- `episodes/<slug>/`: one HyperFrames project per video.
+  - `script.md`: **source of truth** for words, scene order and chapter titles.
+  - `scenes/<id>.html`: one sub-composition per scene. Created from a template on first sync, then yours.
+  - `index.html`, `timing.json`: **generated**. Never hand-edit.
+  - `audio/vo/`: generated narration plus `.words.json` timings. `audio/tts/`: TTS cache.
+  - `audio/recorded/<id>.wav|flac|m4a|mp3`: optional real recording that replaces TTS for that scene.
+  - `assets/brand/`: synced copy of `brand/`. `assets/media/`: episode images and footage.
+  - `build/`: render cache (safe to delete).
+- `out/`: deliverables.
+- **Workspace.** `ROOT` (`tools/studio/common.py`) is `$STUDIO_ROOT`, else the nearest folder at or above the cwd that has `episodes/`, else the cwd. `BRAND` and `TEMPLATES` are the workspace's `brand/` and `templates/` when present (as in this repo), else the copies bundled in the package (`PKG_DATA`, `studio/data/` in the wheel). `brand/music/` and `brand/voices/` are always workspace paths.
+
+## Script format (`episodes/<slug>/script.md`)
+
+```markdown
+---
+title: The Paris Commune
+voice: bf_emma*0.6 + bf_isabella*0.4   # Kokoro voice or weighted blend (UK: bf_*, bm_*; US: af_*, am_*)
+speed: 0.85
+music: brand/music/bed.mp3  # optional, ducked under the voice
+pronounce: { Engels: Engles }
+---
+## hook: Seventy-two days          <- "## <id>: <chapter title>"
+> template: title                  <- pattern for a NEW scene file
+> duration: 4                      <- optional minimum length (required if no narration)
+> Any other quoted line is a visual note, never spoken.
+
+Narration paragraph. {sub} A cue: the scene can act exactly when the next word is spoken.
+Next paragraph (blank line = short pause). {pause 1.5} An explicit pause.
+```
+
+- Scene ids: lowercase, start with a letter, `a-z0-9-`. Consecutive scenes with the same title merge into one YouTube chapter. YouTube needs at least 3 chapters, each 10s or longer; `render` warns when they aren't.
+- Write numbers and abbreviations as they should be **spoken** when the voice gets them wrong, or add a respelling to `pronounce:`. Captions always use the script's spelling.
+- **Kokoro voice.** `voice:` takes one voice or a weighted blend (`a*0.6 + b*0.4`) of their style vectors. Blends sound less synthetic than single voices. By Kokoro's own grades, `bf_emma` (B-) is the best UK voice and the UK male voices are C or lower. Audition with `uv run studio voices <slug> [--scene id] [--speed 0.85] [--voices "spec" ...]`, which writes loudness-matched samples to `out/voice-samples/`. Speed is relative to each voice: aim for ~150–170 wpm.
+- **Kokoro delivery.** Phonemes come from **misaki** (`g2p: misaki`, the G2P Kokoro was trained on: proper RP vowels, "1871" read as a year) rather than espeak (`g2p: espeak`). Each sentence is a separate utterance, so each one gets its own falling intonation; they're joined by `sentence_pause` (0.38s). Kokoro ignores SSML and emotion tags, so punctuation is the only lever: commas for breaths, full stops for resets, `?` for questions, and `{pause n}` for a beat. `voice_fx: true` adds a gentle EQ, de-ess, compressor and faint room (`VOICE_FX` in `voice.py`). Any of these settings change re-synthesises the narration.
+- **ElevenLabs** instead of Kokoro: set `tts: elevenlabs` and `voice: <ElevenLabs voice ID>`. Optional: `tts_model` (default `eleven_multilingual_v2`) and `voice_settings: {stability, similarity_boost, style}`; `speed` is passed through (0.7–1.2). The key is read from `ELEVENLABS_API_KEY`, in the environment or in `.env` at the studio root (never commit it). It costs about 1 credit per character. Chunks are cached like Kokoro's, so only new or changed paragraphs are billed, and `sync` prints the characters it used. British voice picks: `docs/elevenlabs-voices.md`.
+- **Chatterbox** (Resemble AI, local, voice cloning): set `tts: chatterbox` and `voice: brand/voices/<name>.wav`, a reference clip (path relative to the studio root) or `default` for the model's built-in American voice. The clip must be **over 5s** (10–15s is best), clean, dry, mono speech with no music, in the accent and pace you want: pacing comes from the clip, and `speed` is ignored. `chatterbox_model: turbo` (default, 350M, English) or `standard` (500M), which also honours `exaggeration` (0.5; higher is more animated) and `cfg_weight` (0.5; lower is slower and more deliberate). Both use `temperature` (0.8) and `seed` (0, so a re-synthesis repeats). Text goes to the model in sentence groups of up to ~280 characters, joined by `sentence_pause`; a longer sentence is split at clause breaks (`, ; : —`), joined by `clause_pause`, and `voice_fx` applies as with Kokoro. The first run builds its environment and downloads the model (~1–2 GB). It runs on the CPU (~4–5× slower than real time here), but cached chunks are reused, so only changed paragraphs are re-synthesised. Re-recording the clip re-synthesises everything. Output carries Resemble's inaudible Perth watermark. `studio voices <slug>` with `tts: chatterbox` auditions every `brand/voices/*.wav` plus `default`, or the clips given with `--voices`.
+- **Music** (`uv run studio music <slug> --prompt "…"`): an instrumental bed from the ElevenLabs Music API (`POST /v1/music`, `force_instrumental`), sized to `timing.json` (run `sync` first) and cached by prompt, length and model in `audio/music/`. Needs `ELEVENLABS_API_KEY` with the `music_generation` permission (a 401 naming it means the key lacks it) and a paid plan for commercial use. About $0.0083 per second (third-party figure). `--variants N` makes takes to audition, `--out brand/music/x.mp3` shares one across episodes, `--model` picks `music_v1|v2|v2_5`. Describe genre, mood, tempo and instruments; never name artists or songs. Then set `music:` and log the track in `brand/music/CREDITS.md`. Code: `tools/studio/music.py`; the HTTP/retry helper `elevenlabs_post` is shared with narration in `voice.py`.
+- **Reels** (9:16 for Instagram, TikTok and Shorts): `format: reel` renders at 1080x1920, and `burn_captions: true` burns word-highlighted captions into the video (most reels autoplay muted). Scenes use `.stage-reel`; see the "Reel" section of `brand/frame.md` for safe zones. Aim for 30–60s.
+- Settings that can go in the front matter, with their defaults (`tools/studio/common.py`): `format landscape` (or `reel`), `burn_captions false`, `tts kokoro` (or `chatterbox`, `elevenlabs`), `g2p misaki`, `sentence_pause 0.38`, `clause_pause 0.12`, `voice_fx true`, `chatterbox_model turbo`, `exaggeration 0.5`, `cfg_weight 0.5`, `temperature 0.8`, `seed 0`, `fps 30`, `pad_in 0.6`, `pad_out 0.9`, `paragraph_gap 0.45`, `music_prompt` (default prompt for `studio music`), `music_db -24`, `music_fade_in 2`, `loudness -14`, `true_peak -1.5`.
+
+## Authoring scenes (`scenes/<id>.html`)
+
+Read `brand/frame.md` first, and use the `hyperframes-core` and `hyperframes-animation` skills for the composition contract and motion. Rules specific to this studio:
+
+- Keep the `/* <studio:timing> */ … /* </studio:timing> */` block. `sync` rewrites it with `T = {duration, voStart, voEnd, cues, paragraphs}` (scene-local seconds). Time animation with `cue("name", fallback)` and `T.*`, never hard-coded guesses, so re-recording narration re-times the visuals.
+- Prefix every id and scene-local class with the scene id (`#lesson-quote`) because all scenes share one page in preview. Style the root as `#root`. Keep the script in its IIFE.
+- Use `gsap.fromTo` for entrances, and no CSS `transform` on anything GSAP moves. Start each scene with `<div class="paper">` and content in `.stage` (title-safe). Keep the final 0.5s exit fade (except the outro).
+- Images and footage go in `assets/media/` and are referenced as `assets/media/x.jpg`. Show a source/credit line (`.byline`) for every figure, quote and photo.
+- Changing `> template:` after a scene file exists does nothing. Delete the scene file to re-stub it.
+- Before rendering, `uv run studio check <slug>` must pass with 0 errors. Spot-check frames with
+  `npx hyperframes snapshot episodes/<slug> --at 12.5,40` and look at them.
+
+## Rendering and output
+
+- Each scene renders separately, keyed on its HTML, assets, duration and quality, so only changed scenes re-render. `--force [ids]` re-renders explicitly. Scenes are concatenated losslessly. The voice track is built from `audio/vo/` and the music bed is ducked under it (sidechain). Audio is mastered to **−14 LUFS / −1.5 dBTP** (two-pass loudnorm), AAC 48 kHz.
+- `out/<slug>.srt`: upload as YouTube subtitles; captions are not burned in. `out/<slug>.chapters.txt`: paste into the description.
+- Speed on this machine (RX 580, GPU beginframe capture): a full render runs at about real time, and a single-scene change takes seconds.
+
+## Writing for this format (research notes, Oct 2026)
+
+- The first 5–10 seconds decide retention. Open on a question, contrast or striking fact, never "welcome to the channel". Then say what the video will explain.
+- ~150–165 words a minute (the default Kokoro blend at speed 0.85 measures ~165; `bm_george` at 1.0 ~155). 5 minutes ≈ 700–750 words. Leave visual breathing room.
+- Three main sections beat seven. Re-hook at each section change, and keep a payoff for the end.
+- One idea on screen at a time, triggered by the narration. Diagrams, documents and figures carry the argument; bullets are a last resort.
+- Keep the right ~45% of the last 5–20s clear for YouTube end-screen elements (the `outro` template does this).
+
+## Tools
+
+- **HyperFrames** CLI pinned at `HF_VERSION` in `tools/studio/common.py` (override with `STUDIO_HF_VERSION`). To upgrade, bump it, run `studio check` on an episode, and compare a draft render.
+- **Kokoro-82M** TTS runs in-process from the studio venv; the model is cached in `~/.cache/hyperframes/tts`. English phonemes come from misaki plus spaCy `en_core_web_sm`, which PyPI won't accept as a direct-URL dependency, so `voice.ensure_spacy_model()` unpacks the pinned wheel into `~/.cache/hyperframes/spacy` on first use (misaki is installed without `misaki[en]`, whose extra pulls in ~5 GB of torch for the unused transformer model). **Whisper** (`hyperframes transcribe`, small.en) gives word timings, which are aligned back onto the script text. `npx hyperframes models install parakeet` is faster and more accurate, and is used automatically once installed.
+- **Chatterbox** (optional local TTS, `tts: chatterbox`): pins torch and numpy<2, so it can't share the studio venv. On first use, `voice.Chatterbox` builds a separate venv at `~/.cache/hyperframes/chatterbox/<version>` (`uv pip install --torch-backend cpu`, plus `setuptools<81` for the watermarker's `pkg_resources` import) and drives `tools/studio/chatterbox_worker.py` over JSON lines on stdin/stdout. The version is pinned at `CHATTERBOX_VERSION` in `common.py` (override with `STUDIO_CHATTERBOX_VERSION`), and the weights are cached in `~/.cache/huggingface`. Delete the venv folder to rebuild it. No GPU: the RX 580 has no CUDA, and ROCm doesn't support it.
+- **ElevenLabs** (optional cloud TTS, `tts: elevenlabs`): stdlib HTTPS calls from `tools/studio/voice.py`, sending each paragraph with its neighbours' text so the delivery stays continuous.
+- **CI** (`.github/workflows/ci.yml`): `uv sync --locked`, ruff (`[tool.ruff]` in `pyproject.toml`), a CLI smoke test, and `hyperframes check` on every episode. It never narrates or renders, so commit `audio/vo/`, `timing.json` and `index.html` after `sync`.
+- **Releases** (`.github/workflows/release-please.yml`, `release-please-config.json`): release-please turns Conventional Commit messages into a release PR (version in `pyproject.toml` + `uv.lock`, `CHANGELOG.md`); merging it tags, publishes the GitHub release and uploads to PyPI (trusted publishing; see `RELEASING.md`). Only `brand/` files listed under `force-include` in `pyproject.toml` ship in the wheel. Write commit messages as `feat:`, `fix:`, `perf:`, `episode:` (episode content), `brand:` (house style), `docs:`, `deps:`, or `refactor:`/`test:`/`ci:`/`chore:` (not in the changelog). Never hand-edit the version or `CHANGELOG.md`.
+- ffmpeg 9, Chromium (thumbnails), uv (Python 3.12–3.13; `kokoro-onnx` needs <3.14).
+
+## Gotchas
+
+- Only one root-level HTML file may carry `data-composition-id`. `render` creates `_render_<id>.html` shells temporarily and deletes them; if a crash leaves one behind, delete it.
+- If package or model downloads fail with DNS errors (NordVPN + DNSSEC "signature-expired"), run `resolvectl flush-caches`.
+- If a render hangs or reports empty frames under GPU capture, add `--no-browser-gpu` in `render_scenes()` (`tools/studio/render.py`).
+- **DINPro** (the sans: labels, tags, bylines, captions) is a licensed FontFont, not OFL. Its TTFs live in gitignored `brand/fonts-licensed/` and must never be committed or moved into `brand/fonts/` (the repo is public and `brand/fonts/` ships in the wheel). Without them everything falls back to Source Sans 3. This build's `fi`/`fl` ligatures are broken, so `brand.css` turns common ligatures off and burned-in captions insert a zero-width non-joiner.

explainer_studio-0.1.5/README.md → explainer_studio-0.1.6/PKG-INFO

@@ -1,8 +1,30 @@
+Metadata-Version: 2.5
+Name: explainer-studio
+Version: 0.1.6
+Summary: Command-line studio for narrated explainer videos (HyperFrames + Kokoro TTS + ffmpeg)
+Project-URL: Homepage, https://joemountwsws.github.io/explainer-studio/
+Project-URL: Documentation, https://joemountwsws.github.io/explainer-studio/
+Project-URL: Repository, https://github.com/JoeMountWSWS/explainer-studio
+Project-URL: Issues, https://github.com/JoeMountWSWS/explainer-studio/issues
+Project-URL: Changelog, https://github.com/JoeMountWSWS/explainer-studio/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <3.14,>=3.12
+Requires-Dist: kokoro-onnx>=0.6.1
+Requires-Dist: misaki>=0.9
+Requires-Dist: num2words>=0.5
+Requires-Dist: numpy>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: soundfile>=0.12
+Requires-Dist: spacy<3.9,>=3.8
+Description-Content-Type: text/markdown
+
 # Explainer Studio
 
 [![CI](https://github.com/JoeMountWSWS/explainer-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/JoeMountWSWS/explainer-studio/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/explainer-studio)](https://pypi.org/project/explainer-studio/)
 
-A command-line studio for narrated explainer videos in the style of [wsws.org](https://www.wsws.org).
+A command-line studio for narrated explainer videos with a clean, editorial house style.
 You write a script in Markdown. The studio narrates it with local TTS, aligns every word to the audio,
 and turns each scene into a [HyperFrames](https://www.npmjs.com/package/hyperframes) HTML composition
 that is timed to the narration. It then renders a mastered 1920×1080 MP4 for YouTube, with captions
@@ -27,16 +49,7 @@ script.md ──► narration (Kokoro, local; or ElevenLabs) ──► word timi
 The first `sync` downloads the Kokoro-82M model to `~/.cache/hyperframes/tts` and spaCy's
 `en_core_web_sm` to `~/.cache/hyperframes/spacy`.
 
-# Usage
-
-Making a video with the studio is a loop of writing and listening. You write the script as plain
-Markdown, and the studio reads it aloud, works out exactly when each word is spoken, and hands those
-timings to your scenes so the visuals move in step with the voice. Change a sentence and only that
-sentence is re-recorded and only the affected scenes are re-rendered, so you can refine a five-minute
-video in seconds rather than starting over. Everything runs from one command, `uv run studio`, and
-nothing leaves your machine unless you choose cloud narration.
-
-## Install
+## Install the studio
 
 With the [requirements](#requirements) in place, either install the `studio` command from PyPI or
 clone the repository.
@@ -44,11 +57,16 @@ clone the repository.
 **From PyPI**, to make videos in a folder of your own:
 
 ```bash
-uv tool install explainer-studio   # or run it without installing: uvx --from explainer-studio studio …
+pip install explainer-studio       # or: uv tool install explainer-studio
 mkdir my-videos && cd my-videos
 studio new my-video "My Video"
 ```
 
+The package is on [PyPI](https://pypi.org/project/explainer-studio/). `uv tool install` puts
+`studio` on your PATH in its own isolated environment, and `uvx --from explainer-studio studio …`
+runs it without installing. With `pip`, install into a virtual environment (or use `pipx install
+explainer-studio`) so its dependencies stay separate from your system Python.
+
 The folder you run `studio` in becomes the workspace. It holds `episodes/`, `out/` and `.env`, and
 `studio` finds it from any subdirectory (or set `STUDIO_ROOT`). The house style (`brand/`) and scene
 templates ship with the package. To customise them, copy `brand/` or `templates/` from this repository
@@ -67,6 +85,31 @@ Run commands from the repository root (or any folder below it). Confirm the inst
 `uv run studio --help`. The first `sync` of an episode downloads the Kokoro voice model and the
 spaCy English model, so it takes a little longer than later runs.
 
+### Install the agent skill
+
+To have Claude Code drive the studio, install the `make-explainer-video` skill into your workspace:
+
+```bash
+cd my-videos
+studio install-skill           # -> .claude/skills/make-explainer-video/
+studio install-skill --user    # or for every project: ~/.claude/skills/
+```
+
+It installs the skill plus the references it reads (the studio guide, house-style spec and starter
+script). Start `claude` in the workspace and ask for a video, or run `/make-explainer-video`. Re-run
+the command with `--force` after upgrading the package to refresh it. From a clone the skill is
+already available with no installation. See
+[Working with a coding agent](https://joemountwsws.github.io/explainer-studio/coding-agents/).
+
+# Usage
+
+Making a video with the studio is a loop of writing and listening. You write the script as plain
+Markdown, and the studio reads it aloud, works out exactly when each word is spoken, and hands those
+timings to your scenes so the visuals move in step with the voice. Change a sentence and only that
+sentence is re-recorded and only the affected scenes are re-rendered, so you can refine a five-minute
+video in seconds rather than starting over. Everything runs from one command, `uv run studio`, and
+nothing leaves your machine unless you choose cloud narration.
+
 ## Quick start
 
 ```bash
@@ -128,6 +171,7 @@ Worked examples: `episodes/demo-paris-commune` (Kokoro, 38s) and `episodes/demo-
 The studio is designed to be driven by Claude Code or another coding agent. `AGENTS.md` (loaded
 through `CLAUDE.md`) gives the agent the conventions it needs, the HyperFrames skills cover the
 composition format and motion, and the `make-explainer-video` skill
-(`.claude/skills/make-explainer-video/`) walks Claude through the whole workflow. Start `claude` in
-the repository root and ask for a video, or run `/make-explainer-video`. See
+(`.claude/skills/make-explainer-video/`, or `studio install-skill` for a pip install) walks Claude
+through the whole workflow. Start `claude` in the repository root or your workspace and ask for a
+video, or run `/make-explainer-video`. See
 [Working with a coding agent](https://joemountwsws.github.io/explainer-studio/coding-agents/).

explainer_studio-0.1.5/PKG-INFO → explainer_studio-0.1.6/README.md

@@ -1,24 +1,9 @@
-Metadata-Version: 2.5
-Name: explainer-studio
-Version: 0.1.5
-Summary: Command-line studio for narrated explainer videos (HyperFrames + Kokoro TTS + ffmpeg)
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: <3.14,>=3.12
-Requires-Dist: kokoro-onnx>=0.6.1
-Requires-Dist: misaki>=0.9
-Requires-Dist: num2words>=0.5
-Requires-Dist: numpy>=2.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: soundfile>=0.12
-Requires-Dist: spacy<3.9,>=3.8
-Description-Content-Type: text/markdown
-
 # Explainer Studio
 
 [![CI](https://github.com/JoeMountWSWS/explainer-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/JoeMountWSWS/explainer-studio/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/explainer-studio)](https://pypi.org/project/explainer-studio/)
 
-A command-line studio for narrated explainer videos in the style of [wsws.org](https://www.wsws.org).
+A command-line studio for narrated explainer videos with a clean, editorial house style.
 You write a script in Markdown. The studio narrates it with local TTS, aligns every word to the audio,
 and turns each scene into a [HyperFrames](https://www.npmjs.com/package/hyperframes) HTML composition
 that is timed to the narration. It then renders a mastered 1920×1080 MP4 for YouTube, with captions
@@ -43,16 +28,7 @@ script.md ──► narration (Kokoro, local; or ElevenLabs) ──► word timi
 The first `sync` downloads the Kokoro-82M model to `~/.cache/hyperframes/tts` and spaCy's
 `en_core_web_sm` to `~/.cache/hyperframes/spacy`.
 
-# Usage
-
-Making a video with the studio is a loop of writing and listening. You write the script as plain
-Markdown, and the studio reads it aloud, works out exactly when each word is spoken, and hands those
-timings to your scenes so the visuals move in step with the voice. Change a sentence and only that
-sentence is re-recorded and only the affected scenes are re-rendered, so you can refine a five-minute
-video in seconds rather than starting over. Everything runs from one command, `uv run studio`, and
-nothing leaves your machine unless you choose cloud narration.
-
-## Install
+## Install the studio
 
 With the [requirements](#requirements) in place, either install the `studio` command from PyPI or
 clone the repository.
@@ -60,11 +36,16 @@ clone the repository.
 **From PyPI**, to make videos in a folder of your own:
 
 ```bash
-uv tool install explainer-studio   # or run it without installing: uvx --from explainer-studio studio …
+pip install explainer-studio       # or: uv tool install explainer-studio
 mkdir my-videos && cd my-videos
 studio new my-video "My Video"
 ```
 
+The package is on [PyPI](https://pypi.org/project/explainer-studio/). `uv tool install` puts
+`studio` on your PATH in its own isolated environment, and `uvx --from explainer-studio studio …`
+runs it without installing. With `pip`, install into a virtual environment (or use `pipx install
+explainer-studio`) so its dependencies stay separate from your system Python.
+
 The folder you run `studio` in becomes the workspace. It holds `episodes/`, `out/` and `.env`, and
 `studio` finds it from any subdirectory (or set `STUDIO_ROOT`). The house style (`brand/`) and scene
 templates ship with the package. To customise them, copy `brand/` or `templates/` from this repository
@@ -83,6 +64,31 @@ Run commands from the repository root (or any folder below it). Confirm the inst
 `uv run studio --help`. The first `sync` of an episode downloads the Kokoro voice model and the
 spaCy English model, so it takes a little longer than later runs.
 
+### Install the agent skill
+
+To have Claude Code drive the studio, install the `make-explainer-video` skill into your workspace:
+
+```bash
+cd my-videos
+studio install-skill           # -> .claude/skills/make-explainer-video/
+studio install-skill --user    # or for every project: ~/.claude/skills/
+```
+
+It installs the skill plus the references it reads (the studio guide, house-style spec and starter
+script). Start `claude` in the workspace and ask for a video, or run `/make-explainer-video`. Re-run
+the command with `--force` after upgrading the package to refresh it. From a clone the skill is
+already available with no installation. See
+[Working with a coding agent](https://joemountwsws.github.io/explainer-studio/coding-agents/).
+
+# Usage
+
+Making a video with the studio is a loop of writing and listening. You write the script as plain
+Markdown, and the studio reads it aloud, works out exactly when each word is spoken, and hands those
+timings to your scenes so the visuals move in step with the voice. Change a sentence and only that
+sentence is re-recorded and only the affected scenes are re-rendered, so you can refine a five-minute
+video in seconds rather than starting over. Everything runs from one command, `uv run studio`, and
+nothing leaves your machine unless you choose cloud narration.
+
 ## Quick start
 
 ```bash
@@ -144,6 +150,7 @@ Worked examples: `episodes/demo-paris-commune` (Kokoro, 38s) and `episodes/demo-
 The studio is designed to be driven by Claude Code or another coding agent. `AGENTS.md` (loaded
 through `CLAUDE.md`) gives the agent the conventions it needs, the HyperFrames skills cover the
 composition format and motion, and the `make-explainer-video` skill
-(`.claude/skills/make-explainer-video/`) walks Claude through the whole workflow. Start `claude` in
-the repository root and ask for a video, or run `/make-explainer-video`. See
+(`.claude/skills/make-explainer-video/`, or `studio install-skill` for a pip install) walks Claude
+through the whole workflow. Start `claude` in the repository root or your workspace and ask for a
+video, or run `/make-explainer-video`. See
 [Working with a coding agent](https://joemountwsws.github.io/explainer-studio/coding-agents/).

{explainer_studio-0.1.5 → explainer_studio-0.1.6}/brand/brand.css

@@ -1,4 +1,4 @@
-/* Explainer house style, after wsws.org. Tokens mirror brand/frame.md.
+/* Explainer house style. Tokens mirror brand/frame.md.
    `studio sync` copies this file (with fonts/ and gsap) into each episode's assets/brand/. */
 
 @font-face { font-family: "PT Serif"; src: url("fonts/PTSerif-Regular.ttf") format("truetype"); font-weight: 400; font-style: normal; }
@@ -8,6 +8,12 @@
 @font-face { font-family: "Source Sans 3"; src: url("fonts/SourceSans3.ttf") format("truetype"); font-weight: 200 900; font-style: normal; }
 @font-face { font-family: "Source Sans 3"; src: url("fonts/SourceSans3-Italic.ttf") format("truetype"); font-weight: 200 900; font-style: italic; }
 @font-face { font-family: "JetBrains Mono"; src: url("fonts/JetBrainsMono.ttf") format("truetype"); font-weight: 100 800; }
+/* DINPro is licensed, not OFL: it lives in brand/fonts-licensed/ (gitignored). `sync` copies it into the
+   episode and appends its @font-face rules to this file's copy, so without it there are no 404s and the sans
+   stack falls back to Source Sans 3. No 400/600 cuts: those map to Medium/Bold.
+   This DINPro build's fi/fl ligatures point at the wrong glyphs ("five" renders "(ve"), and Chromium ignores
+   the @font-face font-feature-settings descriptor, so ligatures are off everywhere. */
+* { font-variant-ligatures: no-common-ligatures; }
 
 :root {
   --paper: #ffffff;
@@ -21,7 +27,7 @@
   --tag: #1b2129;
 
   --font-serif: "PT Serif", Georgia, serif;
-  --font-sans: "Source Sans 3", "Helvetica Neue", Arial, sans-serif;
+  --font-sans: "DINPro", "Source Sans 3", "Helvetica Neue", Arial, sans-serif;
   --font-mono: "JetBrains Mono", ui-monospace, monospace;
 
   --safe-x: 192px;   /* title-safe inset (10%) */

{explainer_studio-0.1.5 → explainer_studio-0.1.6}/brand/frame.md

@@ -1,6 +1,5 @@
 ---
-name: Explainer house style (after wsws.org)
-reference: https://www.wsws.org — typography, palette and page furniture are taken from the site
+name: Explainer house style
 canvas:
   width: 1920
   height: 1080
@@ -19,8 +18,8 @@ typography:
   headline: { family: "PT Serif", weight: 700, line-height: 1.12, min-size: 72px }
   standfirst: { family: "PT Serif", style: italic, weight: 400, color: ink-soft }
   body: { family: "PT Serif", weight: 400, size: 46px, line-height: 1.4 }
-  label: { family: "Source Sans 3", weight: 700, size: 26px, tracking: "0.12em", case: uppercase }
-  ui: { family: "Source Sans 3", weight: 600 }
+  label: { family: "DINPro", fallback: "Source Sans 3", weight: 700, size: 26px, tracking: "0.12em", case: uppercase }
+  ui: { family: "DINPro", fallback: "Source Sans 3", weight: 600 }   # DINPro cuts: 300, 500, 700, 900 (600 renders Bold)
   mono: { family: "JetBrains Mono", weight: 500 }   # formulae, data, code
 spacing:
   safe-title: 192px 108px   # 10% inset: key text stays inside this box
@@ -29,7 +28,7 @@ spacing:
 components:
   section-rule: "6px solid ink above an uppercase label (the site's 'TOP STORIES' head)"
   hairline: "2px solid rule"
-  tag: "tag-coloured box, white uppercase Source Sans label"
+  tag: "tag-coloured box, white uppercase DINPro label"
   blockquote: "PT Serif, indented, 6px red rule on the left"
   corners: 0
   shadow: none
@@ -40,11 +39,11 @@ motion:
   stagger: 0.12s
 ---
 
-# Explainer house style (after wsws.org)
+# Explainer house style
 
 ## Overview
 
-The videos should look like a WSWS article set in motion: a white page, serious
+The videos should look like a serious news article set in motion: a white page, serious
 serif headlines, small uppercase section labels, thin rules, and one red. Plain
 and authoritative, not "content-marketing". The narrator carries the argument. The
 frame shows its structure (claims, evidence, quotations, dates, figures) with the
@@ -61,7 +60,7 @@ same typographic furniture a reader knows from the site.
 - **Standfirst**: PT Serif Italic in `ink-soft` under a headline.
 - **Blockquote**: PT Serif with a red left rule (`.quote`), attribution in `label`
   style. Used for documents, speeches and historical sources.
-- **Byline/date line**: Source Sans, `ink-soft`, small. Use it for sources and
+- **Byline/date line**: DINPro, `ink-soft`, small. Use it for sources and
   citations on screen ("Source: Bureau of Labor Statistics, 2025").
 
 ## The frame
@@ -80,7 +79,7 @@ Episodes with `format: reel` render at 1080x1920 for Instagram Reels, TikTok and
 - Content box: `.stage-reel` (x 72-1008, y 220-1180). The platform's buttons sit on the right
   edge and its caption, handle and audio line take the bottom ~480px, so keep both clear.
 - Caption band: y 1220-1440. `burn_captions: true` puts word-highlighted captions here (white
-  Source Sans on a `tag` box, the spoken word in red). Don't put content in this band.
+  DINPro on a `tag` box, the spoken word in red). Don't put content in this band.
 - Photos may run full-bleed behind everything, under an ink gradient so type stays legible.
 - Minimum sizes: headline 88px, body 52px, label 30px, byline 26px.
 - One statement per screen. Cut every 3-6s, on the narration's cues. Get the striking fact on screen in the first second.
@@ -93,7 +92,7 @@ Episodes with `format: reel` render at 1080x1920 for Instagram Reels, TikTok and
   and charts carry the argument. Always show a source line for a figure or quote.
 - **Charts**: flat, ink and grey with the key series in red. Hairline axes, Source
   Sans labels, no gridline clutter, no 3D.
-- **Lists**: at most 4 items, numbered in red Source Sans, with hairlines between.
+- **Lists**: at most 4 items, numbered in red DINPro, with hairlines between.
 - No stock photos used as decoration, emoji, drop shadows, rounded "app" cards,
   gradients or glow. Photos are allowed only as evidence (archival images, news
   photos with credit), set full-width with a caption, as on the site.

{explainer_studio-0.1.5 → explainer_studio-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "explainer-studio"
-version = "0.1.5"
+version = "0.1.6"
 description = "Command-line studio for narrated explainer videos (HyperFrames + Kokoro TTS + ffmpeg)"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -16,6 +16,13 @@ dependencies = [
     "num2words>=0.5",
 ]
 
+[project.urls]
+Homepage = "https://joemountwsws.github.io/explainer-studio/"
+Documentation = "https://joemountwsws.github.io/explainer-studio/"
+Repository = "https://github.com/JoeMountWSWS/explainer-studio"
+Issues = "https://github.com/JoeMountWSWS/explainer-studio/issues"
+Changelog = "https://github.com/JoeMountWSWS/explainer-studio/blob/main/CHANGELOG.md"
+
 [project.scripts]
 studio = "studio.cli:main"
 
@@ -34,6 +41,9 @@ packages = ["tools/studio"]
 "brand/fonts" = "studio/data/brand/fonts"
 "brand/vendor" = "studio/data/brand/vendor"
 "templates" = "studio/data/templates"
+# The agent skill (`studio install-skill`); it also installs brand/frame.md and templates/script.md as references.
+".claude/skills/make-explainer-video/SKILL.md" = "studio/data/skills/make-explainer-video/SKILL.md"
+"AGENTS.md" = "studio/data/skills/make-explainer-video/references/agents.md"
 
 [tool.hatch.build.targets.sdist]
 only-include = [
@@ -44,6 +54,8 @@ only-include = [
     "brand/fonts",
     "brand/vendor",
     "templates",
+    ".claude/skills/make-explainer-video/SKILL.md",
+    "AGENTS.md",
     "README.md",
     "LICENSE",
 ]

{explainer_studio-0.1.5 → explainer_studio-0.1.6}/tools/studio/build.py

@@ -8,7 +8,7 @@ import re
 import shutil
 from pathlib import Path
 
-from .common import BRAND, FORMATS, HF_VERSION, ROOT, TEMPLATES, die, info
+from .common import BRAND, FORMATS, HF_VERSION, LICENSED_FONTS, ROOT, TEMPLATES, die, info
 from .script import Script
 
 TIMING_RE = re.compile(r"(/\* <studio:timing> \*/)(.*?)(/\* </studio:timing> \*/)", re.S)
@@ -49,6 +49,9 @@ def compute_timing(script: Script, vo: dict[str, dict]) -> dict:
             "duration": t_frames / fps, "scenes": scenes}
 
 
+DINPRO_WEIGHTS = {"Light": 300, "Regular": 400, "Medium": 500, "Bold": 700, "Black": 900}
+
+
 def sync_brand(ep: Path) -> None:
     """Copy the studio's shared look into the episode (edit brand/, not these copies)."""
     dst = ep / "assets" / "brand"
@@ -56,6 +59,17 @@ def sync_brand(ep: Path) -> None:
     shutil.copy2(BRAND / "brand.css", dst / "brand.css")
     shutil.copy2(BRAND / "vendor" / "gsap.min.js", dst / "gsap.min.js")
     shutil.copytree(BRAND / "fonts", dst / "fonts", dirs_exist_ok=True)
+    # Licensed fonts are optional, so their @font-face rules are only written when the files exist.
+    faces = []
+    for font in sorted(LICENSED_FONTS.glob("DINPro-*.ttf")):
+        weight = DINPRO_WEIGHTS.get(font.stem.removeprefix("DINPro-"))
+        if weight:
+            shutil.copy2(font, dst / "fonts" / font.name)
+            faces.append(f'@font-face {{ font-family: "DINPro"; src: url("fonts/{font.name}") format("truetype"); '
+                         f"font-weight: {weight}; font-style: normal; }}")
+    if faces:
+        with (dst / "brand.css").open("a") as f:
+            f.write("\n/* Added by `studio sync` from brand/fonts-licensed/ */\n" + "\n".join(faces) + "\n")
     shutil.copy2(BRAND / "frame.md", ep / "frame.md")
 
 

{explainer_studio-0.1.5 → explainer_studio-0.1.6}/tools/studio/cli.py

@@ -9,6 +9,7 @@
     uv run studio thumbnail <slug>        screenshot thumbnail/thumbnail.html -> out/
     uv run studio voices <slug>           audition Kokoro blends or Chatterbox clips on one scene -> out/voice-samples/
     uv run studio music <slug> --prompt   generate an instrumental music bed (ElevenLabs Music) sized to the episode
+    uv run studio install-skill           install the make-explainer-video agent skill for Claude Code
 """
 
 from __future__ import annotations
@@ -26,7 +27,7 @@ import numpy as np
 import soundfile as sf
 
 from . import build as builder
-from . import music, voice
+from . import music, skill, voice
 from . import render as renderer
 from .common import EPISODES, OUT, ROOT, TEMPLATES, die, episode_dir, hf, info, require_tools
 from .script import Script, parse
@@ -202,6 +203,10 @@ def audition(tts, scene, table: dict, out: Path) -> None:
     info(f"  {out.relative_to(ROOT)}")
 
 
+def cmd_install_skill(a):
+    skill.install(user=a.user, dest=a.dir, force=a.force)
+
+
 def main():
     p = argparse.ArgumentParser(prog="studio", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = p.add_subparsers(dest="cmd", required=True)
@@ -257,6 +262,12 @@ def main():
     s.add_argument("--out", metavar="PATH", help="write here instead, e.g. brand/music/my-bed.mp3 to share across episodes")
     s.set_defaults(fn=cmd_music)
 
+    s = sub.add_parser("install-skill", help="install the make-explainer-video agent skill (Claude Code) into this workspace")
+    s.add_argument("--user", action="store_true", help="install for every project (~/.claude/skills) instead of this workspace")
+    s.add_argument("--dir", metavar="SKILLS_DIR", help="install into this skills folder instead, e.g. for another agent")
+    s.add_argument("--force", action="store_true", help="replace an existing, different copy")
+    s.set_defaults(fn=cmd_install_skill)
+
     a = p.parse_args()
     a.fn(a)
 

{explainer_studio-0.1.5 → explainer_studio-0.1.6}/tools/studio/common.py

@@ -28,6 +28,8 @@ PKG_DATA = _HERE / "data" if (_HERE / "data").is_dir() else _HERE.parents[1]
 ROOT = _workspace()
 BRAND = ROOT / "brand" if (ROOT / "brand" / "brand.css").exists() else PKG_DATA / "brand"
 TEMPLATES = ROOT / "templates" if (ROOT / "templates" / "script.md").exists() else PKG_DATA / "templates"
+# Commercial fonts (e.g. DINPro) the user holds a licence for: gitignored, never shipped in the wheel.
+LICENSED_FONTS = ROOT / "brand" / "fonts-licensed"
 EPISODES = ROOT / "episodes"
 OUT = ROOT / "out"
 

{explainer_studio-0.1.5 → explainer_studio-0.1.6}/tools/studio/render.py

@@ -11,7 +11,20 @@ import numpy as np
 import soundfile as sf
 
 from .build import render_shell
-from .common import BRAND, HF_VERSION, OUT, SAMPLE_RATE, die, ffprobe_duration, hf, info, run, sha, tree_hash
+from .common import (
+    BRAND,
+    HF_VERSION,
+    LICENSED_FONTS,
+    OUT,
+    SAMPLE_RATE,
+    die,
+    ffprobe_duration,
+    hf,
+    info,
+    run,
+    sha,
+    tree_hash,
+)
 from .script import Script
 
 # ---------------------------------------------------------------- video
@@ -191,14 +204,23 @@ def _ass_color(hexcolor: str) -> str:
     return f"&H00{b}{g}{r}".upper()
 
 
+def caption_font() -> tuple[str, Path]:
+    """(libass font name, fonts dir) for burned-in captions."""
+    if (LICENSED_FONTS / "DINPro-Bold.ttf").exists():
+        return "DINPro-Bold", LICENSED_FONTS
+    return "Source Sans 3 Bold", BRAND / "fonts"
+
+
 def ass_captions(ep: Path, timing: dict, dst: Path) -> int:
-    """Burn-in captions in house style: white Source Sans on a dark tag box, the spoken word in red.
+    """Burn-in captions in house style: white sans on a dark tag box, the spoken word in red.
     Short single-line cues (a few words), one event per word so the highlight follows the voice.
-    libass can't pick weights from the variable font, so this relies on the static brand/fonts/SourceSans3-Bold.ttf."""
+    libass can't pick weights from the variable font, so this relies on a static bold: DINPro-Bold from
+    brand/fonts-licensed/ when present, else brand/fonts/SourceSans3-Bold.ttf (see caption_font())."""
     w, h = timing["width"], timing["height"]
     portrait = h > w
     size, y = (72, int(h * 0.69)) if portrait else (52, int(h * 0.86))  # reel caption band / lower third
     ink, red, white = _ass_color("#1b2129"), _ass_color("#e71e25"), _ass_color("#ffffff")
+    font = caption_font()[0]
     head = [
         "[Script Info]", "ScriptType: v4.00+", f"PlayResX: {w}", f"PlayResY: {h}", "WrapStyle: 2",
         "ScaledBorderAndShadow: yes", "",
@@ -206,7 +228,7 @@ def ass_captions(ep: Path, timing: dict, dst: Path) -> int:
         "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: Cap,Source Sans 3 Bold,{size},{white},{white},{ink},{ink},-1,0,0,0,100,100,0,0,3,14,0,5,0,0,0,1",
+        f"Style: Cap,{font},{size},{white},{white},{ink},{ink},-1,0,0,0,100,100,0,0,3,14,0,5,0,0,0,1",
         "", "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
     ]
     cues = _caption_cues(ep, timing, max_chars=13 if portrait else 21, max_secs=2.5, max_words=4, min_sentence=0)
@@ -219,6 +241,8 @@ def ass_captions(ep: Path, timing: dict, dst: Path) -> int:
             b = cue[k + 1]["start"] if k + 1 < len(cue) else cue_end
             text = " ".join(("{\\c" + red + "&}" + x["text"] + "{\\c" + white + "&}") if j == k else x["text"]
                             for j, x in enumerate(cue))
+            if font == "DINPro-Bold":  # its fi/fl ligatures are broken; a zero-width non-joiner stops HarfBuzz forming them
+                text = re.sub(r"f(?=[il])", "f‌", text)
             events.append(f"Dialogue: 0,{_ts(a, '.')[1:-1]},{_ts(b, '.')[1:-1]},Cap,,0,0,0,,{{\\pos({w // 2},{y})}}{text}")
     dst.write_text("\n".join(head + events) + "\n")
     return len(cues)
@@ -251,7 +275,7 @@ def render_episode(ep: Path, script: Script, timing: dict, draft: bool, only: se
         ass = build / "captions.ass"
         ass_captions(ep, timing, ass)
         crf = "26" if draft else "16"
-        vcodec = ["-vf", f"ass={ass.name}:fontsdir={BRAND / 'fonts'}", "-c:v", "libx264", "-preset", "medium",
+        vcodec = ["-vf", f"ass={ass.name}:fontsdir={caption_font()[1]}", "-c:v", "libx264", "-preset", "medium",
                   "-crf", crf, "-pix_fmt", "yuv420p"]
     run(["ffmpeg", "-v", "error", "-y", "-i", str(video.resolve()), "-i", str(master.resolve()), "-map", "0:v", "-map", "1:a",
          *vcodec, "-c:a", "aac", "-b:a", "384k", "-ar", str(SAMPLE_RATE),

explainer_studio-0.1.6/tools/studio/skill.py

@@ -0,0 +1,49 @@
+"""Install the `make-explainer-video` agent skill into a workspace or the user's skills folder."""
+
+from __future__ import annotations
+
+import filecmp
+import shutil
+from pathlib import Path
+
+from .common import PKG_DATA, ROOT, die, info
+
+NAME = "make-explainer-video"
+
+# Where each file of the skill comes from, relative to PKG_DATA (the wheel's studio/data/, or the
+# repository root in a checkout). The house-style spec and starter script sit at the same path in both.
+_WHEEL = {"SKILL.md": f"skills/{NAME}/SKILL.md", "references/agents.md": f"skills/{NAME}/references/agents.md"}
+_CHECKOUT = {"SKILL.md": f".claude/skills/{NAME}/SKILL.md", "references/agents.md": "AGENTS.md"}
+_SHARED = {"references/frame.md": "brand/frame.md", "references/script-template.md": "templates/script.md"}
+
+
+def sources() -> dict[str, Path]:
+    own = _WHEEL if (PKG_DATA / _WHEEL["SKILL.md"]).is_file() else _CHECKOUT
+    paths = {rel: PKG_DATA / src for rel, src in {**own, **_SHARED}.items()}
+    missing = [str(p) for p in paths.values() if not p.is_file()]
+    if missing:
+        die(f"skill files missing from this install: {', '.join(missing)}")
+    return paths
+
+
+def target_dir(user: bool, dest: str | None) -> Path:
+    if dest:
+        return Path(dest).expanduser().resolve() / NAME
+    return (Path.home() if user else ROOT) / ".claude" / "skills" / NAME
+
+
+def install(user: bool = False, dest: str | None = None, force: bool = False) -> None:
+    src = sources()
+    target = target_dir(user, dest)
+    if (target / "SKILL.md").exists() and (target / "SKILL.md").samefile(src["SKILL.md"]):
+        info(f"{target} is this repository's own copy: the skill is already available here")
+        return
+    stale = [rel for rel, s in src.items() if (target / rel).exists() and not filecmp.cmp(s, target / rel, shallow=False)]
+    if stale and not force:
+        die(f"{target} already has a different copy ({', '.join(stale)}). Re-run with --force to replace it")
+    for rel, s in src.items():
+        out = target / rel
+        out.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(s, out)
+    info(f"installed the {NAME} skill to {target}")
+    info(f"start Claude Code in {ROOT if not user else 'your workspace'} and ask for a video, or run /{NAME}")