reel-studio
Make short branded explainer and promo videos (TikTok, Reels, Shorts, square, landscape or embedded in a web page) entirely on this machine, for free, with no paid video or voice service. A script of scenes plus a brand file becomes a voiced MP4 with animated UI mock-ups, step flows, diagrams, bar charts, word-by-word captions, music and sound effects, plus caption files and a small web copy with a poster. Use whenever the user wants a TikTok, Reel, Short, promo video, explainer video, product demo video, ad, or "a video for social media" or for a web page, for any project or brand, or wants to re-cut, re-voice or restyle a video made this way.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 21 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/VinVirtual/reel-studio with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/VinVirtual/reel-studio'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/vinvirtual--reel-studio)HTML
<a href="/listings/vinvirtual--reel-studio"><img src="/api/listings/vinvirtual--reel-studio/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# 1. the skill itself (for Claude Code; any folder works if you only use the command line) git clone https://github.com/VinVirtual/reel-studio ~/.claude/skills/reel-studio # 2. voice: a Python venv with Kokoro, and the two model files python3 -m venv ~/kokoro/.venv ~/kokoro/.venv/bin/pip install kokoro-onnx soundfile numpy imageio-ffmpeg curl -L -o ~/kokoro/kokoro-v1.0.onnx https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.onnx curl -L -o ~/kokoro/voices-v1.0.bin https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/voices-v1.0.bin # 3. renderer: Playwright, and a browser if you have no Chrome npm i -g playwright-core npx playwright-core install chromium # optional when Google Chrome is installed; a good fallback either way # 4. check ~/.claude/skills/reel-studio/reel check
`imageio-ffmpeg` brings its own ffmpeg binary. Leave it out if you already have ffmpeg on your PATH.
Everything is found in default places that you can change with environment variables:
| Variable | Default | What | |---|---|---| | `KOKORO_HOME` | `~/kokoro` | folder with the model files and the `.venv` | | `KOKORO_MODEL`, `KOKORO_VOICES` | `$KOKORO_HOME/kokoro-v1.0.onnx`, `$KOKORO_HOME/voices-v1.0.bin` | the two model files | | `REEL_PYTHON` | `$KOKORO_HOME/.venv/bin/python`, else `python3` | Python that has kokoro-onnx | | `FF` | `ffmpeg` on PATH, else the one from imageio-ffmpeg | ffmpeg binary | | `PLAYWRIGHT_CORE` | found through node and `npm root -g` | folder of playwright-core | | `REEL_CHROME` | installed Chrome, then other browsers found, then Playwright's Chromium | browser binary to try first |
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 139 lines
- ---
- name: reel-studio
- description: Make short branded explainer and promo videos (TikTok, Reels, Shorts, square, landscape or embedded in a web page) entirely on this machine, for free, with no paid video or voice service. A script of scenes plus a brand file becomes a voiced MP4 with animated UI mock-ups, step flows, diagrams, bar charts, code and terminal panels, timelines, word-by-word captions, music and sound effects, plus caption files and a small web copy with a poster. Use whenever the user wants a TikTok, Reel, Short, promo video, explainer video, product demo video, ad, or "a video for social media" or for a web page, for any project or brand, or wants to re-cut, re-voice or restyle a video made this way.
- ---
- # reel-studio
- Local pipeline: **Kokoro TTS** (voice) → **timeline** (word timings) → **canvas engine** in headless Chrome (each frame is a pure function of t) → **ffmpeg** (H.264 + AAC). Output is 30 fps, CRF 17, ready to post. It makes motion graphics from a script. It is not a generative video model.
- Skill folder: `~/.claude/skills/reel-studio/` (written below as `$R`). Every command is `$R/reel <command> <project> [script]`. `$R/reel help` lists them.
- ```
- $R/reel the command line (check, themes, new, lint, audio, sheet, stills, video, web, captions, preview, build, test)
- $R/engine/gen_audio.py voice + timings + music/SFX mix (run by `reel audio`)
- $R/engine/engine.js layout, captions, brand, drawing helpers
- $R/engine/scenes*.js the scene types
- $R/themes/ ready-made brand files (ember, midnight, paper, poster, pastel, terminal)
- $R/examples/ finished scripts with their rendered videos
- $R/engine/lib/ rendering, lint, batch build, caption files
- $R/templates/ brand.json, script.json (shows every scene type except image and custom), custom.js
- $R/references/scenes.md every scene type and its fields
- $R/README.md install, licences, limits
- ```
- ## Workflow
- 1. **Check the machine** with `$R/reel check`. It tells you how to fix anything missing, and whether a browser really starts.
- 2. **Scaffold** with `$R/reel new <dir>`. Put the project next to the user's other marketing files, not inside an app repo unless they ask.
- - `$R/reel themes` lists six ready-made looks. `$R/reel new <dir> --theme paper` starts from one, and `--format square` sets the shape. Pick the theme that suits the subject (for example `terminal` for developer tools, `paper` for calm explainers, `poster` for loud promos), then change its colours to the brand's.
- 3. **Brand** (`brand.json`):
- - Set colours, fonts, wordmark or `logo`, `format`, voice and pronunciations.
- - `format` is `vertical` (1080×1920) | `square` (1080×1080) | `landscape` (1920×1080) | `embed` (1920×1080 with type 1.2× larger, for a video that sits in a web page column).
- - `logo` is a project-relative PNG and should have a transparent background. Otherwise its box shows on the CTA card. Use the text `wordmark` when there's no good logo file.
- - Take colours from the product's real design tokens if a codebase exists.
- - Add brand names that the voice will mispronounce to `pronounce` (regex → spoken spelling).
- 4. **Script** (`script.json`):
- - Write it with the user, following the "Writing the script" rules below.
- - Pick a scene `type` for each beat from `references/scenes.md`. Write `custom.js` only when no built-in type fits.
- 5. **Lint**: `$R/reel lint <dir> [script]`. Fix every `error` before going on.
- - It reports `at` and `keys` words that are not in `say`, text over the length guide, missing image and font files, unknown scene types and fields, and bad values.
- - It then lays every scene out in the real engine (no voice needed) and reports content that overflows the body area, runs into the captions or off the frame, and text that overlaps.
- - It warns (`contrast`) when a text colour in brand.json is hard to read on the colour behind it.
- 6. **Voice**: `$R/reel audio <dir> [script]`. It prints each scene's start time and voice length, and writes `out/<script>.vtt` and `.srt`. Phrases that have not changed are reused, so a second run is quick.
- 7. **Review**:
- - Run `$R/reel sheet <dir> [script]`, then **Read the sheet PNG**. It shows one frame per scene, taken after the scene's last word.
- - Check for overlaps, text under captions, cut-off text, and anything outside the safe area.
- - For a closer look, run `$R/reel stills <dir> [script] 3.2 7.5`.
- - Fix the problems and re-render the sheet. Always look before rendering video.
- - For quick iteration, `$R/reel preview <dir> [script]` serves a local page that plays the video with its voice and a scrub bar, with no rendering. It reloads when the script or brand changes. A changed `say` line still needs `reel audio`. It does not replace reading the sheet.
- 8. **Render**: `$R/reel video <dir> [script]`. This takes about half a second of rendering per 1 s of video on a machine with 8 or more cores (frames are drawn in up to 4 browser pages at once).
- - It writes `out/<script>.mp4` (voice, SFX and music), `out/<script>-voiceonly.mp4` (voice and SFX only, for laying a trending sound over in the app), `out/<script>.vtt` and `out/<script>.srt`.
- - Add `--web` (or run `$R/reel web <dir> [script]` afterwards) for a web copy in `out/web/`: a small 720p faststart MP4 (CRF 27, mono 64k audio), a poster JPEG drawn without captions, and the `.vtt`.
- 9. **Verify and deliver**:
- - Check streams and length with ffmpeg (`$FF -i out.mp4 -af volumedetect -f null -`). Mean volume around −20 to −24 dB is right.
- - Send the file to the user (SendUserFile if available).
- - Include a ready-to-paste caption and hashtags, plus a list of every factual claim the video makes, for the user to confirm.
- Several videos in one project: name scripts `customers.json`, `vendors.json` and so on, and pass the name to each command. They share `brand.json`. Build them all with one command:
- ```
- $R/reel build <dir> [script ...] --jobs 3 --web
- ```
- The same script in another shape: add `--format vertical|square|landscape|embed` to `lint`, `sheet`, `stills`, `video`, `web`, `build` or `preview`. brand.json is not changed, the files are named `<script>-<format>` (for example `out/script-square.mp4`), and the voice is shared. Lint and read the sheet for each shape: a layout that fits one shape can overflow another. Do not name a script `<other>-<format>` (such as `promo-square.json`): its files would collide with `promo --format square`, and the command refuses to run.
- `build` runs voice and video (and the web copy with `--web`) for every script in the project, or only the ones named. It skips a script whose inputs have not changed (`--force` rebuilds), carries on past a failure, prints a summary, and exits non-zero if anything failed. Each script's output is in `build/<script>.build.log`.
- ## Writing the script
- - **30–45 s, 6–10 scenes.** Each scene has one idea and one sentence or two short ones.
- - **The hook comes first** (`title` type): a question or a "you know this pain" line, said within 2 s. No logo intro.
- - A strong format for promos is **problem → fix pairs**:
- - Set `tone: "problem"` (red tag, thud SFX, red progress segment) or `tone: "fix"` (green tag, chime, accent headline).
- - Give both scenes of a pair the same `step` number, which drives the progress bar.
- - For explainers, show the structure: `steps` for a sequence or a loop, `diagram` for what connects to what, `bars` for a few numbers, `timeline` for dated or ordered milestones, `compare` with `variant: "neutral"` for two things side by side.
- - For developer videos, use `code`: a terminal (`variant: "terminal"`) for commands and their output, or an editor for a few lines of a file, with `highlight` on the line that matters. Keep it to about 12 short lines.
- - `keys` are the words highlighted in the captions. Use 1–3 per scene, written exactly as they appear in `say`, including punctuation (for example `"confirms."`).
- - Use `at: "word"` on items, buttons, steps, nodes, bars, code lines and milestones so things appear exactly when that word is spoken.
- - **End on a CTA with an action** ("Tag a friend who…", "Comment X", "Link in bio", "Read the full note"). Put the URL on screen.
- - **On-screen text is short**: headlines are 4 words or fewer (the hook and CTA title 6 or fewer), list items 5 or fewer, tags 4 or fewer, chips and diagram or bar labels 3 or fewer. The voice-over carries the detail. Lint warns when text is longer.
- - **Claims:** never invent prices, stats, reviews, ratings or features. Made-up terminal output and dates count too: tag them `EXAMPLE OUTPUT` or `EXAMPLE DATA`. Use the user's real numbers, or mark mock-up data as an example on screen and tell the user. Avoid real people's or other businesses' names in mock chats and cards unless the user supplies them.
- ## Safe areas (vertical 1080×1920)
- TikTok and Reels cover the top ~200 px (tabs), the bottom ~470 px (caption and audio bar) and the right ~120 px (like/comment rail). The vertical layout already keeps the tag, title, body (y 640–1250) and captions (baseline 1420) inside the safe area, and content stays left of x=940. Custom scenes must stay between `L.bodyTop` and `L.bodyBottom`, and inside `L.x0`–`L.x1`.
- Lists, comparisons, step flows, cards, chats, quotes, code and timelines shrink to fit the body area by themselves. Lint tells you when something still does not fit.
- ## Voices
- `brand.voice` or `script.voice` takes a Kokoro voice:
- - **American English:** `af_heart` (warm, the default), `af_bella`, `af_nicole`, `af_sarah`, `am_michael`, `am_adam`, `am_onyx`
- - **British English:** `bf_emma`, `bf_isabella`, `bm_george`, `bm_daniel`
- - **Other languages:** Spanish (`ef_`/`em_`), French (`ff_siwis`), Hindi (`hf_`/`hm_`), Italian (`if_`/`im_`), Japanese (`jf_`/`jm_`), Portuguese (`pf_`/`pm_`), Chinese (`zf_`/`zm_`). Set `lang` to match: `es`, `fr-fr`, `hi`, `it`, `ja`, `pt-br` or `zh`.
- `speed` 1.0–1.15 suits social video. Kokoro has voices only for the languages above. For a line in any other language, keep the voice-over in English and show the other language on screen, or note that a different TTS would be needed.
- ## Options
- - `music`:
- - `{"on": false}` turns the beat off.
- - `bpm` and `chords` (for example `"C-G-Am-F"`) change the mood.
- - `volume` is 0–1 under the voice. The music ducks automatically while someone is speaking.
- - `background`: `glow-dots` | `glow` | `plain` | `grid` (ruled lines) | `paper` (grain and a thin rule) | `blobs` (soft drifting colour) | `stripes` (slanted bands).
- - `style` in brand.json sets the look beyond colour. Every key is optional, and a brand without `style` looks as it always did:
- - `corners`: 0 (square) to 2; 1 is the default roundness.
- - `shadow`: `soft` (default) | `faint` (for light backgrounds) | `hard` (a solid offset block) | `none`.
- - `border`: panel outline width in pixels, 0 to 12 (default 2). `borderColor`: a palette key or hex for it.
- - `glow`: `false` removes the coloured glows behind buttons, big numbers and lit steps (better on light backgrounds).
- - `motion`: `smooth` (default) | `calm` (no overshoot, slower) | `bouncy` | `snappy` (short, quick).
- - `transition`: how scenes change: `rise` (default) | `fade` | `slide` | `cut`.
- - `captions`: `outline` (default) | `box` (each line on a solid strip) | `highlight` (a block behind the word being spoken). `captionCase: "upper"`, `captionFont: "display"`.
- - `titleCase: "upper"` draws headlines in capitals.
- - Extra colours a light or unusual palette may need (all optional): `onAccent` and `onGood` (text on accent and green buttons), `shadow`, `pattern` (grid and stripes), `capText`, `capKey`, `capBg`, `capStroke` (captions). On a light background `goodHi` and `badHi` must be dark, because they are used as text.
- - `fonts.mono` sets the font of `code` scenes (JetBrains Mono by default). Bundled fonts: Fraunces (italic), Geist, JetBrains Mono, Anton, Instrument Serif, Fredoka.
- - Captions: `"captions": false` in brand.json or in a script, or `--no-captions` on `video`, `sheet`, `stills` and `build`, hides the burned-in captions. The `.vtt` and `.srt` files are written either way, so a web player can show captions itself.
- - Size on screen:
- - `"format": "embed"` for a landscape video that will be shown small, inside a page.
- - `"density": 1.2` (1 to 2) does the same for any format: the frame keeps its pixel size and everything on it is drawn that much larger.
- - `layout` in brand.json still overrides any single layout number (for example `{"bodyTop": 700}`).
- - Per scene:
- - `hold` sets the seconds after the voice ends (default is `pause`).
- - `sfx` is `thud` | `chime` | `whoosh` | `none`.
- - `voice` and `speed` override the defaults.
- - Web copy: `--web-size 720` (short side in pixels), `--web-crf 27`, `--web-dir <dir>`, `--poster-at <seconds>` (or `"poster": 2.2` in the script). The poster defaults to the first scene once it is fully built.
- - Render: `--workers N` sets how many browser pages draw frames at once. `--lossless` sends frames as PNG instead of JPEG (about twice as slow, pixel exact).
- - Paths: `KOKORO_HOME`, `REEL_PYTHON`, `FF`, `PLAYWRIGHT_CORE` and `REEL_CHROME` override where the tools are found (see `README.md`).
- ## Troubleshooting
- - **Text overflows a card:** run `reel lint`. Shorten the copy first. Otherwise lower `titleSize` or split the scene.
- - **Word timing:** `reel audio` prints where word times came from. Normally that is the voice model's own phoneme durations. If it says "estimated", it also says why (usually kokoro-onnx older than 0.6); things then appear up to a few tenths of a second early or late. `REEL_TIMING=estimate` forces the old estimate. Reading the durations makes `reel audio` peak at about 1.0 GB of memory while the model loads (about 0.56 GB with the estimate).
- - **Captions unreadable on a light background:** set `style.captions` to `box` or `highlight`, and run `reel lint` for the contrast warnings.
- - **A word is highlighted or timed on the wrong word:** check the `keys` and `at` spelling against `say` (lint reports words that are never spoken). `at` matches the first word equal to it, and otherwise the first word that starts with it.
- - **A name is mispronounced:** add it to `pronounce`. Spell it phonetically, or use hyphens for syllables.
- - **`pageerror` lines in the render output:** usually a bug in `custom.js`. The engine's own errors name the scene field involved.
- - **"No browser could be started":** the message lists what was tried. Install Chrome, or Playwright's own Chromium with the command it prints, or set `REEL_CHROME`. `reel check` shows which browsers are found.
- - **Changing the voice-over or timing:** re-run `reel audio`. Visual-only changes need just `reel sheet` or `reel video`. `reel build` works out which steps are needed.
- - **Old commands** (`python gen_audio.py <dir>`, `node engine/render.mjs <dir> video`) still work.
README.md · README · 183 lines
- # reel-studio
- Short voiced motion-graphics videos made from a text script, entirely on your own machine.
- You write two small JSON files: a **script** (a list of scenes, each with a line to say and what to show) and a **brand** (colours, fonts, voice). reel-studio speaks the lines with a local text-to-speech model, draws every frame in a headless browser, and encodes an MP4 with word-by-word captions, music and sound effects. Nothing is uploaded and no paid service is used.
- ## Examples
- Made by the scripts in [`examples/`](examples/). Click a preview for the video with sound.
- | Product promo | Developer tool | Explainer | Data story |
- |:---:|:---:|:---:|:---:|
- | <a href="examples/promo/promo.mp4"><img src="examples/promo/preview.gif" alt="Vertical promo for an invented plant-care app, pastel theme" height="270"></a> | <a href="examples/devtool/devtool.mp4"><img src="examples/devtool/preview.gif" alt="Square clip for an invented command-line tool, terminal theme, with a code scene" height="270"></a> | <a href="examples/explainer/explainer.mp4"><img src="examples/explainer/preview.gif" alt="Landscape explainer of how DNS works, paper theme" height="270"></a> | <a href="examples/datastory/datastory.mp4"><img src="examples/datastory/preview.gif" alt="Data story with a bar chart, poster theme" height="270"></a> |
- | vertical · `pastel` | square · `terminal` | landscape · `paper` | embed · `poster` |
- | [video](examples/promo/promo.mp4) · [script](examples/promo/script.json) · [brand](examples/promo/brand.json) | [video](examples/devtool/devtool.mp4) · [script](examples/devtool/script.json) · [brand](examples/devtool/brand.json) | [video](examples/explainer/explainer.mp4) · [script](examples/explainer/script.json) · [brand](examples/explainer/brand.json) | [video](examples/datastory/datastory.mp4) · [script](examples/datastory/script.json) · [brand](examples/datastory/brand.json) |
- The apps, tools and numbers in these are invented, and say so on screen. [`examples/README.md`](examples/README.md) shows how to render each one again.
- It is packaged as a [Claude Code](https://claude.com/claude-code) skill (`SKILL.md` tells the assistant how to use it), and it also works by hand from the command line.
- ## What it makes
- - Vertical (1080×1920), square (1080×1080) and landscape (1920×1080) video at 30 fps, plus an `embed` format with larger type for video shown small inside a web page.
- - Scene types: title, bullets, chat thread, card, big number, two-column compare, quote, image, call to action, numbered steps, box-and-arrow diagram, bar chart, code or terminal panel, timeline, and your own custom scenes in JavaScript.
- - Six ready-made themes (`reel themes`) that differ in colours, fonts, background, corners, shadows, motion and caption style. A `style` block in `brand.json` sets the same things by hand.
- - Elements appear on the word that names them (`"at": "word"`).
- - Captions burned in (optional) and as `.vtt` and `.srt` files.
- - A web copy: a small 720p faststart MP4 and a poster JPEG.
- - A batch build for many scripts that share one brand.
- ## Limits
- - It makes **motion graphics from a script**. It is **not a generative video model**: it does not create footage, people, photos or illustrations. Pictures come from files you supply (screenshots, photos).
- - The voice is Kokoro. It covers American and British English, Spanish, French, Hindi, Italian, Japanese, Brazilian Portuguese and Mandarin Chinese, with a fixed set of voices. It does not clone voices.
- - Word timings come from the voice model's own phoneme durations, read through kokoro-onnx 0.6 or newer. `scripts/measure_word_timing.py` checks them against the audio. It uses 8 list-like sentences ("Red, green, blue, …") said by 4 voices at 2 speeds, which gives 73 words that come after a pause, the only places where a word's start can be read from the sound. There, word starts were 17 ms from the sound onset on average, 90% within 36 ms, and at most 50 ms off. The old syllable estimate was 166 ms off on average and up to 465 ms. The script prints these figures when you run it. Inside a phrase with no pauses there is nothing to measure against, so the figure is not proven there.
- - Reading those durations makes the voice step use more memory while the model loads: with nothing cached, `reel audio` peaked at about 1.0 GB, against about 0.56 GB with the estimate (measured on one 33-second script). With an older kokoro-onnx, another model file or `REEL_TIMING=estimate`, times are estimated from syllable counts instead, as before, and `reel audio` says which was used.
- - The music is a simple generated beat. For anything else, use the `-voiceonly.mp4` and add music in your editor.
- - Layout is automatic and has limits. `reel lint` and the review sheet show what does not fit; long text has to be shortened.
- - Tested on Linux with Chrome. macOS is supported by the scripts but has not been tested by the author. Windows is untested.
- ## Requirements
- | Needed | Why | Licence |
- |---|---|---|
- | Node.js 18 or newer | runs the renderer | MIT |
- | [playwright-core](https://www.npmjs.com/package/playwright-core) | drives the browser | Apache-2.0 |
- | Google Chrome, Chromium or Playwright's own Chromium | draws the frames | Chrome: proprietary freeware. Chromium: BSD-style and others |
- | Python 3.10 to 3.13 | runs the voice step | PSF |
- | [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx) (0.6 or newer for measured word timings) | text to speech | MIT |
- | Kokoro v1.0 model files (`kokoro-v1.0.onnx`, `voices-v1.0.bin`, about 340 MB) | the voice model | Apache-2.0 (see the note below) |
- | phonemizer and espeak-ng (installed with kokoro-onnx) | turn text into phonemes | GPL-3.0-or-later |
- | onnxruntime, numpy, soundfile (installed with kokoro-onnx or beside it) | run the model, write audio | MIT, BSD-3-Clause, BSD-3-Clause |
- | ffmpeg with libx264 and AAC | encodes the video | LGPL or GPL, depending on the build. The binary from `imageio-ffmpeg` is a GPL build |
- None of these is included in this repository. You install them yourself, and their licences apply to your use of them.
- About 1 GB of disk space and 4 GB of free memory are enough. No GPU is needed.
- ### Licence notes
- Checked on 21 November 2026. Check again before you rely on them.
- - **Bundled fonts** (`assets/fonts/`): Fraunces (Copyright 2020 The Fraunces Project Authors), Geist (Copyright 2024 The Geist Project Authors), JetBrains Mono (Copyright 2020 The JetBrains Mono Project Authors), Anton (Copyright 2020 The Anton Project Authors), Instrument Serif (Copyright 2022 The Instrument Serif Project Authors) and Fredoka (Copyright 2016 The Fredoka Project Authors) are all under the **SIL Open Font License 1.1**, as stated in the licence field inside each font file. The last four were taken unchanged from the Google Fonts repository (`ofl/jetbrainsmono`, `ofl/anton`, `ofl/instrumentserif`, `ofl/fredoka`), where each has an `OFL.txt` saying the same. None of the six declares a Reserved Font Name. The OFL allows bundling and redistribution, including in commercial work, provided the copyright and licence notice travel with the fonts and the fonts are not sold on their own. `assets/fonts/OFL.txt` carries the notices.
- - **kokoro-onnx** is MIT (its `LICENSE` file). Its README says the Kokoro model is Apache-2.0.
- - **Kokoro-82M** (the model, by hexgrad) is tagged Apache-2.0 on its Hugging Face model card. The model card does not give a separate licence for the individual voice files, and neither does the kokoro-onnx release page for `voices-v1.0.bin`. This could not be verified beyond the model's own Apache-2.0 tag.
- - **phonemizer** (GPL-3.0-or-later, from its package metadata) and **espeak-ng** (GPL-3.0-or-later, from its README) are loaded by kokoro-onnx inside the Python process that runs `engine/gen_audio.py`. If you redistribute a bundle that includes them, or build a product on top, read the GPL's terms. This is not legal advice.
- - **ffmpeg** is run as a separate program. Its licence depends on how your copy was built.
- - **Videos you make** are yours. Check the licence of any fonts, images and logos you add to a project.
- reel-studio's own code is under the **MIT License** (see `LICENSE`). The bundled fonts keep their own licence, as above.
- ## Install
- ```bash
- # 1. the skill itself (for Claude Code; any folder works if you only use the command line)
- git clone https://github.com/VinVirtual/reel-studio ~/.claude/skills/reel-studio
- # 2. voice: a Python venv with Kokoro, and the two model files
- python3 -m venv ~/kokoro/.venv
- ~/kokoro/.venv/bin/pip install kokoro-onnx soundfile numpy imageio-ffmpeg
- curl -L -o ~/kokoro/kokoro-v1.0.onnx https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.onnx
- curl -L -o ~/kokoro/voices-v1.0.bin https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/voices-v1.0.bin
- # 3. renderer: Playwright, and a browser if you have no Chrome
- npm i -g playwright-core
- npx playwright-core install chromium # optional when Google Chrome is installed; a good fallback either way
- # 4. check
- ~/.claude/skills/reel-studio/reel check
- ```
- `imageio-ffmpeg` brings its own ffmpeg binary. Leave it out if you already have ffmpeg on your PATH.
- Everything is found in default places that you can change with environment variables:
- | Variable | Default | What |
- |---|---|---|
- | `KOKORO_HOME` | `~/kokoro` | folder with the model files and the `.venv` |
- | `KOKORO_MODEL`, `KOKORO_VOICES` | `$KOKORO_HOME/kokoro-v1.0.onnx`, `$KOKORO_HOME/voices-v1.0.bin` | the two model files |
- | `REEL_PYTHON` | `$KOKORO_HOME/.venv/bin/python`, else `python3` | Python that has kokoro-onnx |
- | `FF` | `ffmpeg` on PATH, else the one from imageio-ffmpeg | ffmpeg binary |
- | `PLAYWRIGHT_CORE` | found through node and `npm root -g` | folder of playwright-core |
- | `REEL_CHROME` | installed Chrome, then other browsers found, then Playwright's Chromium | browser binary to try first |
- ## Quick start
- ```bash
- R=~/.claude/skills/reel-studio
- $R/reel new my-video # brand.json, script.json (an example that shows the scene types), custom.js, fonts/. Add --theme <name> for another look
- $R/reel lint my-video # check the script and the layout
- $R/reel audio my-video # voice, timings, captions files
- $R/reel sheet my-video # stills/script-sheet.png: one frame per scene. Look at it.
- $R/reel video my-video --web # out/script.mp4, plus out/web/script.mp4 and a poster
- ```
- Edit `my-video/script.json` and `my-video/brand.json`, then run the steps again. `references/scenes.md` lists every scene type and field, and `SKILL.md` has the writing rules.
- ### A finished example
- `examples/` holds five finished scripts, four of them with the rendered video beside them (see the top of this page). Each folder is a project, so it renders where it is:
- ```bash
- $R/reel audio $R/examples/demo && $R/reel video $R/examples/demo --web
- ```
- ### Themes
- ```bash
- $R/reel themes # list them
- $R/reel new my-video --theme paper # start from one
- $R/reel new my-video --theme poster --format square
- ```
- | Theme | Look |
- |---|---|
- | `ember` | warm dark, serif italic headline, glowing dots. The look you get without `--theme` |
- | `midnight` | deep navy with drifting colour, tight sans headline, a block that follows the spoken word, scenes slide sideways |
- | `paper` | cream paper with grain and a thin rule, ink text, serif headline, no shadows, boxed captions, slow fades |
- | `poster` | yellow and black, condensed capitals, square corners, hard shadows, striped background, quick moves |
- | `pastel` | soft lilac with drifting colour, rounded headline, very round corners, bouncy pop-ins |
- | `terminal` | green on black, monospaced type, ruled grid, hard cuts |
- A theme is an ordinary `brand.json` (they are in `themes/`). The parts that set the look are `colors`, `fonts`, `background` and `style`; `SKILL.md` lists every `style` key. `reel lint` warns when a brand's text colours have too little contrast to read, and the tests check that for every bundled theme.
- ## Commands
- | Command | What it does |
- |---|---|
- | `reel check` | checks Python, Kokoro, ffmpeg, node, Playwright and that a browser really starts |
- | `reel themes` | lists the ready-made looks |
- | `reel new <dir>` | starts a project from the templates. `--theme <name>` uses a theme as `brand.json`, `--format <f>` sets the shape |
- | `reel lint <project> [script]` | reports words in `at`/`keys` that are never spoken, text over the length guide, missing files, unknown types and fields, and content that overflows or overlaps (measured in the real engine). `--no-browser` skips the layout part, `--strict` fails on warnings, `--json` prints JSON |
- | `reel audio <project> [script]` | voice, word timings, music and SFX mix, `.vtt` and `.srt` |
- | `reel sheet <project> [script]` | one frame per scene in a single PNG |
- | `reel stills <project> [script] 1.5 4` | frames at those seconds |
- | `reel video <project> [script]` | `out/<script>.mp4`, `-voiceonly.mp4`, `.vtt`, `.srt`. `--web` adds the web copy |
- | `reel web <project> [script]` | `out/web/<script>.mp4` (720p, CRF 27, mono 64k AAC, faststart), `<script>.jpg` poster without captions, `<script>.vtt` |
- | `reel captions <project> [script]` | only the `.vtt` and `.srt` |
- | `reel preview <project> [script]` | serves a page on this machine (`http://127.0.0.1:4173/`, or `--port N`) that plays the video with its voice and a scrub bar, drawn live by the engine. Visual edits to the script or brand show within a second or two; a changed spoken line needs `reel audio` |
- | `reel build <project> [scripts...]` | voice + video for many scripts. `--jobs N` at a time, `--web`, `--force`. Skips unchanged scripts, continues after a failure, exits non-zero with a summary |
- | `reel test` | runs the unit tests (plain `node --test`, no extra packages) |
- `script` defaults to `script`.
- `--format vertical|square|landscape|embed` on `lint`, `sheet`, `stills`, `video`, `web`, `build` and `preview` uses that shape for one run instead of the `format` in `brand.json`. The files are named `<script>-<format>` (`out/script-square.mp4`, `stills/script-square-sheet.png`, `out/web/script-square.mp4`), so shapes do not overwrite each other, and they share one voice track. Lint with `--format` checks the layout of that shape. A hand-set `layout` in `brand.json` belongs to the brand's own shape and is left out when the shape changes. The command stops with an error if the project already has a script with the output name, for example `promo-square.json` when you run `promo --format square`, because the two would overwrite each other's files. Rename one of them.
- Other options: `--no-captions`, `--workers N`, `--lossless`, `--quality 0.95`, `--web-size 720`, `--web-crf 27`, `--web-dir <dir>`, `--poster-at <seconds>`.
- ## How it works
- 1. `engine/gen_audio.py` speaks each phrase with Kokoro, reads when each word starts from the model's phoneme durations (`engine/word_timing.py`), and writes a timeline (`build/<script>.timeline.json`) and two audio mixes.
- 2. `engine/engine.js` and the scene files draw a frame for any time `t` on a canvas. A frame depends only on `t`, so frames can be drawn in any order, in several browser pages at once, and every render of the same inputs gives the same video.
- 3. `engine/lib/video.mjs` collects the frames and pipes them to ffmpeg.
- ## Development
- ```bash
- ./reel test # unit tests for layout maths, lint rules, themes and contrast, code scenes, captions, build planning, word alignment
- ./reel lint <project> # layout checks run in the real engine
- ./reel sheet <project> # then look at the PNG
- ```
- Scene types live in `engine/scenes.js`, `engine/scenes-explain.js` and `engine/scenes-dev.js`. Layout maths that can be tested without a browser lives in `engine/fit.js`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.