01 · TL;DR
Premium 16:9 YouTube videos, directed.
Premium 16:9 YouTube video OS for Remotion with native Higgsfield generation. Output is 1920×1080 at 30fps. Buy once, install in 60 seconds, scaffold with one slash command, render to MP4.
The 60-second install loop
15 chapters
This page starts with the mental model, then walks through install, four families, preset catalog, slash commands, workflow, Higgsfield gate, audio lock, 16:9 safe zones, lint & critique, render, accessibility, troubleshooting, and cheat sheet.
02 · Mental model
A skill, an engine, two renderers.
YT OS is shaped in three parts. A skill you invoke from Claude Code, an engine on disk that does the heavy lifting, and a renderer that turns a composition into a 1920×1080 MP4 — with Higgsfield reachable only when you ask for it.
The skill
The /yt-os-* commands, installed into Claude Code at ~/.claude/skills/yt-os/. This is the surface you talk to.
~/.claude/skills/yt-os/
The engine
The companion CLI at ~/.yt-os/. It does the work — scaffolds, beats, lint, render — while the skill orchestrates.
~/.yt-os/
Two renderers
Remotion renders every video by default. Higgsfield is opt-in per shot, only in the Cinematic family.
Remotion · Higgsfield
Two commands are free and need no license — init and preview. Every other command needs a valid license.
03 · Prompt template
Paste this. Ship a video.
Two paths. The simplest is to type a family slash command and let Claude walk you through every choice. The most precise is the structured brief below — drop your script, fill a few fields, and paste. Both work — pick by mood.
Just type the slash command — Claude asks the rest
No brief required. Use this when you're exploring or don't have a script ready yet.
Type any family slash command (e.g. /yt-os-glass) — or /yt-os-direction "<brief>" to have Claude pick the family for you — and Claude walks you through:
- Picks a preset.Claude prints the family's preset menu with one-line use-cases and the recommended default. Reply with a number or preset key.
- Asks for a video name. PascalCase, no spaces (e.g. Opus48).
- Asks for the voiceover path. Point at a .wav, or skip to record later.
- Scaffolds the video at src/<Name>/index.tsx and surfaces the family palette, primitives, and reference video — so iteration starts immediately.
The structured brief below is for when you already have the script, the family, and the render target in mind and want to encode all of it in one paste.
- 01Script
Drop the full voiceover narration. Claude reads the hook, the key beats, and the CTA straight out of it — no need to repeat them as separate fields.
- 02Family + preset
Type a family slash command (/yt-os-studio · -glass · -cinematic · -editorial) or run /yt-os-direction to have Claude rank the four families against your brief. Claude then prints the preset menu — reply with a number or key.
- 03Voiceover path
The spine everything locks to. Pass an absolute path to a .wav — /yt-os-beats reads it to emit frame-accurate BEAT constants at 30fps. Without it, motion drifts on a long-form upload.
- 04Workflow list
Spell out the slash commands in order. Stops Claude skipping /yt-os-beats (audio lock) — and on the Cinematic family, the /yt-os-plan cost gate before /yt-os-generate.
- 05Acceptance criteria
Define “done” up front: lint clean, critique threshold, render preset, Higgsfield spend approved. Without it Claude ships early.
The brief is just labelled lines. Here's what every key does and a concrete value for each — fill them in, or write skip on the optional ones (Logo, Screenshots).
VideoThe video name in PascalCase, no spaces. Becomes the component and folder Claude scaffolds (src/<Name>/index.tsx) and the value you pass to --video and --comp.
e.g. Video: Opus48Familystudio | glass | cinematic | editorial — or leave it to /yt-os-direction. Sets the palette, primitives, and accent allowlist. Cinematic is the only Higgsfield family.
e.g. Family: glass (/yt-os-glass --preset=graphify)VoiceoverPath to the narration .wav. /yt-os-beats reads it to generate the BEAT constants every layer locks to. Skip only if you'll record later.
e.g. Voiceover: public/audio/Opus48.wavRenderThe export target. youtube is the everyday 1920×1080 upload; youtube-hq is an upscaled 2560×1440 for detail-heavy cuts.
e.g. Render: youtubeLogoBrand marks to fetch as real SVGs — the /yt-os-icons command plus Iconify ids. List one or many, or write skip.
e.g. Logo: /yt-os-icons logos:anthropic-iconScreenshotsProduct captures to pull into the scene — the /yt-os-capture command plus a URL and optional flags (e.g. --scroll for a scroll-recording). Or write skip.
e.g. Screenshots: /yt-os-capture https://devini.io --scroll
Standard brief
Recommended default. Most videos start here.
# YT OS brief # Replace every <Name> with your video name (PascalCase, no spaces — e.g. Opus48, LaunchExplainer). Script: <paste full voiceover script here> Video: <Name> Family: glass # studio | glass | cinematic | editorial — or run /yt-os-direction to choose Voiceover: public/audio/<Name>.wav Render: youtube # youtube (1920x1080) | youtube-hq (2560x1440) Logo: /yt-os-icons logos:anthropic-icon (or skip) Screenshots: /yt-os-capture https://devini.io --scroll (or skip) Workflow (run in order): 1. /yt-os-direction "<one-line brief>" # optional — ranks the 4 families, recommends one 2. /yt-os-glass --preset=graphify --vo=public/audio/<Name>.wav 3. Pick a preset — Claude prints the family's menu; reply with a number or key 4. /yt-os-beats public/audio/<Name>.wav --video=<Name> # paste BEATS into src/<Name>/index.tsx 5. /yt-os-plan --video=<Name> # CINEMATIC ONLY — approve Higgsfield credits before generating 6. /yt-os-generate --video=<Name> # CINEMATIC ONLY — generate approved shots, then cache 7. /yt-os-capture <urls if any> 8. /yt-os-icons <brands if any> 9. /yt-os-lint src/<Name>/index.tsx # fix every error (warnings inform) 10. /yt-os-critique src/<Name>/index.tsx # apply every "Quick" fix 11. /yt-os-render --comp=<Name> --preset=youtube Acceptance: - /yt-os-lint passes with zero errors (warnings reviewed) - /yt-os-critique scores >= 8 across all 5 dimensions (palette, motion, timing, hierarchy, brand) - BEATS const sourced from /yt-os-beats output, not eyeballed - 16:9 safe zones respected — nothing critical in the title-unsafe edge or the bottom-right player-controls / end-screen corner - Only the active family's accent colors appear (accent allowlist) - Audio <-> visuals locked per frame — every spoken line lands on the exact frame its on-screen text appears (no lead, no lag) - Scrub the final 1920x1080 render against <Name>.wav end to end
Opus48 — Studio Dark, filled-in
The brief populated for a Studio Dark long-form flagship. The script is illustrative — swap in your real narration.
# YT OS brief — Opus48 (illustrative script — replace with your real narration) Script: Claude Opus 4.8 just shipped, and it changes how you ship. A one-million-token window. Faster output. The same deep reasoning. Here's what that means for the way you actually build. Video: Opus48 Family: studio # Studio Dark — zinc void, drifting terracotta spotlights Voiceover: public/audio/Opus48.wav Render: youtube-hq # long-form flagship — upscale for detail Logo: /yt-os-icons logos:anthropic-icon Workflow (run in order): 1. /yt-os-studio --preset=opus48 --vo=public/audio/Opus48.wav 2. Pick a preset — Claude prints the Studio menu; reply with a number or key (e.g. opus48) 3. /yt-os-beats public/audio/Opus48.wav --video=Opus48 # paste BEATS into src/Opus48/index.tsx 4. /yt-os-icons logos:anthropic-icon 5. /yt-os-lint src/Opus48/index.tsx 6. /yt-os-critique src/Opus48/index.tsx 7. /yt-os-render --comp=Opus48 --preset=youtube-hq # Studio Dark is pure Remotion — no Higgsfield, so it skips /yt-os-plan and /yt-os-generate. Acceptance: - /yt-os-lint passes with zero errors - /yt-os-critique scores >= 8 across palette, motion, timing, hierarchy, brand - BEATS const sourced from /yt-os-beats output (not eyeballed) - 16:9 safe zones respected; bottom-right kept clear for player controls + end-screen cards - Audio <-> visuals locked per frame against Opus48.wav, scrubbed end to end
| Don't write | Reason |
|---|---|
| “Make it a 9:16 short” | Wrong product. YT OS is 16:9 long-form (1920×1080). Reach for ReelStack for 9:16. |
| “Make it look cinematic” | Vague. “Cinematic” is a family — type /yt-os-cinematic (or /yt-os-direction). Lint and critique enforce quality, not adjectives. |
| “Generate all the Higgsfield shots” | Skips the /yt-os-plan cost gate. Approve the credit estimate first; /yt-os-generate only fires approved shots, so you never double-bill. |
| “Use a custom purple accent” | Accent-allowlist rule blocks render. Only the active family's accents are permitted — switch families instead of forcing an off-palette color. |
| “Put the CTA in the bottom-right” | Safe-zone rule. The bottom-right is covered by player controls and, in the last ~20s, YouTube end-screen cards. Keep it clear. |
| “Eyeball the timing / skip the beats step” | Audio-lock rule. BEATS must come from /yt-os-beats (a whisper SRT), frame-accurate at 30fps. Eyeballed timing drifts across a long-form cut. |
| “Match graphify exactly” | License forbids verbatim re-publish. Reference videos are pattern study only. |
| “My voiceover” (no path) | Claude has to ask — wastes a turn. Pass the absolute path to the .wav. |
| “Just render, skip the lint” | Defeats the product. Lint errors block render by design — it's why YT OS videos look earned, not guessed. Warnings inform; errors stop. |
Drop one of these into Claude Code right after running npx @devinilabs/yt-os init, or just type the family slash command and let the menu walk you through. The skill triggers on family and preset names automatically — no wrapping prompt about YT OS itself.
04 · Install & activation
Sixty seconds, one key.
One command activates your license, checks your machine is ready, and installs the engine, the skill, and the slash commands into Claude Code. Run it and answer the prompt.
Readiness check
- Node 20+
- ffmpeg
- ffprobe
- whisper-cli
- Higgsfield CLI + auth (only if you generate)
License key
Paste the key from your purchase email when init prompts for it. That single key unlocks every gated command.
3 machines
Activates on up to 3 machines on a rolling 30-day window. Email [email protected] to release a slot.
7-day cache
After activation the license is cached locally and silently re-validates on the next gated command you run.
Try it free first
Free 5-second demo render. No license, no Higgsfield spend.
05 · Four families
Four cinematic languages.
Every YT OS video speaks one of four visual dialects. Each family is a fixed palette, a set of motion primitives, and the presets that ship inside it — so a brief snaps to a look instead of starting from a blank canvas.
Studio Dark
Zinc void, drifting terracotta spotlights. Premium ad-film mood.
motion
presets
Encodes Opus 4.8 — the long-form flagship
Glass Iridescent
Light lavender, iridescent caustics, frosted glass, sonar rings.
motion
presets
Encodes Graphify — premium product reveal
Cinematic
Teal-orange filmic grade, anamorphic streaks. Higgsfield-leaning.
motion
presets
Encodes Content Research — the research engine, in cinema
Editorial Warm
Warm cream paper, Fraunces serif, gold + terracotta. Calm, magazine-grade.
motion
presets
Encodes Editorial Essay — the warm, magazine-grade explainer
06 · Preset catalog
Ten presets, harvested from real videos.
Each preset carries the exact palette, beat structure, and frame count of a shipped video. Scaffold one and you start from a production timeline, not a template. Filter by family to see what lives where.
| preset | family | frames | sec | notes |
|---|---|---|---|---|
| opus48 | studio | 8,190 | 273 | long-form flagship explainer |
| claudedispatch | studio | 2,640 | 88 | insider dispatch reveal |
| huashu | studio | 2,984 | 99 | design-critique narrative |
| contentresearch | studio | 2,286 | 76 | research-engine explainer |
| graphify | glass | 1,956 | 65 | premium product reveal |
| reelstackreveal | glass | 1,740 | 58 | product reveal, strong motion |
| mattpocock | glass | 7,560 | 252 | long-form technical deep-dive |
| gstack | glass | 2,820 | 94 | toolkit launch, heavy glass |
| cinematicresearchHiggsfield | cinematic | 2,286 | 76 | ships 3 Higgsfield shots |
| editorialessay | editorial | 2,286 | 76 | warm editorial explainer |
07 · Slash commands
The full command set.
Two commands are free — activate and preview — and run with no license. Everything that scaffolds, beats, lints, or renders needs your one-time license key, active on up to three machines.
Free · no license
Needs license
scaffold
pipeline
08 · End-to-end workflow
From brief to MP4.
One line in, a lint-gated 1920×1080 file out. Each step hands its artifact to the next — direction picks a family, the scaffold lays down palette and beats, and the render only fires once lint is clean.
- 1$ /yt-os-direction "<brief>"
Rank the 4 families against a one-line brief and recommend one.
- 2$ /yt-os-glass --preset=graphify --vo=script.wav
Scaffold a family with palette, primitives, and a BEAT skeleton.
- 3$ /yt-os-beats script.wav --video=MyVideo
ffmpeg + whisper → frame-accurate BEAT constants at 30fps.
- 4$ /yt-os-plan --video=MyVideo
Cinematic only: estimate Higgsfield credits before approving.
- 5$ /yt-os-generate --video=MyVideo
Cinematic only: generate approved shots, then cache.
- 6$ /yt-os-lint src/MyVideo/index.tsx
20 rules — safe zones, audio lock, accents. Errors block render.
- 7$ /yt-os-render --comp=MyVideo --preset=youtube
Render 1920x1080, lint-gated and spend-guarded.
/yt-os-plan and /yt-os-generate are cinematic-only — they exist for the Higgsfield family. Studio Dark and Glass Iridescent are pure Remotion, so they skip straight from beats to lint.
09 · Higgsfield cost gate
AI shots, behind a gate you control.
The Cinematic family can call Higgsfield for real shots — but never silently. Generation is opt-in per shot, the credit total is quoted before anything bills, and finished shots cache so a re-render costs nothing.
plan
Quote each shot's credits against your balance — nothing generates yet.
approve
The total sits in front of you. You say yes before a single credit moves.
generate
Only the approved shots generate, then download.
cached
Keyed by checksum — re-renders pull the cache and never re-bill.
costs are quoted live by Higgsfield at plan time
You approve every credit — nothing generates until the total is on screen and you say yes.
Cached shots never re-bill: edit one prompt and only that shot regenerates.
Generation spends your own Higgsfield credits — separate from your YT OS license.
Three of four families (Studio Dark, Glass Iridescent, Editorial Warm) need no generation at all.
10 · Audio-lock pipeline
Beats that never drift.
Motion is keyed to the voiceover, not to a stopwatch. The voiceover is transcribed to frame-accurate timestamps and frozen into BEAT constants, so every cut lands on the word it was meant for.
Because the beats are sourced from the transcript itself, there is no six-second drift on a four-minute video — the last cut lands exactly where the audio does.
11 · 16:9 safe zones
Framed for YouTube, not cropped by it.
Every layout is composed against the same four reserves YouTube imposes — the title-safe inset, the player-controls corner, the end-screen card zone, and the slight thumbnail crop. Headlines and hero UI stay inside them, so nothing clips on a TV, a phone, or a preview tile.
The research engine, in cinema.
overlay · title-safe inset · player controls · end-screen reserve
Title-safe
Keep headlines and key UI inside a ~5% inset so nothing clips on older players or TVs.
Bottom-right
Leave the player-controls and timestamp corner clear — it is covered during playback.
End-screen reserve
In the last ~20 seconds, keep the bottom-right clear for YouTube end-screen cards.
Thumbnail crop
Don't rely on the exact edges — thumbnails and previews crop in slightly.
Enforced automatically by /yt-os-lint — there is no separate safe-zones command.
12 · Lint & critique
Twenty rules, then a second opinion.
Lint is the hard gate — twenty deterministic rules that pass or fail. Critique is the soft pass — a five-dimension read on whether the cut actually lands. One stops a bad render; the other makes a good one better.
/yt-os-lint
rules, four groups
Safe zones
title-safe · bottom-right · end-screen reserve · thumbnail crop
Audio lock
BEAT constants present, sourced from a whisper SRT, frame-accurate
Accent allowlist
only the active family's allowed accent colors appear
Manifest integrity
shots, presets, and durations stay internally consistent
Errors block render. Warnings are advisory.
/yt-os-critique
A five-dimension radar over the cut.
Each dimension scores, then the read resolves into a Keep / Fix / Quick punch list — what is already working, what to change, and the fast wins worth taking before you render.
13 · Render
YouTube masters, lint-gated.
Render is the last gate. It runs lint first and refuses on any error, smoke-checks three frames before committing to the full pass, and writes a clean 16:9 master at 30fps — 1920×1080 on the youtube preset, 2560×1440 on youtube-hq.
--preset=youtube
1920x1080 · 30fps · 12 Mbps H.264 / AAC 192k — the everyday upload.
--preset=youtube-hq
2560x1440 · 30fps · 20 Mbps — upscaled cinematic for detail-heavy uploads.
H.264 / AAC 192k · lint-gated · spend-guarded · 3-frame smoke check.
14 · Accessibility
Motion that respects the reader.
Premium motion should never tax the people watching it. YT OS treats reduced motion as a first-class path, holds a baseline so scenes stay alive, and renders one clean master every time.
prefers-reduced-motion
When the reader's OS asks for less motion, perpetual loops, marquees, and scroll scrubs fall back to static frames. The video still reads — nothing essential lives in the animation alone.
Motion floors
Every scene keeps enough layered motion to feel alive without churning. The floor is a baseline, not a ceiling — quiet by default, never dead.
1920×1080
Every render is a clean 16:9 master at 1920×1080 · 30fps · audio-locked. One canonical aspect, no cropped surprises across players, TVs, or thumbnails.
15 · Troubleshooting
When something's off.
The four things that trip people up, and the one move that fixes each. Most resolve by re-running a single command.
16 · Cheat sheet
Print this. Keep it next to your monitor.
Every slash command and all four families on one page. It prints clean on white — the whole pipeline at a glance, no scrolling.
All slash commands
The four families