diff --git a/engineering/demo-video/skills/demo-video/SKILL.md b/engineering/demo-video/skills/demo-video/SKILL.md index 70abbd04a..09d3f3149 100644 --- a/engineering/demo-video/skills/demo-video/SKILL.md +++ b/engineering/demo-video/skills/demo-video/SKILL.md @@ -26,12 +26,14 @@ Before starting, verify available tools: - **playwright MCP available?** — needed for automated screenshots. Fallback: ask user to screenshot the HTML files manually. - **edge-tts available?** — needed for narration audio. Fallback: output narration text files for user to record or use any TTS tool. - **ffmpeg available?** — needed for compositing. Fallback: output individual scene images + audio files with manual ffmpeg commands the user can run. +- **Atlas Cloud configured?** — optional for generating conceptual B-roll when no real product visual exists. Never replace inspectable product screenshots with generated imagery. If none are available, produce HTML scene files + `scenes.json` manifest + narration scripts. The user can composite manually or use any video editor. | Mode | How | When | |------|-----|------| | **MCP Orchestration** | HTML → playwright screenshots → edge-tts audio → ffmpeg composite | Use when playwright + edge-tts + ffmpeg MCPs are all connected | +| **AI-assisted B-roll** | Product screenshots + optional Atlas Cloud scene images → ffmpeg composite | Use only for abstract transitions or concepts that cannot be captured from the real product | | **Manual** | Write HTML scene files, provide ffmpeg commands for user to run | Use when MCPs are not available | ### 2. Pick a story structure @@ -52,6 +54,12 @@ Hook (2s) -> Demo (8s) -> Logo (3s) -> Tagline (2s) - For conceptual demos: use text-heavy scenes with the color language and typography system - Ask the user for screenshots only if the product is visual and descriptions are insufficient +When a conceptual scene genuinely benefits from generated imagery and Atlas Cloud is configured, +follow the [Atlas Cloud scene generation](references/scene-design-system.md#atlas-cloud-scene-generation) +reference. +Atlas is an opt-in source: keep the screenshot/HTML workflow as the default, submit each scene +once, and fall back to HTML rather than retrying a failed paid generation. + Every scene has exactly ONE primary focus: - Title scenes: product name - Problem scenes: the pain (red, chaotic) @@ -77,6 +85,8 @@ For each video, produce these files in a `demo-output/` directory: - `playwright screenshot` each HTML scene → `frames/` - `edge-tts` each narration file → `audio/` - `ffmpeg` concat with crossfade transitions → `output.mp4` +5. `generated-assets.json` — only when AI B-roll is used; record prompt, model, prediction ID, + output path, and scene number so generated media remains auditable If MCPs are unavailable, still produce items 1-3. Include the ffmpeg commands in `build.sh` for the user to run manually. @@ -102,6 +112,7 @@ See [references/scene-design-system.md](references/scene-design-system.md) for t | **Generic narration** — "This feature lets you..." | Use specific numbers and concrete verbs | | **No story arc** — just listing features | Use problem -> solution -> proof structure | | **Raw screenshots** | Always add rounded corners, shadows, dark background | +| **Generated fake product UI** | Use real screenshots for product states; reserve AI imagery for conceptual B-roll | | **Using `ease` or `linear` animations** | Use spring curve: `cubic-bezier(0.16, 1, 0.3, 1)` | ## Cross-References diff --git a/engineering/demo-video/skills/demo-video/references/scene-design-system.md b/engineering/demo-video/skills/demo-video/references/scene-design-system.md index d3fcce113..b03598d41 100644 --- a/engineering/demo-video/skills/demo-video/references/scene-design-system.md +++ b/engineering/demo-video/skills/demo-video/references/scene-design-system.md @@ -59,3 +59,67 @@ Background: dark with subtle purple-blue glow gradients. Screenshots: always `bo | 3-4s | 8-12 | ~70% | | 5-6s | 15-22 | ~75% | | 7-8s | 22-30 | ~80% | + +## Atlas Cloud Scene Generation + +Use this optional path only for conceptual B-roll that cannot be captured from the real +product. Product UI, results, dashboards, and workflows must use real screenshots. + +### Preconditions + +1. Confirm `ATLASCLOUD_API_KEY` is set without printing it. +2. Read the live model catalog at `https://api.atlascloud.ai/api/v1/models`. +3. Confirm the selected model is an enabled text-to-image model and read its live schema. +4. Keep the demo-video screenshot and HTML pipeline as the default. + +`google/nano-banana-2-lite/text-to-image-developer` is a suitable low-latency example +when it is present in the live catalog. Its current text-to-image schema accepts a prompt +and supports a `16:9` aspect ratio. + +### Submit Once + +Create one request per approved conceptual scene: + +```bash +curl --fail-with-body https://api.atlascloud.ai/api/v1/model/generateImage \ + -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ + -H "Content-Type: application/json" \ + -H "User-Agent: demo-video-skill/1.0" \ + -d '{ + "model": "google/nano-banana-2-lite/text-to-image-developer", + "prompt": "", + "aspect_ratio": "16:9", + "resolution": "1k" + }' +``` + +Do not automatically retry this POST. Save the returned prediction ID immediately. If the +request fails, use the HTML scene fallback instead of spending on another generation. + +### Poll and Save + +Poll only the returned prediction with bounded backoff: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ + -H "User-Agent: demo-video-skill/1.0" \ + "https://api.atlascloud.ai/api/v1/model/prediction/" +``` + +Stop on `completed` or `failed`, and stop after the agreed timeout. Download the first +completed output into `demo-output/scenes/` and inspect it before compositing. Reject any +asset that resembles fabricated product UI, contains broken text, or conflicts with the +real product branding. + +Record each generated asset in `demo-output/generated-assets.json`: + +```json +{ + "scene": 3, + "model": "google/nano-banana-2-lite/text-to-image-developer", + "prediction_id": "", + "prompt": "", + "output": "scenes/scene-03-broll.png" +} +```