Skip to content
Back to search

shorts-kit

Make narrated vertical shorts (TikTok, YouTube Shorts, Reels) with a coding agent and Remotion. 9+ agent skills, 20+ story flows, fact ledger, CC0 SFX.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/howznguyen--shorts-kit/badge.svg)](/listings/howznguyen--shorts-kit)

HTML

<a href="/listings/howznguyen--shorts-kit"><img src="/api/listings/howznguyen--shorts-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.

git clone https://github.com/howznguyen/shorts-kit.git
cd shorts-kit
bun install

For ElevenLabs, copy `.env.example` to `.env` and set `ELEVENLABS_API_KEY`.

For VieNeu (Vietnamese), install it once into a local Python env (needs [uv](https://docs.astral.sh/uv/)):

uv venv --python 3.12 .venv-vieneu
uv pip install --python .venv-vieneu/bin/python vieneu
.venv-vieneu/bin/python scripts/lib/engines/vieneu_bridge.py --voices   # downloads the model (~600 MB), lists voices

Then in `narration.json`: `"voice": {"engine": "vieneu", "voice": "Thiện Minh"}`. `voice` is a preset name or the path to a 3–8 s `.wav` to clone (only a voice you have the right to use).

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.

README.md · README · 292 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. <p align="center">
  2. <img src="docs/assets/logo.png" alt="shorts-kit logo" width="128">
  3. </p>
  4. # shorts-kit
  5. [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.knowns.dev)
  6. [![Facebook group](https://img.shields.io/badge/Facebook-Agentic%20Coding%20Vietnam-1877F2?logo=facebook&logoColor=white)](https://www.facebook.com/groups/agentic.coding.vietnam)
  7. [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  8. ![shorts-kit: narrated shorts and product promos, vertical or landscape, made with your coding agent](docs/assets/cover.webp)
  9. Make narrated vertical shorts (TikTok, YouTube Shorts, Reels), and product promos in 9:16 or 16:9, with a coding
  10. agent and [Remotion](https://www.remotion.dev).
  11. You talk to your agent ("make a video about why the sky is blue"). The agent follows
  12. the kit's skills step by step: facts first, a storytelling flow, the script, the voice,
  13. the scenes, stills to check, the render, the cover and the caption. You review, then you
  14. upload the file yourself. The kit never posts anything.
  15. The rules and skills come from a private pipeline that took a new knowledge channel from
  16. zero to about 120k views on its best video in two months. Every rule keeps the reason it
  17. exists, because most of them were written after a published video broke it. They are
  18. defaults: change them for your own channel.
  19. ## Results
  20. The channel these rules came from, two months in. The best videos and the flops sit side
  21. by side on purpose: topics close to the audience carried it (tens of thousands of views),
  22. topics that drifted from the channel's niche got a few hundred. The kit cannot pick your
  23. topic for you.
  24. ![A TikTok profile grid: 122.1K, 63.3K, 48.4K, 31.7K and 11.8K views next to 3,692, 768, 349 and 232](docs/assets/tiktok-results.jpg)
  25. What a finished run reports, from the original private pipeline (it also copied files to
  26. a NAS and applied that channel's own swearing rule; neither is part of this kit):
  27. ![An agent's end-of-run report: narration, TTS, scenes, render, loudness and encode, cover, caption, hand-off, and the fact checks it caught](docs/assets/agent-run.jpg)
  28. ## What is in the box
  29. - **10 agent skills** (`.claude/skills/sk-*`), started by `sk-pipeline` (shorts) or `sk-promo` (ads and launch films). They work in
  30. Claude Code, and in any agent that reads `AGENTS.md` (Codex, OpenCode, ...).
  31. - **SOUL.md**: your channel's rulebook. Voice, sentence style, writing for a
  32. text-to-speech voice, safe zones, captions, audio, facts, covers, hand-off. Each rule
  33. is tagged `[measured]`, `[default]`, `[craft]` or `[hard]` so you know how freely to
  34. change it.
  35. - **20 storytelling flows** (`docs/flows/`): Three reasons, Trace back, Explain it,
  36. Reading a graph, Empty world with a late reveal, and more. Each has beats, when to use
  37. it and its traps.
  38. - **A fact ledger** (`docs/facts/`). No sentence goes into a script before its claim
  39. has a verified record, and the linter enforces it.
  40. - **A Remotion library** (`src/shared/`): word-timed captions, kinetic type, safe-zone
  41. overlay, music bed and SFX, camera moves, and an illustrated world (sky, sea, sun,
  42. moon, stars, clouds, rain, birds, people, fish).
  43. - **Maps and a globe** (`src/shared/map/`): satellite imagery with a camera that flies
  44. from country to street and stays sharp, coastlines, borders and rivers from Natural
  45. Earth, routes that draw on, pins, measured distances, filled regions, a ready Vietnam map
  46. with the Hoàng Sa and Trường Sa archipelagos, a 3D globe with great-circle lines, and a
  47. pull-out from any scene to the globe.
  48. - **Shared graphics** for any video: strike-and-replace, slot word, word slam, typewriter,
  49. hand-drawn circles, arrows, underlines, cross-outs and stamps, and charts that stay true to
  50. scale (compare bars, progress ring, unit grid, odometer). Browse them with `bun run dev gallery`.
  51. - **Your own voice or footage instead of TTS** (`bun run ingest`, `bun run cut`): Whisper
  52. transcribes the recording, fillers, retakes and long silences are proposed as cuts, and
  53. the cut voice drives the video like a TTS voice would. Film yourself (`talking-head`, the
  54. take is the background and effects stay off your face) or bring a voice recording only.
  55. The words stay what was said: every claim in them still needs a verified fact. See
  56. [docs/visuals/talking-head.md](docs/visuals/talking-head.md).
  57. - **Product promos** (`sk-promo`, `docs/promo/`): the gates an agency would run, in order: objective and
  58. placement, the user's pain first, concept routes, a confirmed treatment, a timed animatic with the real music
  59. on a measured beat grid (`bun run beats`) and a scratch voice (`bun run voice`), a shot-by-shot storyboard,
  60. then the build, cutdowns (15 s, 6 s) and a stranger comprehension test. Vertical feed ads and 16:9 launch films.
  61. - **A shot library** (`docs/shots/`): 160+ named motion recipes (camera, typography, UI entrances, rhythm,
  62. transitions, effects, outros, isometric piles, real typed search), each with parameters in frames, and sound
  63. cards for the SFX pack. Storyboard shots name their card.
  64. ![Twelve shot cards' demos playing at once: kinetic type, card flips, a 3D camera, transitions, a neon frame, a 3D carousel, a card stack, gauges, type assembly, a slam entrance, element moves and a beat cut](docs/assets/shots.webp)
  65. - **Real interface components** in films (`docs/promo/real-ui.md`): Knowns UI by default, or a product's own
  66. components copied from its repo, driven frame by frame, deterministic (a render twice gives the same file);
  67. `bun run capture` for real pages (`--type` to type into the page's own search, `--hide` for overlays).
  68. - **3D**: a Three.js scene kit (`src/shared/three/`: shots, camera rigs, callouts glued to a model) and procedural
  69. models built headless with Blender (`bun run model`), plus CSS-3D isometric piles and turns
  70. (`src/shared/motion/iso.tsx`).
  71. - **8 CC0 sound effects** generated by the kit (`public/sfx/`), and a guide to using
  72. them ([docs/shots/sfx/](docs/shots/sfx/README.md)).
  73. - **Scripts** for every step, from TTS with word timestamps to a platform-ready encode.
  74. - **A local dashboard** (`bun run preview`) showing each video's progress, the render,
  75. the stills, the cover at profile-grid size, and the caption ready to copy. The Script tab
  76. plays the voice with the spoken word highlighted; the Storyboard tab shows every planned
  77. shot with its line, still and playback, for approval before scenes are built. The steps
  78. it tracks come from `docs/pipeline.json`, so a step your channel adds shows up too.
  79. ![The shared library playing at once: sea, moon, rain, props, figures, kinetic type, marks, odometer, satellite map, regions, a globe line, a globe reveal, a 3D model and an isometric pile](docs/assets/gallery.webp)
  80. ![The preview dashboard: the example video at 12/12 steps, with its player, voice timings and stills](docs/assets/preview.jpg)
  81. ## Requirements
  82. - [Bun](https://bun.sh) 1.3 or later
  83. - [ffmpeg](https://ffmpeg.org) and ffprobe on your `PATH`
  84. - A coding agent: [Claude Code](https://claude.com/claude-code), Codex, OpenCode, ...
  85. - A voice. The default depends on the video's language; pick another any time:
  86. - **English → `edge`** (Microsoft Edge online voices): free, no key. The service
  87. sometimes stops answering; `bun run tts` retries.
  88. - **Vietnamese → `vieneu`** ([VieNeu-TTS](https://github.com/pnnbao97/VieNeu-TTS)):
  89. free and offline on CPU, 25 preset voices or clone your own. Needs Python 3.10+.
  90. - [ElevenLabs](https://elevenlabs.io): best quality in either language, needs an API key.
  91. - `say` (built into macOS): free and offline, for testing only. The example uses it
  92. so the kit runs with no network.
  93. - **Your own recording** (optional): needs [whisper.cpp](https://github.com/ggml-org/whisper.cpp)
  94. (`whisper-cli`) and its `large-v3-turbo` model, below.
  95. Install the tools:
  96. ```bash
  97. # macOS
  98. brew install bun ffmpeg
  99. # Linux
  100. curl -fsSL https://bun.sh/install | bash
  101. sudo apt install ffmpeg
  102. # Windows (PowerShell)
  103. powershell -c "irm bun.sh/install.ps1 | iex"
  104. winget install ffmpeg
  105. ```
  106. ## Install
  107. ```bash
  108. git clone https://github.com/howznguyen/shorts-kit.git
  109. cd shorts-kit
  110. bun install
  111. ```
  112. For ElevenLabs, copy `.env.example` to `.env` and set `ELEVENLABS_API_KEY`.
  113. For VieNeu (Vietnamese), install it once into a local Python env (needs [uv](https://docs.astral.sh/uv/)):
  114. ```bash
  115. uv venv --python 3.12 .venv-vieneu
  116. uv pip install --python .venv-vieneu/bin/python vieneu
  117. .venv-vieneu/bin/python scripts/lib/engines/vieneu_bridge.py --voices # downloads the model (~600 MB), lists voices
  118. ```
  119. Then in `narration.json`: `"voice": {"engine": "vieneu", "voice": "Thiện Minh"}`. `voice`
  120. is a preset name or the path to a 3–8 s `.wav` to clone (only a voice you have the
  121. right to use).
  122. To use your own recording instead of TTS, install whisper.cpp and download the model once (1.6 GB):
  123. ```bash
  124. brew install whisper-cpp # macOS; on Linux or Windows build it from github.com/ggml-org/whisper.cpp
  125. mkdir -p .cache/whisper && curl -L -o .cache/whisper/ggml-large-v3-turbo.bin \
  126. https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
  127. ```
  128. ## Check that it works
  129. Build the example video ("Why is the sky blue?", about 43 s) from start to finish. On
  130. macOS this needs no key and no network except for fonts:
  131. ```bash
  132. bun run tts example # voice + word timestamps
  133. bun run lint example # machine checks: 0 errors expected
  134. bun run render example # out/example/example.mp4
  135. bun run cover example # out/example/example-cover.png
  136. bun run normalize example # loudness to -13 LUFS
  137. bun run encode example # out/example/example-upload.mp4, ready to upload
  138. bun run preview # open http://127.0.0.1:7788
  139. ```
  140. On Linux or Windows there is no `say`: set `"engine": "edge"` (or `"elevenlabs"`) in
  141. `src/videos/example/narration.json` first.
  142. ## Make your own channel
  143. Open your agent in the repo and say:
  144. > set up the kit for my channel
  145. `sk-improve` asks about your niche, language, platform, voice, tone and video length,
  146. then edits `SOUL.md` and `docs/soul/thresholds.json` to match, and logs every change.
  147. Then:
  148. > make a video about <your topic>
  149. `sk-pipeline` takes it from there. It tells you where it is and what it needs from you:
  150. mostly approving the script, listening to the voice, and looking at stills.
  151. Already have a recording? Say:
  152. > make a video from ~/Movies/take.mov
  153. The agent runs `bun run from` (a `talking-head` video, or a voice-only one for an audio file;
  154. several clips or a folder work too), and asks you what you actually said wherever Whisper was unsure. Expect
  155. that: on a real take it misheard a phrase as a number and dropped whole words.
  156. ## Commands
  157. | Command | What it does |
  158. | --- | --- |
  159. | `bun run new <id> --flow <A..T>` | scaffold `src/videos/<id>/` from a flow's beats |
  160. | `bun run dev <id>` | Remotion Studio for that video |
  161. | `bun run tts <id> [--force]` | synthesise the whole script, write the audio and `voice.json` |
  162. | `bun run from <file\|dir>...` | "here is my video, edit it": scaffold, transcribe every clip, cut, storyboard stub, and the questions only the speaker can answer |
  163. | `bun run ingest <id> <file>` | recorded voice instead of TTS (a filmed take or a voice recording): Whisper transcript and proposed cuts |
  164. | `bun run cut <id>` | apply the reviewed `cuts.json`: the voice track (and the cut video for `talking-head`), `voice.json` |
  165. | `bun run storyboard <id> [--init\|--sync]` | the shot list after the voice: scaffold it, print each shot with its time and what to fix; `--sync` re-pins shots to their lines after the words change |
  166. | `bun run lint <id>` | style, facts, length and timing checks from `thresholds.json` |
  167. | `bun run facts` | validate the fact ledger |
  168. | `bun run still <id> --frame=N [--safe]` | one frame to `out/<id>/`, with the safe-zone overlay if `--safe` |
  169. | `bun run render <id>` | `out/<id>/<id>.mp4` |
  170. | `bun run cover <id>` | `out/<id>/<id>-cover.png` and `.jpg` |
  171. | `bun run normalize <id>` | loudness to target, `out/<id>/<id>-loud.mp4` |
  172. | `bun run encode <id>` | yuv420p, BT.709, 48 kHz, faststart: `out/<id>/<id>-upload.mp4` |
  173. | `bun run preview [--lan]` | local dashboard; `--lan` adds a token so a phone on your Wi-Fi can open it |
  174. | `bun run satellite <id>` | satellite mosaics for the shots in `src/videos/<id>/map.json` (EOX, CC BY 4.0) |
  175. | `bun run geo <id>` | coastlines, borders and rivers for the same area (Natural Earth) |
  176. | `bun run beats <file>` | measure a music track's beat grid for a promo (bpm, first beat) |
  177. | `bun run voice <id>` | a promo's few spoken lines, one request each, with word times |
  178. | `bun run capture <id> <url> --name <n>` | real pixels of a real page (`--mobile`, `--full`, `--select`, `--type`, `--hide`) |
  179. | `bun run css <id> [--dir <folder>]` | build the Tailwind stylesheet for real components copied into a video |
  180. | `bun run model <name>` | a procedural 3D model with Blender, headless, to `public/models/gen/` |
  181. | `bun run check` | import boundaries and type check |
  182. | `bun run dev gallery` | browse every shared component |
  183. ## Layout
  184. ```
  185. SOUL.md your channel's rules (start here)
  186. AGENTS.md, CLAUDE.md agent entrypoint: invoke sk-pipeline first
  187. .claude/skills/ sk-pipeline, sk-promo, sk-brief, sk-facts, sk-narration,
  188. sk-style, sk-scene, sk-render, sk-handoff, sk-improve
  189. docs/soul/ one file per rule section, plus thresholds.json
  190. docs/flows/ 20 storytelling flows
  191. docs/visuals/ visual types
  192. docs/promo/ promo rules, aesthetics, sound, real UI components
  193. docs/shots/ the shot library (motion and sound cards)
  194. docs/facts/ the fact ledger
  195. docs/lessons/ why videos get zero views; how to measure your niche's style
  196. briefs/ one brief per video
  197. src/shared/ the Remotion library, grouped by kind
  198. src/videos/<id>/ one video: its own entry, narration.json, voice.json (or promo.json)
  199. src/demo/ reference code the shot cards link to (not built)
  200. scripts/ every command above
  201. public/sfx/ CC0 sound effects
  202. out/<id>/ hand-off files (not committed)
  203. ```
  204. Each video has its own Remotion entry, so a broken video never breaks another one, and
  205. `bun run check` stops a video from importing another video.
  206. ## What you still do yourself
  207. - Pick the topic. Topic choice moves views more than anything in this kit.
  208. - Approve the script, listen to the voice once end to end, and approve the storyboard.
  209. - Look at the stills and the render. The agent catches layout bugs, not dull videos.
  210. - Upload, set the cover, and paste the pinned comment (it carries the credits).
  211. - After posting, give your agent the numbers so `sk-improve` can adjust your rules.
  212. ## Community
  213. Made a video with the kit, stuck on a step, or want a second pair of eyes on a script
  214. before you post? Come say hi:
  215. - **Discord:** [discord.knowns.dev](https://discord.knowns.dev): questions, show-and-tell, feedback on drafts
  216. - **Facebook:** [Agentic Coding Vietnam](https://www.facebook.com/groups/agentic.coding.vietnam): cộng đồng tiếng Việt, khoe video và hỏi đáp
  217. Bugs and feature requests go in [GitHub issues](https://github.com/howznguyen/shorts-kit/issues).
  218. ## Licences
  219. The kit is MIT. The sound effects are CC0, generated by the kit. Map data: satellite imagery from EOX Sentinel-2 cloudless (CC BY 4.0, fetched by `bun run satellite`, attribution required), vectors from Natural Earth (public domain), the globe texture from NASA Blue Marble (public domain). The gallery ships four small EOX mosaics of the Mekong Delta and Saigon in `public/img/gallery/`. Fonts come from Google
  220. Fonts (Inter, SIL Open Font License). The preview UI is built from
  221. [Knowns UI](https://ui.knowns.dev) components (MIT), copied into `scripts/preview/kn/`. No music is included: see
  222. `public/music/README.md` before you add any.
  223. Images in `docs/assets/` (README only, not part of the kit): the animated cover (`cover.webp`) plays the kit's
  224. own renders (the example short, a Knowns launch film and feed ad, a MacGrove promo, the 3D gallery), silent;
  225. the animated gallery (`gallery.webp`) is `bun run dev gallery` with its labels off; the shot library
  226. (`shots.webp`) plays the cards' demos from `src/demo/`; the still covers are from the
  227. author's own channel. Satellite imagery in three of them: EOxCloudless
  228. https://cloudless.eox.at by EOX IT Services GmbH (Contains modified Copernicus Sentinel
  229. data 2016), released under the Creative Commons Attribution 4.0 International License.
  230. The Backrooms photo (2002) is from Wikimedia Commons, "Copyrighted free use".
  231. ## Author
  232. Made by [howznguyen](https://howznguyen.dev) · [github.com/howznguyen](https://github.com/howznguyen)

Ratings and comments

Sign in to rate this skill.

Sign in

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