# Read the MP4 Boxes and Refuse HEVC Before Uploading a Byte

> ActionMode's upload page reads an iPhone video's own box headers to detect HEVC and refuse it before a single byte is sent, because HEVC does not play in every browser a lead might open.

- Author: Dil Ahdan (https://dil.dev/)
- Published: 2026-11-04
- Updated: 2026-11-04
- Tags: video, mp4, upload, browser-compatibility
- Canonical: https://dil.dev/notes/mp4-box-probe-refuse-hevc/

## Key takeaways

- Range reads on the MP4 file reveal codec, duration and display size before any upload begins.
- HEVC and Dolby Vision are refused outright rather than converted, because conversion adds complexity the product does not need.
- The fix is one iPhone setting: Settings, Camera, Formats, Most Compatible.
- An MCP tool call carries JSON only and hands back a destination; bytes never travel through the tool.
- The upload token is stored as a hash only, and a used link cannot be uploaded to again.

The upload door on ActionMode's phone video page does one thing before it touches the network: it reads the file's own MP4 box headers, finds the codec, and refuses if it is HEVC. No bytes are sent. No server is involved. The founder sees the exact iPhone setting that fixes it.

That is the whole point. HEVC and Dolby Vision do not play in every browser a lead might open, and the product cannot guarantee which browser a lead uses. Refusing early is cheaper and more honest than silently converting or letting a broken video through.

## Why HEVC Is a Problem Worth Refusing

iPhones default to HEVC because it produces smaller files. That is fine for iCloud and AirDrop. It is not fine for a video that a sales lead opens in Chrome on Windows, or Firefox on Android, or a corporate browser with restricted codec support.

The product's promise is that a founder records a quick video and a lead watches it. If the lead cannot play it, the promise is broken. Conversion would fix playback but adds a transcoding step, storage overhead and a failure mode. The simpler answer is to refuse and explain.

## What the Box Reader Actually Does

`lib/video/mp4-boxes.ts` reads duration, display size and codec from box headers and the moov atom only. It uses HTTP Range reads, so it fetches a small slice of the file rather than the whole thing.

`classifyCodec` maps:

- **avc1 and avc3** to h264 (accepted)
- **hvc1, hev1, dvh1 and dvhe** to hevc (refused)

Dolby Vision boxes (dvh1, dvhe) are refused alongside standard HEVC because they share the same browser support gap. The classification is tested against real ffmpeg-made fixtures, not synthetic data.

## The Refusal Message and the Fix

When the page detects hevc, it stops and tells the founder:

> Go to Settings, Camera, Formats, Most Compatible.

That one change makes the iPhone record H.264 instead of HEVC. The founder re-records or re-exports, picks the new file, and the upload proceeds. No server round-trip, no waiting, no mysterious failure later.

This is the behaviour the code ships. An earlier digest mentioned conversion; the code refuses. Follow the code.

## How the MCP Tool Fits In

An MCP tool call carries JSON, never file bytes. `start_video_upload` hands back a destination: a single-use upload URL with a token. The tool itself does not touch the video payload.

That separation matters because:

- **The tool stays lightweight.** It does not need to handle binary streams or multipart bodies.
- **The bytes go directly to storage** over resumable TUS, uploaded as video/mp4.
- **The token is stored as a hash only.** The raw token is never persisted, so a database leak does not expose usable upload URLs.

`finish_video_upload` closes the session. It is idempotent, so a network retry or a double-tap does not corrupt anything.

## The Single-Use Link

Once a finish is recorded against a token hash, that link is done. A used link cannot be uploaded to again.

This matters for a few reasons:

- **Replay attacks are blocked.** A leaked or replayed URL cannot overwrite an existing video.
- **State is clean.** There is no ambiguity about whether a session is open or closed.
- **The founder gets a fresh link for each upload.** Each session is independent.

The token hash approach means the server can verify a token without storing anything that could be replayed if the database were read.

## Drawing the Poster

If no poster is supplied, the upload page decodes a frame from the video client-side and draws it. The MCP tool also bakes a poster when none is sent.

This keeps the video entry complete without requiring the founder to supply a separate image. A decoded frame is usually good enough for a thumbnail, and it is produced from the actual video rather than a placeholder.

The poster is drawn before the upload completes, so it is available immediately when the video record is created.

## The Full Upload Path in Order

1. Founder picks a file on the phone upload page.
2. The page does Range reads on the file, extracts codec, duration and display size from box headers and moov.
3. If codec is hevc, refuse with the iPhone setting. Stop here.
4. If codec is h264, proceed.
5. Page draws a poster from a decoded frame if none is provided.
6. `start_video_upload` MCP call returns a single-use upload URL (token stored as hash).
7. File uploads over resumable TUS as video/mp4.
8. `finish_video_upload` closes the session, idempotent on retry.
9. Used link is locked. No further uploads accepted on that token.

The Range read step is the one that does the work. Everything else is plumbing that keeps the session clean and the state honest.

## What I'd do differently

The refusal message is correct and specific, but it only appears after the founder has already picked the file. On a phone, picking a video from the camera roll is a few taps. If the page could detect HEVC on a previous session and surface a warning before the file picker opens, the founder would know to change the iPhone setting before they even try again.

That said, detecting a previous HEVC attempt requires storing something about the last session, which adds state. The current approach is stateless and simple. I would want to measure how often founders hit the refusal before adding that complexity.

The other thing I would revisit is the poster quality. A decoded frame from a short video is fine, but if the video starts on a dark or blurry frame, the poster is not great. A seek to a fixed offset, say one second in, would give a more representative frame without much extra work.

## Quick answers

**Why refuse HEVC instead of converting it server-side?**

Conversion adds a server-side transcoding step, extra storage and latency. The product refuses HEVC and tells the founder exactly which iPhone setting produces a compatible H.264 file instead, so the problem is solved at the source.

**Which codecs does the box reader classify as HEVC?**

classifyCodec maps hvc1, hev1, dvh1 and dvhe to hevc. avc1 and avc3 map to h264 and are accepted. Anything else is also refused.

**How does the upload page read codec without downloading the whole file?**

lib/video/mp4-boxes.ts uses HTTP Range reads to pull only the box headers and the moov atom. The full video payload is never fetched just to inspect metadata.

**What is the single-use link and why does it matter?**

Each upload session gets a token whose hash is stored, not the token itself. Once a finish is recorded, the link cannot be uploaded to again, so a replayed or leaked URL cannot overwrite an existing video.

**What happens if the finish call is sent twice?**

finish_video_upload is idempotent. A second call with the same token returns the same result without creating a duplicate or corrupting the record.

**How is the poster image produced?**

If no poster is supplied, the upload page decodes a frame from the video client-side and draws it as the poster. The MCP tool also bakes a poster when none is sent.
