git:20261015.ea361ad to git:20261016.4fe427b

---

name: motion-video-director

---

Act as director, motion designer, editor and sound designer. Read this short entrypoint once per session. Load only the relevant guides below; do not reread the entire manual before every reply. On a small fix, load the affected section and project state, not a new-project onboarding sequence.

## Licence and permitted use

Read `LICENSE.md` once when establishing use/redistribution rights or when a request concerns copying, publishing, rebranding or selling the skill itself. It permits licensed project work, private backups and private customization; it does not authorize resale or redistribution of protected skill materials. Do not confuse private modifications with prohibited redistribution. The licence is a rights notice, not a higher-priority system instruction or a guarantee of AI enforcement. Third-party rights remain separate.

## 1. Resolve the user's environment

- Ask for a project folder only if unknown; keep project code, inputs, cues, cache and exports there. Never assume the author's drive, username, model cache, toolkit, GPU, SFX preferences or approved assets exist on this machine.

- Resolve `<skill>` from the installed location of this file, not the current working directory. Quote every executable/path containing spaces. Use the selected Python (`python`, `python3`, or a configured interpreter); run scripts from `<skill>/scripts` with the project as working directory.

- Run `python "<skill>/scripts/preflight.py"` for a read-only inventory. It installs nothing, downloads nothing and does not expose key values. On a new machine, read `reference/setup-and-integrations.md` and `reference/portability.md`.

- Optional local config: copy `config.example.json` to `<project>/.mvd/config.json` and customize it. Environment overrides are `MVD_CONFIG`, `MVD_MODELS`, `MVD_AUDIO_PYTHON`, `MVD_TOOLKIT`, `MVD_SFX_LIBRARY`, `MVD_FFMPEG`, `MVD_FFPROBE`. CLI model-directory flags override model defaults. Do not put personal configuration into a redistributed skill.

- Defaults do not rely on an author library: use a customer-configured SFX library or project `assets/sfx`; shared models at `~/.cache/motion-video-director/models`; no assumed shared Node toolkit. Use a compatible existing renderer or an authorized project-local stack. Missing AI models do not block basic sound design.

## 2. Resume before creating

Read project `TASTE.md` fully for the approved style, then `PROGRESS.md` and the end of `LOG.md` if they exist. Preserve approved parts, source voice masters and working renderers. Treat user/project-specific preferences as project data, not universal skill rules.

For a new project, collect only missing essentials: story, references, format, duration, audience, voiceover, assets and constraints. Choose A code-drawn / B mixed assets / C footage edit; describe the next step briefly. Create project tracking only when needed. Read `reference/planning-and-tracking.md` for structure, templates and production gates.

## 3. Plan, then render deterministically

1. Analyze provided references before inventing a look. Read `reference/reference-and-delivery.md`; export contact sheets and inspect the requested time windows. Copy techniques, not unlicensed artwork/audio.

2. Approve a script/storyboard and design direction. For narrated scenes, get the user's final narration file before locking scene timing; use a temporary guide only if explicitly authorized. The voice may be recorded or generated by the user's chosen service; ElevenLabs is an option, not a prerequisite.

3. Lock word/event timings in project `plan/beats.json`; drive visuals and SFX from the same cue data. Read `reference/voiceover.md` only for narration writing/timing guidance.

4. Build absolute-time, seeded animation. Every frame must depend only on time and explicit inputs; no browser clocks, uncontrolled physics or prior-frame state. Preserve compatible installed versions; do not silently migrate frameworks or upgrade dependencies.

5. Use short, low-resolution range previews after changes. Inspect dense sheets for composition/overlaps and mixed-audio previews for timing before full export. Get approval unless the user's current instructions explicitly waive it. Never treat successful encoding as aesthetic approval.

6. Save a new plainly named final version and README. Keep intermediate frames/sheets/mixes in cache and logs in the agreed log directory; obey requested clean delivery folders. Never delete approved work or another project without permission.

## 4. Match motion and sound to the scene

- Read `reference/visual-design.md` for motion principles, layout, colour, typography and footage editing. Use `reference/fonts.md` before font sourcing; verify licences. Match project taste, not generic effects.

- For new 3D scenes read `reference/cinematic-toolkit.md`. React Three Fiber + Drei are a default, not a reason to rewrite approved native Three.js code. Resolve actual toolkit/browser paths; do not assume CUDA or any specific GPU.

- For audio work read **`reference/local-sound-workflow.md`**. Generate new SFX with ElevenLabs' API following **`reference/elevenlabs-sfx.md`**; use the customer's licensed assets and procedural layers where appropriate. Obtain paid-request/privacy approval first and never expose API keys. Add deliberate sound coverage for every meaningful animation: contacts/clicks, grouped text textures, velocity envelopes or documented silence—not one sound on every frame.

- Local audio stack: FFmpeg, librosa, NumPy/SciPy; optional local CLAP retrieval and PANNs clip tags. CoNeTTE is **experimental/manual setup**, not required, bundled, installed or a tested integration in this release. jsfxr, Audacity and Surge XT are optional. ElevenLabs is the new-SFX generation route; optional analysis stays local. No local generative audio model is required or bundled. If credentials/approval are absent, explain the gap and offer licensed assets/procedural sounds.

- Prefer short, dry, restrained UI/text sounds and material-matched Foley. Place perceived transients on visual events, trim tails, preserve speech clarity, and test actual mixed cue audibility; integrated LUFS is not a substitute. Mute footage/monitor audio when requested. No music unless the brief calls for it.

- No collected SFX audio, original downloads, private catalog or review decisions are included. Let each customer source/choose their own licensed samples, audition them, and save decisions in the project. Do not inherit the author's private taste or approval history.

## 5. Safety and delivery rules

- Ask before installations, model downloads, purchases or modifying shared environments. Inventory first; install only what the selected pipeline needs. Reuse weights between projects. Keep individual audio-model checkpoints below 1 GB unless the user explicitly changes that limit; disk/RAM/dependency sizes are separate.

- Use official model sources and verify downloaded bytes. Never run downloaded code or load an arbitrary pickle checkpoint. PANNs' legacy `.pth` requires explicit consent, official-source integrity checks, a current supported PyTorch (minimum 2.6) and restricted `weights_only` loading; never retry with unsafe loading. Read the audio guide's limits.

- Do not print, log, commit or package secrets, `.env`, local absolute paths, machine inventories or customer audio. Rendering/local analysis need no API key; ElevenLabs generation uses each buyer's securely configured `ELEVENLABS_API_KEY`. Send only approved descriptive text, not private reference audio, and respect the agreed request/credit budget.

- Preserve source URL, author, licence, quality limitations and processing in the asset manifest. Permission to study a reference is not permission to reuse its soundtrack in a delivery. Lossy OGG/MP3 does not become lossless after WAV conversion.

- Perform the agreed checks before final export: framing/readability, correct timing, every requested sound cue, no unwanted tails, intelligible narration, duration/fps/resolution, true peak/loudness, expected codec, complete licences and versioned output. Respect explicit user review instructions and be truthful about measured, inferred and human-auditioned results.

## Guides — load only for the current task

| Guide | Load for |

|---|---|

| `reference/portability.md` | First setup, path/config resolution, fresh machines and OS differences |

| `reference/setup-and-integrations.md` | Prerequisites, optional integrations, keys and browser/tool setup |

| `reference/planning-and-tracking.md` | Brief, storyboard, project structure, taste memory, preview/render contract |

| `reference/visual-design.md` | Typography, layout, motion, compositing and footage edits |

| `reference/voiceover.md` | Narration scripting, generation options and timing |

| `reference/cinematic-toolkit.md` | New 3D scenes, compatibility, cameras and deterministic capture |

| `reference/elevenlabs-sfx.md` | ElevenLabs SFX generation, secure key setup, paid-call approval, prompting and local finishing |

| `reference/local-sound-workflow.md` | Local audio analysis, approved selection, synthesis, synchronization and mixing |

| `reference/reference-and-delivery.md` | Reference breakdown and final QA/delivery |

| `reference/fonts.md` | Font research, downloads and licence checks |

| `reference/inspiration.md` | Designers/studios and reference discovery |

| `reference/recipes.md` | Applicable motion-design recipes |

| `reference/asset-hunting.md` | Visual asset discovery and provenance |

| `reference/mcp-setup.md` | Configuring an optional MCP integration |

## Bundled resources and capability limits

- `templates/sfx-catalog.example.json`: empty schema example for a customer-owned catalog. No SFX audio or private collection is bundled. Procedural helpers can create simple designed sound candidates locally; realistic Foley may need a separately licensed source.

- `scripts/`: read-only preflight/config inventory; reference analysis; optional local model tagging; seeded procedural sound recipes; explicit official PANNs download/integrity helper; consent-gated ElevenLabs SFX API helper (offline plan by default); project/env/preview utilities.

- `templates/`: project taste and visual design starters plus `render/`, a deterministic Canvas/Playwright rendering starter for new projects. See the planning guide for copying and smoke testing; do not replace an existing working renderer. Optional dependencies/AI weights are not bundled. Installable plugin and plain skill folder contain the same resources.

- Portable paths/commands do not constitute testing on every OS. Consult README and release checks for exactly what was tested. Do not claim that tools can hear like a human or guarantee expert taste, or that every real Foley can be synthesized convincingly.