Developers · Protocol

Build a receiver with an AI assistant.

An open protocol used to mean "if you have a developer." The Airlive wire format is an 18-byte header and some JSON, which is exactly the size of problem a coding assistant handles well. Here is the build order that works, and the three things you have to catch yourself.

Airlive team 7 min read

Why this is now a one-evening job

The protocol was designed to be dull on purpose. One TCP connection carries everything. Each message is a fixed 18-byte header — a magic number, a version, a packet type, a length and a timestamp — followed by a payload. Video is H.264. Control is JSON. There is no handshake dance, no custom compression, no state machine worth drawing.

That matters because it is precisely the shape of task an assistant is good at: a written specification, a small surface, and a result you can test after every step. You are not asking it to invent anything. You are asking it to transcribe a spec into a language you already run.

Point it at the source of truth

Give the assistant the specification repository and tell it that is the authority — not its memory of similar protocols. Two reference implementations are open as well, and they are worth naming in the prompt: Bridge in Swift and the OBS plugin in C++ and FFmpeg. When something behaves oddly, "compare against the reference receiver" is a faster instruction than describing the symptom.

Say what you're building on. The framing is language-agnostic, so name your stack up front — Python, Rust, Go, Node, C — along with the decoder you intend to use. Otherwise you get Swift, because the reference is Swift.

Build in this order

Each step produces something you can verify before moving on. Skipping ahead is how you end up debugging four things at once.

  1. Advertise the service. Publish a Bonjour/mDNS service of type _airlive._tcp and accept a TCP connection. Success looks like: your receiver's name appears in the camera app's list.
  2. Parse the framing. Read the 18-byte header, validate the magic, then read exactly as many payload bytes as the length says. Success looks like: a log line per packet, with plausible types and lengths, that never desynchronises.
  3. Handle the control channel. Packet type 2 is JSON. Print the state snapshot the camera sends on connect. Success looks like: the phone's real ISO, shutter and lens showing in your terminal.
  4. Decode video. Feed the format description to your decoder, then the access units. Success looks like: one frame written to disk as a still image.
  5. Send something back. Emit a control message — setCue is the most satisfying, because the phone's tally lights up in your hand.

Only after step 5 should you build a window, a UI, or anything that looks like an app. A receiver that logs to a terminal and turns a tally red is already a complete proof.

The three things it will get wrong

These are not exotic. They are the standard failure modes of network code, and an assistant writes them confidently.

  1. Treating a TCP read as a message. TCP is a byte stream. One read() may return half a header, or two packets and a fragment. The assistant will often write code that assumes one read equals one packet, and it will appear to work on a fast local network until it doesn't. Say explicitly: buffer incoming bytes, and only consume a packet when the full header and the full declared payload are present.
  2. Confusing AVCC with Annex B. The video is AVCC — each NAL unit is prefixed with its length. Many decoders and most sample code expect Annex B start codes instead. If your decoder outputs nothing at all while the byte counts look right, this is almost always why.
  3. Inventing commands. Ask for something the protocol doesn't carry — audio, a resolution change mid-take — and you may get plausible-looking code for it. The camera ignores verbs it doesn't know, so this fails silently. Check any command against the spec before you trust it.

Know the boundaries before you design around them

The protocol carries video and control, not audio — plan your sound path separately. Discovery is Bonjour, so this is a local-network design; crossing the internet means a receiver that republishes, the way Bridge does over SRT. And the optional password is an access check, not encryption.

What to do with it once it runs

A working receiver is a starting point, not a destination. The interesting versions are the ones that do something no general-purpose tool does: put frames into a model, drive a texture in a renderer, run headless on a small box, or close a loop by reading the camera's state and sending commands back. There is a map of those directions, and the licence is Apache-2.0, so a commercial closed-source receiver is fine.

If you build something, we'd genuinely like to see it.

Related guides

All articles