Skip to content
Back to search

video-explainer-kit

SkillWorks with Claude CodeGitHub

Turn a brief, script or MP4 into a reviewed, verified vertical explainer video, with review receipts before publishing.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

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/runesleo/claude-video-kit 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/runesleo/claude-video-kit'

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/runesleo--claude-video-kit/badge.svg)](/listings/runesleo--claude-video-kit)

HTML

<a href="/listings/runesleo--claude-video-kit"><img src="/api/listings/runesleo--claude-video-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

- **Claude Code** (2.1.275 or later): `/plugin install video-explainer-kit --marketplace runesleo/x-reader` - **Codex**: `codex plugin marketplace add runesleo/x-reader`, then `codex plugin add video-explainer-kit@runesleo`

The `runesleo` marketplace also lists Leo's other tools; see [runesleo/x-reader](https://github.com/runesleo/x-reader).

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.

.claude-plugin/plugin.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "video-explainer-kit",
  3. "version": "0.3.0-rc.1",
  4. "description": "Turn a brief, script or MP4 into a reviewed, verified vertical explainer video, with review receipts before publishing.",
  5. "author": {
  6. "name": "Leo",
  7. "url": "https://github.com/runesleo"
  8. },
  9. "homepage": "https://github.com/runesleo/claude-video-kit",
  10. "repository": "https://github.com/runesleo/claude-video-kit",
  11. "license": "MIT",
  12. "privacyPolicyUrl": "https://github.com/runesleo/claude-video-kit#data-and-network-access",
  13. "keywords": [
  14. "video",
  15. "remotion",
  16. "explainer",
  17. "tts"
  18. ]
  19. }
README.md · README · 267 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # claude-video-kit
  2. **English** · [中文](./README.zh.md) · [README.en.md](./README.en.md)
  3. **Video Explainer Kit** is an Agent Skill for producing and checking **reviewed, verified vertical explainer videos** from a research brief, script, or existing MP4. It can select direct generation, agent-orchestrated tools, or the repository's deterministic TTS + caption alignment + Remotion fallback.
  4. **Who it's for:** people using Claude Code, Codex, Cursor, or another capable AI agent to make research / technical explainers, and who value a repeatable 9:16 workflow with independent quality checks.
  5. **Who it's not for:** a hosted video editor, a Claude-only API product, or a guaranteed one-click “topic → polished AI B-roll Short” service. This repository ships a local Remotion fallback and verification tools; direct video-generation models are not bundled.
  6. > **[v0.3.0-rc.1](https://github.com/runesleo/claude-video-kit/releases/tag/v0.3.0-rc.1) (public release candidate):** installable `video-explainer` Agent Skill. The `legacy_remotion` path requires an independent, script-hash-bound pre-render review; every strategy requires verification and an independent review bound to the exact final MP4. The Skill never uploads or publishes.
  7. ## Install as a plugin
  8. - **Claude Code** (2.1.275 or later): `/plugin install video-explainer-kit --marketplace runesleo/x-reader`
  9. - **Codex**: `codex plugin marketplace add runesleo/x-reader`, then `codex plugin add video-explainer-kit@runesleo`
  10. The `runesleo` marketplace also lists Leo's other tools; see [runesleo/x-reader](https://github.com/runesleo/x-reader).
  11. ## Fastest first success: Agent Skill
  12. ```bash
  13. git clone https://github.com/runesleo/claude-video-kit.git
  14. cd claude-video-kit
  15. npm ci --prefix remotion
  16. npx skills add runesleo/claude-video-kit --skill video-explainer
  17. npm run doctor
  18. npm run demo # macOS + built-in say only; writes a new timestamped demo folder
  19. # npm scripts are thin wrappers — the underlying command works the same:
  20. # node scripts/video-explainer.mjs demo --output /tmp/video-explainer-first-success
  21. ```
  22. The no-key `demo` exercises this local clone's Remotion fallback **on macOS**. It uses the built-in `say` voice and script-timed captions, writes a new timestamped output folder, checks a 1080×1920 MP4, and **does not** perform final-artifact review or qualify the video for publication. For real `legacy_remotion` projects, first prepare a motion storyboard, then run `review` and `render`; `fix`, `block`, missing, or stale receipts stop rendering. The eleven pre-render checks are judged by an independent reviewer — the tool enforces the recorded process, not the truth of those judgments. Direct/agent-orchestrated strategies may skip legacy intermediate files but must pass final MP4 review and release gates.
  23. > Editing scripts or compositions? Read [docs/DESIGN.md](docs/DESIGN.md) first — it's the design system contract.
  24. ## Final release gate
  25. The canonical `video-release-gate` implementation now lives in this pipeline:
  26. [`scripts/video_release_gate.py`](scripts/video_release_gate.py) and
  27. [`config/video_quality_profile.json`](config/video_quality_profile.json).
  28. Keep the pre-render receipt, `review-render`, and `verify-shorts`; then evaluate
  29. the **final master after all edits**, with hash-bound QA and independent review.
  30. `build-distribute-pack` requires a current release receipt and verifies it before
  31. writing any handoff. Downstream uploaders must verify again immediately before an
  32. authorized action. No uploader or automatic publication is added.
  33. See [the complete evaluate → verify → handoff commands](docs/RELEASE_GATE.md).
  34. ## What you get
  35. - **Guarded Remotion fallback** — once a project has the required storyboard and current pass receipt, `render` orchestrates TTS, alignment, metadata, and Remotion; use `npm run demo` for a keyless first run on macOS.
  36. - **Metadata-driven timing** — slide durations computed from actual WAV length, no manual frame counting.
  37. - **Composable slides** — `cover`, `text`, `code` compositions out of the box, each drop-in replaceable.
  38. - **Explicit TTS backends** — `render.sh` defaults to CosyVoice (requires your DashScope key and cloned voice ID); Fish Audio is opt-in via `TTS_BACKEND=fish`, and local IndexTTS2 requires its own setup. The no-key demo deliberately uses macOS `say`.
  39. - **Word-level captions** — faster-whisper produces frame-accurate caption tracks that burn into the render.
  40. - **Remotion Studio hot reload** — iterate on compositions in React with live preview.
  41. ## How the deterministic Remotion fallback works
  42. ```
  43. script.json ──▶ TTS ──▶ *.wav ──▶ Whisper align ──▶ captions.json
  44. │
  45. build-metadata ◀──────────┘
  46. │
  47. ▼
  48. Remotion render ──▶ out/full.mp4
  49. ```
  50. **Input** (`examples/my-first/script.json`):
  51. ```json
  52. {
  53. "title": "My first AI video",
  54. "fps": 30,
  55. "width": 1080,
  56. "height": 1920,
  57. "slides": [
  58. { "type": "cover", "title": "Hello world", "subtitle": "in 10 seconds" },
  59. { "type": "text", "text": "This is my first AI-rendered video.",
  60. "voice_text": "This is my first AI-rendered video." },
  61. { "type": "code", "language": "ts",
  62. "code": "const video = await kit.render(script);",
  63. "voice_text": "One function call, one video file." }
  64. ]
  65. }
  66. ```
  67. **First run (macOS, no keys)**:
  68. ```bash
  69. npm run demo
  70. ```
  71. **Output**: `out/video-explainer-demo-*/out/full.mp4` — a 1080×1920 demo-quality vertical video. `examples/my-first/script.json` remains a legacy input example; calling `render.sh` directly on that example without the required motion storyboard is **not** a supported current first-run path.
  72. ## Setup
  73. **Clone and install:**
  74. ```bash
  75. git clone https://github.com/runesleo/claude-video-kit.git
  76. cd claude-video-kit
  77. cd remotion && npm install && cd ..
  78. pip install -r scripts/requirements.txt
  79. cp .env.example .env # optional: only if you choose a provider that reads these settings
  80. ```
  81. **AI coding agents:** start with the [Agent Skill](skills/video-explainer/SKILL.md) and [current quickstart](docs/quickstart.md). Production requires its documented storyboard/review/final-MP4 gates; do not treat old single-script examples as current first-run recipes.
  82. ## Requirements
  83. - Node 20+
  84. - Python 3.10+
  85. - ffmpeg (`brew install ffmpeg`)
  86. - **Keyless demo:** macOS built-in `say` (the `demo` command intentionally clears Fish credentials; it is not the Linux/Windows demo path).
  87. - **Production Remotion narration:** default `cosyvoice` requires `DASHSCOPE_API_KEY`, `COSYVOICE_VOICE_ID`, and the `dashscope` Python package; optional Fish Audio requires its own key/voice and an explicitly set `TTS_BACKEND=fish` environment variable.
  88. - (Optional) CUDA GPU if you separately configure local IndexTTS2.
  89. Fish Audio is an optional provider, not a requirement for this kit. Its [signup link](https://fish.audio/?code=VCG6XOES4XIY2) is relevant only if you choose that backend.
  90. That's it. No video editor, no recording gear, no timeline.
  91. ## Supported slide types
  92. | Type | Purpose | Required fields | Optional fields |
  93. |------|---------|----------------|----------------|
  94. | `cover` | Opening / closing cards | `title` | `subtitle` |
  95. | `text` | Narrated text slide | `text`, `voice_text` | `voice`, `textMode` (`"hero"` for big-font shorts hook), `textReveal` (`"spring"` \| `"typewriter"`), `accentColor` |
  96. | `code` | Code-as-video blocks | `code`, `language`, `voice_text` | `voice` |
  97. | `numberHero` | Big-number data hook (shorts) | `heroValue` | `heroLabel`, `heroBadge`, `heroPrefix`, `heroSuffix`, `heroAccentColor` |
  98. **`voice_text`** is the narration script — kept separate from on-screen `text` so your voice-over can be more natural than what the slide shows. **`voice`** can override a per-slide provider voice where the selected backend supports it (including Fish Audio); do not assume the override behaves identically across backends.
  99. Add your own slide type by dropping a new composition into `remotion/src/compositions/` and registering it in `Root.tsx`. See `docs/quickstart.md`.
  100. ## Shorts pipeline (vertical 9:16)
  101. Phase 1 adds a vertical short-video pipeline: 1080×1920 canvas, dense motion, big text — built for YouTube Shorts / 抖音 / TikTok / 小红书 / B 站 Shorts. Set `"preset": "shorts"` in metadata to flip canvas + font scale in one place; render normally, then run `node scripts/verify-shorts.mjs <out.mp4> --format shorts --check-audio` for a technical preflight (9:16 canvas, recipe duration and shared release-gate audio rules). A 720×1280 vertical video is accepted with a resolution warning; scene-cut rhythm and opening-cut detection are review prompts, not hard failures or aesthetic scores. For longer vertical explainers, use `--format explainer`. Every final video still needs independent visual/factual review and the separate release gate before distribution. See [`docs/SHORTS_PIPELINE.md`](docs/SHORTS_PIPELINE.md) for slide-type schema, captions config, and rhythm guidance.
  102. ## Examples in this repo
  103. - **`examples/my-first/`** — a legacy 3-slide `script.json` example, not a current production-ready project. For a first run, use the guarded `npm run demo` path.
  104. - **`examples/schoger-demo/`** — the script behind [my first AI-generated short on X](https://x.com/runes_leo). A worked example of a real shipped video, kept for reference (assets not included, only the script).
  105. ## Historical verification (v0.1)
  106. The original v0.1 release was end-to-end tested on macOS (Apple Silicon) with `examples/my-first`. This historical result is **not** a fresh-install acceptance test of all v0.3.0-rc.1 strategies. The shipped pipeline produces a **1080×1920 @ 30fps, 8 seconds, 442 KB** vertical mp4 — narration via Fish Audio (or `say` fallback if no API key), captions via Whisper, render via Remotion. See `docs/quickstart.md` for first-run notes (including China network setup).
  107. ## Historical limitations (v0.1; some may be superseded)
  108. - **The `say` fallback is rough and never qualifies a demo for publication.** Without an API key the pipeline degrades to macOS `say`, which is fine for "does my pipeline run end-to-end" but ships with two real annoyances: (a) it can't disambiguate Chinese homographs, e.g. `行` in `一行代码` gets read as `háng` instead of `xíng`; (b) Whisper's `base` model struggles to align robotic synthetic voices, so captions drift by a beat. A better voice backend may help, but pronunciation and caption alignment still need explicit review.
  109. - No automatic cover generator — covers are whatever the `cover` slide renders
  110. - No B-roll / video clip support — slides are still-frame + audio + captions
  111. - Single voice per video (per-slide voice override is in the schema but undertested)
  112. - IndexTTS2 backend is a placeholder — script is documented, CUDA wiring is left to the user
  113. - Chinese is the primary tested language; other languages work but captioning quality scales with Whisper model size (`base` → `medium` → `large-v3`)
  114. ## What's new in v0.2 — post-render pipeline
  115. The v0.1 pipeline stopped at `out/full.mp4`. v0.2 adds the "every time you make
  116. a video, you end up redoing this" steps into composable scripts you can chain
  117. or compose; the release gate is mandatory before handoff:
  118. - **`scripts/prepend-cover.sh`** — prepend a still-image cover clip (default
  119. 3s) to the rendered video. Probes the main video's width/height/fps and
  120. matches them exactly so concat stays lossless. Falls back to re-encode only
  121. if codec params differ.
  122. - **`scripts/shift-subtitles.py`** — shift every timestamp in an `.srt` by a
  123. fixed offset. Pair with `prepend-cover.sh` when you need captions to stay
  124. aligned after adding an intro.
  125. - **`scripts/build-distribute-pack.mjs`** — emit per-platform upload packages
  126. (one of Bilibili / Xiaohongshu / Douyin per invocation) after release verification, with chapter timestamps derived
  127. from `metadata.json`. Supports a blacklist-based compliance pass that strips
  128. regulator-sensitive words while keeping brand names — stripping brands costs
  129. vertical-search discoverability.
  130. - **Pre-render review gate** (historical v0.2 description; see the current [`video-explainer` Skill](skills/video-explainer/SKILL.md))
  131. — originally a manual convention, now enforced through a script-hash-bound review receipt for the legacy Remotion path. Have an independent reviewer read the
  132. script. TTS + render costs ~30 min per iteration; 5 min of review usually
  133. avoids 2 hours of rerun.
  134. Historical v0.2 chained usage (not a current first-run recipe; current storyboard, review, and final-release gates still apply):
  135. ```bash
  136. # 1. Render as usual (v0.1)
  137. ./scripts/render.sh examples/my-first
  138. # 2. Prepend cover
  139. ./scripts/prepend-cover.sh \
  140. --cover my-cover.png \
  141. --video examples/my-first/out/full.mp4 \
  142. --duration 3 \
  143. --out examples/my-first/out/full-with-cover.mp4
  144. # 3. Complete final QA/review and evaluate full-with-cover.mp4 (see docs/RELEASE_GATE.md).
  145. # 4. Verify and build one platform's handoff; repeat with each platform's evidence.
  146. node ./scripts/build-distribute-pack.mjs examples/my-first --intro-offset 3 \
  147. --platform bilibili --video examples/my-first/out/full-with-cover.mp4 \
  148. --cover examples/my-first/cover-bilibili.png \
  149. --release-receipt examples/my-first/VIDEO-RELEASE-GATE-bilibili.json
  150. ```
  151. `shift-subtitles.py` is an optional utility for the case where you keep a
  152. separate `.srt` file outside the v0.1 pipeline (e.g. exported from Whisper
  153. and used as an overlay). The v0.1 pipeline burns captions during Remotion
  154. render, so most users don't need it.
  155. ```bash
  156. ./scripts/shift-subtitles.py \
  157. --input path/to/captions.srt \
  158. --offset-seconds 3 \
  159. --output path/to/captions-with-intro.srt
  160. ```
  161. Each script is self-contained and independently runnable — use the ones you
  162. need, skip the rest.
  163. ## Roadmap
  164. **Pipeline**
  165. - [ ] v0.3 — AI-generated B-roll clips (SDXL / video models for visual variety)
  166. - [ ] v0.4 — Auto cover image generator (1080×1920, platform-aware)
  167. - [ ] v0.5 — Multi-voice conversations (multiple voice IDs per script)
  168. **Compositions**
  169. - [ ] Chart slide (render data as animated SVG)
  170. - [ ] Diff slide (before/after comparison, Schoger-style)
  171. - [ ] Diagram slide (Mermaid → animated reveal)
  172. **Tooling**
  173. - [ ] Web UI — non-coders can edit scripts in a browser
  174. - [ ] `kit init` CLI — scaffold new video projects without copying examples
  175. **API** (planned)
  176. - [ ] REST endpoint for render-as-a-service — POST a script, receive an MP4
  177. ## About the author
  178. *Leo ([@runes_leo](https://x.com/runes_leo)) — AI × Crypto independent builder. Trading on [Polymarket](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=claude-video-kit), building data and trading systems with Claude Code and Codex.*
  179. [leolabs.me](https://leolabs.me) — writing · community · open-source tools · indie projects · all platforms.
  180. [X Subscription](https://x.com/runes_leo/creator-subscriptions/subscribe) — paid content weekly, or just buy me a coffee 😁
  181. *Learn in public, Build in public.*
  182. ## Data and network access
  183. The kit runs on your machine. There is no telemetry, and nothing is sent to the author's servers. The offline demo (`node scripts/video-explainer.mjs demo`) uses the local macOS `say` voice and script-timed captions, so it calls no API.
  184. When you render your own video, data goes only to the services you choose:
  185. | What | Where it goes |
  186. |---|---|
  187. | Narration text, default `cosyvoice` backend | Alibaba Cloud DashScope (`wss://dashscope.aliyuncs.com`, or `DASHSCOPE_WS_URL`), with your `DASHSCOPE_API_KEY` |
  188. | Narration text, `fish` backend | `api.fish.audio`, only if you set `FISH_AUDIO_API_KEY` and `FISH_AUDIO_VOICE_ID`; without them it falls back to the local `say` command |
  189. | Narration text, `indextts2` backend | Nowhere: it runs your local IndexTTS2 checkout with network downloads turned off |
  190. | Narration text and your voice reference audio, optional `scripts/modal_tts_batch.py` | Modal, only when you run it yourself with `modal run`; the Modal image clones `github.com/index-tts/index-tts` |
  191. | Word-level caption alignment | Runs locally with faster-whisper, which downloads the Whisper model from Hugging Face on first use |
  192. | Video rendering | Runs locally with Remotion, which downloads Chrome Headless Shell into `remotion/node_modules` on the first render |
  193. Setup downloads dependencies you install yourself: Remotion and its packages from the npm registry (`npm ci --prefix remotion`), and the Python packages in `scripts/requirements.txt` (plus `dashscope` for CosyVoice) from PyPI.
  194. TTS backends read credentials from their supported process environment; Fish Audio's script also attempts `.env` loading. Simply editing `.env` does **not** set `TTS_BACKEND` for `render.sh`. Credentials are used only when you explicitly choose the corresponding provider; the keyless demo clears Fish credentials.
  195. Stored only on your machine: everything a render produces inside your project folder (`workspace/` audio and captions, `metadata.json`, `out/full.mp4`, review and gate receipts), demo output (`out/video-explainer-demo-*` in the kit, or the path you pass with `--output`), and model caches (Hugging Face cache for Whisper, Chrome Headless Shell under `remotion/node_modules`).
  196. ## License
  197. MIT

Version history

  • v0.3.0-rc.111/5/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.