@desplega.ai/agent-swarm 1.159.0 → 1.161.0

package/templates/community/open-prompt-showreel/skills/open-prompt-showreel/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: open-prompt-showreel
+description: Make a design-led motion-graphics video (showreel, eval comparison, feature or bug-hunt story) from one open prompt. Claude Opus at max effort designs, codes and renders the whole thing itself in a scratch dir, with no template and no repo PR. Use for any "make a video for X" / "do a showreel for Y" / "a little comparison video" ask aimed at X, LinkedIn or a launch post. Covers the Lead brief template, grounding every on-screen number in a real source, the real Agent Swarm end logo, CC0/CC BY music with credit, render specs (16:9 + 4:5), the contact-sheet self-critique loop, agent-fs delivery, feedback rounds and crash-safe retries. Not for fixed-template creatives or for replicating a reference clip.
+metadata:
+  type: procedure
+---
+
+# Open-prompt showreel videos
+
+The approach: give a strong model on max effort one open creative prompt plus hard content rules, and let it design, code and render the whole video itself. Template pipelines produce generic cuts. This one produced the showreels and the TLA+ races cuts that the team liked.
+
+## When to use which skill
+
+| Ask | Skill |
+|---|---|
+| A video that should look designed: showreel, model/eval comparison, "we found N bugs", launch hype | **this skill** |
+| A standard on-brand card or clip from a fixed template (release, proof stat, quote, OG image) | a template toolkit, if your swarm has one |
+| Rebuild the feel of a reference clip someone linked | `motion-design-video-analysis`, then `motion-design-replication` |
+| Repo-committed Remotion video (README hero, landing demo, case-study clip) | `video-generation` |
+
+If the ask says "like the showreel", "your own design" or "go all out", or someone complained a cut looks generic, it is this skill.
+
+## Model, effort, harness
+
+- The maker runs **model `claude-opus-5-5`, effort `max`**, on a **Claude Code harness worker** (`provider: claude`). Set both on the task.
+- Other harnesses were not tried for this workflow. Do not route to them without a test run.
+- Every brief ends with a gate: "If you are not on claude-opus-5-5, stop and say so instead of rendering." The maker checks this first.
+- The worker needs Playwright + Chromium, ffmpeg, python3 with numpy, and write access to agent-fs. The community template's `setup.sh` checks and installs all of them (numpy goes in a venv; the stock image does not ship it).
+
+## Lead brief template
+
+One task, one open prompt. Do not write a storyboard, shot list, palette or template for the maker; that is what made earlier cuts generic.
+
+```
+GOAL: <one line: what the video is and where it goes (X / LinkedIn / internal)>.
+Made by you on claude-opus-5-5, max effort, ad hoc, your own design.
+
+<Requester>, verbatim: "<the ask>"
+
+Your prompt: make a dynamic <15 | 15-30> second motion graphics video <about SUBJECT>.
+Make it your showreel: show what an incredible motion designer you are. Go all out.
+
+Content rule: every number or claim on screen comes from <SOURCE: eval writeup path /
+test file on origin/main / PR numbers> and matches it exactly. Anything not in the
+source stays off screen. Fewer numbers is fine: design-led, not a table.
+
+How:
+- Ad hoc: scratch dir, any tools or code you like. No repo, no PR, no shared template.
+- Real brand: Agent Swarm logo = origin/main apps/ui/public/logo.png (verify vs agent-swarm.dev/logo.png). Never draw your own mark.
+- Look at a contact sheet at least 3 times, fixing what looks weak each round; in the last round check every on-screen number against the source and look at the end-card frame.
+- Music optional; CC0 or CC BY only (no NC, no ND, no SA); short credit on the end card; in your output the full attribution from music/current.json (source link, license link, changes made).
+- If you are not on claude-opus-5-5, stop and say so.
+- Nothing is owed to a human by you; Lead reviews and relays.
+
+Deliver to agent-fs thoughts/<maker-agent-id>/videos/<slug>/: <1920x1080 [+ 1080x1350]> h264 yuv420p mp4,
+contact sheet(s), facts.json.
+Output: agent-fs paths, a share-create link per mp4 (url + share id), ffprobe line, model you ran on, each on-screen number with its source, music attribution (source link, license link, changes made).
+```
+
+Optional style add-on for a calmer, premium cut (the "Apple framework"): 3 colors, one background, one font, no HUD/grain; one shot = one idea; ~3 s open and ~2 s held end; key object centered; eased, overlapping keyframes; no hard cuts; ~108 BPM, phrase hit on the first product frame; no SFX. Add it only when asked.
+
+## Maker procedure
+
+### 1. Scratch dir first, and say where it is
+
+`mkdir /workspace/personal/<slug>` and store-progress with the path in the first minute. `/workspace/personal` survives a container restart; the session does not. A retry that found the scratch dir of its crashed predecessor delivered in 8 minutes.
+
+### 2. Facts before design
+
+Write a small script (`facts.ts`, run with `bun facts.ts > facts.json`) that reads every on-screen fact live from its source right before render, and have the reel read `facts.json` instead of hard-coding numbers.
+
+- Code facts: `git fetch origin main`, read the file at `origin/main` (for example count `test.failing` vs `test` in `src/tests/workflow-tla-races.test.ts`), `gh pr view` / `gh pr list` for PR states. Record the short SHA in facts.json.
+- Eval facts: the writeup the eval task produced on agent-fs, and the run id. Copy numbers exactly.
+- A fact turns "green" only if main says so. Unmerged stays in its old state, even if the brief expects otherwise.
+- If the source disagrees with the brief, the source wins; say so in the output (the TLA+ v3 brief listed four merged PRs; main also had a fifth, so the reel said "ALL 10 FIXED ON MAIN").
+- Drop any claim the source does not support.
+- If the source is not ready yet (eval still running, PRs still merging), build the design on draft facts, then `defer-task` with `wakeOn:{event:"settled",taskIds:[...]}` and re-read the facts on wake. Never ship draft numbers.
+
+### 3. Build: one HTML canvas reel, frame-addressable
+
+A single `reel.html` that draws each frame on a `<canvas>` as a pure function of the frame number, with scenes as `sceneN(f)` functions. It exposes:
+
+```js
+window.boot = async (facts, fonts, logo) => { /* load fonts + logo, stash facts */ };
+window.frame = (f) => { render(f); return cv.toDataURL("image/png"); };
+```
+
+`render.mjs` (Playwright, `chromium.launch({args:["--disable-gpu-vsync"]})`) opens the file at the target viewport, calls `boot` with facts, base64 fonts and the base64 logo, then either grabs a comma list of frames to PNGs (stills mode, for sheets) or grabs every frame and pipes PNGs to ffmpeg over `image2pipe` (video mode). The community template ships a working `tools/render.mjs`.
+
+- Always pass `-pix_fmt yuv420p` to the ffmpeg that encodes the piped PNGs. Without it libx264 keeps the PNG's 4:4:4 and writes `yuv444p` (High 4:4:4 Predictive), which phones and social uploaders handle badly.
+- ffmpeg in the worker image has no `drawtext` filter. Draw text on the canvas (this approach does anyway), or burn captions with the `ass` filter.
+- Fonts are local TTFs inlined as base64 (Space Grotesk, JetBrains Mono, Instrument Serif Italic in the TLA+ reels; all SIL OFL).
+- For long 60 fps cuts, render frames in several parallel Playwright workers and encode once.
+
+### 4. Brand: the real end logo
+
+- Agent Swarm logo = `apps/ui/public/logo.png` on origin/main: a solid gold hexagon inside a lighter gold honeycomb. It is byte-identical to `docs-site/public/logo.png` and `https://agent-swarm.dev/logo.png`. Check the sha256 against the live site; if they differ, the live site wins and you say so.
+- Not an old cartoon asset. Not a mark you draw yourself: the first TLA+ cut drew a ring + hex + rays and the requester asked for the correct logo.
+- Your own hex motif may morph into the real logo; the last frames must show the real asset, sharp.
+- Colors from agent-swarm.dev (ink background, amber/gold accents). Do not invent brand elements.
+
+### 5. Music: CC0 / CC BY, timed to the cut
+
+- License: CC0 or CC BY only. No NC (company post), no ND (we cut and stretch it), no SA (it would carry over to the video). `fetch-music.sh` enforces an allowlist (CC0 1.0, CC BY 1.0-4.0); read the license on the source page yourself. Sources that worked: incompetech.com (Kevin MacLeod, CC BY 4.0), OpenGameArt (filter by license).
+- Pick a fresh track per video; the requester asked for different music on the first TLA+ cut. Offer two alternates when music is in question.
+- `fetch-music.sh` writes `music/<track>.json` (`{title, artist, license, license_url, source, credit}`). After `music-cut.sh`, run `music-current.sh music/<track>.json music/cut.wav`: it writes `music/current.json` with `wav` (without it `render.mjs` renders silent) and `attribution`. Render with `--music music/current.json` and check the mp4 has an `aac` stream. `credit` is the short end-card line; CC BY also needs the source link, the license link and the changes made in the post, which is what `attribution` carries.
+- Time the cut to the music: find tempo, beat phase and the drop (numpy spectral-flux + low-end energy: `music-analyze.py`, `music-refine.py`), then time-stretch so the beats sit on the reel's frame grid (120 BPM = 15 frames per beat at 30 fps) and the drop lands on the key reveal (`music-cut.sh`: `atempo` + trim, fade in 0.3 s, fade out ~1.7 s).
+- When the music is the feedback, also render the 16:9 with two runner-up tracks (audio swap only).
+
+### 6. Render specs
+
+- Container: h264 High, `yuv420p`, AAC 192k, `-movflags +faststart`, `libx264 -preset slow -crf 16`.
+- 16:9: 1920x1080, stream at exactly that size. Add 4:5 1080x1350 for LinkedIn/X feeds. Build the layout responsive to `?w=&h=` rather than cropping.
+- 30 fps by default; 60 fps for heavy motion.
+- Length: 15 s for a brand showreel; 20-30 s when the story carries data.
+- The worker image has no `ffprobe`. Read stream lines from `ffmpeg -i` stderr, or install ffprobe with the template's `setup.sh`.
+- A clip from a screen recording, a JPEG pipeline or `remotion render` can be tagged `yuvj420p` (full range). Re-encode it with `x-reencode.sh` before posting to X.
+
+### 7. Self-critique loop (minimum 3 rounds)
+
+- Contact sheet: render 16 stills across the timeline and tile them 4x4 with ffmpeg `xstack` (`sheet.sh`); look at it with Read. Keep sheets per round (`r1-16x9.png`, `r2-...`).
+- Transition strip: 20 stills densely around each cut (5x4 grid) to catch pops and empty frames.
+- Each round, write down what looks weak (dead space, text too small for a phone, cramped 4:5, jumpy easing, off-beat hit) and fix it.
+- Final round: check every on-screen number against facts.json and the source, and open the end-card frame on its own at full size to confirm the logo and credit.
+
+### 8. Deliver
+
+- agent-fs: `thoughts/<maker-agent-id>/videos/<slug>/` (versions as `<slug>-v2`, `<slug>-v3`, never overwrite an earlier version).
+- Upload the mp4s, contact sheet(s), `facts.json`, the music json, and `reel.html` so the next round can start from it. After every non-trivial write, `agent-fs stat <path> --json` and check the size.
+- Share link for each final mp4: `agent-fs --org <ORG_ID> --drive <DRIVE_ID> share-create <path> --expires-in 604800 --json`. The share page plays the video inline with no login. Max 7 days; report the url, the share id and the expiry. Do not hand out raw signed URLs or viewer URLs for video.
+- agent-fs serves a raw `.mp4` download as `application/octet-stream`; the share page's player gets `video/mp4`. Mention it rather than retrying.
+- Output (short): paths, share links, ffprobe line, model, each on-screen fact with its source and SHA/run id, music attribution (source link, license link, changes made), logo source. No Slack post by the maker; Lead relays.
+
+## Feedback rounds (v2, v3)
+
+- Lead writes a new task per round that quotes the requester verbatim and maps each point to a concrete change.
+- The maker copies the previous scratch dir to `<slug>-vN`, changes only what the feedback names, and keeps design, music and logo otherwise identical.
+- Always re-run `facts.ts` against current origin/main or the latest writeup; never carry numbers over.
+- If a point depends on other work (PRs merging), do the rest now, deliver an interim, then `defer-task` on the blocking task with a ceiling.
+
+## Failures to avoid
+
+- **Dying mid final render.** Two runs were failed by a reboot sweep during the last render. Keep everything under `/workspace/personal/<slug>`, name it in progress early, upload an interim cut before the long render, and on a retry look for the prior working dir before starting over.
+- **Pipeline cuts read as generic.** Fixed-template cuts of the same subjects were rejected as "too meh". Ad hoc scratch dir, no PR.
+- **Invented logo** on the end card. Use the real asset.
+- **Stock music the requester already heard.** Pick a fresh track each time.
+- **Numbers ahead of the source.** Draft or expected states on screen before main or the eval says so.

package/templates/community/open-prompt-showreel/skills/video-generation/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: video-generation
+description: How to generate repo-committed video content (README hero videos, case-study clips, landing demos) with Remotion. Covers project layout, fonts and colors that match the brand, audio sourcing, rendering in a worker container, the full-range yuvj420p gotcha, CI exclusions, and the "honest read" pacing principle. Use whenever you are asked to create a video from a Remotion project, animate a wireframe, or re-render an existing Remotion project. For a design-led one-off showreel use open-prompt-showreel instead.
+metadata:
+  type: procedure
+---
+
+# Video generation (Remotion)
+
+Remotion (React + TypeScript) is the stack for videos that live in a repo: README heroes, landing demos, case-study clips, thread dramatizations. `assets/video-source/` in `desplega-ai/agent-swarm` is the reference implementation; read it before starting a new project.
+
+## Golden rules
+
+1. **Remotion for repo-committed video.** `npx remotion studio` for previews, `remotion render` for mp4s. For a one-off design-led cut with no repo, use `open-prompt-showreel` instead.
+2. **Ask for audio, don't pick it.** Music is a brand call. A person on the team chooses the track (CC0 or CC BY 4.0, for example from https://freesound.org). Never grab something yourself; ask. There is no default bed.
+3. **Attribute in the video folder's README.** Artist name, source URL, license. Not in the repo root README; in the video project's own README.
+4. **Design tokens mirror the product.** Pull colors and fonts from the product's own `globals.css` (Agent Swarm: Space Grotesk + Space Mono, zinc dark palette, amber `#f2a93b` accent). Do not invent new ones.
+5. **Honest read pacing.** The first draft always over-packs the opening and under-weights the payoff. Compress setup scenes, expand the one that carries the message. See "Pacing" below.
+6. **One Remotion project, many compositions.** Do not spin up a new repo per video. Register additional `<Composition>` entries in `src/Root.tsx` and add a `build:<slug>` script.
+
+## Project layout
+
+```
+<project>/
+  package.json            # remotion + @remotion/cli + @remotion/google-fonts + react 18
+  remotion.config.ts
+  tsconfig.json           # isolated: exclude from the root tsconfig (see CI below)
+  README.md               # render commands + audio attribution
+  src/
+    index.ts              # registerRoot(Root)
+    Root.tsx              # <Composition> per video
+    fonts.ts              # loadFont() for Space Grotesk + Space Mono at module scope
+    theme.ts              # brand tokens (bg/fg/accent/sans/mono)
+    compositions/         # one per video: stitches scenes + audio
+    scenes/<video-slug>/  # per-scene components, one folder per composition
+  public/
+    audio/bed.mp3         # music bed, referenced via staticFile("audio/bed.mp3")
+  out/                    # rendered mp4s (gitignored)
+```
+
+## Bootstrapping a new video project
+
+Ran in a worker container (Remotion 4.0.532, 23 s install):
+
+```bash
+mkdir -p assets/video-source && cd assets/video-source
+npm init -y
+npm install remotion @remotion/cli @remotion/google-fonts react@^18.3.1 react-dom@^18.3.1
+npm install -D @types/react typescript
+npx remotion studio   # scaffolds config + opens preview
+```
+
+`npx remotion studio` opens an interactive preview and was not run for this playbook.
+
+## Rendering in a worker container
+
+The worker image already ships Chromium (`/opt/playwright/chromium`) and its system libraries, so no apt install is needed. Point Remotion at it instead of letting it download its own browser:
+
+```bash
+npx remotion render src/index.ts <CompositionId> out/<name>.mp4 \
+  --browser-executable=/opt/playwright/chromium --color-space=bt709
+```
+
+A 30-frame 1280x720 test composition rendered in 14 s this way.
+
+**Color-range gotcha.** Without `--color-space=bt709`, `remotion render` writes `yuvj420p(pc, bt470bg)`: full range, not the limited-range `yuv420p` that social uploaders expect. With the flag it writes `yuv420p(tv, bt709)`. Check with `ffmpeg -hide_banner -i out.mp4 2>&1 | grep Stream`. If a clip is already rendered, re-encode it with the template's `x-reencode.sh`.
+
+For a bare Debian/Ubuntu container that is not a worker image, Chromium needs system libraries and root. **Unverified, not run for this playbook:**
+
+```bash
+sudo apt-get install -y ffmpeg libnspr4 libnss3 libatk1.0-0 libatk-bridge2.0-0 \
+  libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
+  libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2t64 libatspi2.0-0
+```
+
+## Fonts
+
+Load once at module scope in `src/fonts.ts` and import from `src/Root.tsx`:
+
+```ts
+import { loadFont as loadSpaceGrotesk } from "@remotion/google-fonts/SpaceGrotesk";
+import { loadFont as loadSpaceMono } from "@remotion/google-fonts/SpaceMono";
+
+loadSpaceGrotesk("normal", { weights: ["400", "500", "600", "700"], subsets: ["latin"] });
+loadSpaceMono("normal", { weights: ["400", "700"], subsets: ["latin"] });
+```
+
+## Theme tokens (dark palette, amber accent)
+
+```ts
+export const theme = {
+  bg: "#09090b",
+  card: "#18181b",
+  fg: "#fafafa",
+  muted: "#a1a1aa",
+  mutedDim: "#52525b",
+  border: "rgba(255,255,255,0.10)",
+  borderStrong: "rgba(255,255,255,0.18)",
+  accent: "#f2a93b",      // amber: brand primary in dark mode
+  accentDim: "#7a4d12",
+  accentFg: "#1a1409",
+  success: "#4ade80",
+  danger: "#f87171",
+  sans: "'Space Grotesk', system-ui, -apple-system, sans-serif",
+  mono: "'Space Mono', ui-monospace, 'SF Mono', Menlo, monospace",
+};
+```
+
+## Multiple compositions
+
+Register each video as its own `<Composition>` in `src/Root.tsx`. `durationInFrames` is at 30 fps unless you raise the fps:
+
+```tsx
+<Composition id="DailyEvolution" component={DailyEvolution}
+  durationInFrames={900} fps={30} width={1920} height={1080} />
+<Composition id="SlackToPR" component={SlackToPR}
+  durationInFrames={1350} fps={30} width={1920} height={1080} />
+```
+
+Add a `build:<slug>` script per composition in `package.json`:
+
+```json
+"build:daily-evolution": "remotion render src/index.ts DailyEvolution out/daily-evolution.mp4",
+"build:slack-to-pr":     "remotion render src/index.ts SlackToPR     out/slack-to-pr.mp4",
+"build:all":             "npm run build:daily-evolution && npm run build:slack-to-pr"
+```
+
+## Audio
+
+```tsx
+import { Audio, staticFile } from "remotion";
+
+// Inside a composition, per composition, so some can ship silent:
+<Audio src={staticFile("audio/bed.mp3")} volume={0.4} />
+```
+
+- Put attribution in `<video-project>/README.md` with artist, source URL and license, for example:
+  > _Track title_ by **Artist** (https://freesound.org/s/<id>/), License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+- Not every composition needs music. A case-study clip that pairs with a written thread can ship silent on purpose.
+- If someone says "I can't hear the audio", first check the actual bytes of the mp3 (`file public/audio/bed.mp3`, `ls -lh`); stub or broken files are the usual cause. Then verify `<Audio>` is mounted inside the composition that is being rendered, not a sibling. Verify the render has an audio stream with `ffmpeg -i out.mp4`.
+
+## Pacing: the "honest read"
+
+First drafts always front-load setup and shortchange the payoff. After the first render, do an honest read:
+
+1. **Which single scene carries the message?** That one gets the most frames.
+2. **Which scenes are setup or framing?** Compress them, usually 60-120 frames (2-4 s at 30 fps).
+3. **Does the payoff have room to breathe?** 450+ frames (about 15 s) is typical for a scene the viewer needs to absorb.
+4. **Do the beats spread across the available time, or cluster at the start?** If they cluster, spread the `delay` / `spring` staggers across the full scene duration.
+
+Example distribution for a 30 s composition (900 frames at 30 fps): scenes 1-4 (setup) 60 / 90 / 120 / 120 frames, scene 5 (payoff) 450 frames, scene 6 (tagline) 60 frames.
+
+## CI and repo integration
+
+A Remotion project lives inside the repo but must be isolated from its build tooling:
+
+1. **Exclude from the root `tsconfig.json`.** The project has its own deps (React, Remotion) that the parent repo does not resolve. Add `"assets/video-source"` (or wherever it lives) to the root tsconfig `exclude`.
+2. **Scope the linter.** If Biome or ESLint is scoped to `src/`, no change is needed. If it scans the whole repo, add an ignore pattern.
+3. **Keep its own `tsconfig.json`** inside the video folder. Run `npx tsc --noEmit` there for type coverage.
+4. **`out/` and `node_modules/` must be gitignored.** Commit `public/audio/bed.mp3` and source, not render outputs.
+5. **Do not install Remotion's heavy deps at the repo root.** They belong only in the video project's `package.json`.
+
+## README video embed (GitHub renderer gotchas)
+
+For README hero videos, use a raw-URL `<video>` tag:
+
+```html
+<video src="https://github.com/<org>/<repo>/raw/main/assets/<name>.mp4"
+  autoplay muted loop playsinline></video>
+```
+
+- GitHub's markdown renderer is strict about `<video>` attributes. Keep it simple.
+- Prefer `raw/main/...` over `blob/main/...`; the latter serves the HTML page, not the mp4 bytes.
+- Target file size: under 3 MB if possible.
+- If the embed does not render, fall back to a link preview: `[![demo](thumbnail.png)](video-url)`.
+
+## When to use what
+
+| Need | Approach |
+|---|---|
+| README hero (the "what is this?") | 30 s, 1080p, one composition, audio bed, low-fi wireframe tokens |
+| Case study or thread dramatization | 45 s, multiple short scenes, typically silent |
+| Landing demo (product in action) | Remotion scaffolding + real screen recordings composited in |
+| Design-led one-off (showreel, eval comparison) | `open-prompt-showreel`, not this skill |
+| Audio-first asset (podcast clip, TTS demo) | A text-to-speech service, not Remotion |
+
+## Common mistakes
+
+- Picking music without asking.
+- Inventing colors or fonts instead of pulling them from the product.
+- Cramming 6 scenes into the first 10 s. That is the drift the honest read fixes.
+- Forgetting to exclude the video folder from the root tsconfig: CI fails on React/Remotion types the root repo does not have.
+- Shipping a silent video where audio was expected, or the reverse.
+- Dropping attribution. CC BY 4.0 requires credit.
+- Posting a `remotion render` output to X without checking its pixel format.

package/templates/community/open-prompt-showreel/tools/fetch-music.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Downloads one CC0 / CC BY track and writes the credit file the reel and the output need.
+#
+#   fetch-music.sh incompetech <Title> <out-dir>          # Kevin MacLeod, CC BY 4.0
+#   fetch-music.sh url <audio-url> <out-dir> <title> <artist> <license> <source-page>
+#
+# Writes <out-dir>/<slug>.<ext> and <out-dir>/<slug>.json =
+#   { title, artist, license, license_url, source, credit }
+# `credit` is the short line for the end card. The full attribution (source link, license link and
+# the modification notice) is added by music-current.sh once the track has been cut.
+#
+# Allowlist: CC0 1.0 and CC BY 1.0 to 4.0, matched case-insensitively ("cc-by 4.0" works). Everything
+# else is refused: NC (it is a company post), ND (we cut and stretch the track), SA (it would carry
+# over to the video), "All rights reserved", unknown strings. Check the license on the source page
+# yourself; the script cannot.
+set -euo pipefail
+
+mode=${1:-}
+case "$mode" in
+  incompetech)
+    title=$2 outdir=$3
+    url="https://incompetech.com/music/royalty-free/mp3-royaltyfree/${title// /%20}.mp3"
+    # Kevin MacLeod asks for the site root, not a per-track page.
+    artist="Kevin MacLeod" license="CC BY 4.0" source="https://incompetech.com"
+    ;;
+  url)
+    url=$2 outdir=$3 title=$4 artist=$5 license=$6 source=$7
+    ;;
+  *)
+    echo "usage: fetch-music.sh incompetech <Title> <out-dir> | url <url> <out-dir> <title> <artist> <license> <source>" >&2
+    exit 2
+    ;;
+esac
+
+# Normalize ("cc-by_4.0" -> "CC BY 4.0") and map to the canonical name and the license deed URL.
+norm=$(tr '[:lower:]' '[:upper:]' <<<"$license" | tr -s ' _-' ' ' | sed 's/^ //; s/ $//')
+if [[ "$norm" =~ ^CC\ ?0(\ 1\.0)?(\ UNIVERSAL)?$ ]]; then
+  license="CC0 1.0" license_url="https://creativecommons.org/publicdomain/zero/1.0/"
+elif [[ "$norm" =~ ^CC\ BY\ (1\.0|2\.0|2\.5|3\.0|4\.0)$ ]]; then
+  license="CC BY ${BASH_REMATCH[1]}" license_url="https://creativecommons.org/licenses/by/${BASH_REMATCH[1]}/"
+else
+  echo "refusing license '$license': only CC0 1.0 and CC BY 1.0-4.0 are allowed (no NC, ND, SA or unknown terms)" >&2
+  exit 1
+fi
+case "$source" in
+  http://* | https://*) ;;
+  *) echo "source must be a http(s) link to the track's page, got '$source'" >&2; exit 1 ;;
+esac
+
+mkdir -p "$outdir"
+slug=$(tr '[:upper:] ' '[:lower:]-' <<<"$title" | tr -cd 'a-z0-9-')
+ext="${url##*.}"
+curl -fsSL "$url" -o "$outdir/$slug.$ext"
+python3 - "$outdir/$slug.json" "$title" "$artist" "$license" "$license_url" "$source" <<'EOF'
+import json, sys
+path, title, artist, license, license_url, source = sys.argv[1:]
+credit = f'"{title}" by {artist} ({source.split("//")[-1].split("/")[0]}) · {license}'
+json.dump(
+    {"title": title, "artist": artist, "license": license, "license_url": license_url, "source": source, "credit": credit},
+    open(path, "w"),
+    indent=2,
+)
+print(credit)
+EOF
+echo "$outdir/$slug.$ext $(stat -c%s "$outdir/$slug.$ext") bytes"

package/templates/community/open-prompt-showreel/tools/music-analyze.py

@@ -0,0 +1,69 @@
+# usage: music-analyze.py <audio> -> tempo, beat phase, drop candidates (json on stdout)
+# Drop = a beat where the next 4 bars carry much more low-end + total energy than the previous 4 bars.
+import json, subprocess, sys
+import numpy as np
+
+SR = 22050
+path = sys.argv[1]
+raw = subprocess.run(["ffmpeg", "-v", "error", "-i", path, "-ac", "1", "-ar", str(SR), "-f", "f32le", "-"], capture_output=True, check=True).stdout
+x = np.frombuffer(raw, dtype=np.float32)
+dur = len(x) / SR
+
+hop, win = 512, 2048
+n = 1 + (len(x) - win) // hop
+frames = np.lib.stride_tricks.as_strided(x, shape=(n, win), strides=(x.strides[0] * hop, x.strides[0]))
+spec = np.abs(np.fft.rfft(frames * np.hanning(win), axis=1))
+logs = np.log1p(spec * 10)
+flux = np.maximum(0, np.diff(logs, axis=0)).sum(axis=1)
+flux = np.concatenate([[0], flux])
+flux = flux - np.convolve(flux, np.ones(16) / 16, mode="same")
+flux = np.maximum(flux, 0)
+fps = SR / hop
+freqs = np.fft.rfftfreq(win, 1 / SR)
+low = spec[:, freqs < 150].sum(axis=1)
+rms = np.sqrt((frames ** 2).mean(axis=1))
+
+# tempo: autocorrelation of onset envelope, 90..160 bpm, with half/double resolution
+ac = np.correlate(flux, flux, mode="full")[len(flux) - 1:]
+best = None
+for bpm in np.arange(90, 160.01, 0.1):
+    lag = 60 / bpm * fps
+    s = sum(np.interp(lag * k, np.arange(len(ac)), ac) for k in (1, 2, 4)) / 3
+    if best is None or s > best[1]:
+        best = (bpm, s)
+bpm = float(best[0])
+period = 60 / bpm
+# phase
+tt = np.arange(len(flux)) / fps
+bestp = None
+for ph in np.arange(0, period, 0.005):
+    beats = np.arange(ph, dur, period)
+    s = np.interp(beats * fps, np.arange(len(flux)), flux).sum()
+    if bestp is None or s > bestp[1]:
+        bestp = (ph, s)
+phase = float(bestp[0])
+beats = np.arange(phase, dur, period)
+
+def seg(arr, a, b):
+    ia, ib = int(max(0, a) * fps), int(min(dur, b) * fps)
+    return float(arr[ia:ib].mean()) if ib > ia else 0.0
+
+bar = 4 * period
+cands = []
+for b in beats:
+    if b < 2 * bar or b > dur - 2 * bar:
+        continue
+    pre_l, post_l = seg(low, b - 2 * bar, b), seg(low, b, b + 2 * bar)
+    pre_r, post_r = seg(rms, b - 2 * bar, b), seg(rms, b, b + 2 * bar)
+    score = np.log((post_l + 1e-6) / (pre_l + 1e-6)) + np.log((post_r + 1e-6) / (pre_r + 1e-6))
+    cands.append((float(score), float(b), post_r / (pre_r + 1e-9), post_l / (pre_l + 1e-9)))
+cands.sort(reverse=True)
+top = []
+for c in cands:
+    if all(abs(c[1] - t["t"]) > 2 * bar for t in top):
+        top.append({"t": round(c[1], 3), "score": round(c[0], 2), "rmsx": round(c[2], 2), "lowx": round(c[3], 2)})
+    if len(top) == 6:
+        break
+# energy curve per 2s for eyeballing
+curve = [round(seg(rms, t, t + 2) * 100, 1) for t in np.arange(0, dur, 2)]
+print(json.dumps({"file": path, "dur": round(dur, 2), "bpm": round(bpm, 2), "phase": round(phase, 3), "drops": top, "rms2s": curve}))

package/templates/community/open-prompt-showreel/tools/music-current.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Writes the music file that render.mjs reads: the credit json from fetch-music.sh plus the cut wav.
+#
+#   music-current.sh <track.json> <cut.wav> [out.json]       # out.json defaults to <cut.wav dir>/current.json
+#
+# Run it after music-cut.sh and before the final render. It adds two things to the track json:
+#   wav          the cut wav, as given (render.mjs muxes it in; without it the video is silent)
+#   attribution  the full credit for the post: title, artist, source link, license link and, for
+#                CC BY, a notice that the track was edited (CC BY requires all of these)
+# `credit` stays the short line for the end card. MODIFIED overrides the default edit description.
+set -euo pipefail
+
+track=${1:?usage: music-current.sh <track.json> <cut.wav> [out.json]} wav=${2:?missing <cut.wav>}
+out=${3:-$(dirname "$wav")/current.json}
+[ -f "$track" ] || { echo "no such track json: $track" >&2; exit 1; }
+[ -s "$wav" ] || { echo "no such wav (run music-cut.sh first): $wav" >&2; exit 1; }
+
+MODIFIED=${MODIFIED:-"trimmed, time-stretched to the video's beat grid, faded in and out, and loudness-normalized"} \
+python3 - "$track" "$wav" "$out" <<'EOF'
+import json, os, sys
+track, wav, out = sys.argv[1:]
+m = json.load(open(track))
+for k in ("title", "artist", "license", "license_url", "source", "credit"):
+    if not m.get(k):
+        sys.exit(f"{track} has no '{k}'; re-run fetch-music.sh (older credit files lack license_url)")
+m["wav"] = wav
+m["attribution"] = f'"{m["title"]}" by {m["artist"]}, {m["source"]}, licensed under {m["license"]}, {m["license_url"]}.'
+if m["license"].startswith("CC BY"):
+    m["modified"] = os.environ["MODIFIED"]
+    m["attribution"] += f' Changes: {m["modified"]}.'
+json.dump(m, open(out, "w"), indent=2)
+print(out)
+print(m["attribution"])
+EOF

package/templates/community/open-prompt-showreel/tools/music-cut.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Time-stretches a track so its beats sit on the reel's frame grid and its drop lands on the key reveal.
+#
+#   music-cut.sh <in> <track_bpm> <drop_sec_in_track> <out.wav>
+#
+# Get <track_bpm> and <drop_sec_in_track> from music-analyze.py / music-refine.py.
+# Env (defaults match the TLA+ reel: 30 fps, 120 BPM = 15 frames per beat, drop at 14.0 s, 24 s cut):
+#   TARGET_BPM=120  DROP_AT=14.0  DUR=24  DIP=0
+# DIP=1 ducks the track by ~86% for the 0.6 s before the drop, then snaps it back on the drop.
+set -euo pipefail
+
+in=$1 bpm=$2 drop=$3 out=$4
+target=${TARGET_BPM:-120} drop_at=${DROP_AT:-14.0} dur=${DUR:-24}
+
+# atempo ratio, where in the source to start, and how much source to read.
+read -r a start len < <(python3 - "$bpm" "$drop" "$target" "$drop_at" "$dur" <<'EOF'
+import sys
+bpm, drop, target, drop_at, dur = map(float, sys.argv[1:])
+a = target / bpm
+print(a, drop - drop_at * a, (dur + 0.6) * a)
+EOF
+)
+if python3 -c "import sys; sys.exit(0 if $start < 0 else 1)"; then
+  echo "drop too early in the track: start=$start" >&2
+  exit 1
+fi
+
+env="afade=t=in:st=0:d=0.3,afade=t=out:st=$(python3 -c "print($dur - 1.7)"):d=1.7"
+if [ "${DIP:-0}" = 1 ]; then
+  d0=$(python3 -c "print($drop_at - 0.6)")
+  env="$env,volume='1-0.86*min(1,max(0,(t-$d0)/0.06))*min(1,max(0,($drop_at-t)/0.02))':eval=frame"
+fi
+ffmpeg -v error -y -ss "$start" -t "$len" -i "$in" \
+  -af "atempo=$a,atrim=0:$dur,asetpts=N/SR/TB,$env,loudnorm=I=-14:TP=-1.5:LRA=11" \
+  -ar 48000 -ac 2 "$out"
+echo "atempo=$a start=$start"

package/templates/community/open-prompt-showreel/tools/music-refine.py

@@ -0,0 +1,39 @@
+# usage: music-refine.py <audio> <bpm_guess> <drop_guess>
+# Fine tempo+phase over the window the reel uses (drop-16s .. drop+12s), snap drop to the nearest beat,
+# and print the 0.5s RMS envelope of that window (to see the build, the drop, the tail).
+import subprocess, sys
+import numpy as np
+
+SR = 22050
+path, bpm0, d0 = sys.argv[1], float(sys.argv[2]), float(sys.argv[3])
+raw = subprocess.run(["ffmpeg", "-v", "error", "-i", path, "-ac", "1", "-ar", str(SR), "-f", "f32le", "-"], capture_output=True, check=True).stdout
+x = np.frombuffer(raw, dtype=np.float32)
+hop, win = 256, 1024
+n = 1 + (len(x) - win) // hop
+fr = np.lib.stride_tricks.as_strided(x, shape=(n, win), strides=(x.strides[0] * hop, x.strides[0]))
+spec = np.log1p(10 * np.abs(np.fft.rfft(fr * np.hanning(win), axis=1)))
+flux = np.concatenate([[0], np.maximum(0, np.diff(spec, axis=0)).sum(axis=1)])
+flux = np.maximum(0, flux - np.convolve(flux, np.ones(32) / 32, mode="same"))
+fps = SR / hop
+a0, a1 = max(0, d0 - 16), min(len(x) / SR, d0 + 12)
+idx = np.arange(len(flux))
+best = None
+for bpm in np.arange(bpm0 - 2, bpm0 + 2, 0.02):
+    p = 60 / bpm
+    for ph in np.arange(0, p, 0.004):
+        bt = np.arange(a0 + ph, a1, p)
+        s = np.interp(bt * fps, idx, flux).sum() / len(bt)
+        if best is None or s > best[0]:
+            best = (s, bpm, a0 + ph)
+_, bpm, ph = best
+p = 60 / bpm
+k = round((d0 - ph) / p)
+drop = ph + k * p
+rms = np.sqrt((fr ** 2).mean(axis=1))
+env = []
+for t in np.arange(drop - 14 * 120 / bpm * bpm / 120, drop + 10.5, 0.5):
+    i, j = int(t * fps), int((t + 0.5) * fps)
+    env.append(int(rms[max(0, i):max(1, j)].mean() * 100) if j > 0 else 0)
+print(f"{path} bpm={bpm:.2f} drop={drop:.3f}")
+print(" pre :", env[:28])
+print(" post:", env[28:])