# DirectoryLM: Grounded Explainer Videos From Any Folder By AJTheDev — 2026-07-10 Canonical: https://ajthe.dev/case-studies/posts/directorylm-explainer-engine.html --- **Category:** AI & Automation **Client:** Personal Project **Duration:** Ongoing **Tech:** Python, Playwright, WebCodecs, Canvas2D, sqlite-vec, Piper, faster-whisper, sentence-transformers, FFmpeg Point it at a directory and it makes a 3–6 minute explainer video about that directory — where every single factual claim is traceable back to a source file. NotebookLM meets a YouTube documentary, running entirely on your machine. - **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](https://ajthe.dev/ai-solutions/) — 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](https://ajthe.dev/ai-solutions/#pricing) or [get in touch](https://discord.gg/d39aaZXAjh). For another angle on frame-perfect, in-browser rendering, see my [Lyric Video Builder case study](https://ajthe.dev/case-studies/posts/lyric-video-builder.html) — same WebCodecs approach, aimed at music instead of documentation. --- **Written by AJTheDev** — North London developer. AI, FiveM, and web stuff. No bullshit. [Full story here](https://ajthe.dev/about/). Need trustworthy AI content pipelines? Explore my [AI services](https://ajthe.dev/ai-solutions/), join the [Discord](https://discord.gg/d39aaZXAjh), or use the [contact page](https://ajthe.dev/contact/).