MotionSnip Studio
You build the video. The user reviews it in a local player. The loop is:
- Build and render the video.
- Describe it in
reel.json. - Open the player.
- The user reviews and clicks Send to Claude. You get one line:
Apply the MotionSnip Studio feedback in <abs path>. - Apply the feedback, re-render, bump
version. The player reloads by itself and helps the user check your changes.
In this file, <skill dir> means the folder that holds this SKILL.md, usually ~/.claude/skills/motionsnip-studio.
1. Set up the project
Use one folder per video:
<project>/
reel.json you write this
video.mp4 the render (any name; reel.json "src" points at it)
assets/ music, images, logos (user uploads land here too)
public/ optional; Remotion staticFile() assets
exports/ made by the player's Export; never edit
.motionsnip/ player state and history; never edit
If the user has no renderer yet, Remotion is a good default (npx create-video@latest). Any tool that writes an mp4, webm or mov works.
2. Build it so edits are cheap
- Keep copy, colours, fonts and timings in one data object (Remotion
defaultPropsor acontent.ts), not scattered through components. Then a feedback edit is a one-line change. - Give every on-screen element a stable id and use the same id in
reel.json. - Ship music as its own file. Render the video with sound effects only. Put the track in
assets/and pointaudio.musicat it, and setaudio.videoAudioto"effects". The player plays the music beside the video, so the user can swap tracks, move the start and set levels without a re-render. Their Export mixes it in with ffmpeg. - Only bake music into the video when the user asks for it. Then set
videoAudioto"mix".
3. Render and look before you show
Render, then check your own work with a contact sheet:
ffmpeg -v error -y -i video.mp4 -vf "fps=1,scale=480:-1,tile=4x3" -frames:v 1 /tmp/sheet.png
Open the image and look at it. Fix clipped text, empty frames, wrong colours and timing gaps before you open the player. For one frame:
ffmpeg -v error -y -ss 12.4 -i video.mp4 -frames:v 1 /tmp/frame.png
Self-review. Then look again as a picky reviewer would, and write down what you still see. Check:
- Safe area. Anything that matters inside a 10% inset from every edge (title-safe)?
- Size. Body text at least about 3% of the frame height, so it reads on a phone.
- Contrast. Text and key shapes clearly apart from what is behind them.
- Typos and overflow. Every word spelled right, nothing clipped or running out of its box.
- Cuts and timing. No flash frames on a cut, no empty frames, nothing gone before it can be read.
Fix what you can. For anything left, or anything that is a matter of taste, add a finding to review in reel.json (section 4). The player draws each one as a dashed blue ring labelled C1, C2… on that frame, and the user either adds it as their own note or dismisses it. Only write what you actually saw in a frame grab: give the time, and the spot or element, so the ring lands on it. Leave review empty when there is nothing to say; don't pad it.
4. Write reel.json
reel.json is the contract between you and the player. Write plain JSON (no comments).
{
"id": "acme-launch", // stable; the user's saved edits are keyed by it
"title": "Acme launch",
"version": 1, // bump on every render; the player reloads when it changes
"path": "/abs/path/to/project", // where you work; shown in the prompt
"src": "video.mp4",
"w": 1920, "h": 1080, "fps": 30, "duration": 32.0,
"reference": "optional: what the video is modelled on",
"brand": {
"colors": [{ "id": "accent", "name": "Accent", "v": "#5B5BF7" }],
"fonts": [{ "id": "head", "name": "Headlines", "v": "Inter" }],
"logo": "assets/logo.svg" // or null
},
"audio": {
"music": "assets/track.mp3", // played beside the video, or null
"videoAudio": "effects", // "effects" = video has sound effects only; "mix" = music is baked in
"bpm": 120, "drop": 4.0, // optional beat grid; drop = seconds where the drop lands
"musicVol": 1, "sfxVol": 1, // 0..1
"musicOffset": 0, // seconds; + starts the music later, - skips into the track
"musicFade": 0, // seconds of fade-out at the end
"note": "free text"
},
"assets": [{ "id": "assets/track.mp3", "name": "track.mp3", "type": "audio", "from": "User" }],
"scenes": [
{ "id": "S1", "name": "Hook", "t": [0, 4.5], "els": [
{ "id": "headline", "label": "Headline", "t": [0.3, 4.3],
"box": [20, 38, 60, 24], // x, y, w, h in % of the frame; null for voiceover, audio, full-frame footage
"src": "src/Hook.tsx:12", // the file (or file:line) that draws it
"props": {
"text": { "type": "text", "label": "Text", "v": "Meet Acme" },
"color": { "type": "color", "label": "Color", "v": "brand.accent" },
"motion": { "type": "motion", "label": "Motion", "v": "Words blur in one by one" }
} }
] }
],
"notes": [],
"review": [ // optional: your own self-review findings (section 3)
{ "id": "v1-1", "t": 1.5, "elId": "headline", "kind": "safe area",
"title": "Headline runs into the right edge",
"detail": "At 1.5 s the last word ends 2% from the edge, outside title-safe.",
"fix": "Narrow the box to 56% or drop the size a step." }
],
"outputs": [ // optional: other shapes and lengths you made from it (section 9)
{ "id": "vertical", "label": "9:16", "kind": "reframe", "src": "out/vertical.mp4", "w": 1080, "h": 1920, "platform": "reels" }
],
"live": "live.js", // optional live renderer (section 7)
"export": { "cwd": "/abs/build/folder", "props": {}, "cmd": "npx remotion render ... \"$OUT\" --props=\"$PROPS\"" } // optional (section 8)
}
Rules:
- Prop types:
text,longtext,number,color(brand.<id>links to the palette),media(an asset id),list(rows;cols: [{ k, type, options? }]),choice(options: [...]),motion(a plain description of the movement; the user can only comment on it). - Scenes cover
0..durationwith no gaps. Times are seconds. - Keep scene and element ids stable between versions. Saved edits match by id.
boxmust match where the element really is on screen, in % of the frame. Measure it from a frame grab if unsure. The user clicks these boxes to select things.srcshould point at the code that draws the element, so you can find it later.- Every prop value must equal what is actually rendered. The player ticks an edit as done when the new
reel.jsonvalue matches what was asked. pathcan be left out; the server fills in the project folder.reviewfindings:id(unique in this version, e.g.v2-1),t(seconds),title(one line), optionaldetail,fixandkind(safe area,size,contrast,typo,overflow,cut,timingor your own word). Place it withelId(an element id, ringed at its box),box: [x, y, w, h], orx,yin % of the frame. Write a fresh list for every version; don't repeat anything the user dismissed.outputs: see section 9.- Unknown fields are ignored. Missing optional fields get defaults.
5. Open the player
Start the server in the background, then give the user the URL it prints:
node <skill dir>/player/server.mjs <project> &
# MotionSnip Studio: http://localhost:4321 (project: /abs/path)
Options: --port 4321 (moves up if busy), --no-open (don't open a browser), --ffmpeg /path/to/ffmpeg (for Export). Node 18 or newer, no install step. If a server for this project is already running, don't start another; the player picks up new versions by itself.
Tell the user what to do in one or two lines: watch it, click anything to fix it, right-click to circle a problem, then Send to Claude.
A plain video. If the user wants to review or edit a video file that has no reel.json (a screen recording, a phone clip), pass the file itself: node <skill dir>/player/server.mjs path/to/clip.mp4 &. Don't write a reel.json for it. The player lets them trim, cut, add text, a logo or a blur, and set the colour, and its Export applies those edits itself. Their feedback file then only carries notes pinned on the frame; follow those, and if a note asks for a new cut, export over the same file name so the player counts it as the next version.
6. Apply a feedback file
The user pastes Apply the MotionSnip Studio feedback in <project>/.motionsnip/feedback-vN.md. Read that file. It has these parts:
- Exact changes. Lines like
[00:01.2 · S1 · Headline] Text (src/Hook.tsx:12): "Meet Acme" -> "Say hi to Acme". Make exactly that change in the code and inreel.json. Don't reword it. A colour edit tobrand.<id>changes the palette entry, so everything linked to it changes. - Size and position edits.
[x, y, w, h] -> [x, y, w, h] (scale 1.12)in % of the frame. Convert to pixels with the frame size (x% * w / 100), move or resize the element in code, and update itsbox. - Sound settings. New track (already saved in
assets/), start offset, fade, volumes. Updateaudioinreel.json. If the video carries effects only, you usually don't need to re-render for these. If music is baked in (videoAudio: "mix"), re-render with the new settings. - Comments on the {label} version. The same kind of comment, left on a cutdown (9:16, 1:1, a bumper) instead of the master. Times and spots are on that version's own frame and clock; a bumper's section says which parts of the master it is cut from. Fix the cause in the master when you can (keep the important things where the crops see them). If you made that version yourself (it is in your
outputs), render it again too and bump its ownversion. - Cutdowns made in MotionSnip Studio. Versions the player renders itself from the master, with their crop keys or ranges. Leave their files alone; the reviewer re-renders them after your next version.
- Comments on the frame. Free comments pinned to a time and a spot (
x 23.9% y 81.8%), often on a named element. Grab that frame and look at it before you decide what to do. Notes are requests, not exact values; use judgement and keep the rest of the scene intact. - Not quite from vN-1. Things you changed last round that the user says aren't right yet, with their reason. Fix these first.
- From your self-review. A comment ending
(from your self-review, v1-2; the reviewer agrees)is one of your own findings that the user accepted. Treat it like any other note. - Dismissed from your self-review. Findings the user looked at and is happy with. Leave those things as they are, and don't flag them again in the next
review. - Scenes. Each scene's status. Leave approved scenes alone unless an edit or note names them.
Then:
- Make the changes. Keep ids stable.
- Re-render to the same
srcfile (or a new file and updatesrc). - Check the contact sheet and the frames you touched.
- Update every changed value in
reel.jsonand setversionto N+1 (the file says which number). Bump the version last, after the render has finished. - Tell the user in one line what changed, for example "v4 is in · 5 changes applied, the outro note needs your eye".
Never edit .motionsnip/, exports/ or the player's cutdowns in outputs/ (listed in .motionsnip/outputs.json); they belong to the player.
7. Optional: live renderer
If the video can run in a browser (canvas, DOM, Remotion Player bundle), you can ship live.js and set "live": "live.js". The player loads it as a classic script and calls:
window.MotionSnipLive = (container) => ({
seek(timeSeconds) {}, play() {}, pause() {}, setRate(rate) {},
// boxes[id] = [x, y, w, h, nx, ny, nw, nh]: original then edited, % of the frame
setBoxes(boxes) {},
});
The player then hides the video and drives your renderer, so moved or resized elements show for real.
8. Optional: export hook
Add export to reel.json to let the user render a final from the player:
"export": {
"cwd": "/abs/path/to/remotion/project",
"props": { "musicSrc": null },
"cmd": "npx remotion render src/index.ts Main \"$RAW\" --props=\"$PROPS\""
}
The server runs cmd with sh -c in cwd and sets:
PROPS: path to a JSON file withexport.propsmerged with the user's edits. The edits arrive as{ "edits": { "<elId>": { "<prop>": value } }, "boxes": { "<elId>": [x, y, w, h] }, "colors": { "<id>": "#hex" }, "fonts": { "<id>": "Name" } }(boxes in % of the frame). Have your composition read these so the render includes them.OUT: the final file inexports/. Write here if your render already includes everything.RAW: a temp path. Write here instead and the server mixes the user's chosen music and levels into it to makeOUT.PROJECT: the project folder.
Progress comes from the last n/m pair the command prints (Remotion prints frame counts like this).
Without an export hook, Export still works: it copies the video and mixes in the music with ffmpeg.
9. Optional: other shapes and lengths (outputs)
The player makes cutdowns itself: + Cutdown renders a 9:16, 1:1 (or 16:9 from a vertical master) or a 6-second bumper from the master with ffmpeg, into outputs/<id>.mp4. A reframe follows crop keys the reviewer drags on the master (or a first guess from your element boxes, so keep box accurate), or fits the whole frame on a blurred fill. Each output gets its own tab, safe-area guides for Reels, TikTok and Shorts, and its own notes. You don't need to do anything for these.
When a code-built video looks better laid out again than cropped, render that version yourself and list it in reel.json:
"outputs": [
{ "id": "vertical", "label": "9:16", "kind": "reframe", "platform": "reels",
"src": "out/vertical.mp4", "w": 1080, "h": 1920, "duration": 12,
"audio": { "music": null, "videoAudio": "mix" }, // if the music is mixed into this file
"version": 1, // bump it when you render this output again
"review": [ /* findings on this version, placed on its own frame and clock */ ] },
{ "id": "bumper", "label": "6 s", "kind": "bumper", "src": "out/bumper.mp4", "duration": 6,
"ranges": [[0, 3.3], [9.3, 12]] } // which master seconds it is cut from
]
idis unique and stable;kindisreframe,bumper,renderorlang.w,handdurationdefault to the master's.- Scenes and elements are the master's. A bumper's scenes follow its
ranges; any other output keeps the master's clock. - An output you list replaces a player cutdown with the same id. The player won't re-render yours.
- Self-review per output: look at each output's frames too (captions under the platform UI, a logo cut off by the crop) and put findings in that output's
review.
10. Scenes: describe an idea, get an animation
When the user describes a scene in words ("a dev stuck on a slow render, a robot hands her an idea", "explain our pipeline", "an abstract intro for the launch") and doesn't need a code renderer, make a scene project: a folder with scene.json and no reel.json. You write data, not animation code. MotionSnip Studio draws it live in a hand-drawn style, builds the reel from it (shots become scenes, the cast and props become elements, every line of dialogue is editable) and runs its own checks, which show as self-review rings.
The loop:
- Pin down the idea in one line: who, what changes, what the viewer should feel.
- Pitch 2 or 3 visual metaphors in a sentence each (for example "the render bar as a mountain she climbs" or "a robot that hands over a lit bulb"). Let the user pick unless they asked you to just make it.
- Write
scene.jsonin a new folder and open the player on it:node "<skill dir>/player/server.mjs" "<folder>". - Look at it before you show it: scrub each shot, read the rings (lines too fast to read, a line cut off by the next shot, things off the frame, names that point at nothing) and fix them.
- Feedback works as for any project, except you edit
scene.jsonand bump itsversion. Lines name exact paths, likescene.json › shots[0].beats[1].text; a moved box says how many pixels to move that thing in that shot. Keep ids stable so notes and rings stay attached.
The format:
{
"title": "Idea to animation", "version": 1,
"size": [1920, 1080], "fps": 30, // the stage; positions are in these pixels
"style": { "preset": "ink" }, // ink | marker | flat; override "palette", "wobble", "stroke", "font"
"cast": {
"ana": { "kind": "person", "name": "Ana", "look": { "hair": "bun", "shirt": "accent" } },
"bolt": { "kind": "robot", "name": "Bolt", "look": { "body": "soft" } }
},
"props": {
"laptop": { "kit": "laptop", "text": "render 12%" },
"chart": { "kit": "chart", "data": [2, 3, 5, 9] },
"rocket": { "draw": "M0 40 L20 0 L40 40 Z", "fill": "accent" }, // any SVG path, scaled to fit
"logo": { "image": "assets/logo.svg" } // a file in the project
},
"shots": [
{ "id": "stuck", "name": "Stuck", "dur": 4.5,
"place": { "ana": [770, 885], "laptop": [930, 715] }, // bottom centre of each thing
"beats": [
{ "at": 0.3, "who": "ana", "do": "type", "dur": 1.4 },
{ "at": 1.5, "who": "ana", "do": "say", "text": "Another forty-minute render?" },
{ "at": 3.1, "who": "ana", "do": "emote", "as": "frustrated" } ] },
{ "id": "help", "name": "Help arrives", "dur": 5, "in": "fade",
"place": { "laptop": null, "bulb": [1180, 520] }, // null takes a thing off stage
"beats": [ { "at": 0.2, "who": "bolt", "do": "enter", "from": "right", "to": [1240, 885] } ] }
]
}
- Things keep their place from shot to shot unless
placemoves them. The floor is at 82% of the height (y 885 on a 1080 stage); people stand on it. - Palette names (
ink,paper,accent,soft,second) or any colour work wherever a colour goes. The player shows them asbrand.<name>. inis how a shot starts:cut(default),fade,wipe,pushormatch:<id>(the camera pushes into that thing and comes out of it in the next shot).camera: { "on": "ana", "zoom": 1.2 }frames a shot;tempoabove 1 makes everything in it quicker.- Kit props: laptop, phone, screen, doc, box, cloud, database, sign, chart, desk, plant, star, check, bulb, text (
size,bold), arrow (fromandto: ids or points,bend). Anything else isdraw(an SVG path) orimage.textwith{n}shows acountbeat's number. - Every beat has
at(seconds into the shot) and optionaldurandease(linear,in,out,inOut,back,spring).
| Verb | Fields | What happens |
|---|---|---|
walk, run | who, to (point or id) | Walks with planted feet; time comes from the distance |
enter, exit | who, from/to (left, right or a point) | Walks in from off stage, or out |
say, think | who, text | Speech or thought bubble, typed on; reading time comes from the words |
emote | who, as (happy, sad, surprised, frustrated, thinking, neutral) | Face and body |
point, look | who, at (id or point) | Points or turns toward it |
wave, cheer, type, nod, jump | who | Gestures |
pick, hand, put | who, what, to (hand: a person; put: a point) | Picks up, hands over, puts down, along an arc |
move | what, to, arc | Moves a thing |
pop, fade-in, draw-on | what | Appears: springs in, fades in, or draws itself on (charts grow) |
fade | what, to (0 hides it) | Fades |
grow, shake | what, to (scale) | Emphasis |
count | what, from, to | Rolls a number in its text |
camera | on (id or point), zoom | Moves the camera |
Plain words to fields: "slower" is a higher dur or a shot tempo below 1; "more bounce" is "ease": "back" or "spring"; "brand colours" is style.palette; "make it chalky / cleaner" is style.preset or wobble; "add a dog" is a new prop (draw path) placed in a shot; "she should notice the chart" is a look or point beat before the line.
Don't draw real people, logos or characters you don't have rights to. Export to video comes in a later version; for now the scene plays live in the player.