---
title: "Scripted Media Pipeline"
description: "Schema-driven scripted video generation — request JSON, cast bible, first-frame stills, I2V, thumbnails, run-scripted-video CLI"
locale: "en"
---
# Scripted Media Pipeline (Ring Media Conductor)

Provider-neutral, schema-driven pipeline for marketing and explainer reels. A creative agent authors one **`scripted-video-generation-request-.json`**; **`ring-video-create`** chains:

1. **First-frame still** (`firstFramePrompt` → ImageConductor)
2. **I2V video** (grok-imagine-video-1.5 @ 480p when draft + image)
3. **Optional thumbnail** (deterministic text overlays via `next/og`)

  
- **[ring-video-create](/docs/mcp/ring-video-create.md)** — MCP tool reference (overloaded scene path).

  
- **[Generative videos](/docs/development/generative-videos.md)** — VideoConductor presets and remaster modes.

## Architecture

```text
Creative agent → scripted-video-generation-request.json
  → run-scripted-video.mjs (CLI) OR ring-video-create (MCP)
    → VideoConductor.generate
      → ImageConductor (firstFramePrompt)
      → xAI I2V (compiled ACTION/DIALOGUE prompt)
      → thumbnail compositor (optional)
    → manifest v3 + ring-filebase URLs
```

| Artifact | Path |
|----------|------|
| JSON Schema | `lib/media/scripted-video-generation.schema.json` |
| Zod validation | `lib/media/schemas.ts` |
| Prompt compiler | `lib/media/prompt-compiler.ts` |
| Thumbnail | `lib/media/thumbnail.tsx` |
| Example request | `scripts/ring-viral-video/scripted-video-generation-request-hoa-nightclub.json` |
| CLI runner | `scripts/ring-viral-video/run-scripted-video.mjs` |
| Director lens | `AI-LEGIOX/legiox-truth-lens/scripted-video-director.nodus.json` |

## Request file shape

```json
{
  "schemaVersion": "1.0",
  "requestId": "hoa-nightclub-viral-2026-06",
  "purpose": "viral-ad",
  "defaults": { "qualityMode": "draft", "aspectRatio": "16:9", "imageResolution": "2k" },
  "cast": [{ "id": "guy", "description": "…" }],
  "setting": "San Francisco nightclub at night…",
  "clips": [{
    "id": "03_sf_nightclub_ring_opener",
    "duration": 12,
    "firstFrame": { "imagePrompt": "{{girl}} and {{guy}} at bar…" },
    "scene": {
      "action": "{{guy}} gestures warmly…",
      "dialogue": [{ "speaker": "guy", "line": "So your HOA uses Ring?", "tone": "warmly" }]
    },
    "thumbnail": { "enabled": true, "overlays": [{ "text": "Your HOA on Ring", "role": "title" }] }
  }]
}
```

**Cast placeholders:** `{{guy}}`, `{{girl}}` resolve to `cast[].description` at compile time.

## Clip types

| Type | firstFrame | scene.dialogue | Video mode |
|------|------------|----------------|------------|
| Montage / UI | omit | optional | T2V `grok-imagine-video` @ 480p |
| Dialogue | `imagePrompt` required | required | I2V `grok-imagine-video-1.5` @ 480p |

## CLI

```bash
cd ring-platform.org/scripts/ring-viral-video

# Full pipeline via MCP gateway (needs RING_MCP_ACCESS_KEY + dev server)
node run-scripted-video.mjs scripted-video-generation-request-hoa-nightclub.json --download

# Single clip
node run-scripted-video.mjs scripted-video-generation-request-hoa-nightclub.json --clip=03_sf_nightclub_ring_opener

# Remaster from manifest URL
node run-scripted-video.mjs request.json --remaster --clip=03_sf_nightclub_ring_opener --source-url=https://...
```

Manifest v3 tracks `firstFrameUrl`, `thumbnailUrl`, `pipelineRequestId`, `clipId` per upsert key `id::qualityMode`.

## MCP (single clip)

```
ring-video-create \
  prompt "ACTION: … DIALOGUE: …" \
  firstFramePrompt "Cinematic still {{guy}} and {{girl}} at bar…" \
  qualityMode draft duration 12 purpose viral-ad clipId 03_sf_nightclub_ring_opener
```

With `thumbnail.enabled` in body — see [ring-video-create](/docs/mcp/ring-video-create.md).

## Agent workflow

Consult **`scripted-video-director`** truth lens when authoring requests. Validate with:

```typescript
import { scriptedVideoGenerationRequestSchema } from '@/lib/media/schemas'
scriptedVideoGenerationRequestSchema.parse(request)
```

## Environment

```bash
XAI_API_KEY=…
RING_MCP_ACCESS_KEY=long-random-token
RING_API_BASE_URL=http://localhost:3000
FILE_BACKEND=ringbase
```

## Legacy

`xai-video-jobs.json` + `generate-xai-videos.mjs` remain for direct xAI batch runs without gateway. Prefer the scripted request file for new campaigns.