From 311cd32725cfdc69cf2c8ee18eb602753d4ffdae Mon Sep 17 00:00:00 2001 From: jieling-jenson Date: Fri, 19 Jun 2026 21:09:20 +0800 Subject: [PATCH] refactor(embedded-captions): merge motion-vocabulary + direction-catalog into live homes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 14->12 reference files. Both advertised a retired "10 looks / 10 motion primitives" model that contradicts the live 48-identity catalog, and neither is read by any compiler. Kernels migrated first (verified no-successor): - direction-catalog's tone x shot x platform CLASSIFICATION MATRIX -> CATALOG.md as a shortlisting crosswalk (verbatim table + a usage header tying direction labels to current identities + the anchor-fallback). The 10 per-direction specs map ~1:1 onto shipped identities and drop with the file. - motion-vocabulary's "palette not a cage / pick by content tone / invent deterministically" permission -> _motion.md intro. Its 10 move definitions are redundant with _motion.md's richer mood->entrance catalog (type/fade-up/pop/whip/ glitch/blur-in + 50 moves) and drop; its 60% exit rule was DROPPED, not carried, as it conflicts with _motion.md's canonical "exit ~= 75% of entry". Repointed all 5 inbound links: SKILL:211 (matrix cross-ref -> CATALOG), the two SKILL table rows (removed), SKILL:240 prose ("and direction catalog" dropped), and typographic-moves.md:203 (the dead direction-catalog §1 parenthetical dropped; it already names the `documentary` identity). Verified: zero residual refs, no dangling file/anchor links, kernels present in their new homes, CJK-free, oxfmt clean. Co-Authored-By: Claude Opus 4.8 --- skills/embedded-captions/CATALOG.md | 14 ++ skills/embedded-captions/SKILL.md | 6 +- .../embedded-captions/modes/shared/_motion.md | 2 + .../references/direction-catalog.md | 138 ---------------- .../references/motion-vocabulary.md | 148 ------------------ .../references/typographic-moves.md | 2 +- 6 files changed, 19 insertions(+), 291 deletions(-) delete mode 100644 skills/embedded-captions/references/direction-catalog.md delete mode 100644 skills/embedded-captions/references/motion-vocabulary.md diff --git a/skills/embedded-captions/CATALOG.md b/skills/embedded-captions/CATALOG.md index bf1f92ae07..d99c2143de 100644 --- a/skills/embedded-captions/CATALOG.md +++ b/skills/embedded-captions/CATALOG.md @@ -14,6 +14,20 @@ Routing procedure (replaces any mode decision): 4. Author the identity's file (last column), then render with its engine's pipeline. Done — no category question ever surfaced. +### Tone × shot × platform — direction crosswalk (shortlisting aid) + +A pre-shortlist input for step 2: intersect the clip's register with the delivery platform to get a **direction**, then pick the CATALOG identity of that register from the table below (documentary → `documentary` / `anchor`; keynote → `keynote`; poetic → `cream`; conversational → a cinematic column-flow or a rail theme; energetic → a loud theme). The cells are direction labels, not identity names; when none fits cleanly → **`anchor`**. + +| Tone ↓ / Platform → | 9:16 portrait | 16:9 landscape | 1:1 square | +| ------------------- | ---------------------------------------- | ------------------------ | ------------------------ | +| **Documentary** | documentary-dignified (vertical variant) | documentary-dignified | broadcast-dignified | +| **Conversational** | portrait-header + default | memory-wall OR champion | broadcast-dignified | +| **Energetic** | high-energy-vlog | high-energy-vlog-wide | high-energy-vlog-sq | +| **Poetic** | lyrical-poem-on-wall (portrait) | lyrical-poem-on-wall | chapter-card | +| **Keynote/tech** | — (9:16 not ideal) | tech-keynote-confident | tech-keynote-confident | +| **Investigative** | — | investigative-typewriter | investigative-typewriter | +| **Music video** | k-pop-lyric | k-pop-lyric | k-pop-lyric | + ## Identities | Identity | Reading surface | Voice (one line) | Recommend for | Scene needs | Author → engine | diff --git a/skills/embedded-captions/SKILL.md b/skills/embedded-captions/SKILL.md index 1d136b0135..de85ec717e 100644 --- a/skills/embedded-captions/SKILL.md +++ b/skills/embedded-captions/SKILL.md @@ -208,7 +208,7 @@ Classify the clip on 3 axes and feed the result into CATALOG.md's shortlisting - 9:16 portrait (TikTok/IG/Shorts) | 16:9 landscape (YouTube/web) | 1:1 square | broadcast export -Cross-reference in [references/direction-catalog.md § Classification matrix](references/direction-catalog.md) for direction language — then return to [CATALOG.md](CATALOG.md) to shortlist identities (this matrix informs the shortlist; the catalog is the only routing surface). +Cross-reference the **tone × shot × platform crosswalk** in [CATALOG.md](CATALOG.md) for direction language — it informs the shortlist; the catalog is the only routing surface. ## Composition craft (embed track) — read before embedding @@ -230,8 +230,6 @@ track has its own, much simpler spec → **[references/rail.md](references/rail. | [dna/README.md](dna/README.md) | **The DNA registry** — ten scene-parameterized visual languages; how to pick. | | [references/reference-bar.md](references/reference-bar.md) | **The taste bar** — per-register world-class references + the 5 positive checks. | | [references/aesthetic-principles.md](references/aesthetic-principles.md) | **The 18 rules.** Beat Veed AI on taste. Read first. | -| [references/motion-vocabulary.md](references/motion-vocabulary.md) | 10 named motion primitives + tone→timing lookup | -| [references/direction-catalog.md](references/direction-catalog.md) | 10 ship-ready aesthetics + tone×shot×platform matrix | | [references/anti-patterns.md](references/anti-patterns.md) | Bugs already locked out (CoreML, letter-spacing reflow, etc.) | | [references/layout-heuristics.md](references/layout-heuristics.md) | Step 0 embed-viability gate (is a surface usable — 4 conditions); plane positioning, clean-zone selection, crown 3 conditions, pillarbox math | | [references/typography-presets.md](references/typography-presets.md) | Font-size × column-width matrix (starting points) | @@ -239,7 +237,7 @@ track has its own, much simpler spec → **[references/rail.md](references/rail. | [references/failure-modes.md](references/failure-modes.md) | Long tail of dev gotchas | | [references/bespoke-vs-presets.md](references/bespoke-vs-presets.md) | Why presets fail sometimes; clone-and-tweak pattern | -**Read the aesthetic principles and direction catalog FIRST.** Everything else is implementation detail. +**Read the aesthetic principles FIRST.** Everything else is implementation detail. --- diff --git a/skills/embedded-captions/modes/shared/_motion.md b/skills/embedded-captions/modes/shared/_motion.md index cc9eeab10b..eea3799713 100644 --- a/skills/embedded-captions/modes/shared/_motion.md +++ b/skills/embedded-captions/modes/shared/_motion.md @@ -9,6 +9,8 @@ metadata: `_anatomy.md` wires four hooks onto one paused timeline: `FLOW_IN`, `FLOW_OUT`, `CLIMAX_IN`, `CLIMAX_OUT`. This file is the catalog each template picks from. Each recipe is a GSAP tween on the climax `span` (or a flow `.w`); placed at an absolute time it is fully **seek-safe**. Multi-stage looks use GSAP `keyframes:{}` (still seek-safe) — never CSS keyframes. +**A palette, not a cage.** Pick the entry by mood (the mood→entrance table below) and **by content tone — never default every group to one move**. When a scene genuinely demands a move this catalog lacks, invent one — as long as it stays deterministic + seek-safe and animates transform/opacity only (the reflow rule, [\_anatomy.md](_anatomy.md)). + ## Numerics (shared) **Ease palette** (sanctioned — reads clean on video, stays distinct): diff --git a/skills/embedded-captions/references/direction-catalog.md b/skills/embedded-captions/references/direction-catalog.md deleted file mode 100644 index 2d8414339a..0000000000 --- a/skills/embedded-captions/references/direction-catalog.md +++ /dev/null @@ -1,138 +0,0 @@ -# Direction catalog - -10 distinct aesthetic directions the skill can express. Each is a complete look: font, motion, color, placement, rhetorical defaults. The agent picks by **content tone × shot type × platform**, not preset name. - -**Superseded for routing by [CATALOG.md](../CATALOG.md) → [dna/](../dna/README.md) (the 10 column-flow voices) + [themes/](../themes/README.md) (38 themed)** — the per-direction specs below map ~1:1 onto shipped identities. Kept for the **classification matrix** (tone × shot × platform), which the live registries don't restate; the rest are future ship-ready aesthetics. - -Classification matrix — pick direction by intersection: - -| Tone ↓ / Platform → | 9:16 portrait | 16:9 landscape | 1:1 square | -| ------------------- | ---------------------------------------- | ------------------------ | ------------------------ | -| **Documentary** | documentary-dignified (vertical variant) | documentary-dignified | broadcast-dignified | -| **Conversational** | portrait-header + default | memory-wall OR champion | broadcast-dignified | -| **Energetic** | high-energy-vlog | high-energy-vlog-wide | high-energy-vlog-sq | -| **Poetic** | lyrical-poem-on-wall (portrait) | lyrical-poem-on-wall | chapter-card | -| **Keynote/tech** | — (9:16 not ideal) | tech-keynote-confident | tech-keynote-confident | -| **Investigative** | — | investigative-typewriter | investigative-typewriter | -| **Music video** | k-pop-lyric | k-pop-lyric | k-pop-lyric | - ---- - -## Direction specs - -### 1. documentary-dignified _(Errol Morris / PBS Frontline)_ — rail-surface direction (use the `documentary` / `anchor` identities) - -- **Family**: Söhne Mono OR GT Sectra for name cards; Inter for body -- **Weights**: 500 body, 700 name card -- **Color**: bone `#F5EFE6` on charcoal, OR charcoal `#1A1A1A` on bone. No accent. -- **Motion**: burn-in (no animation). Held 0.5s past last word. -- **Placement**: bottom-left block, 10% margin, locked position for whole interview. -- **Rules**: 2-line max. Speaker name card once at first utterance + after each cut. No emphasis styling — gravitas IS the style. -- **Rhetorical**: aggressive filler suppression. Every word is chosen. - -### 2. cinematic-noir _(Kyle Cooper / Se7en)_ - -- **Family**: Distressed serif (Hoefler Text) + tight mono for detail -- **Weights**: 700 mostly; thin italic ONLY for whispers -- **Color**: off-white `#E8E0D0` with deep red `#8B0000` single-word accent for menace -- **Motion**: typewriter with 10% chance of 1px jitter on entry; scratched etch for chapter beats -- **Placement**: off-axis — avoid dead-center, slightly high-left or low-right -- **Rules**: no emoji, no rounded corners, everything hand-feeling - -### 3. tech-keynote-confident _(Apple / Jony Ive ad)_ - -- **Family**: SF Pro Display OR Inter, nothing else -- **Weights**: 800 headline keyword, 400 context -- **Color**: pure white on any bg; `mix-blend-mode: difference` fallback for bright scenes -- **Motion**: swipe-reveal from bottom via clip-path (400ms); exit fades 400ms -- **Placement**: dead center, large. NOT lower-third. -- **Rules**: one caption on screen at a time. 2–5 words per caption. Long held silences between. Feels like slides. - -### 4. lyrical-poem-on-wall _(extends current memory-wall template)_ - -- **Family**: Serif with personality — EB Garamond / GT Sectra / Caslon Italic -- **Weights**: 400–500 only. **This direction rejects bold.** -- **Color**: picks up wall via `mix-blend-mode: overlay`, opacity 0.85, no stroke -- **Motion**: etch in 600ms, hold 1.5–3s, etch out -- **Placement**: always on a surface in the scene (back wall, foam, whiteboard). Uses matte pipeline. -- **Rules**: captions are **fewer** than spoken text — 40–60%. Intentional silences. No other tool does this; strong differentiation. - -### 5. high-energy-vlog _(controlled Hormozi)_ - -- **Family**: Inter ExtraBold, uppercase -- **Weights**: 900 always -- **Color**: white body + ONE accent (`#FFD600` or `#00E676`) + narrow 2px dark stroke -- **Motion**: word-pop with elastic, 60ms stagger; active word scales 1.15× on speech onset -- **Placement**: center-frame, ~35% from top -- **Rules**: max 3 words per frame. Hard break at breath pauses. Accent color on ~15% of words. **One full silence every 10s** (what Hormozi imitators miss). - -### 6. chapter-card _(Wes Anderson / Grand Budapest)_ - -- **Family**: Futura Bold (modern) / Archer (warm) / Bodoni (formal) -- **Weights**: 700 chapter title, 400 attribution -- **Color**: pastel hue sampled from scene -- **Motion**: full-frame static card between interview segments -- **Placement**: centered card for chapters; lower-left name card during speech -- **Rules**: chapter cards get their own beat (0.8s silence before, 0.4s after). Feels authored. - -### 7. investigative-typewriter _(Frontline / 60 Minutes / Morris Interrotron)_ - -- **Family**: IBM Plex Mono OR JetBrains Mono -- **Weights**: 500 -- **Color**: white with 3px shadow, no stroke -- **Motion**: typewriter char-by-char 25ms/char; cursor blink 600ms after last char -- **Placement**: bottom band with 40% opacity gradient up — **NOT a hard box** -- **Rules**: one line only, two-line max. Every caption ends with 1-frame cursor-hold before next enters. - -### 8. k-pop-lyric _(music video typographic flex)_ - -- **Family**: oversized display serif (Playfair Display / GT Super) + tiny mono detail line -- **Weights**: display 900, mono 400 -- **Color**: deep saturated single hue per song/segment -- **Motion**: cascade entries alternating sides; words cross subject with mix-blend -- **Placement**: intentionally LARGE — sometimes bigger than the face -- **Rules**: emotional/musical moments only. Never informational content. **Breaks rule #1 (subject wins) on purpose** — that's the whole point. - -### 9. broadcast-dignified _(BBC / NYT documentary standard)_ - -- **Family**: Helvetica Now / Neue Haas Grotesk -- **Weights**: 500 body, 700 name -- **Color**: white on 40% black gradient pill (not hard box, not plain shadow — gradient is the signature) -- **Motion**: 200ms fade-up, 150ms fade-down -- **Placement**: bottom-center, 10% margin, title-safe locked -- **Rules**: strict BBC — 160–180wpm, 32–34 chars/line, 2 lines max, 1.5s min gap. "Export to broadcast" mode. Boring on purpose. Never wrong. - -### 10. conference-lower-third-killer _(B2B but not lame)_ - -- **Family**: GT America / Aktiv Grotesk -- **Weights**: dual-weight name card — role 400, name 700, same size -- **Color**: scene-sampled accent on name, white on role -- **Motion**: name card swipes in from left 400ms on first appearance only; subsequent static -- **Placement**: lower-left card + active-word highlight inline in dialogue above -- **Rules**: mode for podcast clips, founder interviews, keynote pulls. Sophisticated without being arty. - ---- - -## Which to ship next - -Current templates: `memory-wall` (roughly direction #4), `champion` (roughly a mix of #5 and #9), `portrait-header` (default vertical). - -Priority ship order based on competitive gap: - -1. **documentary-dignified** — no one else does this well; Errol Morris aesthetic is an unserved niche -2. **lyrical-poem-on-wall** (as distinct template) — the one that most uses our matte-embed moat -3. **high-energy-vlog** — matches but out-designs Hormozi/Submagic presets -4. **tech-keynote-confident** — big for product launch videos -5. **investigative-typewriter** — niche but highly distinctive - ---- - -## How the agent picks - -1. Classify the clip: `tone × shot × platform` (see matrix above) -2. Look up direction in matrix -3. Read that direction's spec in this file -4. Translate spec into plan.json parameters OR clone the canonical HTML from `examples/` -5. Tune layout per scene (agent judgment, see `aesthetic-principles.md §1–18`) - -If no direction fits cleanly → the **`anchor` theme** (the conservative verbatim default). Don't fake-fit an ill-matched direction. diff --git a/skills/embedded-captions/references/motion-vocabulary.md b/skills/embedded-captions/references/motion-vocabulary.md deleted file mode 100644 index 84b8bd0dce..0000000000 --- a/skills/embedded-captions/references/motion-vocabulary.md +++ /dev/null @@ -1,148 +0,0 @@ -# Motion Vocabulary — named word-entry moves - -10 motion primitives the skill uses. Each has a specific timing + easing + situational fit. Agent picks by **content tone**, not default to one. - -**Easing philosophy:** `cubic-bezier(.2,.7,.2,1)` is the "considered confident" default. `linear` is almost always wrong. Back-easing (elastic) is for playful content only — never documentary. - -**Exit rules:** Default exit is the same tween reversed at 60% duration. Never exit with a different motion than entry unless doing a rhetorical pivot. Never fade out during speech — only during the gap between phrases. - ---- - -## The 10 moves - -### 1. typewriter - -Char-by-char reveal, 25–35ms/char, linear easing. Documentary / data-heavy / tense / interrogative. - -```js -// GSAP -words.forEach((w, i) => { - const chars = w.textContent.split(""); - w.textContent = ""; - chars.forEach((c, j) => { - const span = document.createElement("span"); - span.textContent = c; - span.style.opacity = 0; - w.appendChild(span); - tl.to(span, { opacity: 1, duration: 0 }, wordStart + j * 0.028); - }); -}); -``` - -### 2. word-fade-up (DEFAULT) - -Per-word, 80ms stagger, `opacity 0→1 + translateY 8→0`, `cubic-bezier(.2,.7,.2,1)` (ease-out). Default for conversational content. - -```js -tl.fromTo( - word, - { opacity: 0, y: 8 }, - { opacity: 1, y: 0, duration: 0.45, ease: "power2.out" }, - wordStart, -); -``` - -### 3. word-pop - -Per-word, 60ms stagger, `scale 0.85→1 + opacity 0→1`, elastic-light `cubic-bezier(.34,1.56,.64,1)`. Energetic / YouTube-vlog / high-tempo. **Never for documentary.** - -### 4. swipe-reveal - -Whole phrase at once, 400ms, `clip-path inset 0 100% 0 0 → 0 0 0 0`, expo `cubic-bezier(.77,0,.175,1)`. Keynote / tech product / announcement. - -```css -.cap { - clip-path: inset(0 100% 0 0); -} -/* animate to inset(0 0 0 0) */ -``` - -### 5. drop-and-settle - -Per-word, 120ms stagger, `y: -30→0` with back-bounce `cubic-bezier(.68,-.55,.27,1.55)`. Playful but controlled. **Not for documentary.** - -### 6. etch - -Whole word at once, 600ms, opacity ramp `0→1` with slight blur→sharp transition. Ease-in-out. Poetic / lyrical / "quote on wall" direction. - -### 7. crosshair - -Per-word, 200ms total: two 1px lines converge on word center (linear 150ms), then word snaps in (expo-out 50ms). Thriller / investigative doc. - -### 8. breathing-hold - -**Static but alive.** No entry animation. Once visible, micro-scale loop `1.00↔1.008` over 2s, sine ease. Used on climax lines held 1.5s+. - -### 9. cascade - -Each word from alternating direction: L, R, L, R. `translateX: ±40→0`, ease-out 300ms. **Rhythm-break move** — use sparingly, once per 30s max. - -### 10. burn-in - -**Zero animation.** Sudden 1-frame opacity 1. No fade, no transform. Interview-doc style. Use for every 6–8th phrase in a documentary direction for variety (see direction-catalog §1). - ---- - -## Tone → timing lookup table - -| Tone | Stagger | Hold | Entry move | -| -------------- | ------------------------- | ----------- | ---------------------------------- | -| documentary | 150ms | 600ms | burn-in (70%) + word-fade-up (30%) | -| conversational | 80ms | 400ms | word-fade-up | -| energetic | 50ms | 300ms | word-pop | -| poetic | 250ms | 1200ms | etch | -| broadcast | 0 (burn-in) | BBC timings | burn-in | -| investigative | 25ms/char | 500ms | typewriter | -| keynote | 0 per-word (phrase swipe) | 600ms | swipe-reveal | - -Agent picks tone → this table → GSAP parameters. Data, not guesswork. - ---- - -## Per-word vs per-phrase animation axis - -Orthogonal to the 10 moves above. - -- **Per-word animation** (default): each word enters at its `w.start` timestamp. Tight sync with speech. -- **Per-phrase animation**: whole group enters/exits at `g.in`/`g.out`. Words appear together. Used for: - - swipe-reveal moves - - burn-in (no animation, but the "reveal" is a group event) - - title cards / chapter breaks - -Rule: per-word for content that tracks speech; per-phrase for moments that step outside the speech flow. - ---- - -## Stagger breakdown by context - -Fine-tune stagger within a tone: - -- **Documentary dialog**: 150ms (measured) -- **Documentary punchline**: 250ms (weighted) -- **Vlog opener**: 50ms (fast hook) -- **Vlog narration**: 70ms (conversational but snappy) -- **Poem / lyric**: 250–400ms per word, with 500–1000ms gaps between phrases -- **Keynote hero**: per-phrase only (stagger = N/A) -- **Interview name card**: 0 stagger (static) - ---- - -## Anti-patterns (motion pacing) - -The animation-property bans — never animate `letter-spacing` / `filter:blur` / font-size (inline-block reflow) — live in [failure-modes.md § Animation](failure-modes.md). Motion-pacing-specific: - -- `Math.random()` / `Date.now()` in timeline → non-deterministic render -- Entries under 100ms total → frantic, unreadable -- Same motion for every group for 30s+ → eye adapts, stops registering - ---- - -## When to break the vocabulary - -The 10 moves are a comfortable coverage, not a ceiling. Invent new moves when the scene demands it: - -- Kyle Cooper's scratched typewriter for noir -- K-pop lyric's directional word-from-side -- Film-title flash-cut burn-in with chromatic aberration - -When inventing: stay deterministic, stay transform+opacity only, state the motion in terms of the 4 axes (entry, hold, exit, stagger). diff --git a/skills/embedded-captions/references/typographic-moves.md b/skills/embedded-captions/references/typographic-moves.md index 066df0df94..ee84e4de7c 100644 --- a/skills/embedded-captions/references/typographic-moves.md +++ b/skills/embedded-captions/references/typographic-moves.md @@ -200,7 +200,7 @@ This DNA assumes mid-to-dark backgrounds (the cream/`screen` luma band — see t - Bright white studios → cinematic-cream's cream + `screen` washes out, and the DNA is **locked** (no recolour — see [../SKILL.md](../SKILL.md) § Non-negotiables) → use the **`anchor` theme** or **`ink`** (opaque rail / letterpress) instead -- Documentary formal → the **`documentary`** column-flow identity (see references/direction-catalog.md §1) +- Documentary formal → the **`documentary`** column-flow identity - Energetic vlog hooks → future `kinetic-vlog` DNA (not yet shipped) ## Example: memory-wall original, expressed in freeform