From Git Diff to Video Script: How VidNo Reads Your Commits

Step 1: Change Classification

The first step is understanding what kind of change each diff represents. VidNo classifies diffs into categories:

• New feature: New files created, new functions/classes added, new routes or endpoints
• Bug fix: Changes to existing logic, especially in error handling or conditional branches
• Refactoring: Structural changes without behavioral differences -- renames, extractions, reorganization
• Configuration: Changes to package.json, environment files, build configuration
• Testing: Changes in test files, new test cases
• Documentation: Changes to README, comments, JSDoc/docstrings
• Dependency: Package additions, version bumps, import changes

Classification is based on multiple signals: which files changed (test files vs source files), the nature of the changes (additions vs modifications), and semantic analysis of the code itself.

Step 2: Significance Scoring

Not all changes deserve equal narration time. A 200-line new module needs more explanation than a one-line version bump. VidNo assigns significance scores based on:

• Lines changed: More changes generally mean more significance, but with diminishing returns
• File type: Source code changes are more significant than configuration changes for tutorial purposes
• Novelty: New files and new functions score higher than modifications to existing code
• Complexity: Changes involving control flow (if/else, loops, error handling) score higher than simple assignments
• Dependencies: Changes that affect many other parts of the codebase score higher

Step 3: Narrative Ordering

Git commits have a chronological order, but chronological order is not always the best narrative order. Consider a session where the developer:

1. Added a utility function
2. Created the main feature
3. Fixed a typo in the README
4. Added tests for the feature
5. Fixed a bug found during testing

The narrative order for a tutorial might be: main feature first (context), utility function (supporting code), bug fix (debugging lesson), tests (verification). The README typo is omitted entirely as non-educational.

VidNo reorders diffs to create a logical learning progression, not a chronological replay.

Step 4: Script Generation

With classified, scored, and ordered diffs, the system sends structured context to the Claude API for script generation. The prompt includes:

• The classified diff data with significance scores
• OCR-extracted screen content showing what the developer saw
• The suggested narrative order
• The target video format (full tutorial, quick recap, or highlight reel)

Claude generates a script that:

• Explains each significant change in natural language
• Provides context for why the change was made (inferred from the code structure and patterns)
• Uses appropriate technical terminology for the language and framework
• Maintains a coherent narrative arc from problem to solution

Example: Diff to Script

Given this diff:

+ async function validateEmail(email: string): Promise<boolean> {
+   const regex = /^[^s@]+@[^s@]+.[^s@]+$/;
+   if (!regex.test(email)) return false;
+   const domain = email.split('@')[1];
+   const mxRecords = await dns.resolveMx(domain);
+   return mxRecords.length > 0;
+ }

The generated script might include:

"Next, we add email validation that goes beyond the typical regex check. The validateEmail function first tests the email format against a standard pattern, but then takes it a step further -- it performs a DNS lookup on the domain to verify that MX records exist. This catches cases where the email format looks valid but the domain cannot actually receive mail. Notice that this is an async function because the DNS lookup is a network operation."

This narration would be impossible without understanding both the code structure (AST parsing) and its purpose (diff classification + Claude's code comprehension).

Handling Edge Cases

• Large diffs: When a commit touches hundreds of lines, the system summarizes at a higher level rather than narrating every change
• Generated code: If a diff includes clearly auto-generated code (migrations, lockfiles), it is acknowledged briefly but not explained line by line
• Reverted changes: If code was added and then removed within the same session, the system can either skip it or narrate it as a lesson in exploration

The git diff is the most information-dense artifact a developer produces. Turning it into a coherent narrative is what makes automated video scripting actually useful rather than generic.