DirectoryLM: Grounded Explainer Videos From Any Folder

• Project Type: Personal / Tooling
• Timeline: Ongoing (phased build)
• Category: AI / Video / Local-First
• Year: 2026

The Challenge

AI-generated video has a trust problem, and it's a bad one. The tools that turn text into a slick narrated video will happily invent a statistic, misattribute a quote, or confidently describe a feature that doesn't exist — and because the output looks like a polished documentary, nobody questions it. That's fine for entertainment. It's useless for anything where being wrong matters: onboarding docs, technical explainers, turning a written guide into its video counterpart.

I wanted the opposite. Point a tool at a folder — a codebase, a set of notes, a project directory — and get a proper explainer video out the other end, but with a hard guarantee: every factual claim in the narration is traceable back to a specific source file. Not "roughly based on your docs". Traceable, to a line range, a heading, a page number, a timestamp. If the sources don't say something, the video doesn't say it either.

On top of that, I wanted it local-first. No uploading a client's private codebase to somebody's cloud to find out what it does. The whole pipeline — indexing, scripting, verification, narration, rendering — should run on my own machine. Think NotebookLM's grounding discipline, but pointed at a directory and producing an actual watchable documentary instead of a chat.

The Approach

The core design decision is that the language model is never allowed to free-generate about the directory. Every claim-making prompt contains only retrieved index chunks plus a system preamble that forbids outside knowledge, and "the sources don't specify that" is a valid, expected answer rather than a failure. That single rule shapes everything downstream.

From there, the honesty is enforced mechanically, not on trust:

• Typed sentences. Every sentence in the script is classified as factual (must cite index anchors), inferred (a cautious reading, flagged as such), or framing (transitions with no factual content). Framing or inferred sentences that sneak in a checkable assertion get flagged.
• Machine verification before render. Citations are mechanically resolved, then a second-pass LLM judge checks that each cited snippet actually supports the claim it's attached to. Unsupported sentences are rewritten — up to two rounds — or removed. The renderer flat-out refuses to run unless the verification report says it passed with zero unsupported claims.
• Auditable in seconds. A verification table lists every sentence, its citations, the exact supporting snippet, and the verdict. A separate audit classifies every file it found — included, ignored, unreadable, duplicate or low-confidence — with reasons. Duplicates, corrupt files and dodgy OCR are recorded, never quietly hidden.

Citation anchors are stable and human-readable on purpose — things like src/main.py#L40-L88, notes/plan.md#pricing, report.pdf#p4, or memo.wav#t0-t30 for a transcribed audio clip. You can click a claim and land exactly where it came from.

The index itself is one file: a single sqlite-vec database holding file metadata, sections and embeddings in the same transactional store. No separate vector server, no second on-disk store — at directory scale, brute-force cosine over a vector table is instant, and one file is trivially resumable. Every stage of the pipeline caches its artefacts, so re-running with unchanged inputs is a no-op and editing one thing re-does only that thing.

What Was Built

The pipeline runs end to end from the command line: ingest and index a folder, generate a cited script, verify it, then render a 1080p MP4 with burned captions and TTS narration and a matching subtitle file beside it. It reads a wide spread of inputs — markdown, text, PDF, Word docs, CSV, JSON/YAML, a stack of code languages, HTML converted to clean markdown, images with EXIF and OCR, and audio transcribed locally with faster-whisper. Unknown binaries aren't dropped silently; they're recorded honestly as low-confidence.

The part I'm proudest of is the motion engine. Scenes render in headless Chromium via Playwright on a virtual clock — every animation is a pure function of time t, so identical inputs produce byte-identical frames, and that determinism is asserted by tests. The default engine draws frames in immediate-mode Canvas2D and encodes them inside the browser with WebCodecs, which the render roadmap measures at roughly 3.5× faster per worker than the older screenshot approach.

What you see is driven by what a sentence cites. Stats anchors become animated bar charts, stat punch-cards or timelines; code anchors become snippets with a line-highlight that follows the narration; image files get the Ken Burns treatment; prose becomes typed-on quote cards or evidence panels. Citations always ride along in the footer chrome. A deterministic pacing pass picks transitions per edit and guarantees something visually changes at least every eight seconds, so nothing sits static and dull.

There's also a tutorial mode: pass a topic and the video becomes a how-to answering that question from the sources — prerequisites, then steps in doing order, then pitfalls, then a recap — with UI names quoted verbatim from the material and any step the sources don't cover openly declared missing rather than invented. You can even mirror a written guide's own structure section-for-section, which is exactly what you want when turning documentation into its video version.

Where It Stands

DirectoryLM is further along than most of my personal projects, and I'll be specific about it. Phase 1 (the MVP gate) and Phase 2 (the motion graphics engine) are complete and gated. The canvas-plus-WebCodecs renderer is shipped and is now the default. Phase 3 — vertical 9:16 Shorts with hook-ranked, individually verified clips plus style packs that drive persona, pacing, captions and transitions — is shipped. Phase 4, a local web UI at directorylm serve with tabs for audit, script, verification and video and clickable citations that resolve to source snippets, is shipped too. Every phase went out behind its own gate; the remaining unchecked boxes are human watch-and-sign-off items, not missing features.

It's genuinely local: the default LLM endpoint is a locally-run OpenAI-compatible server (LM Studio out of the box), TTS defaults to bundled Piper, transcription and embeddings are local, and the only hard external requirement is ffmpeg on your PATH — which it checks for and errors clearly about if it's missing. Cloud providers work if you want them, by pointing the base URL at a gateway, but nothing depends on any specific vendor. There's a stub provider for fully offline, deterministic testing, and the integration test drives the real CLI over a deliberately messy fixture project, asserting 100% citation coverage, a passing verification report, correct caption timing and a playable MP4.

The honest summary: the trust mechanism is the whole product, and it works — the renderer literally won't produce a video that contains an unsupported claim. That's the bit that makes this worth using over the slicker, less careful tools. It's a tool I reach for when I need a folder explained truthfully, not just impressively.

Related Services

DirectoryLM is part of my broader AI Solutions offering — grounded RAG systems, local-first AI pipelines, and bespoke automation for clients across the UK. If you need documents, codebases or knowledge bases turned into something people will actually consume — and trust — check my pricing or get in touch.

For another angle on frame-perfect, in-browser rendering, see my Lyric Video Builder case study — same WebCodecs approach, aimed at music instead of documentation.

---