What The FFMPEG began as a 1,122-line plan

Corruption Check shipped on June 27, 2025: a route that runs FFprobe against an upload and flags corruption with repair suggestions, 569 lines for the API and 514 for the page, with the README updated to describe it the same commit. It's the last commit before things go quiet. Then nothing. The next commit on main is dated December 4, over five months later, and it's a one-line fix: renaming KV_REST_API_URL and KV_REST_API_TOKEN to STORAGE_KV_REST_API_URL and STORAGE_KV_REST_API_TOKEN after a Redis integration rename broke the existing wiring. No commit in between explains the gap. It's just there.

Two days after that Redis fix, on December 6, a commit titled "inital wtffmpeg" opens the next real stretch of work.

A plan before any code

The typo is in the original. It's also the first commit in what becomes "What The FFMPEG," the deep video-analysis tool that's now a core part of the product, and it doesn't start with a component. It starts with a 1,122-line plan document, docs/WHAT_THE_FFMPEG_PLAN.md, that opens by naming its own approach:

A comprehensive FFMPEG visualizer tool that provides extremely detailed analysis of media files using FFProbe, FFPlay, and FFMPEG. Inspired by StreamEye's detailed stream analysis capabilities, this tool will visualize every aspect of media files including codec information, frame-level data, bitstream analysis, and more. This plan reuses existing infrastructure and patterns from the BeemMeUp codebase.

What it reuses is specific: the same signed-URL upload flow the June analyzer built, the same Cloud Run FFprobe service (called with the exact same { url, initUrl, detailed } request shape the fMP4 work established), the same GCS and Redis key structure, the same shadcn/ui styling. The plan's first section is titled "Quick Start: Reusing Existing Infrastructure" before it gets to anything new. Six months of near-silence on main, and the next feature still starts by pointing back at what June already built rather than starting over.

The same commit ships the first real page too: app/what-the-ffmpeg/[fileId]/page.tsx, 2,001 lines in its first version, plus overview, streams, packets, and timeline routes. A second doc, docs/WHAT_THE_FFMPEG_QUICK_REF.md, ships alongside the plan at 255 lines, a shorter reference for whichever parts of the 1,122-line plan actually needed to stay handy while building.

Down to the bitstream

Three days later, on December 9, in a commit titled "adding more docs," the tool goes a level deeper than stream-level metadata. lib/nal-parser.ts (291 lines) and five new viewer components (hex viewer, NAL timeline, parameter-set viewer, structure tree, binary visualizer) add bitstream-level inspection. The tool can now show the individual units of encoded data inside a stream, on top of which codec it uses.

For anyone who hasn't had a reason to know this: a NAL unit is the basic packaging format H.264 and H.265 video data is broken into for storage or transmission, and every frame's compressed data is split across one or more of them. Two special NAL unit types, the sequence parameter set (SPS) and picture parameter set (PPS), carry the decoder configuration (resolution, profile, reference-frame settings) that every other NAL unit in the stream depends on to decode correctly. Visualizing them individually is what turns "this file is H.264" into "here's the exact SPS this encoder wrote, and here's what would break if a client didn't support it."

The first PRs wrap work already written

The repo's PR-based workflow doesn't start until January 1, 2026, three weeks after this code was written. PR #1, "inital wtffmpeg," merges at 22:10 UTC that day. PR #2 merges three minutes later, at 22:13. Both are squashed wrappers around commits that had already landed on main in early December. The repo's PR history starts with paperwork for code that was already there.

PR #2's own body, titled "Performance Optimizations and Health Monitoring," lists Cache-Control headers for favicon and icon requests, CSS containment for layout and paint performance, and a /api/health endpoint that checks the Redis connection and falls back to in-memory storage if it's down. None of that is What The FFMPEG. What it also carries, folded into the same commit, is the change that actually matters for every deploy after it: lib/gcs-config.ts rewritten to require GCP_SERVICE_ACCOUNT_KEY as base64-encoded JSON instead of parsing raw JSON out of an environment variable.

const base64Content = process.env.GCP_SERVICE_ACCOUNT_KEY.trim();
const jsonString = Buffer.from(base64Content, 'base64').toString('utf-8');
const credentials = JSON.parse(jsonString);

Every GCS credential in the codebase is still read this way. It arrived as a line item in a performance PR, three weeks after the code it now protects.