repo2video reads a code repository and directs a finished video about it. It writes a script built only from
facts in the repository, narrates it with a voice that reads code the way engineers say it, scores it with original
synthesized music, and renders frame-exact motion graphics. One command produces five different shows: a launch
trailer, a ride through the architecture, a contributor's onboarding quest, a release broadcast and a vertical short.
pip install git+https://github.com/burhan-mujahid/repo2video
repo2video rtk-ai/rtk -m all
Contents
Formats
Each mode is a complete show with its own script structure, visual language, voice, score, transition style and
caption style. The same facts are told five different ways.
Quick start
Requirements: Python 3.11 or 3.12 (the pronunciation library, misaki, does not yet support 3.13), FFmpeg, and Chrome or Chromium. On first use, the
Kokoro voice model (about 120 MB) and the spaCy English model (about 13 MB) are downloaded from GitHub Releases
into ~/.cache/repo2video.
pip install git+https://github.com/burhan-mujahid/repo2video
python -m playwright install chromium # skip if Chrome is installed
Render every format for a GitHub repository, or one format for a local folder:
repo2video rtk-ai/rtk -m all
repo2video . -m engineering -e all # MP4, HyperFrames, Remotion and BRIEF.md
Edit the script before rendering. Names in backticks are read with their symbols.
repo2video . -m marketing --plan-only -o film
$EDITOR film/story.json
repo2video --story film/story.json
Each run writes a folder such as repo2video-out/rtk-engineering/:
| File | Contents |
|---|
video.mp4 | The finished film, H.264 and AAC at 30 fps |
preview.gif | The first eight seconds, sized for a README |
soundtrack.wav | Voice, score and sound effects, mixed at 48 kHz |
story.json | The editable script and scene data |
facts.json | Everything the analyzer found, with sources |
BRIEF.md | A director's brief for other video tools |
How it works
The pipeline runs in six stages. Facts flow in one direction, and story.json sits in the middle as the contract
that every renderer reads.
| Stage | Module | Responsibility |
|---|
| Analyze | analyze.py | Reads the README, manifests, lockfiles, CHANGELOG and git history. Detects the entry point from package.json, pyproject.toml, Cargo.toml or conventions, follows real function calls into other files, and resolves import statements into a module graph for Python, JavaScript and TypeScript, Rust and Go. |
| Plan | plan.py | Turns facts into one of five shows. Every line is traceable to a file and line range, a manifest field or a commit range. Lines are varied deterministically per repository. |
| Speak | speech.py | Converts written text into how a person says it, then into phonemes, then into audio with per-word timings. |
| Lay out | engine.js | Computes scene timing from the measured speech, quantizes cuts to the beat, aligns the drop to a bar, and emits a sound cue for every visible action. |
| Score | sound.py | Synthesizes the score and effects, places effects on the engine's cues, ducks the music under the voice and normalizes loudness. |
| Render | render.py | Seeks a headless browser frame by frame, encodes with FFmpeg and writes the GIF. |
Facts, not filler. Narration and on-screen text come from the repository. Code is shown verbatim with its path
and line range. Numbers come from the README or git. When text has to be shortened for the screen, the narrator only
reads complete clauses, never a truncated sentence. The call trace prefers hand-offs into other files, because a
call that crosses a module boundary explains more architecture than a local helper.
The voice
Speech engines mispronounce code. repo2video places three layers in front of the
Kokoro voice model.
1. Names are read with their symbols. Paths, files, identifiers, flags, URLs and package names are detected
and verbalized. Punctuation in ordinary prose stays silent, and hyphenated English such as "command-line" is left alone.
| Written | Spoken |
|---|
brief.md | brief dot M D |
main/skills | main slash skills |
register_all() | register underscore all |
src/lib.rs | source slash lib dot R S |
github.com/rtk-ai/rtk | github dot com slash R T K dash A I slash R T K |
--dry-run | dash dash dry dash run |
2. Heteronyms follow the sentence. Part-of-speech tags from spaCy drive the pronunciation
dictionary in misaki, and rule overrides correct what taggers miss.
| Sentence | Pronunciation |
|---|
| Your app goes live. / Ship it live. | /laɪv/ |
| We live in the terminal. | /lɪv/ |
| Have you read it? | /rɛd/ |
| Read the docs. | /rid/ |
| Export the video. / Update your config. | verb stress: ex-PORT, up-DATE |
| The export is ready. / The update is out. | noun stress: EX-port, UP-date |
| Reset the cache. / Do a full reset. | re-SET / RE-set |
The overrides cover 33 stress pairs (export, import, update, upgrade, reset, record, object, project, present,
progress and others), context rules for live, read, lead, tear, wind and bass, and a lexicon of technical terms
(config, README, JSON, YAML, nginx, npm, CLI, API, LLM and more).
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
