Wise Songs — Media Pipeline Architecture

Wise Songs — Media Pipeline Architecture Additive to wise-songs-video-pipeline-spec.md (implementation detail). This doc covers ownership boundaries, command s...

Wise Songs — Media Pipeline Architecture

Additive to wise-songs-video-pipeline-spec.md (implementation detail). This doc covers ownership boundaries, command surface, channel management, and board design.

Ownership Boundaries

supernal-coding/                      BASE PLATFORM — zero knowledge of wise_songs
  packages/media-pipeline/            Generic orchestrator, backends, DB schema, interfaces
  skills/media-pipeline/              Generic `content` commands (channel CRUD, video ops)
  soul-widgets/media-pipeline/        Installable widget template + generic board components

supernal-family/                      FAMILY INSTANCE — all wise_songs specifics
  widgets/wise-songs-media/           The installed widget
    soul-widget.yaml                  References media-pipeline equipment pack
    channels.yaml                     ← written by commands, never edited by hand
    board/                            Board customizations using media-pipeline components

Nothing wise_songs-specific touches supernal-coding. The base platform is blind to content. Another family installs the same widget template and gets the same infrastructure with their own channels.

Channels Are DB-Managed, Not Hand-Edited

channels.yaml (or its DB equivalent) is the storage layer, not the interface.

Users never open and edit channels.yaml
The board provides forms that call commands
Agents create/update channels by calling commands (MCP tools)
Power users use the CLI
All three surfaces hit the same command handler

User intent
  ├── Board form    → POST /api/content/channel/create → command handler → writes storage
  ├── Agent         → MCP tool content_channel_create  → same handler
  └── CLI           → content channel create            → same handler
                                        ↓
                              validation + cost estimate
                                        ↓
                              channels config/DB updated
                                        ↓
                              board refreshes, channel appears

CLI Namespace: `content`

Not sc (that's coding). Not wise (too specific to this family). content is the namespace any content-focused widget can register commands into. A cooking-videos widget would also register content channel create with its own config schema.

# Channel management
content channel create  --name "GRE Word Wizards" --audience adult --coppa false --style kinetic
content channel update  gre_word_wizards --prompt-strength 0.45
content channel list
content channel show    gre_word_wizards
content channel delete  gre_word_wizards   # warns about orphaned pipeline jobs

# Video pipeline
content video generate  --slug X --channel gre_word_wizards
content video review    --job-id X --action approve|reject [--notes "..."]
content video publish   --slug X [--target youtube]
content video queue     --channel aesops_fables [--status review]
content video cost      [--month 2026-04] [--channel X]

All commands via @supernal/universal-command → auto-exposed as CLI + API + MCP tool. Same command, three surfaces.

Safety Controls Built Into Commands

Channels have financial implications — a wrong backend choice changes cost from $0.15 to $5.25/video.

content channel create
  → if backend is wan_720p or ltx_video:
      "⚠️  This backend costs ~$5.25/video (vs $0.15 for ken_burns). Confirm? [y/N]"
  → shows estimated cost per video before writing
  → requires --confirm if cost > $1.00/video

content channel update --backend
  → shows cost delta: "$0.15/video → $5.25/video"
  → audit record written: who changed what, when, from what value

content channel delete
  → "This channel has 4 videos in pipeline and 2 in review. Delete anyway? [y/N]"

content video publish
  → always requires prior approve action (no auto-publish path exists)
  → confirm prompt: "Publishing 'The Wind and Sun' to YouTube — Wise Fables channel. Confirm? [y/N]"

All mutations write an audit record.

Board Form UX — Creating a Channel

A non-technical user creating a channel sees this, not YAML:

┌─────────────────────────────────────────────────────────────┐
│  New Channel                                                │
│                                                             │
│  Name         [_________________________________]           │
│                                                             │
│  Audience     [Kids (4–12) ▾]                              │
│               ● Kids (4–12)  ← auto-sets COPPA, lowers CPM │
│               ○ Teens (13+)                                 │
│               ○ Adults                                      │
│                                                             │
│  Visual style [Storybook ▾]                                │
│               ● Storybook — warm watercolor illustration    │
│               ○ Kinetic text — bold typography, dark bg     │
│               ○ Cinematic — moody wide-angle scenes         │
│               ○ Diagram — clean infographic style           │
│               ○ Abstract — philosophical / surreal          │
│                                                             │
│  Video engine ● Our pipeline ($0.15/video)                 │
│               ○ Revid movie mode (subscription)             │
│                                                             │
│  Estimated cost per video:  $0.15                          │
│  Expected RPM:  $9–25 (adult, non-COPPA)                   │
│                                                             │
│  [Create Channel]                                           │
└─────────────────────────────────────────────────────────────┘

Form submission calls content channel create. The user never sees prompt_strength: 0.60 or image_backend: flux_dev_img2img — those are resolved from their style selection.

Agent Workflow

User: "I want to start a channel for mental model songs for kids"

Agent (knows content-tracker equipment pack, has content_channel_create MCP tool):
  → calls content_channel_create(
       name="Mental Models for Kids",
       audience="kids",
       coppa=true,
       style="storybook"
     )
  → "Created. Estimated cost: ~$0.12/video, RPM: $0.50–1.00 (COPPA).
     Want me to queue the 3 songs already in the mental_models category?"

The agent knows the command because it has the equipment pack installed. The MCP tool is auto-generated from the universal-command definition.

System Layers

┌────────────────────────────────────────────────────────────────┐
│  Dashboard Board  (soul widget: wise-songs-media)              │
│  Installed from: supernal-family/widgets/wise-songs-media/     │
│                                                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────┐ │
│  │ Channels │ │  Queue   │ │  Scenes  │ │ Review │ │ Cost │ │
│  └──────────┘ └──────────┘ └──────────┘ └────────┘ └──────┘ │
│  Board actions call content commands via /api/content/*       │
└──────────────────────────────┬─────────────────────────────────┘
                               │
┌──────────────────────────────▼─────────────────────────────────┐
│  content commands  (supernal-coding/skills/media-pipeline/)    │
│  content channel * | content video *                           │
│  Reads/writes channels config; dispatches to orchestrator      │
└──────────────────────────────┬─────────────────────────────────┘
                               │
┌──────────────────────────────▼─────────────────────────────────┐
│  @supernal/media-pipeline  (supernal-coding/packages/)         │
│  Generic — no content knowledge                                │
│                                                                │
│  PipelineOrchestrator                                          │
│  ├── ScenePlanner       (LLM → visual world + scene descs)    │
│  ├── ImageChain         (pluggable: FluxSchnell, FluxDev)     │
│  ├── VideoAssembler     (pluggable: KenBurns, LTX, Wan)       │
│  ├── TextOverlay        (Whisper + PIL karaoke)               │
│  └── HookExtractor      (ffmpeg 9:16 Short)                   │
│                                                                │
│  ImageBackends:  FluxSchnell | FluxDevImg2Img | OpenAI        │
│  VideoBackends:  KenBurns | LTXVideo | Wan | Revid            │
│  PublishBackends: YouTube | TikTok | Manual                   │
└──────────────────────────────┬─────────────────────────────────┘
                               │
┌──────────────────────────────▼─────────────────────────────────┐
│  content.db  (generic schema — no content specifics)           │
│  pipeline_jobs | pipeline_scenes | pipeline_costs              │
│  video_assets | channels | publish_events                      │
└────────────────────────────────────────────────────────────────┘

Dashboard Board Panels

Panel 1 — Channels

┌───────────────────────────────────────────────────────┐
│  CHANNELS                            [+ New Channel]  │
│                                                       │
│  🎓 GRE-at Word Wizards   adult  $9–25 RPM   3 songs │
│  📖 Wise Fables            kids  $0.50 RPM  32 songs  │
│  🔬 Actually Useful...     kids  $0.50 RPM  12 songs  │
│  🧠 Cerebral Songs        adult  $9–25 RPM   4 songs  │
│  💡 Mental Models         adult  $9–25 RPM  25 songs  │
│                                                       │
│  [Select to manage →]                                 │
└───────────────────────────────────────────────────────┘

Panel 2 — Pipeline Queue (per selected channel)

┌───────────────────────────────────────────────────────┐
│  QUEUE — Wise Fables              [▶ Generate all]    │
│                                                       │
│  ● The Wind and Sun     scene  ████░ generating s4/7  │
│  ◐ Bundle of Sticks     scene  queued                 │
│  ✓ Dog and His Reflection       review ← needs you   │
│  — The Milkmaid                 lyrics (no audio yet) │
└───────────────────────────────────────────────────────┘

Panel 3 — Scene Gallery (selected job)

┌───────────────────────────────────────────────────────┐
│  SCENES — The Wind and Sun   7 scenes · scene backend │
│                                                       │
│  [🖼] [🖼] [🖼] [✦] [○] [○] [○]                      │
│   s1   s2   s3  s4   s5  s6  s7                      │
│                                                       │
│  s4: "wind deity descending, traveller clutches cloak"│
│  Transitions: fade → dissolve → circleopen → fade ... │
│  Strength: 0.60 · Cost so far: $0.08                 │
└───────────────────────────────────────────────────────┘

Panel 4 — Review Player

┌───────────────────────────────────────────────────────┐
│  REVIEW — Dog and His Reflection                      │
│  ┌─────────────────────────────────────────────────┐  │
│  │           [video player]                        │  │
│  └─────────────────────────────────────────────────┘  │
│  19.7MB · hook 2.5MB · cost $0.15 · 299 words        │
│  [▶ Full] [▶ Hook] [✓ Approve] [✗ Reject] [↺ Re-render]│
│  Channel: Wise Fables  Playlist: Aesop's Fables Songs │
│  [🚀 Publish to YouTube]  ← only after approval      │
└───────────────────────────────────────────────────────┘

Panel 5 — Cost Tracker

┌───────────────────────────────────────────────────────┐
│  COSTS — April 2026        [by channel ▾]             │
│  FLUX images  $1.23  ████████░  48 calls              │
│  Whisper      $0.18  ██░░░░░░░  30 min                │
│  GPT-4o       $0.09  █░░░░░░░░  12 calls              │
│  Total: $1.50 · Budget: $20/mo ✓ · $0.15/video avg   │
└───────────────────────────────────────────────────────┘

ss widget apply wise-songs-media

# Registers: content commands, board, equipment pack
# Symlinks: channels config into media-pipeline skill dir
# A different family installs their own instance with their channels

Implementation Phases

Phase 1 — Foundation
  [ ] @supernal/media-pipeline package (orchestrator, backends, DB schema)
  [ ] content channel + content video commands
  [ ] channels stored in DB (not raw YAML), managed via commands
  [ ] FluxDevImg2ImgBackend (img2img chain)
  [ ] ScenePlanner (GPT-4o → visual world JSON)
  [ ] KenBurnsBackend migrated from video_pipeline.py

Phase 2 — Revid + Review
  [ ] RevidBackend (Playwright automation)
  [ ] content video review workflow
  [ ] Audit log for all channel mutations

Phase 3 — Dashboard Board
  [ ] wise-songs-media soul widget (supernal-family)
  [ ] All 5 panels: Channels, Queue, Scenes, Review, Costs
  [ ] Board forms call content commands (not raw API)
  [ ] ss widget apply wise-songs-media

Phase 4 — Motion + Scale
  [ ] LTXVideoBackend, WanBackend
  [ ] Batch queue runner
  [ ] Monthly compilation builder
  [ ] YouTube publish automation

Wise Songs — Media Pipeline Architecture

Wise Songs — Media Pipeline Architecture

Ownership Boundaries

Channels Are DB-Managed, Not Hand-Edited

CLI Namespace: `content`

Safety Controls Built Into Commands

Board Form UX — Creating a Channel

Agent Workflow

System Layers

Dashboard Board Panels

Panel 1 — Channels

Panel 2 — Pipeline Queue (per selected channel)

Panel 3 — Scene Gallery (selected job)

Panel 4 — Review Player

Panel 5 — Cost Tracker

Widget Installation

Implementation Phases

Comments

Wise Songs — Media Pipeline Architecture

Wise Songs — Media Pipeline Architecture

Ownership Boundaries

Channels Are DB-Managed, Not Hand-Edited

CLI Namespace: content

Safety Controls Built Into Commands

Board Form UX — Creating a Channel

Agent Workflow

System Layers

Dashboard Board Panels

Panel 1 — Channels

Panel 2 — Pipeline Queue (per selected channel)

Panel 3 — Scene Gallery (selected job)

Panel 4 — Review Player

Panel 5 — Cost Tracker

Widget Installation

Implementation Phases

Comments

CLI Namespace: `content`