Getting started

This page takes you from nothing to a rendered short. It takes about ten minutes, most of it installing tools.

1. Install the system tools#

You need four things:

On macOS:

brew install node ffmpeg python@3.11
python3.11 -m pip install openai-whisper

On Ubuntu:

sudo apt install ffmpeg python3.11 python3.11-venv
python3.11 -m pip install openai-whisper

Whisper downloads its turbo model (about 1.5 GB) the first time it runs.

Any Python that has openai-whisper works. reelsmith doctor shows which one it found. To force one, set REELSMITH_PYTHON:

export REELSMITH_PYTHON=/path/to/python

2. Get Reelsmith#

Pick one of two modes.

Clone mode: the repo is your project#

Good for trying it out, or for changing the framework itself.

git clone https://github.com/Aabishkar2/reelsmith.git
cd reelsmith
npm install
npx playwright install chromium
node bin/reelsmith.js --help

In a clone, run the CLI as node bin/reelsmith.js <command> from the repo. If you want a reelsmith command on your PATH, run npm link once.

The repo already contains a working project: videos/fixture-e2e and ten tutorial videos.

Package mode: a fresh project#

Good for a channel of your own. init creates the project folder and installs the framework into it. The package is not on npm yet, so run it from GitHub:

npx github:Aabishkar2/reelsmith init my-channel
cd my-channel

Once the package is published, npx reelsmith init my-channel does the same. From a clone, node bin/reelsmith.js init ../my-channel works too.

init writes:

my-channel/
  package.json            the reelsmith dependency (github:Aabishkar2/reelsmith)
  reelsmith.config.json   project settings
  .env.example            keys to fill in
  .gitignore
  CLAUDE.md  README.md    instructions for your agent and for you
  config/                 audio.md, music.md, voice/performance.md, fillers.json, strategy.md
  videos/                 your videos
  music/                  CREDITS.md and download.sh for the background tracks
  plugins/                your own plugins
  .claude/skills/         the agent skills
  runtime                 a symlink into node_modules/reelsmith
  styles/                 a real folder: one symlink per built-in pack, plus design.md; your own packs go beside them

It runs npm init -y if there is no package.json, adds the reelsmith dependency, runs npm install and installs Playwright Chromium. It refuses a folder that is not empty unless you pass --force (existing files are kept).

In package mode the CLI is a local dependency. Run it as npx reelsmith <command>. These docs write reelsmith <command> for short.

3. Add your keys#

cp .env.example .env

Open .env and set:

Publish tokens (YouTube, Meta, Discord) come later. See Publishing.

4. Run the doctor#

reelsmith doctor

It checks node, ffmpeg, the Python with Whisper, Playwright Chromium, the project (config, runtime, style packs), each key and every plugin's own check, and prints what is missing and how to fix it. Optional items (for example publish tokens) are marked as optional, and it exits 1 only when a required item fails. reelsmith doctor --json prints the same report as JSON.

5. Make your first video#

Six commands, plus two files that you or your agent write.

reelsmith new prompt-caching

Creates videos/prompt-caching/script.md from the template. Add --style=motion to pick a style pack, or --voice=<name> to fill in the TTS voice.

Write the script: one sentence per line, grouped into ### Scene N blocks. Or ask your agent, which uses the script-writing skill. The format is in Script format.

reelsmith tts prompt-caching --voice=Leda

Synthesizes the voice, runs Whisper for word timings and writes voiceover.mp3 plus scenes.json. Voice names depend on the TTS provider; the built-in one uses the Gemini TTS voices. There is no default voice: you choose one per video. A command takes the video as prompt-caching, videos/prompt-caching or a path.

Now videos/prompt-caching/index.html, the animation. Your agent writes it with the html-animation skill. Every overlay is bound to a spoken word. See Animation.

reelsmith sheet prompt-caching --stills

Writes frames/contact-sheet.png: hook frames and three frames per scene, each labelled with the words being spoken, plus full-size stills in frames/stills/. Look at it.

reelsmith draft prompt-caching

Renders draft.mp4 in about 30 seconds: 15 fps, 0.75× size, with the voice. Watch it, give feedback, iterate.

reelsmith approve prompt-caching --by="you"
reelsmith render prompt-caching

approve records a fingerprint of the animation, the timings, the runtime, the style kit and the images. render writes output.mp4 and refuses (exit code 3) without a current approval.

Optional steps you will want soon:

reelsmith mix prompt-caching --track=music/clean-soul.mp3   # music bed 6 dB under the voice
reelsmith lint prompt-caching                               # the sync linters
reelsmith preview prompt-caching                            # live playback in the browser
reelsmith run prompt-caching --voice=Leda                   # tts → mix → lint → sheet → draft in one go

The tracks come from bash music/download.sh. Set "music": { "defaultTrack": "music/clean-soul.mp3" } in reelsmith.config.json and mix (and run) no longer need --track. Without either, mix stops with exit code 2 and lists the tracks it found. draft and render pick up voiceover-mix.mp3 by themselves.

6. Or let the agent drive#

Open the project in Claude Code and say:

make me a video about prompt caching

The agent follows CLAUDE.md and the reelsmith-pipeline skill. It stops for you at each gate: research approval, script approval, the voice choice, the preview, and publishing. See Agent workflow.

Next#

• Concepts: the pipeline, the files, the gates.
• Voice: TTS modes and recording your own take.
• CLI reference: every command and flag.