Brief to Scenes

An 8-stage, deterministic pipeline that reads a creative brief — intent, assets, key messages — and outputs validated scene JSON files without LLM calls.

Overview

The scene generator (generate_scenes) bridges the gap between brief authoring and the sizzle pipeline. You describe what you want — intent, assets, key messages — and the system translates it into scene compositions that feed directly into the sequence planner.

The core generation is rule-based and deterministic. No LLM calls are required. When enhance: true is passed with an ANTHROPIC_API_KEY, two optional LLM stages layer on top for scene plan text improvement and camera move suggestions — but all LLM output is validated and falls back to rule-based output on failure.

The creative brief

A brief answers three questions:

1. What are you making? — type, tone, duration
2. What do you have? — assets, text content
3. What matters most? — hero moments, key messages

Everything else — scene count, layout selection, camera moves, transitions — is the system's job.

Brief schema

{
  "brief_id": "string",
  "template": "product-launch | brand-story | tutorial | investor-pitch | photo-essay | custom",

  "project": {
    "title": "string",
    "description": "string (1-3 sentences)",
    "duration_target_s": "number (optional)",
    "style": "string (optional — style pack name)"
  },

  "tone": {
    "mood": "string (e.g., confident, warm, urgent)",
    "energy": "low | medium | high",
    "audience": "string (optional)"
  },

  "content": {
    "headline": "string (optional)",
    "sections": [
      {
        "label": "string (e.g., 'Hero', 'Features', 'CTA')",
        "text": "string",
        "emphasis": "normal | strong",
        "assets": ["asset_id references"]
      }
    ]
  },

  "assets": [
    {
      "id": "string",
      "path": "string (relative file path)",
      "type": "image | video | svg | text-file",
      "hint": "string (optional — what this asset shows)",
      "role": "hero | supporting | background | logo (optional)"
    }
  ],

  "constraints": {
    "must_include": ["asset IDs that must appear"],
    "scene_count": { "min": "number", "max": "number" },
    "brand_colors": ["hex values"],
    "font_family": "string"
  }
}

Section labels and intent mapping

The label on each content section guides how the system assigns intent tags:

Style inference

When no style is specified in the brief, the system resolves it in priority order:

1. Explicit — project.style field
2. Template default — each template has a default style
3. Tone inference — tone.energy maps to style families
4. Fallback — prestige

Brief templates

Five pre-built templates provide structure and recommended defaults. Use template: "custom" for freeform briefs.

Each template defines a section structure with suggested layouts, content types, and intent tags. Sections can be marked optional or allow repeat ranges — the generator expands or contracts sections based on available assets and constraints.

The 8-stage pipeline

Scene generation runs through 8 sequential stages. Each is a pure function.

Every generated scene passes through validateScene() before returning. Invalid output throws — there is no silent failure.

Asset classification

Assets are classified through a 3-tier priority system:

Filename conventions the classifier recognizes:

• hero-*, product-* — role: hero, type: product_shot
• team-*, headshot-*, portrait-* — type: portrait
• ui-*, screen-*, dashboard-* — type: ui_screenshot
• logo-*, brand-*, mark-* — type: brand_mark
• bg-*, background-* — role: background

Asset assignment (two-pass)

1. Explicit refs — honor content.sections[].assets[] references first
2. Affinity distribution — unassigned assets matched to scenes by content type, then role (hero to opening, logo to closing, background to heavy scenes)
3. Force must_include — remaining constraints.must_include assets forced into best-matching scene

Content type mapping

Each content type maps to a specific layout and layer structure:

Example brief

A minimal product launch brief:

{
  "brief_id": "brief_product_v1",
  "template": "product-launch",
  "project": {
    "title": "Acme Dashboard",
    "description": "30-second product launch sizzle for our new analytics dashboard. Show the UI, highlight key features, end with brand."
  },
  "tone": {
    "mood": "confident",
    "energy": "medium"
  },
  "content": {
    "headline": "Analytics, Reimagined",
    "sections": [
      {
        "label": "Hero",
        "text": "Introducing Acme Dashboard",
        "assets": ["product-hero"],
        "emphasis": "strong"
      },
      {
        "label": "Features",
        "text": "Real-time metrics. Custom reports. Team sharing.",
        "assets": ["ui-metrics", "ui-reports"]
      },
      {
        "label": "CTA",
        "text": "Start free today",
        "assets": ["logo"]
      }
    ]
  },
  "assets": [
    { "id": "product-hero", "path": "assets/hero-dashboard.png", "type": "image", "hint": "product UI hero shot" },
    { "id": "ui-metrics", "path": "assets/screen-metrics.png", "type": "image" },
    { "id": "ui-reports", "path": "assets/screen-reports.png", "type": "image" },
    { "id": "logo", "path": "assets/logo-acme.svg", "type": "svg", "hint": "company logo" }
  ]
}

This brief generates approximately 4-5 scenes: opening typography, hero product shot in a device-mockup layout, feature split-panels, and a closing brand mark.

Try it

Try asking your AI:

List the available brief templates and show me what the brand-story template looks like.

Generate scenes from this brief: I need a 30-second product launch video for a design tool called Canvas. I have a hero screenshot, two feature screenshots, and a logo.

I have 8 photos from a studio visit. Generate a photo-essay with soft transitions and minimal text.