coreslopper
v0.8.0
Published
An open-source, Claude Code-native workflow for producing music videos from brief to render.
Maintainers
Readme
coreslopper
An open-source, Claude Code-native workflow for making music videos and episodes of a series: from an idea and a song (or a script) to a validated storyboard and a finished Remotion render.
Status: work in progress. The pipeline is being tested end to end. Stages, schemas, and provider integrations may still change. Treat it as an experiment, not a production tool.

Agent skills do the creative work (brief, treatment, storyboard, prompts). Tested scripts do the mechanical work (audio analysis, validation, budget checks, caching, rendering). Each shot can be motion graphics, an AI clip, real footage, or a mix. The pipeline runs on its own and stops only for budget, missing credentials, or a validation failure it cannot fix.
Requirements
- Node.js 22+, Python 3.12+, uv,
ffmpeg, and Claude Code.initchecks them and offers to install the missing ones. - For AI visuals: a fal.ai key or a Higgsfield credential. Without one, the mock provider renders placeholders. Video clips can also render locally in ComfyUI.
- A finished song: the mix, ideally its vocal stem, and the lyrics. coreslopper does not generate music.
- Optional: an NVIDIA GPU for faster lyric alignment. CPU works.
1. Create a workspace
A workspace is one folder that holds the workflow and all your video projects. Create it once:
npx coreslopper@latest init my-videos
cd my-videosThe wizard checks your tools, asks for provider keys (stored in .env, gitignored), and creates a first project. Every later command runs inside this folder. See docs/onboarding.md for all flags.
2. New project
coreslopper always starts from a finished song. Bring the mix, ideally its vocal stem, and the lyrics.
Install the lyric aligner once per workspace (WhisperX and Demucs, a large download):
(cd scripts/audio-analysis && uv sync --extra asr --extra stems)Start Claude Code and create the project:
claude/new-videoThe new-video skill walks you through setup:
It asks for the title, artist, slug, budget (USD, mandatory), visual provider (
mock,fal, orhiggsfield), the sung language, and the song's rights, then creates the project.It asks you to paste the lyrics and adds section tags (
[Verse 1],[Chorus], …) for you to confirm.It tells you where to put the audio:
- the mix at
projects/<slug>/audio/song.wav, - the vocal stem at
projects/<slug>/audio/stems/vocals.wav.
WAV goes straight in;
song.mp3,vocals.flac, and other formats with the same name are converted. Export both from the same session so they line up. The stem is optional, but it makes the lyric timing much more accurate. When you confirm, it runsnpm run cli -- import-songto check the files and record them insong.json.- the mix at
It grills you about the video and writes
brief.mdandtreatment.mdwith you.
Higgsfield has no lip-sync yet. For lip-sync shots, add a FAL_KEY to .env and set lipsync: fal in projects/<slug>/project.yaml (details).
Run the pipeline. At the end, new-video offers to start it, or run it yourself:
/video-next <slug>It analyzes the song, builds the style and character bibles, writes and validates the storyboard, generates the assets, and renders projects/<slug>/renders/ without further questions. If you stop halfway through setup, /new-video <slug> resumes where you left off.
3. Review and fix
Watch the result in the review player and leave notes on exact frames:
npm run cli -- review <slug> # newer of preview and master render
npm run cli -- review <slug> --format 9x16 # another format
npm run cli -- review <slug> --video projects/<slug>/renders/shorts/M2-chorus-9x16.mp4Space plays and pauses, ←/→ steps one frame, ↑/↓ one second. While paused, type what is wrong and press Enter: the note is saved with its frame and time in projects/<slug>/review/notes/<video>.json. PageUp/PageDown jumps between notes, Delete removes one, Esc quits. The first start sets up the player's Python environment with uv.
Then ask Claude Code for a fix pass, for example "work through the review notes for ". It maps every note to its shot, fixes timing, motion, or generated media, re-renders, and reports which notes are done. Keys and file format: scripts/review-player/README.md.
Series and episodes
Besides music videos, coreslopper makes episodes of a series from a script instead of a song. A series has a canon in series/<slug>/: bible, style, characters, sets, reference images and voices, and an episode plan. Each episode is its own project that reads this canon and builds its audio from script.yaml: generated or recorded takes per line, ambience per scene, and English subtitles.
Create the series once:
/new-seriesThe new-series skill asks for the title, slug, series budget (USD, mandatory), master format, and providers, then grills you into the bible, characters, sets, and episode plan. It generates the character and set references and the reference voices through the series budget. The series budget covers the canon and every episode's budget.
Create each episode:
/new-episodeThe new-episode skill asks for the series, episode number, slug, and episode budget, creates the project (formats, providers, and brand come from the series), and grills you into script.yaml. Characters and sets come from the canon; if the story needs a new one, add it to the series first.
Run the pipeline as for a music video:
/video-next <slug>
/series-status <series>/video-next generates the takes, mixes the episode track, then storyboards, generates, and renders. To use your own recordings, put them at projects/<slug>/audio/lines/<line-id>.wav and run npm run cli -- import-takes <slug> before the voice-track stage. Review and fix pass work as above. Details and the manual commands: docs/pipeline.md.
Everyday commands
Run these inside the workspace.
| Command | What it does |
|---|---|
| npm run cli -- status <project> | Stages, spend, and the next step. |
| npm run cli -- validate <project> | Check timing, storyboard, style, and characters. |
| npm run cli -- render <project> --format 16x9 | Render a format (16x9, 9x16, 1x1). |
| npm run cli -- review <project> | Watch a render frame by frame and leave review notes. |
| npm run cli -- estimate --role image.keyframe --units 8 --project projects/<project> | Check a cost against the budget. |
| npm run cli -- doctor | Check tools, fonts, Remotion, and keys. |
| /video-next <project> | Run all open stages in Claude Code. |
| /video-next <project> --stage storyboard | Rerun one stage. |
| /video-status <project> | Read-only status in Claude Code. |
| /series-status <series> | Canon, episodes, stages, and spend of a series. |
The pipeline is resumable: run /video-next again after a stop, and it continues where it left off. Generated assets are cached, so a rerun does not pay twice.
Update the workspace
New releases bring new skills and fixes. Commit first, then update from inside the workspace:
git add -A && git commit -m "chore: before coreslopper update"
npx coreslopper@latest updateYour projects, .env, and your own edits to workflow files are kept. If a file you changed also changed upstream, the new version is saved next to it as <file>.coreslopper-new. Workspaces created with 0.1.0 need update --force once. Details: docs/onboarding.md.
Learn more
| Topic | Document | |---|---| | Setup flags, credentials, updating, troubleshooting | docs/onboarding.md | | What each stage does, and running one by hand | docs/pipeline.md | | Series and episodes: stages, takes, re-timing | docs/pipeline.md#episodes, ADR 0016 | | fal.ai, Higgsfield, budgets, and model roles | docs/providers.md | | Review player: keys, notes, fix pass | scripts/review-player/README.md | | Local video clips with ComfyUI | comfyui/README.md | | Optional MCP servers | docs/mcp.md | | How it works inside | docs/architecture.md, docs/adr/ | | Terms used everywhere | docs/glossary.md | | Why it is built this way | docs/adr/ |
License
The workflow is MIT. Remotion, the renderer, is source-available, not open source: it is free for individuals, non-profits, and companies with up to 3 employees; larger for-profit companies need a Remotion license. Make sure you hold the rights to the song before you publish a video. See docs/THIRD_PARTY.md.
Contributing and security
To work on coreslopper itself, clone the repository and follow CONTRIBUTING.md; it includes the demo project, which needs no API keys. Report vulnerabilities privately as described in SECURITY.md.
