vertical-video-kit

vertical-video-kit

Make TikToks, Reels and Shorts in code — narration that doesn't sound like a robot, word-by-word captions, and a real 1080×1920 render.

You don't need an AI subscription to use this. The kit is Python and Node. AI agents make it faster, but every script runs on its own from a terminal, and there's a wizard that asks you five questions and hands back a finished MP4. See Do you need to pay for an AI? or jump straight to docs/NO-AGENT.md.

Español · Sin agente, sin pagar

Why

Editing a short in a timeline means every correction is a manual redo. So corrections don't happen, and videos ship with mistakes nobody was willing to go back and fix.

Here the content lives apart from the design. Changing a line of narration is editing one line and re-running a script — the voice regenerates, the scene length changes to match, the animation re-syncs, and the captions follow.

Three problems this solves properly:

• TTS that sounds like TTS. Most of it is the text, not the engine. Every line is normalized for the ear before it reaches the voice — acronyms spelled out, symbols expanded, pacing punctuation — and you can place real pauses with [pause:0.4]. The default engine runs locally and free.
• Captions as an afterthought. They're generated from the audio that was actually rendered, so the highlight lands on the word being said. The layout reserves their band from the start.
• Text under the platform UI. TikTok and Reels cover the bottom ~380px and the right ~160px of your video. The template knows, and you can switch on an overlay to see it.

Install

One command, on a machine with nothing on it:

git clone https://github.com/SDuarteCorredor/vertical-video-kit
cd vertical-video-kit
python install.py

That installs Node, FFmpeg and the Python packages, creates your first project, and opens the Remotion studio in your browser — the live preview, where you watch the video change as you edit it. Run it twice and it skips whatever is already there.

If python isn't found, try python3 (macOS, Linux) or py (Windows). If Python isn't installed at all, bash setup.sh / powershell -ExecutionPolicy Bypass -File setup.ps1 bootstraps it first.

To open the studio again later:

python skills/vertical-video/scripts/studio.py my-video
# or, inside the project:  npm run dev

75+ agents via skills.sh:

npx skills add SDuarteCorredor/vertical-video-kit

Claude Code (paid plan required):

/plugin marketplace add SDuarteCorredor/vertical-video-kit
/plugin install vertical-video-kit

Codex CLI, Cursor, opencode, Copilot, Windsurf read the AGENTS.md at the repo root, which opens with the install command and tells the agent to leave you looking at the studio. Clone first, then start the agent inside the folder, so it reads that file:

git clone https://github.com/SDuarteCorredor/vertical-video-kit
cd vertical-video-kit
codex          # then: "Install this and leave the studio open for me."

On Linux an agent can't type a sudo password, so install Node and FFmpeg yourself first if they're missing — docs/NO-AGENT.md covers it.

Gemini CLI needs to be pointed at it. Create .gemini/settings.json:

{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

Quick start

The wizard — five questions, no AI, no config:

python skills/vertical-video/scripts/wizard.py

Or by hand, if install.py already made you a project:

cd my-video

python scripts/brand.py --compare   # pick a look: bold, clean, editorial, playful, corporate
# write script.json (what is said) and src/content.ts (what is seen)

python scripts/voice.py        # narration + scene timings
python scripts/captions.py     # word-by-word captions
npm run dev                    # the studio, live preview
npm run render                 # output/video.mp4
python scripts/publish.py      # upload/video.mp4, encoded for the platforms
python scripts/share.py        # output/video_light.mp4, small enough for WhatsApp

Your brand, not the template's. scripts/brand.py sets the look from a style plus whatever the brand already has: a design system file (JSON tokens, CSS variables, Tailwind), a logo, colors, any Google font or the brand's own font file. An agent asks about all of this before it builds anything — see references/style.md.

The studio reloads on every save, so leave it open while you write. It works on a brand-new project too — scenes hold 3 seconds each until voice.py has measured the real narration.

Or ask an AI to write the text for you — docs/PROMPTS.md has prompts for coding agents and for any free chat, including a master prompt that returns both files ready to paste.

Do you need to pay for an AI?

No. An agent edits the files and runs the commands for you, which is convenient and entirely optional.

Codex CLI signs in with a free ChatGPT account — the free tier covers short local coding tasks, which is the size of the work here. Claude Code is the one that isn't free: the free Claude plan doesn't include it.

Full walkthrough for a machine with none of this installed: docs/NO-AGENT.md · docs/SIN-AGENTE.md.

What's inside

Each skill's SKILL.md is written to be read by a human too — the design rules, hook patterns, voice craft and corporate-video constraints are in skills/vertical-video/references/.

Voice engines

Set "engine" in script.json. Swappable, same interface.

edge is the zero-install starting point and needs no account. voicestudio sounds better and is also free, but it's a desktop app you have to keep open — if it isn't running, voice.py falls back to edge and says so.

Nothing leaves the machine on either free engine.

On a smaller machine

The kit sizes itself to the computer it runs on. Nothing to configure.

• Rendering uses one headless Chrome per worker, and each costs ~1.2GB of RAM. Remotion's default is one worker per CPU core, which makes an 8-core, 8GB laptop swap until it crawls or crashes. remotion.config.ts caps the workers by available memory too — container limits included — so it finishes, just slower.
• Captions use Whisper's tiny model instead of base under ~4GB of available RAM.

python skills/vertical-video/scripts/doctor.py shows what it picked and why. To override: REMOTION_CONCURRENCY=2 npm run render (PowerShell: $env:REMOTION_CONCURRENCY=2; npm run render), or python scripts/captions.py --model base.

Requirements

• Node 18+ and FFmpeg — required
• Python 3.9+ — for the scripts
• pip install edge-tts faster-whisper yt-dlp pillow — voice, captions, downloads, contact sheets

python install.py handles all of it. python skills/vertical-video/scripts/doctor.py reports what's missing.

Built on

Remotion for rendering · VoiceStudio for local voice · Whisper via faster-whisper for captions · FFmpeg · yt-dlp

Remotion is free for individuals and small teams but requires a company license above that threshold. The rest is free.

Use it responsibly

Download only what you have the right to use. Clone only your own voice, or one you have explicit permission to clone. Don't put claims, numbers or promises in a video that nobody verified — see references/corporate.md if the video carries a company's name.

License

MIT. See LICENSE.

Español