yazzang-homelab/motion-studio

Studio init (course step 02)

Create a film project that can render, listen to and look at its own frames. The chat app can write an animation; only an agent with a shell can close the render, look, fix loop. That loop is the difference between a "mid" first try and a film worth posting.

Request arguments (may be empty), shown once:

1. Choose the directory and settings

• Directory: the first argument; else . when the working directory is empty; else ask (default ./<slug-of-title>). Never scaffold into the plugin directory.
• Settings from the request: title, duration, formats, fps, bpm, loop, brand URL. Leave the rest at the template defaults (studio.json: 12 s, 60 fps, 4 subframes, 120 BPM, 9x16 primary).

2. Scaffold

node "${CLAUDE_SKILL_DIR}/scripts/init.mjs" <dir> --title "<Title>" [--duration S] [--fps N] [--bpm N] [--formats a,b] [--loop] [--brand-url URL] [--install] [--json]

Flag	Effect
<dir>	target; created if missing
--title T	studio.json title and delivery file slug
--duration S, --fps N, --bpm N	timing
--formats a,b	subset of 9x16, 1x1, 16x9, 4x5 (or all); primaryFormat stays unless it is not listed
--loop	seamless loop film (UI morphs)
--brand-url URL	stores the product URL in brand.url. user:password@ and secret-looking parameters (query, ;matrix, fragment: token, key, secret, password, auth, sig, session, code ...) are removed before anything is written; stderr names what was removed and --json lists it in redacted. Still pass a plain public URL: a secret that is a bare path segment (/reset/<token>) cannot be recognized. A plain URL is stored exactly as typed
--install	runs npm install in the new project (handles npm.cmd on Windows)
--force	refresh an older project to the current template (see the table below)
--json	one JSON result line on stdout

An existing non-empty directory is merged: only missing files are added and skipped files are listed. Report the skipped list to the user; never delete their files.

--force on an existing project (checked against init.mjs):

Path	With --force
studio.json, film/**, docs/**, assets/fonts/fonts.json	kept and listed as kept; a missing one is still created. Flags such as --bpm still patch studio.json
package.json	merged, never replaced: sets type: module, adds private, engines and every template script or dependency the project lacks. A template script whose command differs is reset to the template command (init prints each as was ..., now ... and returns them in packageReset). Dependency versions are never changed, template dependencies included: an existing range stays, newer, older or pinned. Name, version, other scripts and other fields stay
.gitignore	merged: missing template lines are appended under # motion-studio, nothing is removed
everything else (CLAUDE.md, lib/**, tools/**, prompts/**, index.html, .env.example, bundled fonts)	overwritten and listed as overwritten. Local edits to these files are lost: commit or copy them first
your own extra files	untouched

Without --force, package.json and .gitignore are merged the same way, except that a differing script keeps your command. Init lists every script and dependency version that differs from the template under kept your package.json values, which differ from the template (packageKept in the --json result): those npm run names run YOUR command, and --force resets template scripts (never dependency versions). A scripts, devDependencies or optionalDependencies section that is not an object is left untouched with a warning. Because docs/** is kept, a newer template doc never reaches an existing project: compare with the plugin's template/docs/ by hand after an update.

3. Install, browser, doctor

1. Without --install, run npm install inside the project. playwright is the only required dependency; ffmpeg-static is optional and may fail to download behind a proxy.
2. Browser (npm run setup:browser is the same command as the npx line):
   • Windows: run npx playwright install chromium-headless-shell (about 115 MB download, 270 MB on disk). studio.json browser: "auto" starts only that bundled headless shell, never the installed Chrome or Edge. Reason: an installed Chrome or Edge started with a fresh profile (every tool run) makes Chrome test the Windows account for a blank password, which counts as a failed logon. The measured laptop locks the account after 10 failed logons in 10 minutes and logged 464 in 24 h. Do not switch browser to chrome or msedge, and do not set MOTION_CHROME_PATH to a chrome.exe or msedge.exe, unless the user asks for it and accepts the risk: it prints a warning per launch and the 4th launch in 10 minutes is refused, 3 pass (the launch guard). The shell is unsigned, so a real-time antivirus can make every tool run 15 to 25 s slower (measured): tell the user once; an antivirus exclusion for %LOCALAPPDATA%\ms-playwright is their or IT's decision.
   • macOS and Linux: auto tries the installed Chrome, then Edge, then the bundled browser, with no warning. If none is installed, run npx playwright install chromium-headless-shell (Linux: npx playwright install --with-deps chromium-headless-shell), or set MOTION_CHROME_PATH to a Chromium-family executable.
3. npm run doctor. Fix every FAIL row before handing over, and on Windows a WARN browser row too (an installed Chrome or Edge was chosen: clear it and install the headless shell); fixes per OS are in references/troubleshooting.md. Python with librosa is optional (the JS beat engine covers it). Node 22+ is needed only for route B tools.
4. Prove it: npm run stills, then open out/review/9x16/contact.png (a long film is paged: contact.png is page 1, then contact-2.png ..., no page taller than 1800 px; open every page) and look at it. The shipped 12 s demo must show a composed frame at 0 s and a change on every downbeat. npm run preview opens the live preview (Space play/pause, arrows step frames, F cycles formats, G safe-area guides).

4. Explain the project to the user

Summarize in a few lines, then point to the references:

• Layout and who edits what: references/project-layout.md
• Every command: references/commands.md
• Every lib/ signature and default: docs/API.md in the new project (the full reference is docs/ARCHITECTURE.md in the plugin repository)
• House rules live in the project's CLAUDE.md, which Claude Code reads on every run there.

If init printed a ★ star line (starHint in the --json result; it appears once per machine, on the first new project), end your summary with that one line as written. Never star the repository or run gh for the user.

Command	Does
npm run preview	live preview in the browser
npm run stills	one still per beat as a contact sheet
npm run critique	contact, strip, phone test, metrics, review-log block
npm run gate	critique gate: 3 rounds, all axes >= 8, no P0
npm run render:final	every format, final quality (gate enforced)
npm run sfx / npm run mix	synthesize cue SFX / mix to -14 LUFS and mux
npm run deliver	delivery checks and out/deliver/ package
npm run build	score if missing, sfx, final render, mix, deliver

5. Effort and routes

Work	Effort	Set with
small fixes, re-renders	medium	/effort medium
a new film	xhigh	/effort xhigh (the motion-reel skill sets it for you)
flagship first 3 seconds of a launch	max	/effort max

/model also offers the effort choice when picking Opus 5.5. Route A (this engine) is the default. Use Remotion or HyperFrames only when the user names one; /motion-studio:seek-engine has the handoff, including the Remotion license gate.

6. Keys

Copy .env.example to .env only when a key is needed (voice: ELEVENLABS_API_KEY; route C images/video: FAL_KEY). Tell the user to paste the value into .env themselves. In prompts and logs refer to the variable name only. .env is already in the project .gitignore.

7. Optional companions

Mention these only when relevant. Install commands and caveats: references/companions.md.

Companion	Use for	Note
claude-animation (buildwithhanif)	hand-drawn, brush, storybook looks	MIT; separate Node canvas renderer
HyperFrames (heygen-com)	HTML + GSAP compositions	Apache-2.0; Node 22+
Remotion	React series and templates	company license for for-profit orgs over 3 employees

Next: test the engine with /motion-studio:showreel, or make a real film with /motion-studio:motion-reel.