Source2Reel: turn a GitHub project into a local explainer video

A repository often contains the ingredients for a good explanation: code, a README, screenshots and documented development. A clear video still needs selection and a coherent sequence. Source2Reel is my local tool for that production process.

The Source2Reel project combines source ingestion, local AI assistance, a structured storyboard, local narration and FFmpeg rendering. Cisco DOOM is its reference episode. This article explains the workflow and review points; generated text still needs human checking.

A source is not yet a story

A technical explanation should answer a clear question: what does the project do, how does it work and what evidence demonstrates the result? A long README section does not automatically become a coherent scene.

Source2Reel creates an inventory with references and hashes, helping you find used material and identify a version. A hash establishes content identity, rather than truth. An older README or demonstration screenshot may describe a different state.

Prepare the local toolchain

The currently documented installation target is Arch Linux on Cthulhu. Read the current BUILD.md before running the installer elsewhere. It installs packages and local environments, which is more than reading a configuration file.

Create a new checkout:

git clone https://github.com/dennishilk/source2reel.git

Enter it:

cd source2reel

After checking prerequisites and the installer, follow the documented setup:

./install.sh

Check the tools:

./s2r doctor

doctor reports dependencies and optional components. A missing model or stopped API can be marked optional; this does not establish that AI production is ready. A complete fresh hardware installation needs its own functional checks.

Choose the model, provider and voice deliberately

Local model files belong in the ignored models/ directory; private settings belong in config/local.toml. Adapt this excerpt to actual files:

[local_ai]
model_path = "models/YOUR-MODEL.gguf"
mmproj_path = "models/YOUR-PROJECTOR.gguf"

A multimodal projector must match its model. These placeholders are not download filenames. Record model revision, quantization and hash when preserving a reproducible setup.

The documented local runtime includes llama.cpp through a local API endpoint. Vulkan/RADV is the Cthulhu context; CPU is a possible fallback. This does not establish universal ROCm or GPU compatibility for every AMD device.

Narration has a separate environment. Listen to a test:

./s2r voice-test

The supplied workflow uses an English voice environment. A German production profile needs suitable tested narration and text. This blog's bilingual articles do not automatically change the tool's output language.

Take a new project to storyboard review

Open the interactive interface:

./s2r

Choose a new episode and provide an authoritative source. GitHub URLs, websites and local directories provide different inputs. Begin with one subject and a clear question rather than a loosely related collection of large sources.

The explicit CLI route for our example is:

./s2r create https://github.com/dennishilk/cisco9951-doom --review

Review allows stopping before the build. For large sources, Source2Reel budgets input and checkpoints intermediate work. Reusing valid parts saves effort but does not replace review after a source change.

Check claims and imagery before building

For Cisco DOOM, distinguishing development stages is essential. An early streaming demonstration and the final native game have different architectures. A good video explains the transition rather than use an old screenshot as proof of final offline operation.

Ask three questions about each relevant scene: does the claim match its source, does the image show the claimed state, and can a reader unfamiliar with the project follow the explanation? Valid JSON alone cannot answer these questions.

Use original images with appropriate rights. A private local folder may contain credentials or unsuitable files alongside useful footage. Select material before importing it, and inspect the resulting image area for private details too.

Render with local narration and watch the result

After reviewing, select a saved episode through the interactive build menu. A direct command needs its actual slug; YOUR-EPISODE-SLUG is a placeholder:

./s2r build YOUR-EPISODE-SLUG

The documented output is 1920×1080 H.264 video with AAC audio. Scene duration comes from the generated narration. Original media, fonts and required FFmpeg features must exist locally; an episode using additional untracked media is not automatically complete after a fresh clone.

Watch and listen to the entire video. Check pronunciation, line wrapping, burned-in captions, transitions and whether images match the spoken claims. Local rendering does not prevent incorrect conclusions or misleading wording.

Keep artifacts and project status understandable

A production involves more than its MP4. The storyboard, transcript, evidence and provenance help with review. Project notes document an accepted reference episode with twelve scenes and approximately 283.6 seconds on Cthulhu. That is a specific historical checkpoint, rather than a success guarantee for every input.

The consolidated installer and later changes have separate validation boundaries. Consult BUILD.md and current project notes rather than assume an older episode's acceptance verifies every new installation route.

Private models and runtime files live in ignored directories. Preserve them separately when needed; Git does not automatically back them up. A clear Git history helps identify published source revisions instead.

References

• Source2Reel on GitHub.
• Checked workflow description.
• BUILD.md, local AI and project status.
• Cisco DOOM source project.

References checked on 8 October 2026. This article explains the documented pipeline; it does not claim a newly completed full render on Cthulhu.