cueframe 0.2.0 → 0.3.0

package/skills/add-music-bed/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: add-music-bed
+description: Retrofits a music bed (and ambience or SFX) onto an existing composition — license-aware search, correct mix hierarchy, ducking under speech, cuts moved onto the beat. Triggers on "add music to this", "this video feels dead", "put a bed under it", "it needs sound", "add background music", "make the cuts hit the beat", "add some sfx", "the audio is just silence".
+---
+
+# Add a music bed
+
+> **Stock-audio limits (verified in production):** a Freesound import lands with
+> `audioRole:"sfx"` and NO beat grid — `import_resource` takes no audioRole param, and
+> `materializeGrid grid:"beat"` will 422 `grid_unavailable` on it. Set the role yourself when
+> placing the clip (`audioRole:"music"` on the composition clip), put the bed on its own AUDIO
+> track (the judge expects a dedicated music track), and until curated music-pack discovery
+> exists, prefer fades over beat-cuts for stock beds — beat-grid cutting works with pack beds.
+
+
+You point at an existing composition that sounds empty; you get it back with a licensed bed that
+matches the brand's mood, sits correctly under any speech, and — where the bed drives pacing —
+cuts moved onto its beat grid. Attribution included, levels disciplined, one re-render.
+
+## Before you start
+
+Listen first — identify what audio the composition already has before proposing anything. When
+the first tool call approaches and CueFrame isn't connected:
+
+- **Claude Code:** offer to run
+  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — browser OAuth,
+  one **Allow**.
+- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
+  `https://api.cueframe.ai/v1/mcp`.
+- **Other agents:** paste `set up https://cueframe.ai/skill.md`, or run
+  `npx -y cueframe install`.
+
+Then back to the soundtrack — this is usually a one-sitting job.
+
+## Inputs
+
+- **The composition** (required): id, or find it via `list_compositions`.
+- **Mood**: the brand kit's `musicMood` is the default answer — honor it before asking. No kit
+  → ask for one adjective pair ("calm/driving", "warm/dark").
+- **What speech exists**: check `get_media_context` on the composition's media for VO/dialogue —
+  it decides the whole mix shape.
+- **Beat-cut permission**: moving cuts onto the beat changes timing slightly; default yes for
+  social pieces, ask for approved masters.
+
+## Workflow
+
+1. **Read the composition and its speech.** `list_compositions` / the composition body for
+   what's on the timeline; `get_media_context` for transcripts. Speech present → the voice is
+   the rhythm authority and the bed serves it. No speech → the bed IS the rhythm authority and
+   earns beat-cuts.
+2. **Find the bed, license-aware.** Beds come from the curated music packs —
+   `import_resource { kind:"music-pack" }` — honoring the brand kit's `musicMood` (mood and
+   energy matched to the cut rate). For ambience or loop textures, `search_resources
+   kind:"sfx"` (Freesound, CC0-only) works too. For SFX accents, the curated pack
+   (`import_resource { kind:"sfx-pack" }`) is the fast default. Record provider/id/author for
+   everything — attribution ships in the delivery note.
+3. **Place it with a role, not a volume.** `apply_composition`: add the bed as an
+   `audioRole:"music"` clip. The engine's default mix staging already keeps voice on top;
+   author `volumeDb` only to deliberately deviate. Under speech, set `duck` so the bed drops on
+   words and recovers between them — the voice is never fought.
+4. **Fades at the edges.** A bed that starts at full level on frame one is a jolt: fade in over
+   the first beat, fade/resolve out under the end card. The bed should feel like it was always
+   there.
+5. **Cut to the beat where the bed drives.** `materializeGrid { clipId, grid:"beat" }` on the
+   bed — the server lands beat markers at correct timeline times. Move cut points and
+   transition MIDPOINTS onto markers (start a 0.5s transition 0.25s early so its center hits
+   the beat). Skip this when speech is the authority — there you land accents between phrases,
+   on the words that matter.
+6. **Restraint is the discipline.** A few placed sounds read; a wall of them merges into mush.
+   The biggest moment gets the strongest accent ONCE. And silence stays a device — clean air
+   before the first hit, a dropout before the biggest beat, is worth more than any riser.
+7. **Verify, judge, re-render.** `preview_frame` the key beats to confirm nothing visual
+   regressed; `score_composition` to confirm the piece improved (worst-first if not, ≥ 7.5 to
+   ship); then `create_render` → `wait_job (kind:"render")` — one render, on approval.
+
+If, after listening, the right call is NO bed — a raw testimonial, a piece whose room tone is
+the point — that is a legitimate outcome of this skill: record the intentional-silence decision
+and its reason in the delivery note instead of forcing a bed.
+
+## What good looks like
+
+Quoted from `video-craft-standards` (cross-cutting rules — every artifact); this skill exists to
+satisfy the second one:
+
+> **MUST** Audio is decided, never defaulted: a music bed (curated packs via
+> `import_resource {kind:"music-pack"}`) or ambience/loops (Freesound via
+> `search_resources kind:"sfx"`), honoring the brand kit's `musicMood`; cut to the beat via
+> `materializeGrid` when the bed drives pacing — OR an explicit intentional-silence decision
+> recorded in your delivery note with the reason. **K:** a render whose silence nobody chose.
+
+> **MUST** Every stock asset's provenance is recorded (provider, id, author).
+
+And from §1: *"**SHOULD** Cuts land on the music grid when a bed exists."*
+
+## Delivering
+
+The last message carries:
+
+- The new render link and where it lives (project + composition id).
+- The bed's attribution (provider, id, author, license) plus any SFX used.
+- The mix decisions in one line each: role, ducking, any authored level, which cuts moved onto
+  the beat.
+- OR the intentional-silence note with its reason, if no-bed was the right call.

package/skills/brand-reel/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: brand-reel
+description: Produces a 12–20 second 9:16 brand-identity reel — three-beat arc, bespoke cards in the brand's own type and palette, footage graded into the palette. Triggers on "brand video", "identity reel", "make our brand a video", "turn our brand into a reel", "a video that feels like us", "showcase our brand", "anthem video for our launch".
+---
+
+# Brand reel
+
+You bring a brand (a website, a kit, or just a logo and a palette) plus footage of its world;
+you get back a 12–20 second vertical reel with a three-beat arc — wordmark moment, craft/proof
+beat, tagline lockup — where every graphic could belong to this brand and no other.
+
+## Before you start
+
+Talk brand first — palette, type, the one line they'd put on a poster — before any setup. When
+the first tool call approaches and CueFrame isn't connected:
+
+- **Claude Code:** offer to run
+  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` (browser OAuth, one
+  **Allow** click).
+- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector pointing at
+  `https://api.cueframe.ai/v1/mcp`.
+- **Other agents:** paste `set up https://cueframe.ai/skill.md`, or run
+  `npx -y cueframe install`.
+
+Then pick the brand conversation back up where it paused — connection is the smallest step in
+this job.
+
+## Inputs
+
+- **The brand** (required): a brand kit on the project, a website to `extract_brand_kit` from,
+  or explicit colors + fonts + wordmark. Extraction gets colors/fonts only — ask for the tagline
+  and voice.
+- **Footage of the brand's world** (required): product, workshop, hands, city — the craft beat
+  needs a real subject. Ask before defaulting to stock.
+- **Tone**: default premium-calm unless the brand's voice says otherwise.
+
+## Workflow
+
+
+0. **Find the claim (before anything else).** Interrogate the brand/material
+   for its tension — what it believes that its category doesn't — and write
+   the claim in one sentence. Derive the shot list, the bed's mood/tempo, the
+   pacing, and every card's copy FROM that sentence. If you cannot state the
+   claim, you are not ready to compose (video-craft-standards: the
+   controlling idea is kill-level).
+
+1. **Pin the brand as engine state.** `extract_brand_kit` from their site or `create_brand_kit`
+   from what they gave you; set `brandKitId` on the project. Show the kit and let them override
+   — it is the contract every graphic resolves against. Kit contents aren't inspectable over MCP
+   afterward, so verify resolved colors/fonts with a `preview_frame` still, not by re-reading
+   the kit.
+2. **Import the world.** `import_media` their footage; `get_media_context` for what's actually
+   in it. Choose footage that lives in the palette — or plan a `color-grade` toward it. Footage
+   color and brand palette must agree.
+3. **Plan the three beats.** Opening brand moment (a wordmark treatment, not a logo dump) →
+   middle craft/proof beat (the subject's world plus one editorial device: a numbered chapter, a
+   pull-quote, a stat with a source) → closing tagline lockup. Write one line of intent per beat
+   before authoring.
+4. **Seed and author.** `new_composition` at 9:16 → `apply_composition` with the footage beats
+   and `setCropIntents` segments tiling each clip (subject-focused, motivated zooms).
+5. **Author every graphic as a bespoke card.** `kind:"card"` HTML using the brand's type and its
+   palette as FIELDS — plates, bands, blocks of the brand color, not tinted defaults. Persist
+   the card, then shell it with `applyMotionPreset` in a FOLLOWING `apply_composition` call. The
+   test: if another brand's hex swapped in would still look correct, the layout isn't bespoke
+   enough — redo it.
+6. **Decide the audio — required.** `search_resources` for a bed honoring the kit's
+   `musicMood`; place it `audioRole:"music"`, then `materializeGrid { grid:"beat" }` and land
+   the three beat boundaries on the grid. A brand reel almost always wants a bed; if the brand's
+   voice truly calls for silence, record that decision and the reason in the delivery note.
+7. **Preview each beat, then get judged.** `preview_frame` at t=0, each beat boundary, and the
+   final lockup; describe each still before scoring. `score_composition` with the brand facts as
+   `brandContext` and your arc as `editorialIntent`; fix the worst axis first, ship at ≥ 7.5.
+8. **One final render.** `create_render` → `wait_job (kind:"render")`.
+
+## What good looks like
+
+Quoted from `video-craft-standards` §3 (Brand-identity reel) — read the full section; §1's
+social-reel rules apply underneath it:
+
+> **MUST** Three-beat arc: opening brand moment (wordmark treatment) → middle craft/proof beat
+> (the subject's world, with an editorial device — numbered chapter, pull-quote, stat) → closing
+> tagline lockup.
+
+> **MUST** Every graphic is bespoke to the brand: its type, its palette as fields, its layout
+> system. **K:** any layout that would look correct with another brand's hex swapped in.
+
+> **MUST** Footage color and brand palette agree — grade toward the palette or choose footage
+> that lives in it.
+
+And the cross-cutting card rule:
+
+> **MUST** Brand/text graphics are AUTHORED — `kind:"card"` HTML […] **K:** a brand graphic
+> rendered from a catalog text primitive.
+
+## Delivering
+
+The last message is the handoff, never "done":
+
+- The render link and where it lives (project + composition id), plus the kit id the reel is
+  bound to — edit the kit later and a re-render re-themes the whole piece.
+- Attribution for any licensed asset (provider, id, author).
+- The intentional-silence note with its reason, if silence won over a bed.
+- Which beat is weakest in your own judgment — the honest starting point for round two.

package/skills/clip-a-talking-head/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: clip-a-talking-head
+description: Cuts a podcast, talk, or interview into shorts that open on the strongest sentence, reframe to the active speaker, and carry transcript-timed captions. Triggers on "clip this podcast", "pull the best moments out of this talk", "make shorts from this interview", "cut this down for social", "find the viral moment", "turn this recording into clips", "the good part is buried".
+---
+
+# Clip a talking head
+
+You point at long-form footage of people talking; you get back one or more 15–60 second clips
+that each open on the strongest sentence, keep a moving camera on whoever is speaking, cut the
+dead air, and caption every word from the real transcript.
+
+## Before you start
+
+Get the source URL and what "best moment" means to the user before any setup ceremony. When the
+first tool call is close and CueFrame isn't connected:
+
+- **Claude Code:** offer to run
+  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — browser opens,
+  user clicks **Allow**.
+- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
+  `https://api.cueframe.ai/v1/mcp`.
+- **Other agents:** paste `set up https://cueframe.ai/skill.md`, or run
+  `npx -y cueframe install`.
+
+Then straight back to hunting the moment — setup is a footnote, not a phase.
+
+## Inputs
+
+- **The recording** (required): a public https URL or existing media. Any length; the
+  transcript does the finding.
+- **Aspect + count**: default 9:16, 2–3 clips of 20–40s. 16:9 or 1:1 on request.
+- **Brand kit**: use the project's kit for caption styling and any title cards if present;
+  neutral otherwise.
+- **What counts as "best"**: default = the most surprising, quotable claims. Ask only if they
+  hinted at a specific topic.
+
+## Workflow
+
+1. **Import and read.** `import_media` the recording, wait for ready, then `get_media_context`
+   — the transcript with word timings and the face roster (with `faceId`s and speaking share)
+   are your whole map. For an assisted hunt, `suggest_briefs` proposes clip candidates from the
+   transcript; you still own the pick.
+2. **Find the strongest sentence — it goes FIRST.** Read the transcript for the claim that
+   makes someone stop scrolling. The clip opens ON that sentence, mid-conversation if needed.
+   Never open on wind-up ("so, um, one thing I'd say is…") — cut TO the moment.
+3. **Seed the clip.** `new_composition` at the target aspect → `apply_composition` with the
+   clip trimmed so the hook sentence starts at t≈0. Order beats strongest-first; the payoff is
+   the open, the context earns its place after.
+4. **Cut the dead air.** `addExcludedRange` / `cutAndRipple` on false starts, filler, long
+   pauses — the transcript's word timings show you exactly where speech stops. A tight talking
+   clip is mostly this step.
+5. **Reframe to the speaker.** `setCropIntents` with segments tiling the clip:
+   `focus:{mode:"active-speaker"}` as the base, `all-faces` to hold a two-shot, a `face` +
+   `shotScale:"close"` punch-in on the emphasis line. A static center crop is the amateur tell;
+   the camera should move because the conversation moved.
+6. **Captions from the real transcript.** `captions.fromTranscript` with the mediaId and the
+   clip's window; style via `setCaptionStyle` — plated, high-contrast, never over the mouth or
+   eyes. Where the footage allows, put the emphasized keyword BEHIND the speaker as an overlay
+   clip at `zPlane:"behind-subject"` (the caption layer itself carries no zPlane) — the
+   signature depth move.
+7. **Decide the audio — required.** Speech is the spine here, but decide the rest: a subtle bed
+   from `search_resources` honoring the brand kit's `musicMood`, ducked under the voice — or
+   intentional speech-only, recorded with its reason in the delivery note. Either is fine;
+   defaulted silence is not.
+8. **Preview, judge, render once per clip.** `preview_frame` at t=0 and each cut; describe each
+   still (is the framed person the one talking? is the top of the head in frame?).
+   `score_composition` with the clip's claim as `editorialIntent`; fix worst-first to ≥ 7.5,
+   then `create_render` → `wait_job (kind:"render")`.
+
+## What good looks like
+
+Quoted from `video-craft-standards` §4 (Talking-head clip) — the full checklist is the bar:
+
+> **MUST (K)** Hook = the strongest sentence, first. Cut TO the moment; never open on wind-up.
+
+> **MUST** Active-speaker reframe (`focus: active-speaker` / `face`) — a moving camera, not a
+> static center crop.
+
+> **MUST** Captions timed to the real transcript (`captions.fromTranscript`); behind-speaker
+> placement where the footage allows it. **MUST** Dead air and false starts cut
+> (`addExcludedRange` / `cutAndRipple`).
+
+Plus the cross-cutting audio rule: *"Audio is decided, never defaulted […] **K:** a render whose
+silence nobody chose."*
+
+## Delivering
+
+The last message carries, per clip:
+
+- The render link and where it lives (project + composition id), with the clip's opening
+  sentence quoted so the user can tell them apart.
+- The speech-only / bed decision and its reason (the intentional-silence note when applicable).
+- Attribution for any licensed bed (provider, id, author).
+- Which moments you considered and passed on — the shortlist makes the next batch a one-line
+  ask.