# Reuse a brand profile

Profiles apply a small set of existing renderer controls to a **new copy** of a starter project. Your original project and its audio stay intact. Start with `profiles/field-notes.json` for a light green treatment or `profiles/night-studio.json` for a dark blue treatment.

Run from the toolkit folder:

```sh
node scripts/brand-profile.cjs validate profiles/field-notes.json
node scripts/brand-profile.cjs apply profiles/field-notes.json --project examples/starters/explainer --out projects/my-explainer
```

The source folder needs a `project.json` descriptor. Use the actual starter folder name in your download. Choose a fresh output folder outside the source project; the command does not overwrite a previous edit. Apply each profile from an unbranded starter. Reapplying to an already branded project is rejected so name replacement and sound attenuation do not accumulate. Render the new copy with the first-video workflow, then inspect both formats. Read `brand-report.json` in the new project to see exactly what applied.

## What each setting changes

| Setting | Native scene starter | Creator recording starter | Other Studio scenes |
|---|---|---|---|
| `name` | Replaces authored visual `{{brand}}` slots | Replaces authored visual `{{brand}}` slots | Replaces authored visual slots |
| `palette` | Applies the six native color values | Does not override the Creator look | Maps to supported Studio colors; custom art and some special layouts keep their own colors |
| `creatorLook` | Not used | Applies `forest`, `lavender` or `cobalt` | Not used |
| `studio` | Native fonts remain bundled Space Grotesk | Creator glyph fonts remain fixed | Applies existing validated font/background/character/style presets only to scenes that already have `design` |
| `captionMode` | `preserve` or `hide` for burned-in plan captions | `hide` removes ordinary captions and kinetic-caption cues, retaining other title graphics | `hide` is rejected; word captions also drive this scene system |
| `sound` | Existing authored sound plan can be preserved, quieter or disabled | Same | Same |
| `voice` | Only `preserve` is supported | Only `preserve` is supported | Only `preserve` is supported |
| `logo` | Fills an explicitly authored native image/product slot | Fills an explicitly authored supported image cue | General Studio logo placement is not implemented |

Brand names do not change a spoken script, narration file or timed caption words. Screenshots, drawings, product UI assets and logos keep their own pixels. The profile does not recolor every effect or turn the toolkit into a general brand editor. The supplied starters use native scenes or Creator; Studio-specific controls are available only for compatible additional projects.

## Make a profile

Copy one JSON profile to your own folder. Change `id`, `name` and the six palette colors. A name is one line, up to 20 characters. Each color uses six-digit hex notation. The checker requires readable contrast for common foreground/background, foreground/panel and accent/background pairs, plus visible muted text. This catches common mistakes; it does not replace reviewing your actual frames.

The native font is fixed. A `studio.font` value such as `inter` or `manrope` only affects a supported Studio scene. Keeping that field in a profile used by a native starter does not change its font. This boundary is recorded in the application report.

`sound: "quiet"` reduces existing cue gains by 6 dB, bounded by the mixer's -36 dB floor, and uses at least an 18 dB dialogue gap. Timing and sound choices are preserved. If there is no sound plan, the report says so; no effects are invented. `sound: "off"` sets `project.soundEnabled` to `false`. The first-video driver honors that flag; a manually run mixer will not read it automatically. Existing sound already embedded in source footage is preserved.

Voice selection is deliberately separate. Supply or generate permitted speech, align its final words and retime the project using the existing narration workflow. A brand profile does not generate or silently swap a voice.

## Optional logo

The supplied `product-demo` reserves its `replace` scene in both formats. Try its original sample logo with `--profile examples/starters/product-demo/profile-with-logo.json` when initializing that starter. The explainer and recording starters do not reserve logo slots.

Use a local PNG, JPEG or WebP under the profile's folder, up to 5 MB and 4096 pixels per side. SVG, URLs, paths outside the profile folder and symlinks are rejected. Add:

```json
"logo": {
  "path": "assets/my-logo.png",
  "license": "Original artwork owned by me",
  "source": "My original logo",
  "redistribution": "permitted"
}
```

Only make that rights declaration when it is true. You can use `unconfirmed` while working privately; the delivery helper will then stop until the rights record is resolved. The toolkit does not determine ownership for you.

The starter must reserve a logo slot in `project.json`. Native example:

```json
"brandSlots": {
  "logoScenes": { "landscape": ["brand"], "portrait": ["brand"] }
}
```

The named scene must already be a native `image` or `product` scene. For a Creator plan, use `logoCues` with zero-based cue indexes for each format. Supported cue types include `note-bar`, `video-cards`, `raw-take`, `thumbnail-wall`, `storyboard`, `product-window` and `frame-roll`. The command stops if the requested project has no compatible slot. It does not invent a scene or change the timeline.

The imported logo is contained on a white 640-pixel square to avoid cropping in Creator image slots. A small slot can still make fine details unreadable; review the exported frame. The copy and its declared rights are included in the new project. Apply from an unbranded original when changing the logo again.

## Project contract

The starter's `project.json` contains version `1`, a short `id`, `title`, `engine` (`scene` or `creator`), `plans` by format, an explicit `sourceFiles` list and a `rights` manifest path. Optional `audio`, `footage` and `soundPlan` fields identify local inputs. Every required file and media rights record must be listed. Generated render caches, dependencies and unrelated personal files are not copied.

For `captionMode: "hide"`, the original authored captions are preserved in separate source JSON files and referenced by `project.captionFiles`. The delivery helper uses those to create selectable-caption sidecars even when burned-in captions are hidden. This does not upload or publish captions on a platform.

Profiles fail on invalid colors, unsupported settings, missing inputs, unsafe paths or text that exceeds the existing renderer's layout checks. Fix the reported input and choose a fresh output folder. Brand application itself is not a successful render or a listening review.