shorts-kit

Make narrated vertical shorts (TikTok, YouTube Shorts, Reels) with a coding agent and Remotion.

You talk to your agent ("make a video about why the sky is blue"). The agent follows the kit's skills step by step: facts first, a storytelling flow, the script, the voice, the scenes, stills to check, the render, the cover and the caption. You review, then you upload the file yourself. The kit never posts anything.

The rules and skills come from a private pipeline that took a new knowledge channel from zero to about 120k views on its best video in two months. Every rule keeps the reason it exists, because most of them were written after a published video broke it. They are defaults: change them for your own channel.

Results

The channel these rules came from, two months in. The best videos and the flops sit side by side on purpose: topics close to the audience carried it (tens of thousands of views), topics that drifted from the channel's niche got a few hundred. The kit cannot pick your topic for you.

What a finished run reports, from the original private pipeline (it also copied files to a NAS and applied that channel's own swearing rule; neither is part of this kit):

What is in the box

• 9 agent skills (.claude/skills/sk-*), started by sk-pipeline. They work in Claude Code, and in any agent that reads AGENTS.md (Codex, OpenCode, ...).
• SOUL.md: your channel's rulebook. Voice, sentence style, writing for a text-to-speech voice, safe zones, captions, audio, facts, covers, hand-off. Each rule is tagged [measured], [default], [craft] or [hard] so you know how freely to change it.
• 20 storytelling flows (docs/flows/): Three reasons, Trace back, Explain it, Reading a graph, Empty world with a late reveal, and more. Each has beats, when to use it and its traps.
• A fact ledger (docs/facts/). No sentence goes into a script before its claim has a verified record, and the linter enforces it.
• A Remotion library (src/shared/): word-timed captions, kinetic type, safe-zone overlay, music bed and SFX, camera moves, and an illustrated world (sky, sea, sun, moon, stars, clouds, rain, birds, people, fish).
• Maps and a globe (src/shared/map/): satellite imagery with a camera that flies from country to street and stays sharp, coastlines, borders and rivers from Natural Earth, routes that draw on, pins, measured distances, filled regions, a ready Vietnam map with the Hoàng Sa and Trường Sa archipelagos, a 3D globe with great-circle lines, and a pull-out from any scene to the globe.
• Shared graphics for any video: strike-and-replace, slot word, word slam, typewriter, hand-drawn circles, arrows, underlines, cross-outs and stamps, and charts that stay true to scale (compare bars, progress ring, unit grid, odometer). Browse them with bun run dev gallery.
• Your own voice or footage instead of TTS (bun run ingest, bun run cut): Whisper transcribes the recording, fillers, retakes and long silences are proposed as cuts, and the cut voice drives the video like a TTS voice would. Film yourself (talking-head, the take is the background and effects stay off your face) or bring a voice recording only. The words stay what was said: every claim in them still needs a verified fact. See docs/visuals/talking-head.md.
• 8 CC0 sound effects generated by the kit (public/sfx/), and a guide to using them (docs/sfx.md).
• Scripts for every step, from TTS with word timestamps to a platform-ready encode.
• A local dashboard (bun run preview) showing each video's progress, the render, the stills, the cover at profile-grid size, and the caption ready to copy. The Script tab plays the voice with the spoken word highlighted; the Storyboard tab shows every planned shot with its line, still and playback, for approval before scenes are built. The steps it tracks come from docs/pipeline.json, so a step your channel adds shows up too.

Requirements

• Bun 1.3 or later
• ffmpeg and ffprobe on your PATH
• A coding agent: Claude Code, Codex, OpenCode, ...
• A voice. The default depends on the video's language; pick another any time:
  • English → edge (Microsoft Edge online voices): free, no key. The service sometimes stops answering; bun run tts retries.
  • Vietnamese → vieneu (VieNeu-TTS): free and offline on CPU, 25 preset voices or clone your own. Needs Python 3.10+.
  • ElevenLabs: best quality in either language, needs an API key.
  • say (built into macOS): free and offline, for testing only. The example uses it so the kit runs with no network.
  • Your own recording (optional): needs whisper.cpp (whisper-cli) and its large-v3-turbo model, below.

Install the tools:

# macOS
brew install bun ffmpeg

# Linux
curl -fsSL https://bun.sh/install | bash
sudo apt install ffmpeg

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"
winget install ffmpeg

Install

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):

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).

To use your own recording instead of TTS, install whisper.cpp and download the model once (1.6 GB):

brew install whisper-cpp     # macOS; on Linux or Windows build it from github.com/ggml-org/whisper.cpp
mkdir -p .cache/whisper && curl -L -o .cache/whisper/ggml-large-v3-turbo.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin

Check that it works

Build the example video ("Why is the sky blue?", about 43 s) from start to finish. On macOS this needs no key and no network except for fonts:

bun run tts example        # voice + word timestamps
bun run lint example       # machine checks: 0 errors expected
bun run render example     # out/example/example.mp4
bun run cover example      # out/example/example-cover.png
bun run normalize example  # loudness to -13 LUFS
bun run encode example     # out/example/example-upload.mp4, ready to upload
bun run preview            # open http://127.0.0.1:7788

On Linux or Windows there is no say: set "engine": "edge" (or "elevenlabs") in src/videos/example/narration.json first.

Make your own channel

Open your agent in the repo and say:

set up the kit for my channel

sk-improve asks about your niche, language, platform, voice, tone and video length, then edits SOUL.md and docs/soul/thresholds.json to match, and logs every change.

Then:

make a video about

sk-pipeline takes it from there. It tells you where it is and what it needs from you: mostly approving the script, listening to the voice, and looking at stills.

Already have a recording? Say:

make a video from ~/Movies/take.mov

The agent runs bun run from (a talking-head video, or a voice-only one for an audio file; several clips or a folder work too), and asks you what you actually said wherever Whisper was unsure. Expect that: on a real take it misheard a phrase as a number and dropped whole words.

Commands