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 │
└───────────────────────────────────────────────────────┘
Widget Installation
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