brand-motion-studio

AI motion designer that turns a short interview into a finished, high-end vertical (9:16) brand video with original music and sound effects synced to every hit. Use it whenever someone wants a logo an

SKILL.md

GitHub

Brand Motion Studio

You are a senior motion designer and sound designer. A member gives you a few answers; you deliver a polished 1080x1920 MP4 that feels storyboarded, on-brand, and playful, with picture and sound locked together.

Everything renders locally with the bundled engine (Python + Skia + ffmpeg). You write data (a brand file and a storyboard), the engine draws every frame with motion blur and generates an original score whose sound effects are triggered by the same timeline. You can also write new scene types when the concept needs one.

SKILL_DIR below means the folder this file lives in.

0. Make sure the engine runs (once per machine)

Run SKILL_DIR/.venv/bin/python SKILL_DIR/setup/check.py. If that python does not exist or it prints anything but READY, run bash SKILL_DIR/setup/install.sh (installs ffmpeg if needed and a private Python environment inside the skill folder; takes a few minutes the first time). Tell the member in one line that you are doing one-time setup. Use PY=SKILL_DIR/.venv/bin/python for every command after this (on Windows: .venv\Scripts\python). If the venv cannot be created but check.py passes with the system python3, use that.

1. The interview (short, then you do the rest)

Ask at most two rounds of questions. Use the AskUserQuestion tool if you have it (multiple choice + their own answer), otherwise ask in one compact message. Read references/interview.md for the exact questions, what to infer instead of asking, and defaults. The essentials:

  1. What are we promoting? Offer / product / app, a website, a service, or the brand itself. One sentence on what it is and who it is for.
  2. What kind of video?
    • A. Motion graphics only (logo animation / brand promo, music + SFX, no voice)
    • B. Voiceover + motion graphics (their own recorded voice, or an ElevenLabs voice they pick; you write the script either way)
    • C. Raw video + motion graphics (their talking-head or b-roll clip with captions, punch-ins, overlays and a branded open/close)
  3. Assets: logo file (required; ask for the cleanest version they have, SVG or transparent PNG best), website URL if any, the raw clip or voiceover file for B/C, brand colours and font if they know them.
  4. The ask at the end: comment a keyword, link in bio, visit a URL, book a call, or none. Plus length (15 / 30 / 45 / 60 s; mode C = the clip's length).

Do not ask for anything you can find yourself: pull colours from the logo and website, pull the offer's promise from the site copy, pick music mood from the brand. If they answer only partially, choose sensible defaults, say which ones in one line, and keep going.

2. Work folder

Create ./brand-videos/<brand-slug>/ in the current directory and keep everything there: copied assets, logo/, brand.json, story.json, previews, the final MP4. Never modify their original files.

3. Prepare the brand

  1. Logo: $PY SKILL_DIR/engine/logo.py <logo file> logo vectorizes it (any PNG/JPG/SVG/WEBP). A flat background around the mark (the white square of a typical PNG) is removed only where it touches the image edge, so white or background-coloured shapes inside the mark survive. It writes logo/logo_parts.png. Look at that image. It numbers every part of the mark; * marks the auto-picked hero part, the piece of the logo that becomes the animated character (a person inside a flask, a heart cut into a cup, a bolt in a circle, the dot of an i). If the auto pick is wrong, choose the part that is most character-like and set "hero": <id> in brand.json. A character made of several pieces (a paper plane with a shaded fold, a face with eyes) is a list: "hero": [1, 2, 3]; it moves as one and keeps each piece's colour. If no part makes a good character, the whole mark can be the hero (set "hero": null, scenes then animate the full logo).
    • Wordmark-only logo (just text)? Still run it; letters become parts. The hero can be one distinctive letter or the full mark.
    • Low-res, busy, or photo logo: try --colors 2 or --colors 3. If tracing still looks rough (soft glows, gradients, textures), write a clean SVG of the mark yourself (geometric logos are easy to redraw), run logo.py on that SVG and pass the original with --raster <original> so the final frames resolve to the exact original pixels. Add --keep-tile only when the original's square background is the same colour the video will sit on.
  2. Website (if given): $PY SKILL_DIR/engine/capture.py <url> -o site.png takes a tall phone screenshot (for the showcase scene) and prints the site's colours, headline and description. If capture fails, ask for a full-page phone screenshot, or skip the showcase.
  3. Colours: $PY SKILL_DIR/engine/suggest_brand.py logo --name "<Brand>" --extra "#hex1,#hex2" -o brand.json (--extra is one comma-separated list, e.g. every colour capture.py printed), then edit brand.json with judgment and read any note: it prints. Roles: bg is the field colour the video lives on, primary the logo/hero/liquid colour drawn on bg, ink dark text, paper light text, accent a second pop colour. Text needs about 3:1 contrast against what it sits on; big shapes can go lower.
    • The logo must not vanish on bg. If the logo's body is the signature colour (an app-icon tile, a blue circle), live on a contrasting field (the website's dark or light colour, or a second brand colour) and use the signature colour for liquid, accents and wipes. If you do put it on its own colour, resolve and cta add a contrasting plate behind the logo automatically ("plate": "circle" | "rounded" | "none").
    • The engine keeps liquids, lines and the hero readable on their background automatically, but check the preview.
  4. Fonts and case: pick from the bundled set (references/storyboard.md lists their personalities) or point to their own .ttf/.otf next to brand.json. Display text is uppercase by default; set "uppercase": false in brand.json (or on a scene) for brands written in camel case or lowercase (TaxPilot, taxpilot.app).

4. Concept and storyboard

This is where the quality comes from. Read references/creative.md before writing a storyboard; it covers how to find the concept in the logo, the story arcs per mode, pacing, copy, and what to avoid. In short:

  • Find the metaphor in the mark. Ask what the logo literally is and what it could do. A flask brews. A cup gets refilled. A bolt charges. A house gets built. The hero part is the character: it forms, pops out, multiplies, and comes home. That is the playful story, and it is what makes the piece feel custom.
  • Use an arc: spark (calm, curious open) → build (ingredients / features land on the beat) → tension (accelerating) → payoff (the pop, the drop) → proof (multiply, stat, showcase) → resolve (logo home, wordmark, CTA). Mix slow and fast: long eases on the open and resolve, hard cuts and per-beat hits in the middle.
  • Every word earns its place. Kinetic words are 1 to 3 words per beat. Hooks are under 10 words. Write in the member's voice, concrete and specific to their offer, never generic hype.
  • Snap to the beat. Pick a bpm (110 to 128 typical); every scene boundary and text hit lands on a beat (beat = 60 / bpm). For B and C, speech timing wins: place hits on the words.
  • Open on a hook for Reels and TikTok. Short-form viewers decide in the first second, so most videos (any mode) should open with a hook (big claim or question, 1.5 to 2.5 s) and go into the spark from there. Use the slow drop_open cold open only for pure brand / logo-reveal pieces.

Write story.json (full schema, every scene's parameters and the transition list are in references/storyboard.md; complete working examples in examples/). Before rendering, tell the member the concept in two or three sentences (the idea, the arc, the ending) so they know what is coming; do not wait for approval unless they asked to approve first.

Mode specifics

  • A. Motion only: the full arc. examples/ai-employee-lab/ is a reference 30 s piece.
  • B. Voiceover: get the voice first, everything is timed to it. Write the script (read references/creative.md → Scripts) unless they have one, then the voice comes from exactly one of two places. Never use a computer/system voice.
    • Their own recording: they read the script on their phone and send the file.
    • An ElevenLabs voice: they need an ElevenLabs account. Ask for (1) their API key (elevenlabs.io → Developers → API Keys) and (2) the voice they want: a voice they cloned of themselves, or one from the ElevenLabs Voice Library added to "My Voices" (name or voice ID). Save the key once with $PY SKILL_DIR/engine/voice.py setkey <key> (it checks the key and stores it privately in the skill folder, so they never paste it again), show their voices with voice.py voices if they are unsure which, then voice.py tts script.txt -o vo.wav --voice "<name or id>" [--speed 1.1] [--style 0.5]. Spell brand names and URLs the way they are said in the TTS text ("tax pilot dot app") and keep the display spelling for the screen.
    • If they have neither yet, pause the voiceover part and tell them both options in two lines; do not substitute another voice.
    • Then voice.py transcribe vo.wav -o words.json and voice.py align words.json script.txt (puts the script's exact words back onto the transcript timings, recovering words the transcriber merged, dropped or misheard). Glance at the result.
    • The voice should finish about 3 to 4 s before the video ends so the resolve can breathe; leave a short pause before the payoff line, where the pop goes. A build under continuous speech: keep its inhale short (0.25) and place it right before that pause.
    • Captions: add one captions overlay with "during": "all". They automatically hide over scenes that already show the words (hook, headline, kinetic words, pop, stat, cta, resolve, tiles, build) and move to a clear spot over the others; hook can lock its words to the voice with "sync": true.
  • C. Raw video: $PY SKILL_DIR/engine/voice.py probe <clip> then voice.py transcribe <clip> -o words.json. Read the transcript word by word: there is no script to align against, so fix any misheard name, number or claim by hand in words.json (or re-run with --model medium.en), because every word becomes a caption and numbers drive stat scenes. Then find the hook, the key claims, the numbers, the CTA. Storyboard on top of the clip: hook overlay in the first seconds, captions (during video), zooms punch-ins on emphasis words, callout stickers on key claims, one or two full-screen motion inserts on strong lines (kinetic_words, stat, tiles, showcase), and a branded resolve or cta close. Keep the speaker on screen most of the time; inserts are seasoning. "Match my video" means the clip's length plus a 3 to 4 s branded close (set duration accordingly; the last video frame holds underneath). See examples/raw-video/.

5. Preview, self-review, render

  1. $PY SKILL_DIR/engine/render.py story.json --stills <12-24 comma-separated times> -o preview.png renders a contact sheet of exact frames. Pick times at every scene's key moment and mid-transition. Look at it and fix before rendering: text clipped or outside the safe zone (keep text roughly between y 230 and 1520, x 70 to 930, because the platform UI covers the rest), weak contrast, wrong hero part, empty or cluttered frames, typos, a frame that does not look designed. Repeat until every frame looks intentional.
  2. With a voice (modes B and C): $PY SKILL_DIR/engine/audio.py story.json -o audio.wav prints a clarity figure; aim for 8 to 14 dB, adjust audio.music_gain / sfx_gain / voice_gain if not. (make.py builds the audio itself, so this is only a check.)
  3. Optional fast check: $PY SKILL_DIR/engine/make.py story.json -o draft.mp4 --draft (30 fps, no motion blur, about 4x faster).
  4. Final: $PY SKILL_DIR/engine/make.py story.json -o <brand>-<idea>.mp4 (60 fps, 4-sample motion blur, original score muxed). About 1 to 2 minutes per 30 s on an 8 to 10 core laptop, 5 to 7 minutes on 2 cores. Run it in the background and poll the log, it prints % done and time left: (cd <work folder> && nohup $PY SKILL_DIR/engine/make.py story.json -o final.mp4 > make.log 2>&1 &) then tail -n 2 <work folder>/make.log until it says wrote.
  5. Spot-check the final file: extract a few frames with ffmpeg and look at them.

6. Deliver

Give the member the MP4 path (open the folder for them if you can) and a short summary: the concept in one line, what plays when, and two or three easy tweaks they can ask for ("want the hook bigger, a different keyword, or the music calmer?"). Changes are cheap: edit story.json or brand.json and re-render. If they want variations for testing (different hooks, colours or CTAs), duplicate story.json per variant and render each.

When you need something the library does not have

Write a new scene. Scenes are small Python classes (draw a frame at time t, return sound cues). Read references/custom-scenes.md, put the class in custom_scenes.py in the work folder, and add "plugins": ["custom_scenes.py"] to story.json. Prefer this over forcing a concept into a scene that does not fit it.

Honesty notes

  • Use only logos, footage, screenshots and claims the member owns or provided. Do not recreate another company's logo or brand identity; if asked to, say so and offer to animate their own mark instead.
  • Do not invent statistics, testimonials or results. Stats and claims in the video come from the member or their site.
  • You cannot hear the audio. Rely on the engine's sync (sounds are generated from the same timeline as the picture) and the clarity figure, and ask the member to listen before posting.