flatrender/services/remotion/docs/TEMPLATE_BRIEF.md

FlatRender — Template Brief & Creator Flow

The single, repeatable entry point for creating a template. A guided Q&A captures requirements into a structured Template Spec; the Spec drives the build pipeline (see flat-artist skill + ASSET_LIBRARY.md). The Spec is the stable contract — today a human fills it via Q&A and the Flat Artist hand-builds; later an AI prompt or an end-user form can emit the same Spec into the same pipeline (internal-first, extensible).

Engine model (confirmed): a template is a scene list. Each scene is a reusable, typed scene block with its own content + editable duration (within a min/max range). A template ships in one of two structure modes:

• fixed — a static set/order of scenes (user edits content + duration, can't add/remove/reorder).
• flexible — user can add / duplicate / delete / reorder scenes and add as many as needed; empty scenes auto-skip. Every template renders in all three aspects (16:9 / 1:1 / 9:16), re-flowed not letterboxed, Persian-first.

---

The guided Q&A (5 rounds)

Each round ≈ one AskUserQuestion call (≤4 questions), mostly multiple-choice with a "recommended default" so it's fast. Run them in order.

Round 1 — Purpose & format

• Type / use-case — explainer/story · promo/sale · logo reveal · social/channel intro · greeting/seasonal · product/app showcase · quote · event invite · slideshow · countdown · testimonial · (any Renderforest-style type).
• Aspect priority — all three equally (default) · 9:16-first · 16:9-first.
• Structure mode — flexible (add/duplicate/delete/reorder) · fixed (static order).
• Scene count & per-scene duration — default scene count + the editable duration range per scene (e.g. default 3s, min 1s, max 6s).

Round 2 — Art direction

• Visual style — refined flat 2.5D (Remotion+Three) · 3D cinematic · minimal-luxury · kinetic typography.
• Palette & mood — sophisticated muted · dark premium + glow · warm editorial · vibrant · brand blue/violet · custom hex.
• Characters — CC0 Open-Peeps busts (vendored) · none · abstract · Humaaans full-body (needs manual fetch).
• Environment/setting — room/office · outdoor · abstract/studio · per-scene varied.

Round 3 — Content

• Per-scene structure — story beats · single hero message · feature list · before/after.
• Copy — provide now · Persian placeholders to refine.
• Brand assets — logo upload field? · image/screen upload field? · none.
• Hook — what happens in the first 1–2s (the scroll-stopper).

Round 4 — Motion / audio / finishing

• Motion intensity & pacing — calm · energetic · cinematic.
• Audio — music + SFX (beat-synced?) · silent.
• Finishing — grain · vignette · glow defaults (on/off).
• Reference — any link/inspiration to match.

Round 5 — Editability & taxonomy

• Editable fields — which text keys, colors, images, and whether scene-count is user-editable.
• Taxonomy — category · tags · slug.
• Naming — fa + en name/description.
• Tier — free · premium.

---

The reference round — lock the look (runs with Round 2)

Before any building, lock the art direction against real visuals. Two modes, used together:

• You provide — I ask: "Got references for this? Paste them (+ one line of why)." I extract the DNA into references/TASTE_PROFILE.md, so the build inherits your taste, not my defaults.
• I suggest — for the chosen type I propose 2–4 named style directions AND mock each up as a cheap still / SVG (no external images needed), so you pick from real visuals — not words. I can also web-search live examples / asset packs / current trends and link them for you to open and react to.

Output: a locked direction (style + palette + motifs + reference notes) written into the Spec's art block and appended to the taste board. Then the gate continues: build → cheap still → you approve → full render.

Honest constraints:

• I can web-search and link real references, but rendering arbitrary external images inline is unreliable from this environment — so the dependable "suggest" engine is me mocking the directions myself (as today's storyboards/characters were). Web search supplements, doesn't replace it.
• Footage: I suggest CC0 sources + search/link, but footage is vendored-CC0 (manual fetch) or the editable-backdrop architecture — we can't AI-generate it (no GPU). Flag this per brief.

---

Template Spec (the output)

The Q&A produces this structure, saved to services/remotion/briefs/<slug>.md:

{
  "id": "CharacterPromo",            // PascalCase comp id
  "slug": "fr-character-promo",
  "type": "promo",                    // Round 1
  "name_fa": "…", "name_en": "…",
  "desc_fa": "…", "desc_en": "…",
  "aspectPriority": "all",
  "structure": "flexible",            // "flexible" | "fixed"
  "scene": { "defaultCount": 4, "durationDefaultSec": 3, "durationMinSec": 1, "durationMaxSec": 6 },
  "art": { "style": "flat-2.5d", "palette": "muted", "characters": "openpeeps", "environment": "room" },
  "blocks": [                         // ordered scene blocks (defaults; flexible = user edits the list)
    { "type": "intro",   "role": "hook" },
    { "type": "feature", "role": "point" },
    { "type": "feature", "role": "point" },
    { "type": "cta",     "role": "outro" }
  ],
  "content": { /* per-block editable keys -> Persian default values */ },
  "colors": { "accentColor": "#…", "secondaryColor": "#…", "backgroundColor": "#…", "textColor": "#…" },
  "assets": { "characters": ["dicebear/openpeeps-04"], "logoUpload": false, "imageUpload": false },
  "motion": { "intensity": "energetic", "audio": "music+sfx" },
  "finishing": { "grain": true, "vignette": true, "glow": false },
  "editable": { "text": true, "colors": true, "images": false, "sceneCount": true },
  "taxonomy": { "category": "…", "tags": ["…"], "tier": "premium" }
}

This Spec maps directly onto the build pipeline: blocks → kit scene-block components; content/colors → Zod props (globally-unique keys) + the studio editable fields; scene.* → per-scene duration range + structure mode; seeded via scripts/seed_remotion_templates.py (content.scenes rows carry default_duration_sec and sort/order).