Lego Music Video

# Lego Music Video

A brand ad in a Lego music-video world—not the audio-only Brand Jingle Repo.

The downloadable kit contains the official runtime, contracts and two recovered David's Cookies examples. Your coding agent handles research and storytelling. Optional music and image/video providers supply only approved media.

Read **SKILL.md** for the one operating workflow. From the archive root, read **KIT-MANIFEST.json** for the exact version and inventory; all commands run in **v3**.

Local inputs and completed media are under `public/format-repositories/lego-music-video-v1/agent-runs/<run>`. The two goldens include their source media, new local exports, checks and provenance. Both passed technical checks. Their direct audiovisual creative review is **unreviewed**, not passed.

No new paid generations were used to build or test this package. Current optional providers have request-contract tests, not a fresh paid end-to-end certification. Node/npm and a Chrome download need network access during setup; supplied-media rendering needs no generation service.

---
name: lego-music-video
description: Create an evidence-backed brand ad as a three-shot Lego music video with the packaged runtime.
---

# Lego Music Video

Use this standalone Repo, not the audio-only Brand Jingle workflow. It adds a coherent miniature world, a recurring hero object, three cinematic moving scenes, lyric captions and a final vertical MP4. Lego naming is authorized by the operator; never invent an endorsement or reuse unrelated brand assets without permission.

## First actions

Require terminal, filesystem and local media access. If the chat cannot run this package, stop and ask the user to open it in a coding agent. Read KIT-MANIFEST.json at the archive root and report the version. Never rebuild the renderer, use a fallback compositor, or use the parent Wiggly app, database, private checkout or NIM.

All commands run from the archive's v3 directory:

```sh
npm install
npm test
npm run format:lego -- check
npm run smoke
```

Smoke imports the packaged cookie-tin source as a **fixture**, renders the official pipeline, and inspects the output. It sets LEGO_DISABLE_PAID_CALLS=1 and cannot be finalized as creative proof. An installed Chrome can be selected with LEGO_BROWSER_EXECUTABLE. If browser download or execution is denied, report that setup issue and obtain permission; do not spend money or rebuild the renderer. Fix observed setup failures before real work.

## Workflow

1. Ask one short question at a time. Start: “What brand or website is this music video for?” Establish the buyer truth, music direction, authorized assets and any existing song or Lego footage. Research with your own tools and save source-grounded claims. No separate LLM provider is required.
2. Run `npm run format:lego -- init --run=my-ad --brief='the brief'`. Fill the unresolved input.json from the user's evidence, not from smoke content. Read inputs.json and scene-contract.json. Use the goldens to understand structure, never as default customer content.
3. Complete scene.brand, creative, style and layout. Write exactly three compositionPlan.chunks with full lyrics, positive_styles, negative_styles and duration_ms totaling 10–30 seconds. Repeat the brand naturally in the hook. Keep the desired music direction explicit; do not imitate a named artist. Set layout.lyrics to all sung lines and layout.brandPhonetic to the spoken brand.
4. Run `npm run format:lego -- prompt --run=my-ad`. As the host agent, author the returned story schema into input.story: one recurring hero object, three distinct lyric-led events, camera/action continuity and a physical payoff. Follow the packaged allowed scene mechanisms. This is a narrative Lego music video, not a slideshow or a static product packshot.
5. Run `npm run format:lego -- validate --run=my-ad`. Present the lyrics/story and the current costs for any missing media. Reuse supplied media where possible. Do not call paid providers without explicit approval of the exact stages, one-attempt quantities and total budget.
6. Generate or import the song first. The runtime measures its actual duration; it scales the three planned sections to that total. Review the real song and revise timing if necessary. Captions are phrase/section-derived, not word-aligned; never claim timing is perfect without hearing it.
7. Generate/import the world reference, then three separate full-quality production stills. Inspect each for product identity, world consistency, clean composition and action potential. Never animate crops from a storyboard/contact sheet. Record a meaningful review of the exact input before generating a still or clip.
8. Generate/import three silent animated shots, one per section. Clip lengths are selected from measured song timing; the renderer permits only recorded modest retiming, never a frozen tail to hide missing footage. Keep jobs and outputs when something fails; collect the same prediction ID instead of starting over.
9. Run `npm run format:lego -- render --run=my-ad` then `npm run format:lego -- inspect --run=my-ad`. FFmpeg prepares clips; the one official AdRenderSurface/Remotion renderer makes the complete 1080 × 1920 MP4. Inspect that file, not only its source assets.
10. Directly watch the complete moving video and hear the audio. If either channel is unavailable, mark the review inconclusive and request a qualified reviewer. Never score hearing from captions, waveforms or unmuted controls. Fix only observed problems within the three-attempt ceiling.
11. When all checks and genuine creative review pass, write review.json using the exact rendered SHA256: `{"renderSha256":"…","videoPerception":"direct","audioPerception":"direct","verdict":"pass","notes":"Specific observations from this full audiovisual review."}`. Run `npm run format:lego -- finalize --run=my-ad --review=/absolute/path/review.json`. Never fabricate a review to pass the gate.
12. Return the playable MP4 with its contact sheet, input, source provenance, quality report, version and final review receipt. If review is pending, return a clearly labeled draft, not a finalized creative proof.

## Import existing media (free)

Prepare a portable input.json alongside local media using the golden schema. Null means a missing stage, not permission to generate it. Every media path must stay inside that input directory; include an authorized logo locally if needed.

```sh
npm run format:lego -- import --run=my-ad --input=/absolute/path/input.json
npm run format:lego -- validate --run=my-ad
npm run format:lego -- render --run=my-ad
npm run format:lego -- inspect --run=my-ad
```

Import copies sources and measures the song. Historical Jingle scene data is accepted only as an import adapter and becomes Lego Music Video. Do not copy old render state, fixture selections or final receipts into a real run. Preserve your sources and existing attempts.

## Paid commands and recovery

Optional key names are ELEVENLABS_API_KEY and REPLICATE_API_TOKEN. Use environment variables or ignored archive-root secrets.env; do not open .env.local, paste secrets in chat or write keys into the kit. Set LEGO_DISABLE_PAID_CALLS=1 whenever paid calls are prohibited.

Stages: song, reference, shot-1, shot-2, shot-3, clip-1, clip-2, clip-3.

`npm run format:lego -- request --run=my-ad --stage=clip-1` prints the exact route and request hash **without calling it**. Check the current provider quote for that model and settings. A fresh full run uses at most one song, four images and three videos before any reviewed retry. Quotes and wait times vary; never promise $0 for newly generated media.

After actual user approval, use `generate --run=my-ad --stage=… --approve-cost-usd=<quoted-call-cost> --budget-usd=<approved-total>` through npm run format:lego. For shot/clip stages include `--image-review='specific observations about this exact reference or production still'`. These flags record approved estimates, not a guarantee of final provider billing. Do not invent approval or silently switch models.

Use `collect --run=my-ad --stage=clip-1` to check a saved Replicate job. It never starts another prediction. Music submission is synchronous; an uncertain response requires operator recovery, not an automatic retry. `status --run=my-ad` shows attempts and jobs. Three paid submissions per slot and three renders per run are the hard limits; do not reset counters or rename runs to bypass them.

## Evidence limits

The goldens are two distinct existing David's Cookies songs and Lego stories. Their final MP4s are new local exports of recovered media, not newly generated footage and not recovered historical final exports. Technical checks passed; direct audiovisual review remains unreviewed. Historical imagery used google/nano-banana-2; historical video model is unknown. Current defaults in requirements.json are not retroactive provenance and were not freshly paid-tested.

Preserve the official renderer, local fonts, preparation logic, approval gates, attempt ledger and asset hashes. Replace content through input.json and local media only.

## Multi-Platform Social Distribution (Optional)

When a Lego music video is rendered and approved, the agent can distribute it across YouTube Shorts, Instagram Reels, TikTok, and X via the packaged `runtime/publish.mjs` CLI or connected Buffer MCP tools:

1. **Author platform-tailored copy in `inputs/distribution.json`:**
   - **YouTube Shorts:** Punchy music video title (≤100 chars), categoryId (`10` for Music or `24` for Entertainment), duration ≤60s.
   - **Twitter/X:** Engaging hook (≤280 chars total).
   - **Instagram Reels:** Engaging caption with tags, strictly vertical (9:16).
   - **TikTok:** Engaging caption with trending tags (≤2200 chars).
2. **Dry-run validation:**
   ```sh
   node runtime/publish.mjs --dry-run inputs/distribution.json goldens/cookies/final.mp4
   ```
3. **Live dispatch requires explicit human sign-off:**
   - Confirm target channels and copy with the user (`approvalRequired: true`).
   - Execute with connected Buffer MCP tools or `node runtime/publish.mjs inputs/distribution.json outputs/final.mp4`.
   - Generates a verified distribution receipt (`<video>.distribution.json`) with zero secret leakage.

{
  "runtime": {
    "node": ">=22",
    "binaries": [
      "ffmpeg",
      "ffprobe",
      "Chrome (installed or Remotion-managed)"
    ]
  },
  "providers": [
    {
      "name": "ElevenLabs",
      "environmentVariable": "ELEVENLABS_API_KEY",
      "model": "music_v2",
      "purpose": "Optional: one new song, only after explicit approval. A supplied song needs no provider."
    },
    {
      "name": "Replicate",
      "environmentVariable": "REPLICATE_API_TOKEN",
      "models": [
        "google/nano-banana-2-lite",
        "bytedance/seedance-2.0-mini"
      ],
      "purpose": "Optional: one world reference, three full-quality stills and three silent animated clips, only after approval. Supplied media needs no provider."
    },
    {
      "name": "Social Publisher (Buffer MCP or API)",
      "purpose": "Simultaneous multi-platform publishing to YouTube Shorts, Instagram Reels, TikTok, and X.",
      "optional": true,
      "environmentVariables": ["BUFFER_API_KEY"],
      "pricingSource": "https://buffer.com/pricing"
    }
  ],
  "notes": [
    "Your coding agent handles research, lyrics and storytelling; no separate LLM key, NVIDIA NIM, Wiggly login or database is required.",
    "Free smoke and supplied-media runs make zero paid calls. New music and visuals use your provider accounts; get current quotes before approving a batch.",
    "Current provider defaults are inherited from the existing workflow; no new paid end-to-end generation was performed for this package. Historical examples used older media, with provenance included.",
    "Set LEGO_BROWSER_EXECUTABLE to an installed Chrome if automatic browser download is unavailable. Browser execution requires permission in sandboxed coding agents.",
    "Set LEGO_DISABLE_PAID_CALLS=1 to prohibit generation. Never paste keys in chat. Environment variables or an ignored root secrets.env are the only credential sources."
  ]
}

{
  "version": 1,
  "required": [
    "Brand URL or source-grounded brief",
    "One ad angle and approved lyrics in three song sections",
    "One recurring hero object and three distinct lyric-led Lego events"
  ],
  "optional": [
    "Existing 10–30 second song",
    "Existing world reference, three separate full-quality stills and three moving clips",
    "Authorized brand logo"
  ],
  "file": "agent-runs/<run>/input.json",
  "template": "npm run format:lego -- init --run=my-ad --brief='Your brief'",
  "contract": "scene-contract.json",
  "media": "All media must be local relative files inside the input directory. No remote URLs, parent traversal, or external symlinks. Import copies and measures them."
}

{
  "stages": [
    {
      "id": "check-and-smoke",
      "output": "Install the kit and render the included fixture locally. No provider calls."
    },
    {
      "id": "research-and-song-plan",
      "output": "Your coding agent grounds one buyer truth, writes a hook and three song sections, and proposes the Lego story."
    },
    {
      "id": "approve-song",
      "approvalRequired": true,
      "output": "Approve lyrics, music direction and current per-call quote, or supply an existing song."
    },
    {
      "id": "music",
      "paid": true,
      "output": "Generate one song or import existing audio; measure actual duration and align all three sections."
    },
    {
      "id": "world-reference",
      "paid": true,
      "approvalRequired": true,
      "output": "Create or import one coherent Lego world reference; inspect it before production stills."
    },
    {
      "id": "production-stills",
      "paid": true,
      "approvalRequired": true,
      "output": "Create or import three separate full-quality shots; inspect each exact still before animation."
    },
    {
      "id": "animated-shots",
      "paid": true,
      "approvalRequired": true,
      "output": "Create or import three silent moving shots; save and resume original prediction IDs."
    },
    {
      "id": "render-and-inspect",
      "output": "Prepare the clips with FFmpeg and render through the shared AdRenderSurface/Remotion path. Decode and inspect the final MP4."
    },
    {
      "id": "direct-review-and-finalize",
      "approvalRequired": true,
      "output": "Watch the motion and hear the song; finalize only after an honest review of this exact render passes."
    },
    {
      "id": "distribute",
      "approvalRequired": true,
      "output": "Simultaneous multi-platform publishing receipt (YouTube Shorts, Instagram Reels, TikTok, X) with zero secret leakage."
    }
  ]
}

{
  "fixed": [
    {
      "path": "goldens/cheesecake/media/reference.jpg",
      "label": "Cheesecake world reference",
      "purpose": "Recovered example of one coherent Lego world. Replace it for your brand."
    },
    {
      "path": "goldens/cookies/media/shot-1.jpg",
      "label": "Full-quality production still",
      "purpose": "A separate source image for animation, never an enlarged storyboard panel."
    },
    {
      "path": "goldens/cookies/contact-sheet.jpg",
      "label": "Composed-output contact sheet",
      "purpose": "Technical inspection evidence; not a substitute for watching and hearing the final video."
    }
  ],
  "sourceReference": {
    "verification": "Recovered from existing Wiggly media and matching Downloads. New local exports reuse the original footage and songs; no paid generation was performed.",
    "referenceNote": "Lego naming is authorized by the operator. These are brand ads in a Lego visual style, not a claim of an official Lego partnership. Source usage and hashes accompany each example."
  }
}

{
  "automatic": [
    "Input, asset and output hashes are current",
    "1080 × 1920 H.264 video with audio",
    "Output duration matches measured song within 100ms",
    "Entire output decodes",
    "Audio is not entirely silent",
    "No full-frame freeze lasting 2.5 seconds",
    "Three source clips span the actual song without hidden hold padding"
  ],
  "creative": [
    "Directly see the full moving video and hear its audio; screenshots, captions and player controls do not count",
    "Brand identity and buyer truth are accurate; no invented Lego endorsement",
    "One coherent Lego world and hero motif, with three distinct readable events",
    "Lyrics are audible and captions readable without hiding the product",
    "Technical success is not creative approval; missing perception means unreviewed"
  ],
  "limits": [
    "Three render attempts per run and three paid submissions per slot",
    "Failed or uncertain provider submissions never silently restart",
    "Smoke fixtures cannot generate or finalize as real creative work",
    "The two packaged examples passed technical checks; direct audiovisual creative review remains pending"
  ]
}

{
  "purpose": "Two distinct songs, hero objects and stories through the same standalone runtime. Both advertise David's Cookies; this does not certify cross-brand creative generalization or current provider execution.",
  "canonicalContactSheet": "goldens/cookies/contact-sheet.jpg",
  "examples": [
    {
      "id": "cheesecake",
      "title": "Cheesecake surprise",
      "role": "Existing song and footage; new local export",
      "whyItWorks": [
        "A red cheesecake dome connects the refrigerator reveal, storefront delivery and birthday payoff.",
        "All eight technical checks passed."
      ],
      "knownWeaknesses": [
        "Direct audiovisual creative review is pending.",
        "Section-derived captions are not word-aligned.",
        "Historical video model was not recorded."
      ]
    },
    {
      "id": "cookies",
      "title": "Fresh-baked cookie tin",
      "role": "Second existing input through the same runtime",
      "whyItWorks": [
        "A red cookie tin connects a bakery launch, a collapsing stale aisle and a fresh delivery.",
        "All eight technical checks passed."
      ],
      "knownWeaknesses": [
        "Direct audiovisual creative review is pending.",
        "Same brand as the first example; not a cross-brand proof.",
        "Current provider defaults were not exercised with paid generation."
      ]
    }
  ]
}

{
  "id": "lego-music-video",
  "version": "0.1.0",
  "title": "Lego Music Video",
  "description": "A brand ad performed as a three-scene Lego music video: original song, one miniature world, cinematic moving shots and lyric captions.",
  "status": "local-runtime-proven",
  "defaultDurationSeconds": 20,
  "output": [
    "mp4",
    "contact-sheet",
    "quality-report",
    "provenance"
  ],
  "proof": {
    "paidGenerationsDuringPackaging": 0,
    "technical": "passed",
    "creative": "unreviewed",
    "historicalMedia": true
  }
}

{
  "name": "wiggly-lego-music-video-format-kit",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22"
  },
  "scripts": {
    "format:lego": "node --import tsx scripts/lego-music-video-format.ts",
    "smoke": "node --import tsx scripts/lego-music-video-format.ts smoke",
    "test": "node --import tsx tests/lego-music-video-contract.test.ts && node --import tsx tests/lego-music-video-runtime.test.ts"
  },
  "overrides": {
    "ws": "8.21.0",
    "@remotion/bundler": { "esbuild": "0.28.1" }
  },
  "dependencies": {
    "@remotion/bundler": "4.0.473",
    "@remotion/media": "4.0.473",
    "@remotion/renderer": "4.0.473",
    "jpeg-js": "0.4.4",
    "lucide-react": "0.546.0",
    "react": "19.0.1",
    "react-dom": "19.0.1",
    "remotion": "4.0.473",
    "tailwindcss": "4.2.4",
    "tsx": "4.20.6"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

{
  "version": 1,
  "format": "lego-music-video",
  "scene": "Complete LegoMusicVideoAdScene; see features/formats/lego-music-video/contract.ts for executable validation.",
  "song": {
    "actualDurationMs": [
      10000,
      30500
    ],
    "sections": 3,
    "maximumSectionMs": 15000,
    "lyrics": "Every complete sung line; chunk.text may include [Hook] or [Verse].",
    "captions": "Section-derived phrase display, not word alignment; directly review timing against the song."
  },
  "story": {
    "recurringHeroObject": "One specific object, present in all three scenes.",
    "shots": "Exactly three numbered shotIndex slots, each with the slot's lyricLine, funMechanism, sceneDescription and motionHint; npm run format:lego -- prompt prints the full schema and scene grammar."
  },
  "media": {
    "song": "relative path or null",
    "reference": "relative path or null",
    "shots": [
      {
        "image": "Full-quality production still, not a storyboard crop",
        "video": "Silent animated shot matching measured section duration"
      }
    ]
  },
  "render": {
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "codec": "h264",
    "audio": "AAC mixed from the supplied/generated song",
    "duration": "Measured song rounded up to the next frame; no added tail",
    "retiming": "Source/target duration ratio must be 0.75–1.35, recorded explicitly; no freeze padding."
  }
}