rsc-universal 0.1.1

package/skills/shopify/scripts/verify.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+#
+# verify.sh — advisory quality scan for a Shopify theme or app directory.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]
+#
+# Read-only by default. Greps a theme/app dir for high-signal Shopify foot-guns and prints
+# WARN / FAIL advisories. WARN = a smell to review; FAIL = a deprecated/removed mechanism that
+# will break. Exits non-zero only when a FAIL-level issue is found in a real Shopify dir.
+# On an empty or non-Shopify target it SKIPs and exits 0 (no false failure).
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays, find-based globbing.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[0;31m'; GREEN=$'\033[0;32m'; YELLOW=$'\033[0;33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+warn() { printf '%sWARN%s %s\n' "$YELLOW" "$RESET" "$*"; }
+ok()   { printf '%s%s%s\n' "$GREEN" "$*" "$RESET"; }
+fail() { printf '%sFAIL%s %s\n' "$RED" "$RESET" "$*"; }
+
+WARNS=0; FAILS=0
+
+# A Shopify dir has either theme structure (sections/ or templates/*.json or *.liquid) or an
+# app/theme config TOML. Neither → nothing to verify, SKIP (exit 0).
+shopify_present() {
+  if [ -f "$TARGET/shopify.app.toml" ] || [ -f "$TARGET/shopify.theme.toml" ]; then return 0; fi
+  if [ -n "$(find "$TARGET" -type f -name '*.liquid' -print -quit 2>/dev/null)" ]; then return 0; fi
+  if [ -d "$TARGET/sections" ] || [ -d "$TARGET/extensions" ]; then return 0; fi
+  return 1
+}
+
+if ! shopify_present; then
+  warn "no Shopify theme/app found under '${TARGET}' (no *.liquid, no shopify.*.toml, no sections/ or extensions/)"
+  ok "verify.sh: ok (nothing to verify)"
+  exit 0
+fi
+
+# grep_count <pattern> <find-name-filter...> — count matching lines across files, 0 if none.
+# Uses find + grep so it stays bash-3.2 / BSD-grep safe and never errors on no match.
+scan() { # scan <label> <level:warn|fail> <regex> <file-glob>
+  local label="$1" level="$2" regex="$3" glob="$4"
+  local hits
+  hits=$(find "$TARGET" -type f -name "$glob" -print0 2>/dev/null \
+    | xargs -0 grep -nE "$regex" 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    if [ "$level" = "fail" ]; then
+      fail "$label"; FAILS=$((FAILS + 1))
+    else
+      warn "$label"; WARNS=$((WARNS + 1))
+    fi
+    printf '%s\n' "$hits" | sed 's/^/    /' | head -10
+  fi
+}
+
+# 1. Deprecated {% include %} in Liquid (prefer {% render %}).
+scan "deprecated {% include %} — use {% render %} (scoped, cacheable)" warn \
+  '\{%-?[[:space:]]*include[[:space:]]' '*.liquid'
+
+# 2. Raw money output without a | money filter (heuristic: .price echoed without 'money').
+scan "price output without | money — renders raw cents/locale wrong" warn \
+  '\{\{[^}]*\.price[^}|]*\}\}' '*.liquid'
+
+# 3. checkout.liquid present — deprecated; automatic upgrades roll out starting 2026-01.
+if find "$TARGET" -type f -name 'checkout.liquid' -print -quit 2>/dev/null | grep -q . ; then
+  fail "checkout.liquid present — deprecated/removed; migrate to checkout extensibility"
+  FAILS=$((FAILS + 1))
+fi
+
+# 4. ScriptTag / additional-script usage — deprecated checkout/tracking mechanism.
+scan "ScriptTag / additional-scripts usage — deprecated; use Web Pixels / UI extensions" warn \
+  'ScriptTag|additional_scripts|additional scripts' '*'
+
+# 5. REST Admin API calls in app source — legacy; prefer GraphQL.
+scan "REST Admin API call (/admin/api/.../.json) — legacy; use admin.graphql()" warn \
+  '/admin/api/[0-9]{4}-[0-9]{2}/[^"'"'"' ]+\.json' '*'
+
+# 6. apiVersion pinned and within the supported window (2025-10 .. 2026-04 at time of writing;
+#    2025-07 is sunsetting ~2026-07-16, so flag it). Unpinned or an older literal → warn.
+APIV=$(find "$TARGET" -type f \( -name '*.js' -o -name '*.ts' -o -name '*.toml' \) -print0 2>/dev/null \
+  | xargs -0 grep -hoE 'apiVersion[^0-9]*(2[0-9]{3}-[0-9]{2})' 2>/dev/null \
+  | grep -oE '2[0-9]{3}-[0-9]{2}' | head -1 || true)
+if [ -f "$TARGET/shopify.app.toml" ] || find "$TARGET" -type f -name '*.server.*' -print -quit 2>/dev/null | grep -q .; then
+  if [ -z "$APIV" ]; then
+    warn "no pinned apiVersion found in app config/server — pin a supported version (e.g. 2026-04)"
+    WARNS=$((WARNS + 1))
+  else
+    case "$APIV" in
+      2026-04|2026-01|2025-10) : ;;
+      2025-07) warn "apiVersion '2025-07' is sunsetting (accessible only until 2026-07-16) — bump to a current version"; WARNS=$((WARNS + 1)) ;;
+      *) warn "apiVersion '$APIV' is outside the supported window (2025-10..2026-04) — bump it"; WARNS=$((WARNS + 1)) ;;
+    esac
+  fi
+fi
+
+# 7. Run Theme Check if a config and the CLI are both present (still read-only).
+if [ -f "$TARGET/.theme-check.yml" ] || [ -f "$TARGET/.theme-check.yaml" ]; then
+  if command -v shopify >/dev/null 2>&1; then
+    printf '==> shopify theme check\n'
+    if ! shopify theme check "$TARGET"; then
+      warn "theme check reported issues"; WARNS=$((WARNS + 1))
+    fi
+  else
+    warn ".theme-check.yml present but shopify CLI not installed — skipping theme check"
+  fi
+fi
+
+printf '\n%d warn, %d fail\n' "$WARNS" "$FAILS"
+if [ "$FAILS" -gt 0 ]; then
+  fail "verify.sh: deprecated/removed mechanisms detected"
+  exit 1
+fi
+ok "verify.sh: ok"
+exit 0

package/skills/shortform-editing/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: shortform-editing
+description: "Use when you have raw 9:16 footage and need it cut into a posted-ready vertical short — dead air removed, fast jump cuts, karaoke word-by-word burned-in captions from a transcript, cuts and zooms snapped to the music beat, and a platform-correct MP4 export. Use to remove silences, generate or fix burned captions, sync cuts to a beat grid, or encode to TikTok/Reels/Shorts specs. Triggers: 'remove the dead air from this talking-head clip', 'burn TikTok-style word-by-word captions onto this short', 'cut this footage to the beat of the song', 'export this Reel with the right specs', 'my captions are out of sync and getting hidden behind the TikTok buttons', 'quítale los silencios y ponle subtítulos quemados estilo TikTok', 'munta'm aquest clip vertical amb talls sincronitzats amb la música'. NOT writing the script, hook, beats, or caption text (that is video-shorts), NOT building a Remotion React composition codebase (that is remotion-video), NOT deciding when/where to post (that is social-publisher)."
+tags: [video-editing, shortform, captions, ffmpeg, whisper, beat-sync, vertical-video]
+recommends: [video-shorts, remotion-video, shortform-packaging, social-publisher, podcast]
+origin: risco
+---
+
+# Shortform Editing — Cut the Footage Into a Posted-Ready Short
+
+*You are the edit-bay technician.* Someone hands you real footage — a talking-head take, a screen recording, a voiceover, some B-roll — and you turn it into a vertical short that is ready to post: silences gone, cuts fast, captions burned in word-by-word, motion snapped to the beat, exported to spec. You encode pixels and timing. You do not write the words or pick the hook.
+
+The rigor is a **checkable file**: a `1080x1920` H.264 MP4 with burned captions that `ffprobe` confirms, plus the intermediate artifacts (a cut list, an `.ass`/`.srt`, a beat grid). If you cannot `ffprobe` the result and see the specs, you are not done.
+
+## Scope: three skills touch "a vertical video" — know your lane
+
+| The ask | Goes to | Artifact |
+|---|---|---|
+| Write the script, hook, beats, on-screen caption *text*, edit decision sheet | `../video-shorts/SKILL.md` | a `.md` script |
+| Cut/caption/export real footage, tool-agnostic | **here** | edited `.mp4` + caption/cut files |
+| Build a Remotion React composition project (`<TransitionSeries>`, headless render) | `../remotion-video/SKILL.md` | a `.tsx` project |
+
+One-line router: **footage in → cut, captioned, exported → this skill.** Words or a plan → `video-shorts`. A React codebase → `remotion-video`. You are the only one of the three that is tool-portable.
+
+## Pick your route first
+
+Do not start cutting before you have chosen the tool. The choice is about who runs it and whether it must reproduce.
+
+| Situation | Route | Why |
+|---|---|---|
+| Reproducible / batch / CI / "do this to 40 clips" | **ffmpeg + WhisperX** | scriptable, deterministic, no GUI — same input, same output |
+| The repo is already a Remotion project | **`@remotion/captions`** | reuse the existing composition graph; don't shell out |
+| A human is polishing one video by hand | **CapCut click-path** | fastest for a single hands-on pass with auto-captions + auto beat markers |
+
+The rest of this skill is the **ffmpeg + WhisperX pipeline** (the reproducible path), with the Remotion and CapCut routes called out where they diverge. Long command blocks live in `references/ffmpeg-pipeline.md`; the caption detail lives in `references/captions.md`.
+
+## The reproducible pipeline, in order
+
+This is the spine. Run it top to bottom; each step feeds the next.
+
+**1. Extract a clean mono 16 kHz audio track for transcription.**
+
+```bash
+ffmpeg -i in.mp4 -vn -ac 1 -ar 16000 a.wav
+```
+
+*Why mono 16 kHz: that is what Whisper models expect; feeding stereo 48 kHz wastes time and changes nothing about accuracy.*
+
+**2. Transcribe with word-level timestamps.** Segment timestamps are not enough — word-by-word captions need per-word timing.
+
+```bash
+whisperx a.wav --model large-v3 --output_format json --highlight_words True
+```
+
+WhisperX (v3.8.5) runs faster-whisper plus wav2vec2 forced alignment, giving word timing accurate to **under 100 ms** — the floor for karaoke highlight. faster-whisper alone with `word_timestamps=True` works (~10% overhead) but drifts more on word boundaries. *Why forced alignment: Whisper's native word stamps are interpolated and jitter; forced alignment pins each word to the audio.* See `references/captions.md` for the install and the JSON shape.
+
+**3. Detect silence, then cut video AND audio together.** This is the step people get wrong.
+
+```bash
+# Pass 1: find the silent ranges (speech threshold)
+ffmpeg -i in.mp4 -af silencedetect=noise=-25dB:d=0.3 -f null - 2> silence.log
+```
+
+`silenceremove` alone is an **audio-only filter and desyncs the video** — never use it as a one-shot. Parse the `silence_start` / `silence_end` lines from `silence.log`, invert them into keep-ranges, and build a `select` + `aselect` filter (or a trim+concat graph) that drops the same ranges from both streams. Thresholds: speech `noise=-25dB:d=0.3`; music beds `noise=-40dB:d=1`. The filter-generation snippet is in `references/ffmpeg-pipeline.md`.
+
+**4. Build the beat grid** (only if you are cutting to music).
+
+```bash
+python -c "import librosa; y,sr=librosa.load('music.wav'); \
+_,b=librosa.beat.beat_track(y=y,sr=sr,units='time'); print(*b,sep='\n')" > beats.txt
+```
+
+`beats.txt` is a list of beat times in seconds. CapCut drops these markers on the waveform automatically; librosa (or aubio) gives you the same grid in a script.
+
+**5. Snap cut points and zoom keyframes to the nearest beat.** Round each cut time to its closest value in `beats.txt`. A zoom-punch on the beat reads as energy; see Beat sync below for when NOT to.
+
+**6. Burn the karaoke `.ass` captions.**
+
+```bash
+ffmpeg -i tightened.mp4 -vf "ass=captions.ass" -c:a copy captioned.mp4
+```
+
+The `.ass` carries the per-word `\k` timing built from step 2's word timestamps and the safe-zone margins. Generation detail and the template are in Karaoke captions below.
+
+**7. Export the platform master** (see Export specs).
+
+## Karaoke captions
+
+Word-by-word captions are the signature look. Build them from the word timestamps, not from segment timestamps.
+
+- **Timing.** Each word's on-screen highlight comes from its forced-alignment start/end. In `.ass`, the `\k<centiseconds>` tag advances the karaoke fill per word. Word-by-word from *segment* timing jitters and lands the highlight on the wrong word — always use the per-word stamps from step 2.
+- **Legibility for sound-off.** Big bold sans, heavy outline/stroke, optional drop shadow. People watch muted: if it is not readable at a glance on a phone, it failed. Keep it to **≤ 2 lines / ~6 words** on screen at once.
+- **Safe zone — the non-obvious one.** Place captions in the **vertical middle band**, not the bottom. Platform UI (right-rail icons, bottom caption/CTA/profile) covers the bottom ~15–20% and the right edge. Keep captions and key text inside the central ~80% of the `1080x1920` frame. Captions burned at the bottom get hidden behind the TikTok buttons — this is the #1 "my captions are broken" cause.
+
+Minimal `.ass` style block (full template in `references/captions.md`):
+
+```text
+[V4+ Styles]
+Style: Karaoke,Montserrat,64,&H00FFFFFF,&H0000FFFF,&H00000000,&H64000000,-1,0,0,0,100,100,0,0,1,5,2,5,80,80,640,1
+```
+
+`MarginV` (the trailing `640`) lifts the line into the middle band; the heavy `Outline` (`5`) keeps it readable on any background.
+
+**Remotion route:** if you are inside a Remotion project, use `@remotion/captions` — `createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })` pages the tokens. Low (200–500 ms) = word-by-word pop; high (1200–2000 ms) = phrase pages. Page `durationMs` was added in v4.0.261. **CapCut route:** Text → Auto captions → Generate, then restyle.
+
+## Beat sync
+
+A beat grid (step 4) is a list of seconds. Snap your cut points and zoom keyframes to the nearest beat so motion lands on the music.
+
+- **Bad → Good.** Cutting mid-word to land a cut exactly on a beat reads as a mistake → nudge the cut to the nearest beat that also respects the speech boundary. Honor the words first, the beat second.
+- **When NOT to beat-cut.** A talking-head explainer where the words carry the value: clarity beats rhythm. Beat-cutting a person mid-sentence chops their delivery. Reserve beat sync for B-roll montages, transitions, and music-led segments.
+- **Transitions stay cheap and fast.** Hard cut is the default. Whip-pan or zoom-punch only on a beat. Avoid 1-second crossfades in a 30-second short — they kill the pace; a short lives on fast hard cuts.
+
+## Export specs
+
+The universal vertical master — one file that plays cleanly across all three platforms:
+
+```bash
+ffmpeg -i captioned.mp4 \
+  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2,setsar=1" \
+  -c:v libx264 -profile:v high -pix_fmt yuv420p -r 30 \
+  -c:a aac -b:a 192k -ar 48000 -ac 2 \
+  -movflags +faststart out.mp4
+```
+
+`yuv420p` (broad playback), `+faststart` (web streaming starts before full download), AAC-LC 48 kHz. Use 30 fps; bump to **60 fps for high-motion** Shorts.
+
+| Platform | Video bitrate | Notes |
+|---|---|---|
+| TikTok | ~2,000–4,000 kbps | lightest of the three |
+| Instagram Reels | ~3,500–4,500 kbps | |
+| YouTube Shorts (1080p) | ~8,000–15,000 kbps | up to ~53,000 for 4K/60 |
+
+A single `1080x1920` H.264 MP4 @30 fps under **~250 MB** is safe everywhere. Verify before you ship:
+
+```bash
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height,codec_name,avg_frame_rate out.mp4
+```
+
+Expect `width=1080 height=1920 codec_name=h264`. The full per-platform encode flags and `ffprobe` assertions are in `references/ffmpeg-pipeline.md`.
+
+## Anti-patterns
+
+| Bad | Why it breaks | Good |
+|---|---|---|
+| `silenceremove` as a one-shot filter | It is audio-only; the video keeps playing → audio/video desync | `silencedetect` → invert ranges → `select`+`aselect` cut both streams |
+| Word captions from segment timestamps | Highlight jitters and lands on the wrong word | Forced-alignment per-word stamps (WhisperX / `word_timestamps`) |
+| Captions burned in the bottom 15–20% | Platform UI (buttons, CTA, profile) covers them | Place in the vertical middle band, central ~80% |
+| One export reused for every platform | Over/under the bitrate target somewhere | Per-platform bitrate, or the safe universal master |
+| 1-second crossfades in a 30s short | Kills the pace; reads slow | Hard cuts; whip/zoom only on a beat |
+| Beat-cutting a talking-head mid-sentence | Chops the delivery; clarity lost | Beat-sync B-roll/montage only; honor speech boundaries |
+| Re-running the encode to "check the specs" | Wastes minutes; the file already exists | `ffprobe` the output; verify, don't re-render |
+| Writing the caption copy or the hook here | That is the script, not the cut | Route to `../video-shorts/SKILL.md`; you only burn it in |
+| `ffmpeg` overwriting the source in place | One bad flag and the original is gone | Always write to a new file; keep `in.mp4` untouched |
+
+## Verify & references
+
+- `bash scripts/verify.sh <output.mp4>` — runs `ffprobe` and asserts `width=1080`, `height=1920` (9:16), video codec `h264`, audio codec `aac`, fps in `{30, 60}`, and that a sibling `.srt`/`.ass` caption file exists and is non-empty. With no `ffprobe` it falls back to a path/extension check. Read-only; exits 0 on an empty/clean target so it never false-fails. The "does it feel on-beat" judgment is not mechanical — that lives in the capability eval.
+- `references/ffmpeg-pipeline.md` — the full silence-detect → keep-range inversion → `select`/`aselect` filter generation that cuts video+audio together, the concat/trim approach, per-platform encode flags, `ffprobe` assertions, and desync/audio-drift/faststart troubleshooting.
+- `references/captions.md` — WhisperX install + run, the word-timestamp JSON shape, the full `.ass` karaoke template with safe-zone margins, the Remotion `createTikTokStyleCaptions()` snippet with `combineTokensWithinMilliseconds` guidance, and the faster-whisper vs WhisperX tradeoff.

package/skills/shortform-editing/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — shortform-editing
+
+These are routing + capability checks for a human or an LLM judge, not a renderer
+test — nothing here encodes a video. To run them, read `cases.yaml` and confirm the
+skill's `description` would fire on every `should_trigger` prompt (including the
+non-obvious "captions out of sync and hidden behind the TikTok buttons" symptom and
+the Spanish/Catalan phrasings) and that each `should_not_trigger` prompt routes to
+the named sibling instead (`video-shorts`, `remotion-video`, `social-publisher`,
+`youtube-thumbnails`, `podcast`) rather than here. For the `capability` scenario,
+have the skill produce the pipeline/commands and grade them line by line against the
+`must_include` rubric: word-level transcription, a two-pass silence cut that removes
+video AND audio together, a beat grid with cuts snapped to it, karaoke `.ass`
+captions in the safe middle band, a 1080x1920 H.264/AAC export, and `ffprobe`
+verification. The "does it feel on-beat" judgment is subjective and stays in this
+rubric. To mechanically check a produced output, point `scripts/verify.sh` at the
+emitted `.mp4`.

package/skills/shortform-editing/evals/cases.yaml

@@ -0,0 +1,61 @@
+skill: shortform-editing
+
+# This skill is the edit-bay technician: it CUTS real footage into a posted-ready
+# vertical short — silence removal, karaoke burned captions from word timestamps,
+# beat-synced cuts, platform-correct export. It does NOT write the script/hook
+# (video-shorts), build a Remotion codebase (remotion-video), schedule posts
+# (social-publisher), make thumbnails (youtube-thumbnails), or master podcast audio
+# (podcast).
+
+should_trigger:
+  - prompt: "Remove the dead air and silences from this talking-head clip automatically."
+    why: "Core silence-removal job — the skill's two-pass silencedetect → cut-both-streams move."
+
+  - prompt: "Burn TikTok-style word-by-word captions onto this short from my Whisper transcript."
+    why: "Core caption job — karaoke .ass from word-level timestamps."
+
+  - prompt: "Cut this footage to the beat of the song so the cuts land on the drops."
+    why: "Beat sync — build a beat grid and snap cut points to it."
+
+  - prompt: "Export this Reel with the right TikTok and Shorts specs."
+    why: "Export job — 1080x1920 H.264 master plus per-platform bitrate."
+
+  - prompt: "My burned-in captions are out of sync and getting hidden behind the TikTok buttons — fix the timing and placement."
+    why: "Non-obvious — the user names a symptom, not the skill; the fix is word-timestamp re-timing plus moving captions out of the bottom UI safe zone, both signature moves."
+
+  - prompt: "Quítale los silencios a este vídeo y ponle subtítulos quemados estilo TikTok."
+    why: "Spanish for 'remove the silences and add burned TikTok-style captions' — language coverage plus the two core jobs."
+
+  - prompt: "Munta'm aquest clip vertical amb talls ràpids sincronitzats amb la música."
+    why: "Catalan for 'edit this vertical clip with fast cuts synced to the music' — language coverage plus beat-synced cutting."
+
+should_not_trigger:
+  - prompt: "Write me a 30-second hook and script for a Reel about cold brew."
+    route_to: video-shorts
+    why: "Words and a plan, no footage — the script/hook is authored, not cut."
+
+  - prompt: "Build a Remotion React project with a TransitionSeries and composition code I can render in CI."
+    route_to: remotion-video
+    why: "A React composition codebase, not a one-off cut on real footage."
+
+  - prompt: "When and where should I post this short across platforms?"
+    route_to: social-publisher
+    why: "Distribution and cadence, not the cut/encode."
+
+  - prompt: "Make me a thumbnail / cover frame for this short."
+    route_to: youtube-thumbnails
+    why: "A still packaging visual, not video editing."
+
+  - prompt: "Master and chapter my podcast episode audio for the RSS feed."
+    route_to: podcast
+    why: "Long-form audio mastering and feed work, not a vertical video cut."
+
+capability:
+  - scenario: "Given a raw 9:16 talking-head clip plus a music track, produce an edited, posted-ready vertical MP4 with karaoke captions, and verify it."
+    must_include:
+      - "Word-level transcription via WhisperX (or faster-whisper word_timestamps), not segment-only timestamps"
+      - "Two-pass silence handling: silencedetect to find ranges, then a select/aselect (or trim+concat) filter that cuts video AND audio together — NOT silenceremove alone"
+      - "A beat grid (librosa/aubio/CapCut markers) with cut points snapped to the nearest beat, and the note that talking-head clarity can outrank rhythm"
+      - "Karaoke .ass captions with per-word \\k timing from the word timestamps, placed in the vertical middle band / central ~80% (not the bottom 15-20% UI zone)"
+      - "Export to 1080x1920 H.264 (yuv420p, +faststart) at 30 or 60 fps with AAC 48 kHz audio, per-platform bitrate or the safe universal master"
+      - "ffprobe verification of resolution, codecs, and frame rate on the output file"

package/skills/shortform-editing/references/captions.md

@@ -0,0 +1,85 @@
+# Captions — word timestamps, .ass karaoke, Remotion route
+
+## Why word-level timestamps
+
+Karaoke captions highlight one word at a time. That needs each word's start/end, not the segment's. Two sources:
+
+| Tool | Word timing accuracy | Cost | When |
+|---|---|---|---|
+| faster-whisper `word_timestamps=True` | interpolated, drifts on boundaries | ~10% overhead, ~4x faster on GPU / 2x on CPU vs reference Whisper (CTranslate2) | quick, GPU-light, tolerant of small drift |
+| WhisperX v3.8.5 (faster-whisper + wav2vec2 forced alignment) | **< 100 ms** | extra alignment pass | word-by-word highlight where the fill must land on the right word |
+
+For karaoke, prefer WhisperX. Its forced alignment pins each word to the audio instead of interpolating.
+
+## Install + run WhisperX
+
+```bash
+pip install whisperx
+whisperx a.wav --model large-v3 --language en \
+  --output_format json --highlight_words True --output_dir out/
+```
+
+This emits `out/a.json`. Shape (trimmed):
+
+```json
+{
+  "segments": [
+    {
+      "start": 0.31, "end": 2.84, "text": " here is the thing",
+      "words": [
+        { "word": "here", "start": 0.31, "end": 0.52 },
+        { "word": "is",   "start": 0.52, "end": 0.64 },
+        { "word": "the",  "start": 0.64, "end": 0.78 },
+        { "word": "thing","start": 0.78, "end": 1.10 }
+      ]
+    }
+  ]
+}
+```
+
+Each `words[i].start/end` is what drives the `.ass` `\k` timing and the Remotion token pages.
+
+## .ass karaoke template
+
+```text
+[Script Info]
+ScriptType: v4.00+
+PlayResX: 1080
+PlayResY: 1920
+
+[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
+Style: Karaoke,Montserrat,64,&H00FFFFFF,&H0000FFFF,&H00000000,&H64000000,-1,0,0,0,100,100,0,0,1,5,2,5,80,80,640,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+Dialogue: 0,0:00:00.31,0:00:01.10,Karaoke,,0,0,0,,{\k21}here {\k12}is {\k14}the {\k32}thing
+```
+
+- `\k<centiseconds>` per word = `(word.end - word.start) * 100`, rounded. The karaoke fill advances by that many centiseconds.
+- `PrimaryColour` is the highlighted/active fill; `SecondaryColour` is the not-yet-spoken color.
+- `Alignment 5` = centered middle. `MarginV 640` lifts the line off the bottom into the safe middle band.
+- `Outline 5` + `Shadow 2` keep it legible on any background for sound-off viewing.
+
+### Safe-zone math
+
+Frame is `1080x1920`. Reserve the bottom ~15–20% (≈ 290–384 px) for platform UI and the right edge for the icon rail. Keep caption baselines inside the central ~80%: roughly **y from 384 to 1536**. A `MarginV` around `560–720` lands the line in the lower-middle of that band — high enough to clear the buttons, low enough to feel like a caption.
+
+## Remotion route (when the repo is a Remotion project)
+
+```tsx
+import { createTikTokStyleCaptions, type Caption } from "@remotion/captions";
+
+const captions: Caption[] = /* from convertToCaptions(whisperJson) */;
+
+const { pages } = createTikTokStyleCaptions({
+  captions,
+  combineTokensWithinMilliseconds: 350, // low = word-by-word; 1200–2000 = phrase pages
+});
+```
+
+- `combineTokensWithinMilliseconds` is the page-size dial: low (200–500 ms) → one word per page → word-by-word pop; high (1200–2000 ms) → a phrase per page.
+- Per-page `durationMs` is available since v4.0.261.
+- Style the rendered token in the composition, not here; keep it in the same safe middle band (`bottom: ~25%` of a `1080x1920` frame).
+
+Do not build a Remotion project just to caption a one-off clip — that is `../remotion-video/SKILL.md`. Use this route only when the project already exists.

package/skills/shortform-editing/references/ffmpeg-pipeline.md

@@ -0,0 +1,126 @@
+# ffmpeg pipeline — silence cut, beat snap, encode, verify
+
+The reproducible cut path in full. Every command writes to a *new* file; the source `in.mp4` is never overwritten.
+
+## 1. Extract audio for transcription
+
+```bash
+ffmpeg -i in.mp4 -vn -ac 1 -ar 16000 a.wav
+```
+
+Mono 16 kHz is the Whisper input contract. Keep `in.mp4` for the actual cut — the `.wav` is only for transcription and silence detection.
+
+## 2. Detect silence
+
+```bash
+# Speech (talking head): trim gaps longer than 0.3s below -25 dB
+ffmpeg -i in.mp4 -af silencedetect=noise=-25dB:d=0.3 -f null - 2> silence.log
+
+# Music bed: looser, so you don't chop quiet passages
+ffmpeg -i in.mp4 -af silencedetect=noise=-40dB:d=1 -f null - 2> silence_music.log
+```
+
+`silence.log` contains lines like:
+
+```text
+[silencedetect @ 0x...] silence_start: 4.213
+[silencedetect @ 0x...] silence_end: 5.087 | silence_duration: 0.874
+```
+
+## 3. Invert silent ranges into keep-ranges and cut BOTH streams
+
+`silenceremove` alone is audio-only and desyncs picture. Build keep-ranges and apply a `select`/`aselect` graph so the same time windows are dropped from video and audio together.
+
+```bash
+#!/usr/bin/env bash
+# build_cut.sh — parse silence.log, emit a keep-only filtergraph, cut both streams.
+set -euo pipefail
+SRC="${1:-in.mp4}"; LOG="${2:-silence.log}"; OUT="${3:-tightened.mp4}"
+
+# Pull starts/ends in order; pair them into [silence_start, silence_end] gaps.
+starts=$(grep -o 'silence_start: [0-9.]*' "$LOG" | awk '{print $2}')
+ends=$(grep -o 'silence_end: [0-9.]*'   "$LOG" | awk '{print $2}')
+
+# Keep-ranges = the complement of the silent gaps over [0, duration].
+DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$SRC")
+
+# Compose: keep from 0 to first silence_start, then from each silence_end to next start, ... to DUR.
+python3 - "$DUR" <<'PY' > keep.txt
+import sys
+dur = float(sys.argv[1])
+starts = [float(x) for x in open("starts.tmp").read().split()] if False else None
+PY
+# (In practice generate keep.txt as "start end" pairs; see the note below.)
+```
+
+The practical, dependency-light version: write `starts`/`ends` to temp files, pair them in `awk` into `keep_start keep_end` pairs, then assemble a `between(t,s,e)` expression:
+
+```bash
+# keep.txt holds one "S E" pair per kept segment.
+sel=$(awk '{printf "between(t,%s,%s)+", $1, $2}' keep.txt | sed 's/+$//')
+
+ffmpeg -i "$SRC" \
+  -vf "select='${sel}',setpts=N/FRAME_RATE/TB" \
+  -af "aselect='${sel}',asetpts=N/SR/STB" \
+  -c:v libx264 -pix_fmt yuv420p -c:a aac -b:a 192k "$OUT"
+```
+
+`setpts`/`asetpts` re-stamp the surviving frames so there are no gaps — without them the kept pieces keep their original timestamps and the player stalls.
+
+**Trim+concat alternative** (cleaner for a handful of cuts): emit one `trim`/`atrim` pair per keep-range, then `concat=n=<k>:v=1:a=1`. Use this when you have < ~10 segments; the `select` expression is better for many small gaps.
+
+## 4. Beat grid
+
+```bash
+python3 -c "import librosa; y,sr=librosa.load('music.wav'); \
+_,b=librosa.beat.beat_track(y=y,sr=sr,units='time'); print(*b,sep='\n')" > beats.txt
+```
+
+`beats.txt` is beat times in seconds. Snap each cut/zoom keyframe to the nearest line. aubio (`aubiotrack music.wav`) is an alternative; CapCut places the same markers on the waveform automatically.
+
+## 5. Burn captions
+
+```bash
+ffmpeg -i tightened.mp4 -vf "ass=captions.ass" -c:a copy captioned.mp4
+```
+
+Use `ass=` (not `subtitles=`) when the file is `.ass` so styling/karaoke is honored. `-c:a copy` keeps audio untouched — re-encoding here is wasted work since the encode happens at export.
+
+## 6. Export — per-platform encode
+
+Universal master (plays everywhere):
+
+```bash
+ffmpeg -i captioned.mp4 \
+  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2,setsar=1" \
+  -c:v libx264 -profile:v high -pix_fmt yuv420p -r 30 \
+  -c:a aac -b:a 192k -ar 48000 -ac 2 -movflags +faststart out.mp4
+```
+
+Per-platform bitrate (add `-b:v` / `-maxrate` / `-bufsize`):
+
+| Platform | `-b:v` | `-maxrate` | `-bufsize` |
+|---|---|---|---|
+| TikTok | 3M | 4M | 6M |
+| Instagram Reels | 4M | 4.5M | 8M |
+| YouTube Shorts 1080p | 12M | 15M | 24M |
+
+60 fps for high-motion: `-r 60`. Keep the universal master under ~250 MB and it is safe on all three.
+
+## 7. ffprobe assertions
+
+```bash
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height,codec_name,avg_frame_rate -of default=nw=1 out.mp4
+ffprobe -v error -select_streams a:0 \
+  -show_entries stream=codec_name,sample_rate,channels -of default=nw=1 out.mp4
+```
+
+Expect: video `width=1080 height=1920 codec_name=h264 avg_frame_rate=30/1` (or `60/1`); audio `codec_name=aac sample_rate=48000`.
+
+## Troubleshooting
+
+- **Audio leads/lags video after the cut.** You re-stamped one stream but not the other — both `setpts=N/FRAME_RATE/TB` and `asetpts=N/SR/STB` must be present.
+- **Slow progressive drift across a long clip.** Variable frame rate source; normalize with `-vsync cfr -r 30` on the source before cutting.
+- **Plays in VLC but stalls in a browser/upload preview.** Missing `-movflags +faststart`; the moov atom is at the end. Re-mux: `ffmpeg -i out.mp4 -c copy -movflags +faststart fixed.mp4`.
+- **Captions show but unstyled.** You used `subtitles=` on an `.ass` file; switch to `ass=`.