# Marketing Studio — UGC, Ads & Branded Video

Load this file when the user wants **branded ad video** — UGC, unboxing, product showcase, TV spot, virtual try-on, or any "make me an ad / commercial / creator video" request.

For ad **images** (Pinterest pin, hero banner, ad creative pack) see `workflows/product-photoshoot.md`.
For **marketplace listings** (Amazon main + secondary + A+ content) see `workflows/marketplace-cards.md`.
For the **DTC ads engine flow** (brand kit + ad format + avatar + product) see `workflows/dtc-ads.md`.

## The 9 Marketing Modes

| Mode | What it's for | Hook/Setting allowed? |
|---|---|:-:|
| `ugc` | **Default.** Casual, organic-feel content from a presenter | ✅ |
| `ugc_how_to` | Tutorial / explainer — "here's how to use this" | ✅ |
| `ugc_unboxing` | Unboxing reveal — "just got this in the mail" | ✅ |
| `product_showcase` | Clean product highlight, polished | ❌ |
| `product_review` | Presenter giving an opinion on the product | ✅ |
| `tv_spot` | Broadcast-style commercial, higher production | ❌ |
| `wild_card` | Experimental — model picks the vibe | ❌ |
| `ugc_virtual_try_on` | Person trying on clothing / accessories — UGC vibe | ✅ |
| `virtual_try_on` | Same but polished, model-driven | ❌ |

**"Hook/Setting allowed"** = whether reusable opening hook prompts and scene-setting prompts can be prepended to the user prompt. Polished modes (`product_showcase`, `tv_spot`, `wild_card`, `virtual_try_on`) ignore hooks/settings.

**Default when the user doesn't specify a mode:** `ugc`.

## Picking the Mode

| User phrasing | Mode |
|---|---|
| "UGC", "creator video", "talking head", "phone-shot", "selfie video", "vlogger" | `ugc` |
| "tutorial", "how to use", "demonstrate", "walkthrough", "explainer" | `ugc_how_to` |
| "unboxing", "just got this", "reveal", "first impression" | `ugc_unboxing` |
| "product showcase", "highlight reel", "showroom" | `product_showcase` |
| "review", "my take on", "comparing X to Y", "honest opinion" | `product_review` |
| "TV ad", "commercial", "broadcast", "polished ad spot" | `tv_spot` |
| "surprise me", "something different", "experimental" | `wild_card` |
| "try on" / "wearing the X" + organic vibe | `ugc_virtual_try_on` |
| "fashion shoot", "lookbook", polished try-on | `virtual_try_on` |

If the user mentions a product / brand but no mode word, default to `ugc`. If they say "ad" without "TV ad" / "commercial" / "broadcast", default to `ugc` (most modern ads are UGC-shaped).

## Mode → Kolbo MCP Routing

The mode determines which Kolbo MCP tool to call, what defaults to set, and what's forbidden.

| Mode | Primary tool |
|---|---|
| `ugc`, `ugc_how_to`, `ugc_unboxing`, `ugc_virtual_try_on`, `product_review` | `generate_video_from_image` (frame-first) OR `generate_elements` (Visual DNA → video) |
| `product_showcase` | `generate_creative_director` with `workflow_type: "video"` (for multi-shot) OR `generate_video` (single) |
| `tv_spot` | `generate_creative_director` with `workflow_type: "video"` (3–6 shots for a beat structure) |
| `virtual_try_on` | `generate_elements` with character Visual DNA + product as `reference_images` |
| `wild_card` | User's chosen model with broader prompt latitude (no mode-specific defaults) |

Aspect / duration / sound / captions defaults for the `ugc*` family live in "UGC Family Defaults" below.

**Pick the actual model** with `list_models({ type: "..." })` and validate caps before firing — see `references/workflows/cost-and-validation.md`.

## The Look Itself — read `workflows/ugc-smartphone.md`

The modes and defaults below decide WHAT gets made. The physics that make it read as a
real phone capture — deep depth of field, computational HDR, named available light,
imperfect framing — live in `workflows/ugc-smartphone.md`. Read it before writing any
UGC prompt: **"smartphone" on its own does not produce a smartphone look**, and that file
is also where the still-image cases live (a user's product photo re-shot as a customer
snapshot, the to-camera vs observational subject dial).

## UGC Family Defaults (CRITICAL)

When ANY `ugc*` mode is selected, snap to these unless the user explicitly overrides:

| Setting | UGC default | Why |
|---|---|---|
| `aspect_ratio` | `9:16` | TikTok / Reels / Shorts are vertical-first |
| Visual aesthetic | Phone-shot, handheld, natural lighting | UGC works because it doesn't look produced |
| Camera language | Slight handheld sway, selfie-arm framing, key light from window/screen | NOT slow dollies, NOT crane moves, NOT studio key |
| Energy | "Talking to a friend" — casual, direct-to-camera, occasional gestures | Not theatrical, not staged |
| **Captions / subtitles / text overlays** | **NEVER add** unless explicitly requested | Users add captions in CapCut / native editor; baked-in captions limit reuse |
| **Brand watermarks / lower-thirds / banners** | **NEVER add** unless explicitly requested | Same reason |
| Music / SFX | OFF by default unless asked | They'll layer their own audio in post |
| Length | Model's `default_duration` (typically 5–8s) | Shorter = more usable for the algorithm |

**Phrases that activate UGC defaults:** "UGC", "user-generated", "creator video", "TikTok", "Reels", "Shorts", "POV", "selfie video", "phone-shot", "vlogger", "talking head" (when context implies social media), "for social", "Instagram video", "YouTube short".

**Phrases that OVERRIDE UGC defaults** (use them as-given, not as UGC): "commercial", "ad spot" (without UGC), "cinematic", "broadcast", "TV ad", "horizontal", "16:9", "landscape", "billboard". When the user uses one of these, switch to `product_showcase` or `tv_spot` mode.

## Hooks & Settings (concept)

Hooks and settings are **reusable opening angles / scene contexts** that get prepended to the user's prompt. Kolbo does not yet expose these as first-class MCP primitives, but the concept is portable:

- **Hook** = the opening line / angle of the ad (the first 1–2 seconds that earn the scroll). Example hooks: "POV: you just discovered X", "Why I stopped buying Y", "3 reasons this X is worth it", "Watch this before you buy a Y".
- **Setting** = the scene/environment context. Example settings: "in a bright minimalist kitchen", "walking in a busy city street", "on a yoga mat at golden hour".

**When the user asks for an ad and doesn't specify the opening**, offer 2–3 hook options (one-liner each) in a labeled-question style — never freeform "what hook?" Same for setting if the brief is location-agnostic.

**Whitelist rule:** hooks/settings only make sense for `ugc`, `ugc_how_to`, `ugc_unboxing`, `product_review`, `ugc_virtual_try_on`. For `product_showcase`, `tv_spot`, `wild_card`, `virtual_try_on` — skip hooks/settings; those modes are concept-driven not hook-driven.

**Mutually exclusive with ad references** (next section). Pick one path per generation.

## Ad References (modeling new ads after existing ones)

Sometimes the user has a reference ad they want to model the new ad after — their own previous winning ad, a competitor's ad, or a viral video. Kolbo path:

1. **Upload the reference video** via `upload_media` (returns CDN URL).
2. **Pass it as `reference_videos`** to `generate_elements`, OR as `source_video` to `generate_video_from_video` (if you want to actually restyle / re-shoot the reference).
3. **Describe in the prompt** what to preserve from the reference (`@video1`'s pacing / camera move / lighting / cut rhythm) and what to change (subject / product / setting).
4. **Tag with `@video1`** per `workflows/visual-dna.md` reference-tagging rules.

**Mutually exclusive with hooks/settings** — pick one composition path per generation. Either reference-driven (use `@video1`) or composed-from-blocks (hook + setting + product). Mixing produces muddled output.

## Avatars (= Visual DNA characters)

What other platforms call "preset avatars" or "custom avatars" Kolbo calls **Visual DNA characters**. Two ways to get one:

- **Existing character** — use `list_visual_dnas` to find one the user has already created.
- **New character** — create with `create_visual_dna({ type: "character", name, images: [...] })`. See `workflows/visual-dna.md` for the full creation flow (pre-flight, naming rule, generate-reference-images-first).

**For UGC modes:** an avatar is optional if the brief clearly mentions a person (the model can synthesize one). Pass `visual_dna_ids` when the user wants a *specific* presenter — their face, the brand founder, a previously trained character.

**Always use `@<dna-name>` in the prompt** when passing `visual_dna_ids` — see `workflows/visual-dna.md` `@name` rules.

## Products (image upload + reference)

For ads that feature a specific product:

1. **Upload product photo** via `upload_media` → Kolbo CDN URL.
2. **Pass as `reference_images`** to `generate_creative_director` / `generate_elements` / `generate_video_from_image`.
3. **Tag with `@image1`** in the prompt.
4. **After the user approves the product asset, log it in `.kolbo/production.md`** under `### Products` so future ads reuse the same CDN URL. Pending variants stay out.

If the user gives a **product URL** instead of a photo, see `workflows/research-first.md` — scrape, extract images, re-host via `upload_media`, persist as a brand kit at `.kolbo/brand-kits/<slug>.md`.

<!-- SKILL-ONLY: no server parity — UGC output routes through the creative-director / veo / seedance enhancers, so any server-side rule lives in those parity files, not here. -->

## Multi-Slot Board Method (structured shot specs + character consistency)

For any multi-shot UGC / review / how-to where the SAME presenter must stay identical across shots, compose the prompt as explicit **slots** and lock identity with a **board-first** pass. This is a prompt-only convention — no special MCP mode; it uses `generate_image` (board) + `generate_elements` / `generate_video_from_image` (per-slot animate) that already exist.

### 1. Structured input slots

Define each shot as one row. Fill every column before generating — blanks are where identity/quality drift creeps in.

| Slot | Arc role | POV / framing | Presenter action | Product visibility | Aspect | Audio |
|---|---|---|---|:-:|:-:|:-:|
| 1 | hook | selfie arm, chest-up, eye contact | states the problem / grabs attention | held up to camera | 9:16 | monologue seg 1 |
| 2 | demo | slightly wider, hands in frame | uses / demonstrates the product | in active use | 9:16 | monologue seg 2 |
| 3 | payoff | back to selfie framing | reaction + soft CTA | resting in hand / on surface | 9:16 | monologue seg 3 |

Scale to 2–6 slots. Keep `hook → demo → payoff` as the minimum arc; add `tension` / `proof` slots between demo and payoff for longer reviews.

### 2. Rendering rules (hard invariants — apply to EVERY slot)

- One aspect ratio across all slots (UGC = `9:16`). Never mix.
- **Identity lock**: same presenter, same wardrobe, same lighting environment across all slots — bind identity by tagging `@<dna-name>` in every slot description (identity binds via the DNA; the phrase "same character throughout all shots" is FORBIDDEN — see `models/seedance.md`).
- Hands and product must read cleanly — no deformed hands, no floating / clipping product, product logo legible when held.
- Phone-shot aesthetic (handheld sway, window/screen key) unless the mode is polished (`tv_spot`, `product_showcase`).

### 3. Board-first consistency (the grid technique)

Before animating, generate ONE composite board image that locks the presenter's identity, then animate each panel:

1. `generate_image` a labeled N-panel grid (2×2 or 1×N) of the presenter across the slot poses — front hook pose, hands-on-product demo pose, reaction pose — locked to `visual_dna_ids` (the presenter's Visual DNA). Aspect `16:9` for the board sheet.
2. Treat that board image's CDN URL as the **`board_media_id`** — the single source of truth for identity.
3. Animate each slot with `generate_video_from_image` / `generate_elements`, passing the board panel (and product) as `reference_images` and tagging `@image1`, so every clip inherits the same face/wardrobe.

This mirrors how the best UGC pipelines keep a character consistent: lock once as a board, then move each shot — not N independent generations that drift.

### 4. Structured parameters (what to carry per generation)

Track these so each slot's call is reproducible and the arc stays coherent:

| Param | Meaning | Maps to |
|---|---|---|
| `arc_role` | hook / tension / demo / proof / payoff | prompt framing + shot order |
| `board_media_id` | the locked board image URL | `reference_images` (`@image1`) |
| `character_media_id` / `visual_dna_id` | presenter identity | `visual_dna_ids` (`@<dna-name>`) |
| `product_media_id` | product photo URL | `reference_images` (`@image2`) |
| `input_tier` | `draft` (fast preview) vs `hero` (final) | model + resolution choice |
| `monologue_segment` | the spoken line for this slot | prompt audio/dialogue line |
| `aspect_ratio` / `duration` / `sound_enabled` | per UGC Family Defaults above | MCP call args |

### 5. Worked example (brief → slots → board → clips)

Brief: *"15s UGC review of a skincare serum, tech-savvy woman creator."*

1. Ensure/create presenter Visual DNA (tech-savvy woman) → `visual_dna_id`.
2. Board: `generate_image` a 3-panel `16:9` sheet — (a) chest-up hook holding the serum, (b) hands applying it, (c) thumbs-up reaction — `@<dna-name>` tagged in every panel description, locked to the DNA. → `board_media_id`.
3. Slots (each `9:16`, ~5s, sound OFF, animate from the matching board panel + product `@image2`):
   - Slot 1 (hook): "Before this serum my routine was five products…" holding it to camera.
   - Slot 2 (demo): hands applying, product in active use.
   - Slot 3 (payoff): reaction + "…now it's just one step." soft CTA.
4. Deliver as a structured message (setup + monologue + media), humanized refs (names/thumbnails, not raw IDs).

## UX Rules

1. **Always pick a mode explicitly.** Don't auto-pick from one ambiguous word. If the user said "make me an ad" with no other signal, offer labeled options: `[UGC / TV Spot / Product Showcase / Surprise me]`.
2. **Always confirm aspect ratio + duration + sound** before firing — these materially change output and cost. One question, labeled options.
3. **Retries:** one retry only when `failure.retryable === true` or the generation completed with empty URLs (SKILL.md "⚠️ Generation lifecycle"); otherwise surface the reason and let the user adjust prompt or product.
4. **Show results without dumping URLs** — see SKILL.md "Generated URLs in chat".

## Prompt Template Seed for UGC

```
UGC selfie video, vertical 9:16, handheld phone aesthetic.
{presenter description or @<dna-name>} in {everyday setting},
{energy level: relaxed | enthusiastic | curious | reactive}.
They {natural action with the product/subject},
talking directly to camera.
Phone-shot lighting (window/screen key light),
slight handheld sway, no cinematic moves.
Style: authentic creator content, NOT polished commercial.
Sound: ambient room tone only, no music, no SFX overlay.
```

## Prompt Template Seed for TV Spot

```
3-shot broadcast commercial, cinematic 16:9.

Shot 1 [0–5s] — {establishing hook}: {wide angle subject + camera move}, {lighting}, {tone setter}.
Shot 2 [5–15s] — {product reveal / demo}: {medium shot with product in focus}, {practical action}, {emotional beat}.
Shot 3 [15–25s] — {payoff + CTA}: {close-up or pull-back}, {brand line in dialogue or SFX}, {final hold}.

Style: {brand mood — e.g., warm + premium / clean + modern / bold + youthful}.
Audio: full mix — dialogue + score + SFX. Music: {genre/tempo}.
```

(Run via `generate_creative_director` with `workflow_type: "video"`, `scene_count: 3`.)