Putting video back where it belongs

11 June 2026

4 min

The problem with putting video in a git repo

The repo kept getting heavier, sprint after sprint. We were committing big MP4s next to the code, builds were slowing down, and deploys with them. Case studies lead with video, so every new client made it worse. We needed the media to live somewhere else, and to turn up in a size that suited whatever screen it landed on.

But where? The CMS was out: most aren’t built for video, so the first byte takes too long and the bandwidth bills mount up. The repo was out too, and we knew the downsides first-hand: files the content team can’t touch without a commit, and a history that keeps growing. A proper video CDN would handle the delivery, but they’re a pain to set up and never really talk to the CMS. That’s the awkward thing about web video: there’s nowhere good to put it.

The authoring side

Writing a case study, you drop a short asset ID into the MDX, something like ![hero](eA1XzRaWsAB), and the pipeline takes it from there. No encoding flags to remember, no breakpoints to define, and nobody exporting poster frames by hand.

📷 Split-screen: the short MDX asset ID on the top, the rendered html on the bottom showing six responsive sources One ID in the markdown, six responsive sources on the page.

The point of all this is that the asset ID is the stable interface. Everything behind it was free to evolve, and it did, without a single case study needing an edit.

Under the hood

The video component looks at what it’s been handed and decides how to deliver it. A short asset ID turns into fully responsive video, several formats and breakpoints. A streaming URL goes to adaptive bitrate. A plain file just plays. None of that is the author’s call. The component works it out from whatever it’s given.

The same principle for images

Images work the same way. Five layout presets, each with its own responsive widths and loading behaviour, and AVIF output by default, built at compile time. You pick the layout you want, and the component sorts out the format, the sizes and how it loads.

The infrastructure underneath

It started small: the Air.inc API wired up so assets could be referenced by a short ID, first just in Labs. From there it grew. Full Air.inc integration, then HLS streaming, then that same delivery across every case study. Next came mobile, with streaming that adapts to the device it’s playing on. The last move put SpeedyClip into the delivery layer.

Through all of it, the people writing case studies carried on exactly as before, same markdown, while the rendering quietly improved at every step.

Air is still the asset library and source of truth. The team manages the files, versions and metadata there; the site references those assets by stable IDs. SpeedyClip takes over at the delivery point, turning the Air source into the responsive streams we serve on the site.

That means SpeedyClip handles every video embed on the site without replacing Air in the workflow. It serves optimised streams off the same kind of global edge network the big streaming services run on, the sort of setup you’d normally have to stitch together yourself on every project. All of it is built around load speed and time-to-first-byte. The clever part is how it starts. It streams over HLS, but the opening segment is only two or three seconds long, so the video starts playing almost as soon as the poster appears, instead of waiting for a bigger file to land. Not many people bother going that far.

There’s a lot more to say about SpeedyClip, what it actually is and why a studio ends up this deep in video delivery. That’s a post of its own.

On the visitor’s end

A poster image holds the layout while the video loads, so nothing jumps around as it arrives. The video fades in instead of popping into place. On a slow connection the smaller breakpoint files turn up faster than one big high-res file would, so even on patchy mobile the page stays together.

The poster holds the space, the video fades in over it, and there’s no jump or empty box while it loads.

Twenty-eight case studies now open with video that doesn’t shift the layout, doesn’t drag a history of MP4s behind it, and adapts to whatever connection it loads on. None of which changed how a single case study gets written.

The cache that doubled as a coordinator

Mike Leonard

Field Notes

4 June 2026

2 min

The rendering engine is what visitors see. The data layer feeds it, and keeping it stable under load was the less glamorous half of the build.

This is the second post in the ON Labs series. The first covered the WebGL engine: shaders, draw calls, the GPU-level stuff. This one is about what happens before a single pixel renders: fetching project data from an external API, caching it and making sure concurrent requests don’t trip over each other.

The original problem

Labs pulls project boards and media assets from Air.inc. Early on, every page request made a fresh API call. It worked fine in development and immediately hit rate limits in production. Multiple serverless instances spinning up at once meant dozens of identical requests hitting the same endpoints within seconds.

You can’t just “add a cache” when you don’t control how many instances are running or when they start.

One request rebuilds, the rest wait

The core idea is coordination: when the cache expires, only one instance rebuilds while the others wait. If the rebuild takes too long or fails entirely, stale data gets served instead of an error. A crashed process can’t hold the lock forever; it expires on its own.

One request rebuilds. The rest wait or serve stale. No stampede.

It’s stale-while-revalidate implemented in application code, because the hosting layer doesn’t offer it natively for API-driven data. The storage layer doubles as both cache and coordination mechanism between instances that have no other way to communicate.

Cache versioning and the video pipeline

The cached payload carries a version number. When the data shape changes (new fields, restructured assets) the version bumps and every instance treats the old cache as expired. No manual purging, no deploy-time clears.

A separate store handles optimised video URLs. Each asset’s source maps to transcoded variants at different quality levels, cached per-asset with their own expiry. A concurrency limit keeps the transcoding lookups from overwhelming the provider.

Labs loads quickly. Transitions run smoothly. Filters respond without delay. Nobody sees lock negotiation or stale fallbacks or version checks. They see a portfolio that works.

What the data layer protects: a fast, reliable first impression.

Why build this yourself

Most caching is straightforward: set a TTL, serve from cache, refresh when it expires. The complication is concurrency across serverless instances with no shared memory. Off-the-shelf HTTP caching doesn’t solve that. Coordination in a stateless environment means leaning on a shared store and building the locking yourself.

Not glamorous work. But without it, two people visiting at the same time could bring the whole thing down. That’s not hypothetical.