Brand Governance

A ThemePack is your brand encoded as JSON. Register it once, and every .ws file compiled with it automatically uses your colors, fonts, and timing preferences. No manual checking, no design review per video — compliance is structural.

Creating a ThemePack

A ThemePack defines palette, typography, and optional timing overrides:

json
{
  "schema": "themepack.v1",
  "name": "acme-brand",
  "version": "1.0.0",
  "palette": {
    "primary": "#1A1A2E",
    "accent": "#E94560",
    "background": "#FFFFFF",
    "backgroundDark": "#0A0A0A",
    "muted": "#888888",
    "contrast": "#FFFFFF"
  },
  "typography": {
    "families": {
      "sans": "Space Grotesk"
    }
  }
}

The palette object maps semantic color names to hex values. When a .ws script uses color: accent, it resolves to your brand's accent color instead of the mood's default.

Validating Before Registering

Check your ThemePack for schema errors without registering it:

bash
curl -X POST https://api.ws.video/api/themes/validate \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{ "schema": "themepack.v1", "name": "test", "version": "1.0.0", "palette": { ... }, "typography": { ... } }'

Returns { "valid": true, "errors": [] } or a list of specific issues.

Registering a ThemePack

bash
curl -X POST https://api.ws.video/api/themes \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{ "schema": "themepack.v1", "name": "acme-brand", ... }'

ThemePacks are scoped to your organization. Other orgs cannot see or use your themes.

Compiling with a ThemePack

Pass the theme parameter when compiling:

bash
curl -X POST https://api.ws.video/api/compile \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "source": "Film \"Demo\"\n  mood: confident\n\nScene \"Hello\"\n  show \"Hello World\"\n    size: hero",
    "theme": "acme-brand"
  }'

The compiled RenderGraph will use acme-brand's palette and typography instead of the default confident mood colors.

How ThemePacks Compose with Moods

ThemePacks override mood defaults selectively. If your ThemePack defines a palette but not typography, the mood's typography is preserved. If it defines timing overrides, those take precedence over the mood's timing. Everything not overridden falls through to the mood.

This means you can use any mood with any ThemePack. A playful mood with your corporate ThemePack gives you bouncy animation and your brand colors.

Updating a Brand

When your brand evolves — new accent color, updated font — update the ThemePack:

bash
curl -X PUT https://api.ws.video/api/themes/acme-brand \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{ "schema": "themepack.v1", "name": "acme-brand", "version": "2.0.0", ... }'

Every .ws file re-compiled with the updated ThemePack produces video with the new brand. No scripts change — only the theme does.

The Approval Workflow

The ThemePack is the single artifact your design and legal teams need to approve. Once approved:

  1. Register it via API
  2. Every .ws file compiled with it is on-brand automatically
  3. No per-video design review required
  4. Compliance is enforced by the compiler, not by people

This flips brand governance from "review every output" to "approve the system once."

Multi-Tenant Brands

If you manage multiple brands (agency model), register separate ThemePacks per brand under the same org, or use separate org IDs per client. Templates rendered with different themes produce different-looking videos from the same structure.

Next Steps