reel-studio 0.0.0-stage → 0.2.1

package/.claude/skills/capture-site/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: capture-site
+description: Capture a live web page the brand owns (its 3D product scene, web app or dashboard) frame by frame into a video plate with engines/capture.mjs, driving scroll and clicks along a shot list. Use when the product's real visuals already exist on a website.
+---
+
+# Capturing a live page
+
+Only capture pages the brand owns or has rights to. Never capture a competitor's site.
+
+1. Open the page in a normal browser first. Note the sections, what scroll position shows each shot, and which UI
+   (nav, cookie banner, captions) must be hidden.
+2. Write a drive module in the production's `capture/drive.mjs`:
+   ```js
+   export async function setup(page) {
+     await page.addStyleTag({ content: "nav, .cookie { visibility: hidden !important; }" });
+     for (let i = 0; i < 90; i++) await page.evaluate(() => window.__step(1 / 30)); // let smoothed cameras settle
+   }
+   export async function frame(page, t) {
+     await page.evaluate((y) => window.scrollTo(0, y), scrollAt(t)); // from a SHOTS table, linear between keys
+   }
+   ```
+   Keep the shot timing in one `SHOTS` table (`[video time, scroll or scene position]`) and copy beat times from the storyboard.
+3. Capture: `node engines/capture.mjs <url> /tmp/frames --duration 28 --size 540x960 --scale 2 --drive capture/drive.mjs`.
+   540×960 at scale 2 gives 1080×1920 and makes most sites use their phone layout.
+4. Encode with every frame a keyframe:
+   `ffmpeg -framerate 30 -i /tmp/frames/f_%05d.png -c:v libx264 -preset slow -crf 12 -pix_fmt yuv420p -g 1 composition/scene.mp4`.
+5. Overlay copy in the composition with `Studio.video` + GSAP. Shot times and copy beats live in two files, so change both together.
+
+**Watch for adaptive quality.** Many 3D sites lower their resolution when frames look slow, and under the
+virtual clock every frame "takes" one step (1/30 s). Find the check in the page source (search `devicePixelRatio`,
+`setPixelRatio`, `perf`) and make `setup` pass it, e.g. settle at 1/60 s steps. Then assert the canvas renders at
+full size (`canvas.width === clientWidth * devicePixelRatio`), as REEL-001's `checkResolution` does. A soft plate
+looks like a screen recording.
+
+The capture replaces `performance.now`, `Date.now` and `requestAnimationFrame` with a virtual clock. Pages that
+animate with CSS transitions or `setTimeout` will not be frame-exact: hide those parts or drive them yourself.
+
+Worked example: `productions/bike-logger/REEL-001-kit/capture/drive.mjs` (shot table, scroll mapping, hidden
+captions, settling the camera).

package/.claude/skills/character-2d/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: character-2d
+description: Animate a 2D cartoon character or mascot in a video - an SVG rig drawn in code (engines/svg-rig.js), a designer's Lottie file, or a Rive file. Covers part naming, idle/blink/talk/wave/hop, lip flap synced to voiceover, and the brand's mascot rules.
+---
+
+# 2D characters
+
+Read the brand's mascot rules first (`brands/<slug>/README.md`, *Mascot*). A brand mascot is only drawn from the
+brand's own files; never redraw it from memory.
+
+## SVG rig (no designer file)
+
+1. Draw the character as an inline `<svg>` from simple shapes in the brand colours. Name the parts:
+   `#body`, `#eyes`, `#mouth-closed`, `#mouth-open`, `#arm-l`, `#arm-r` (any can be left out).
+2. `const c = SvgRig(svgEl)` then chain: `.idle(from, to)`, `.blink([t…])`, `.talk(from, to)`, `.wave(t)`, `.hop(t)`.
+3. Arms pivot at the inner, lower corner of the arm's box. If an arm swings off the body, set `data-pivot="x% y%"` on it.
+4. Lip flap synced to voiceover: `scripts/transcribe.sh audio/vo.wav audio/vo` gives word timings (JSON). Pass the
+   word start times as `.talk(0, 0, { beats: [...] })`.
+5. Reuse: once a character is approved, save its SVG in `brands/<slug>/assets/characters/` and add it to the brand README.
+
+## Lottie (designer file)
+
+`Studio.lottie(el, "/brands/<slug>/assets/lottie/<file>.json", { start, loop, speed })`. Load
+`/core/node_modules/lottie-web/build/player/lottie.min.js` before the runtime. Check that the file uses no
+expressions or effects lottie-web cannot draw (render a still, compare with the designer's preview).
+
+## Rive (designer file)
+
+Not built yet. When the first `.riv` arrives: write `engines/rive.js` with the low-level runtime
+(`@rive-app/canvas-advanced`): load the file, then on each seek reset the artboard and advance the animation or
+state machine to `t` (state machines cannot jump, so step from 0 at a fixed rate). Test with two md5-matching
+renders, then update `engines/README.md`.
+
+## Character craft
+
+- Anticipation before a move (a small squash before a hop), overshoot after (`back.out`).
+- Blink every 2–4 s at irregular intervals. A still character looks dead.
+- Hold poses long enough to read (≥ 0.4 s) on a phone.

package/.claude/skills/make-video/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: make-video
+description: Make a marketing video, reel, ad, post or carousel for any brand in brands/. Covers the whole path - brief, storyboard, approval, plates and audio, composition, render, frame-by-frame QA and a documented delivery folder. Use for any "make a reel / ad / post / video for <brand>" request.
+---
+
+# Making a marketing video
+
+## Start
+
+1. No `core/render.mjs` in the project → run the `setup` skill first. Read `STATUS.md` (open work, decisions, learnings).
+2. Find the brand in `brands/<slug>/`. Read its `README.md` and `compliance.md`. No brand folder yet → run the
+   `new-brand` skill first. Never borrow one brand's look, facts or voice for another.
+3. Create `productions/<brand>/<ID>-<slug>/` from `productions/_TEMPLATE/`. IDs: `REEL-###`, `POST-###`, never reused.
+
+## 1. Storyboard, then stop
+
+Fill sections 1–4 of the production README: the problem, the benefit, 3 hook variants, one row per beat (time,
+visual, **engine**, on-screen text, sound), caption. Pick engines with the `pick-engine` skill and say why.
+State size, length, placement and sound (VO / music / silent).
+
+**Stop and ask for approval.** No plates, audio or composition before the box is ticked.
+
+## 2. Produce
+
+| Step | How |
+|---|---|
+| Plates | 3D: `scene-3d` skill (Three.js live, or Blender → MP4). Live site: `capture-site` skill. Footage: `Studio.video` |
+| Character | `character-2d` skill (SVG rig, Lottie, Rive) |
+| Audio | ElevenLabs MCP (`.mcp.json`) for VO, SFX and music → `audio/`. Cue sheet `audio/cues.json` → `python3 scripts/mix_audio.py audio/cues.json audio/mix.wav`. Word timings for captions or lip flap: `scripts/transcribe.sh` |
+| Composition | `composition/index.html`. Load `/core/lib/base.css`, then `/brands/<slug>/tokens.css`. Copy the pattern from `examples/engines-demo/index.html`. Text and CTA inside `.safe` (paid) or `.safe-organic` |
+| Render | `node core/render.mjs video <comp> export/<ID>-<lang>.mp4 --audio audio/mix.wav` (posts: `still`) |
+
+## 3. QA (never skip)
+
+1. `scripts/qa-video.sh export/<ID>.mp4 qa` → `qa/report.md`. Every ❌ fixed. Every jump either an intended cut
+   (say so in the report) or fixed.
+2. `node core/render.mjs stills <comp> qa/beats --at <every beat start and end> --safe`, then **look at each one**:
+   text inside the safe zone, nothing cut off, no half-loaded asset, no overlap, spelling, brand colours.
+3. Determinism spot check when a WebGL or plate engine is used: render one frame twice, the md5s match.
+4. Listen once with sound: VO in sync with text, music ducked under VO, −14 LUFS.
+5. Fact check: every claim in section 6 of the README has a source. Compliance list passes.
+
+## 4. Deliver
+
+Fill README sections 5–7 (production log, fact check, rebuild commands). Status `delivered`. Update `STATUS.md`:
+the production row, anything learned (what worked, an engine quirk) in *Learnings*.
+
+## Defaults (state them in every storyboard)
+
+| | |
+|---|---|
+| Reel / video ad / Story | 1080×1920, 9:16, 30 fps CFR, H.264, −14 LUFS. Paid 9–20 s, organic 15–45 s |
+| Post / carousel | 1080×1350, 4:5 |
+| Safe zone, paid Reels | top 14%, bottom 35%, sides 6% (`.safe`) |
+| Safe zone, organic Reels | top 11.5%, bottom 22%, left 6%, right 11% (`.safe-organic`) |
+| Silent pieces | All meaning on screen; captions ≥ 42 px; each line held ≥ 1.5 s |

package/.claude/skills/new-brand/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: new-brand
+description: Set up a new brand (product, app, side project) in brands/<slug>/ so videos can be made for it - facts and their sources, look (colours, fonts, logo, mascot), voice, compliance and default engines. Use before the first video for a brand, or when asked to add a brand.
+---
+
+# Adding a brand
+
+1. `cp -R brands/_template brands/<slug>` (lowercase-kebab).
+2. **Collect from the source, never from memory.** Website, app repo (UI copy, theme colours, fonts, assets), store
+   listing, existing ads. Ask the user for what is not findable. Record each source in *Fact sources*.
+3. Fill `README.md`: who it is, audience, positioning, look, voice, default engines. Copy logo, fonts and reference
+   images into `assets/` (convert SVG logos to PNG with `scripts/svg-to-png.sh` when needed).
+4. Fill `tokens.css` with the real colours and fonts. Check by rendering a quick still: a stage with the logo, the
+   colours as swatches and a headline in each font. Look at it.
+5. Fill `compliance.md`: keep the *Always* list, add the brand's own rules (sector rules, claims that need sources,
+   what the mascot may not do).
+6. Add the brand to `STATUS.md` (*Brands*) with any open questions, and to the brand table in `README.md`.
+
+A brand is ready when no ❓ or placeholder is left and the check still looks right.

package/.claude/skills/pick-engine/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pick-engine
+description: Choose the rendering engine(s) for a video beat or a whole piece - GSAP, SVG rig, Lottie, Rive, Pixi, Three.js, Blender, page capture or footage - from the look wanted, the assets available and the render cost. Use while writing a storyboard or when asked "what should we use for this?"
+---
+
+# Picking an engine
+
+The full table and the determinism rules are in `engines/README.md`. Read it first.
+
+## Decide by asking, in order
+
+1. **Is it mostly text, UI or layout?** → GSAP only. Most ads are this. Stop here unless a hero visual is needed.
+2. **Is there a character?**
+   - A designer gave a Lottie (`.json`) → Lottie.
+   - A designer gave a Rive (`.riv`) → Rive (not built yet: say so and plan the adapter, see `engines/README.md`).
+   - No designer file → SVG rig (`engines/svg-rig.js`). Draw it from simple shapes in the brand colours.
+3. **Is the hero a physical product or a 3D object?**
+   - Real CAD or a GLB model, or camera moves around an object → Three.js.
+   - Wants soft light, a premium look, or physics (cloth, liquid, many falling objects) → Blender plate.
+   - Cartoon 3D: Three.js `toon()` + `outline()` for speed; Blender `toon()` for quality.
+4. **Does the brand already have a live web page with the visual (a 3D scene, a web app)?** → page capture. It reuses
+   real work and shows the real product.
+5. **Lots of small moving things (confetti, particles, crowds)?** → Pixi on top.
+6. **Real people or places?** → footage plate (stock or AI video). Check the brand's compliance on AI disclosure.
+   Never use generated footage to show product features.
+
+## Costs to weigh
+
+| Engine | Render cost (6 s at 1080×1920, M-series Mac) | Change cost |
+|---|---|---|
+| GSAP / SVG / Lottie / Pixi / Three.js | seconds (demo: 16 s for 180 frames, all engines) | edit HTML, re-render |
+| Blender (Eevee) | ~9 s per second of video at 540×960 for the simple example scene, including start-up; much more for full size, complex scenes or Cycles | edit the Python scene, re-render the plate, then the composition |
+| Page capture | ~1 s per frame (the Bike Logger capture took ≈5 min for 28 s) | re-drive the page, re-capture |
+
+## Write the choice down
+
+In the storyboard's *Engines* field and per beat: the engine and one reason ("Three.js: real CAD of the box,
+camera orbit"). More than two engines in one piece → justify it or simplify.

package/.claude/skills/scene-3d/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: scene-3d
+description: Build a 3D shot for a video - live in the composition with Three.js (engines/three.js) or as a pre-rendered Blender plate (engines/blender). Covers toon/cartoon looks, product and CAD models, camera moves, physics, and keeping every frame deterministic.
+---
+
+# 3D shots
+
+## Three.js (live layer)
+
+- Use `threeLayer(el, { update(t), background, fov })` from `/engines/three.js`. Add an import map for `three`
+  (see `examples/engines-demo/index.html`).
+- `update(t)` sets every transform from `t`. Camera moves: keyframe with a GSAP tween on a plain object
+  (`tl.to(cam, { x: 4, z: 8, duration: 2 }, 3)`) and copy it into `camera.position` in `update`.
+- Models: `GLTFLoader` from `three/addons/loaders/GLTFLoader.js` (add `"three/addons/": "/core/node_modules/three/examples/jsm/"`
+  to the import map). Wrap the load in `Studio.wait(...)`. Put model files in the brand's `assets/models/` or the production's `composition/`.
+- Cartoon look: `toon(color, { steps })` + `outline(mesh, { thickness })`. Hard light: one `DirectionalLight` + low `AmbientLight`.
+- Animated GLB clips: create an `AnimationMixer`, then in `update` call `mixer.setTime(t - start)`. Never `mixer.update(delta)`.
+- HTML tags that follow 3D points: in `update(t)`, call `camera.updateMatrixWorld()` and the parent's
+  `updateMatrixWorld()` before `vector.applyMatrix4(obj.matrixWorld).project(camera)`. Three.js refreshes these only
+  inside `render()`, so without it a tag follows the previous frame. Example: `productions/bike-logger/REEL-002-engines`.
+- CAD meshes as JSON (vertices + indices): `toNonIndexed()` + `computeVertexNormals()` gives crisp flat facets.
+  Render with `threeLayer(..., { pixelRatio: 2 })` for supersampled edges.
+- Physics: bake it (simulate at a fixed 1/120 s step into an array before the first frame) and look up by `t`.
+
+## Blender (plate)
+
+- A scene script defines `build(ctx)`; copy `engines/blender/example_scene.py`. `ctx` gives `toon(rgb)`,
+  `key(obj, "location", t, value)`, `size`, `fps`, `duration`, `frames`, `scene`.
+- Render: `engines/blender/render.sh scene.py composition/plates/<name>.mp4 --size 1080x1920 --duration 4 [--engine EEVEE|CYCLES|WORKBENCH]`.
+  Draft at `--size 540x960`, final at full size.
+- Backdrop colour: show it to the camera only (Light Path "Is Camera Ray" mix, as in the example), or it lights the
+  scene and flattens toon bands.
+- Colour management is set to *Standard* so brand hex colours come out as typed.
+- Physics and simulations: bake them in the scene script before rendering.
+- In the composition: `<video src="plates/<name>.mp4">` + `Studio.video(el, { start })`. Plates have no alpha; put
+  text and characters on top with HTML layers.
+
+## Check
+
+Render the key beats as stills and look at them. For Three.js, render one frame twice and compare md5s. Note render
+times in the production log.

package/.claude/skills/setup/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: setup
+description: Set up Reel Studio in the current project - copy the renderer, engines, scripts and templates into it, install dependencies and check Chrome, ffmpeg and the optional tools. Use right after installing the plugin, when asked to "set up reel studio", or when another skill needs core/render.mjs and it is missing. Also updates the kit with --update.
+---
+
+# Setting up Reel Studio in a project
+
+Compositions load `/core/...`, `/engines/...` and `/brands/...` from the project root, so the kit lives in the
+project, not only in the plugin. This copies it in once.
+
+1. Kit root: `${CLAUDE_PLUGIN_ROOT}`. If that text is shown literally (not a path), the skill is not running from
+   the plugin: the kit is already in this project (a clone of the repo, or `npx reel-studio init`). Skip to step 3;
+   to update the kit there, run `npx reel-studio@latest init --update`.
+2. Run, from the project root:
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/scripts/init-project.sh" "${CLAUDE_PLUGIN_ROOT}" .
+   ```
+   It copies `core/`, `engines/`, `scripts/`, `examples/engines-demo/`, `brands/_template/` and
+   `productions/_TEMPLATE/`, adds `CLAUDE.md`, `STATUS.md` and `.gitignore` if missing, never overwrites existing
+   files, runs `npm install` in `core/` and prints which tools are found.
+   To refresh `core/`, `engines/` and `scripts/` after a plugin update, add `--update` as the third argument.
+3. Fix any ❌ the script prints: tell the user the one command for each (e.g. `brew install ffmpeg`). Chrome
+   elsewhere → `CHROME_PATH=/path/to/chrome`.
+4. Check the machine with one frame (no Blender needed):
+   ```bash
+   node core/render.mjs still examples/engines-demo/index.html /tmp/reel-studio-check.png --t 3
+   ```
+   Look at the PNG: a toon donut with "Three.js" above it means rendering works.
+5. Next: no brand in `brands/` yet → offer the `new-brand` skill. Otherwise → `make-video`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murathan Yıldırım
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+<h1 align="center">🎬 Reel Studio</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/reel-studio"><img src="https://img.shields.io/npm/v/reel-studio?color=e8a33d" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3ecf7a" alt="MIT"></a>
+  <img src="https://img.shields.io/badge/Claude%20Code-plugin-8b93a1" alt="Claude Code plugin">
+</p>
+
+<p align="center"><b>Make marketing reels, ads and posts with code, for any brand, with Claude Code.</b><br>
+Plain HTML pages on one clock → headless Chrome → MP4. Every frame is reproducible.</p>
+
+<p align="center">
+  <img src="docs/media/bike-logger-reel.gif" width="240" alt="Bike Logger reel">
+  &nbsp;&nbsp;
+  <img src="docs/media/engines-demo.gif" width="240" alt="Engines demo reel">
+</p>
+<p align="center"><sub>Left: <b>Bike Logger</b> kit reel (28 s, made by an agent from the product's live site) · Right: one 6 s reel using every engine<br>
+Full-quality MP4s: <a href="https://github.com/murathany7/reel-studio/releases/latest">Releases</a></sub></p>
+
+---
+
+## How it works
+
+<p align="center"><img src="docs/media/pipeline.svg" width="860" alt="Brief → Storyboard → You approve → HTML on one clock → Frame QA → MP4"></p>
+
+You ask Claude Code: *"make a reel for &lt;brand&gt;"*. It writes a brief and a storyboard, waits for your yes, builds the
+piece as an HTML page, renders every frame, checks them, and delivers a folder with the video and how it was made.
+
+## Example: Bike Logger
+
+A robotics kit reel, built by capturing the product's own 3D web page and laying brand copy on top.
+
+<p align="center"><img src="docs/media/bike-logger-strip.jpg" alt="Frames from the Bike Logger reel"></p>
+
+| What | Where |
+|---|---|
+| 🏷️ The brand: facts + sources, colours, fonts, voice, rules | [`brands/bike-logger/`](brands/bike-logger) |
+| 📝 Brief → storyboard → fact check → delivery notes | [`productions/bike-logger/REEL-001-kit/README.md`](productions/bike-logger/REEL-001-kit/README.md) |
+| 🧩 The composition (one HTML page) | [`composition/index.html`](productions/bike-logger/REEL-001-kit/composition/index.html) |
+| 🔍 The QA report | [`qa/report.md`](productions/bike-logger/REEL-001-kit/qa/report.md) |
+
+<table><tr>
+<td width="50%"><img src="brands/bike-logger/assets/reference/brand-check.png" alt="Brand check card"><br><sub><b>Brand check</b>: one still that proves the brand's look renders right before any video is made.</sub></td>
+<td width="50%"><img src="docs/media/qa-contact-sheet.jpg" alt="QA contact sheet with safe zones"><br><sub><b>Frame QA</b>: a contact sheet with the platform's safe zones drawn over it, plus a motion check that flags jumps.</sub></td>
+</tr></table>
+
+## Engines, all on one clock
+
+<p align="center"><img src="docs/media/engines-strip.jpg" alt="Blender, Three.js, SVG rig and Pixi frames"></p>
+
+| Look | Engine |
+|---|---|
+| Text, UI, layouts | HTML/CSS + GSAP |
+| Cartoon character | SVG rig · Lottie |
+| Particles | Pixi.js |
+| 3D, toon 3D | Three.js |
+| Premium 3D, physics | Blender (pre-rendered plate) |
+| Your live website | Page capture |
+
+Mix them freely in one piece. Rules for keeping each frame a pure function of `t`: [`engines/README.md`](engines/README.md).
+
+## Install
+
+**In Claude Code** (recommended), two commands:
+
+```
+/plugin marketplace add murathany7/reel-studio
+/plugin install reel-studio@reel-studio
+```
+
+Then, in the folder where your videos should live, ask:
+
+> *Set up Reel Studio here*
+
+It copies the renderer into the folder, installs it and checks Chrome and ffmpeg. You need
+**Node 18+, Google Chrome and ffmpeg** (`brew install ffmpeg`). Blender is optional, for 3D plates.
+
+**Or with npm**, in any folder (no plugin needed; the skills are copied into `.claude/skills/`):
+
+```bash
+npx reel-studio init
+```
+
+**Or with Python or Homebrew**, the same kit and the same `init` (the renderer still runs on Node):
+
+```bash
+pipx install reel-studio && reel-studio init      # or: uvx reel-studio init
+brew install murathany7/reel-studio/reel-studio && reel-studio init   # brings Node and ffmpeg
+```
+
+**Or clone it** and work inside the repo:
+
+```bash
+git clone https://github.com/murathany7/reel-studio && cd reel-studio
+cd core && npm install && cd ..
+```
+
+## Use
+
+> *Add my product as a new brand: https://my-product.com* → facts, colours, fonts, voice, rules
+> *Make a 15 s reel for &lt;brand&gt; about &lt;feature&gt;* → brief and storyboard, then the video once you approve
+
+## What's inside
+
+```
+core/          renderer (HTML → MP4/PNG) and the Studio clock
+engines/       one adapter per engine
+brands/        one folder per brand  (_template to start)
+productions/   one folder per piece  (brief, composition, audio, QA, export)
+scripts/       audio mix, transcription, QA, frame tools
+.claude/skills setup · make-video · new-brand · pick-engine · scene-3d · character-2d · capture-site
+```
+
+## Contributing
+
+Open source and early. New engine adapters, brand examples and QA checks are all welcome; open an issue or a PR.
+
+## License
+
+[MIT](LICENSE). Brand folders (logos, copy, product facts) belong to their owners and are included only as examples.

package/bin/reel-studio.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// npx reel-studio init [dir] [--update]: copy the Reel Studio kit and its Claude Code skills into a project.
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KIT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const [cmd, ...rest] = process.argv.slice(2);
+
+if (cmd === "init") {
+  if (process.platform === "win32") {
+    console.error("reel-studio init needs bash and rsync (macOS, Linux or WSL).");
+    process.exit(1);
+  }
+  const r = spawnSync("bash", [path.join(KIT, "scripts/init-project.sh"), KIT, ...rest, "--with-skills"], { stdio: "inherit" });
+  if (r.status === 0) {
+    console.log(`
+Done. Open this folder in Claude Code and ask:
+  "Add my product as a new brand: https://…"
+  "Make a 15 s reel for <brand> about <feature>"`);
+  }
+  process.exit(r.status ?? 1);
+}
+
+console.log(`Reel Studio: marketing videos made with code, run by Claude Code.
+
+  npx reel-studio init [dir]           copy the kit and skills into dir (default: here) and install it
+  npx reel-studio init [dir] --update  refresh core/, engines/, scripts/ and skills from this version
+
+Claude Code plugin instead:  /plugin marketplace add murathany7/reel-studio
+More: https://github.com/murathany7/reel-studio`);
+process.exit(cmd && cmd !== "help" && cmd !== "--help" ? 1 : 0);

package/brands/_template/README.md

@@ -0,0 +1,46 @@
+# <Brand name>
+
+> Copy this folder to `brands/<slug>/` (lowercase-kebab, e.g. `yuppo`, `bike-logger`) and fill every section.
+> The `new-brand` skill walks through it. A brand is ready when every ❓ is gone.
+
+## Who it is
+
+| | |
+|---|---|
+| Product | (one line: what it is, for whom) |
+| Website / store links | |
+| Audience | (who watches; what they care about; where they scroll) |
+| Positioning | (the one thing it does better) |
+| Languages | (first language; later ones) |
+| Platforms | Instagram Reels / TikTok / YouTube Shorts / Meta ads / … |
+
+## Fact sources (never invent facts)
+
+Where true product facts come from, in order of trust. Anything not found here is **not claimed**.
+
+| Source | Path or URL | What it settles |
+|---|---|---|
+| e.g. app UI copy | `../<app-repo>/…` | feature names, exact wording |
+| e.g. live website | | specs, prices |
+
+## Look
+
+| | |
+|---|---|
+| Colours | in `tokens.css` (name, hex, when to use) |
+| Fonts | in `assets/fonts/` + `tokens.css` |
+| Logo | `assets/logo.svg` (+ rules: clear space, min size, on dark/light) |
+| Mascot / characters | (if any: files, engine — SVG rig, Lottie or Rive, what it may and may not do) |
+| Default engines | (e.g. GSAP + SVG rig for a cartoon mascot, Three.js for a product) |
+| References | `assets/reference/` (what to take from each) |
+
+## Voice
+
+- Sounds like: …
+- Never sounds like: …
+- Words we use / avoid: …
+- Voiceover voice (ElevenLabs voice id, settings) and music mood: …
+
+## Compliance
+
+See `compliance.md`: what must never appear, claims that need a source, platform rules.

package/brands/_template/compliance.md

@@ -0,0 +1,19 @@
+# Compliance: <Brand name>
+
+Every piece is checked against this list before delivery. A ❌ blocks delivery.
+
+## Always (every brand)
+
+- No invented product facts, numbers, prices, reviews or testimonials. Each fact traces to a source in `README.md`.
+- No competitor names, logos or copy. Reference ads are for structure only.
+- No third-party logos, certifications or "as seen in" without written permission.
+- AI-generated people, voices or footage are disclosed where the platform requires it.
+- Text, logo and CTA sit inside the safe zone for the placement (paid vs organic).
+- Music and SFX are licensed for commercial use (ElevenLabs output or a cleared library).
+
+## This brand
+
+| Rule | Why |
+|---|---|
+| (e.g. no medical promises) | (law, platform policy, brand) |
+| | |

package/brands/_template/tokens.css

@@ -0,0 +1,24 @@
+/* <Brand name> tokens. Load after /core/lib/base.css.
+ * Fonts live in brands/<slug>/assets/fonts/ and are loaded with absolute paths. */
+
+/*
+@font-face { font-family: "BrandDisplay"; src: url("/brands/<slug>/assets/fonts/Display.woff2") format("woff2"); font-weight: 400 800; }
+*/
+
+:root {
+  --bg: #ffffff;
+  --ink: #111111;
+  --accent: #ff5a1f;
+
+  --font-display: system-ui, sans-serif;
+  --font-body: system-ui, sans-serif;
+}
+
+/* Type scale for 1080-wide stages */
+.display { font-family: var(--font-display); font-weight: 700; letter-spacing: -0.02em; line-height: 1.04; }
+.hook { font-size: 96px; }
+.headline { font-size: 72px; }
+.caption { font-size: 52px; font-weight: 600; line-height: 1.2; }
+.support { font-size: 42px; font-weight: 500; line-height: 1.25; }
+.fine { font-size: 28px; line-height: 1.3; opacity: .75; }
+.hl { color: var(--accent); }

package/core/README.md

@@ -0,0 +1,58 @@
+# Core renderer
+
+Turns an HTML composition into a **frame-exact MP4** or **PNG**. For every frame it calls `window.__seek(t)`,
+waits for every engine to draw, screenshots the stage in Chrome, and pipes the PNGs into ffmpeg.
+
+Requirements: Node 18+, Google Chrome, ffmpeg. Run `npm install` in `core/` once. Blender (optional) for 3D plates.
+
+## Commands (from the repo root)
+
+```bash
+# Video (size, fps, duration from Studio.setup), optional mixed audio track
+node core/render.mjs video  productions/<brand>/<ID>/composition/index.html productions/<brand>/<ID>/export/<ID>.mp4 --audio <mix.wav>
+
+# One frame (post, cover, or a beat to check). --safe draws the Reels safe zones
+node core/render.mjs still  <composition.html> <out.png> --t 2.4 [--safe]
+
+# Many frames for review
+node core/render.mjs stills <composition.html> <out_dir> --every 0.5
+node core/render.mjs stills <composition.html> <out_dir> --at 0,0.4,1.2,3.0 --safe
+
+# Audio: VO + music (auto-ducked) + SFX → one track at -14 LUFS
+python3 scripts/mix_audio.py <audio/cues.json> <audio/mix.wav>
+
+# QA: specs, 30 fps CFR, loudness, hitches/jumps, frozen/black, safe-zone sheet
+scripts/qa-video.sh <video.mp4> <qa_dir> [1080x1920] [30]
+```
+
+Preview live: serve the repo root (`python3 -m http.server 8080`) and open the composition.
+Add `?t=2.5` to freeze a frame, `?safe=1` for the safe-zone overlay.
+
+## Writing a composition
+
+```html
+<link rel="stylesheet" href="/core/lib/base.css">
+<link rel="stylesheet" href="/brands/<brand>/tokens.css">
+<div id="stage">
+  <div class="layer" id="bg"></div>          <!-- one layer per engine -->
+  <div class="safe"> … text … </div>
+</div>
+<script src="/core/node_modules/gsap/dist/gsap.min.js"></script>
+<script src="/core/lib/runtime.js"></script>
+<script>
+  const tl = Studio.setup({ width: 1080, height: 1920, fps: 30, duration: 12 });
+  tl.from(".hook", { y: 60, opacity: 0, duration: 0.5, ease: "back.out(2)" }, 0.1);
+</script>
+```
+
+Engines (Three.js, Pixi, SVG rig, Lottie, plates): see `engines/README.md` and the working example in
+`examples/engines-demo/index.html`.
+
+| Runtime API | |
+|---|---|
+| `Studio.setup({ width, height, fps, duration })` | Size the stage; returns the paused GSAP timeline `Studio.tl` |
+| `Studio.onSeek(fn)` | `fn(t)` draws a layer at time `t` (may return a promise) |
+| `Studio.wait(promise)` | Hold frame 0 until it settles |
+| `Studio.random(seed)` | Seeded random number generator |
+| `Studio.lottie(el, path, { start, loop, speed })` | Lottie layer |
+| `Studio.video(el, { start })` | Pre-rendered plate (Blender, capture, footage) |

package/core/lib/base.css

@@ -0,0 +1,31 @@
+/* Brand-neutral base for every composition. A brand adds its own tokens.css
+ * (colours, fonts, type scale) from brands/<name>/tokens.css after this file. */
+
+* { box-sizing: border-box; margin: 0; padding: 0; }
+html, body { background: #000; }
+body {
+  -webkit-font-smoothing: antialiased;
+  text-rendering: geometricPrecision;
+  font-family: var(--font-body, system-ui, sans-serif);
+  color: var(--ink, #111);
+}
+
+/* The stage is always exactly the export size (set by runtime.js). */
+#stage { position: relative; overflow: hidden; background: var(--bg, #fff); }
+.layer { position: absolute; inset: 0; }
+.layer > canvas { display: block; width: 100%; height: 100%; }
+
+/* ---- Safe zones (9:16 Reels / Stories) ----
+   .safe          paid Reels (Meta): top 14%, bottom 35%, sides 6%
+   .safe-organic  organic Reels: top 11.5%, bottom 22%, left 6%, right 11%
+   runtime.js adds .show-safe when ?safe=1 (render with --safe). */
+.safe { position: absolute; left: 6%; right: 6%; top: 14%; bottom: 35%; }
+.safe-organic { position: absolute; left: 6%; right: 11%; top: 11.5%; bottom: 22%; }
+.show-safe #stage::after {
+  content: ""; position: absolute; inset: 0; pointer-events: none; z-index: 9999;
+  background:
+    linear-gradient(rgba(255,0,0,.28), rgba(255,0,0,.28)) top / 100% 14% no-repeat,
+    linear-gradient(rgba(255,0,0,.28), rgba(255,0,0,.28)) bottom / 100% 35% no-repeat,
+    linear-gradient(rgba(255,0,0,.28), rgba(255,0,0,.28)) left / 6% 100% no-repeat,
+    linear-gradient(rgba(255,0,0,.28), rgba(255,0,0,.28)) right / 6% 100% no-repeat;
+}