h264: wait for a partition head before depayloading

[ajplotkin]

Summary

RTPDepay (pkg/h264/rtp.go) creates a fresh codecs.H264Packet and begins feeding it whatever RTP packet arrives first. A consumer that attaches to a live stream partway through a fragmented NAL unit therefore starts with FU-A fragments whose start fragment was never received.

codecs.H264Packet appends FU-A fragments without checking the start bit, and on the end bit it synthesizes a NAL header from the fragment type. The result is a NAL unit that never existed on the wire: correctly shaped, but missing its head — including the slice header. When the fragmented type is 5, it also passes IsKeyframe, so callers treat it as a valid keyframe and hand it to a decoder that cannot decode it.

Reproduction

The added test feeds only the tail fragments of a fragmented IDR. On current main it emits:

[0 0 0 5 101 170 187 204 221]

101 is 0x65 — nal_ref_idc=3, nal_unit_type=5 (IDR) — followed by nothing but the orphan fragment bytes. A synthesized keyframe assembled from a NAL whose beginning was never seen.

Fix

Skip packets until IsPartitionHead reports one, then depayload exactly as before. Packets dropped by this gate could only ever have produced a malformed NAL.

This matches what pion already does elsewhere: IsPartitionHead is part of the Depacketizer interface, and pion's own SampleBuilder refuses to begin a sample that is not a partition head. RTPDepay bypasses SampleBuilder, so it never gets that protection. RFC 6184 §5.8 likewise requires discarding fragments that follow a lost start.

Where this shows up

Anything that builds a depayloader per consumer and attaches mid-stream. The snapshot path is the most visible: /api/frame.jpeg creates a new keyframe consumer per request, so a request landing mid-IDR gets a head-truncated "keyframe" and ffmpeg fails on it — intermittently, without any error that identifies the cause. On one long-running deployment this produced a few percent of snapshot requests failing with Invalid data found when processing input or a 100% decode-error rate, plus occasional solid-grey JPEGs (a decoder concealing a keyframe with no slice header). Live restream and MP4 consumers attach the same way.

I am deliberately not claiming this is the sole cause of those production failures — mid-stream packet loss can corrupt an access unit too, and I have not instrumented enough to separate them. The defect above stands on its own at the code level regardless, which is what the test demonstrates.

Notes

• No behavior change once synced — the gate is one bool check per packet until the first partition head.
• Does not address corruption from loss after attach (a sequence-continuity check would be a separate change).