MP4(3)

💖 MP4(3) — the MP4 File Format Library, bestie edition 💖

okay so you're here for MP4ReadRtpPacket, and honestly? iconic behavior. this is a page from the MP4 File Format Library manual (section 3, library calls, if you're keeping score 🎀), and I'm gonna walk you through every single bit of it. grab a snack. let's go. ✨

---

🌸 NAME 🌸

MP4ReadRtpPacket — read an RTP packet. that's it, that's the whole job. she reads one packet. queen of doing one thing well. 👑

---

✨ SYNTAX ✨

#include <mp4.h>

bool MP4ReadRtpPacket(
     MP4FileHandle hFile,
     MP4TrackId trackId,
     u_int16_t packetIndex,
     u_int8_t** ppBytes,
     u_int32_t* pNumBytes,
     u_int32_t ssrc = 0,
     bool includeHeader = true,
     bool includePayload = true
);

look at that signature. the way it has defaults?? ssrc = 0, includeHeader = true, includePayload = true. C++ vibes in a C library, we love a lil flexibility. 🫶

---

🦋 ARGUMENTS 🦋

• hFile — the mp4 file we're operating on. which file? this file. point at it, love it, pass it in. 💅
• trackId — the hint track we're operating on. not just any track, bestie. the hint track specifically.
• packetIndex — which packet do you want? valid values run from zero up to the number of packets in this hint minus one. so like, zero-indexed, as the universe intended. 🌈
• pNumPackets — pointer to a variable that will hold the number of packets in the hint. (yes she's listed here, no she's not in the signature above — I don't make the rules, I just report them faithfully. 😭)
• ppBytes — pointer to the pointer to the packet data. this one's spicy, there are two whole buffering strategies for it, scroll down to DESCRIPTION, I promise it's worth it. 🍓
• pNumBytes — pointer to a variable that will hold the size, in bytes, of the packet. so you know how big the thing you just got is. very demure, very mindful. ✨
• ssrc — the RTP SSRC to use when constructing the RTP packet header. it's the whole "who made this stream" ID.
• includeHeader — should the library bolt the standard 12 byte RTP header onto the returned packet? the header gets constructed from the info in the hint sample plus the ssrc you passed. yes/no, your call. 🎀
• includePayload — should the library include the packet payload (that's the RTP payload header and the media data) in the returned packet? again, your call.

---

💜 RETURN VALUES 💜

• success? true (1). slay. ✅
• error? false (0). not slay, but at least it's honest. 💀

---

👑 DESCRIPTION 👑

MP4ReadRtpPacket reads the specified packet from the current hint sample — and that hint sample is whatever was previously read by MP4ReadRtpHint(). so read your hint first, then come get your packet. order matters, no cap. 🔥

---

🧚 the ppBytes situation (two ways to buffer, pick your fighter)

Route one: you bring your own buffer. if the calling application wants to handle its own buffering, it can set *ppBytes to the buffer it wishes to use. and then — plot twist — the calling application is responsible for ensuring that the buffer is large enough to hold the packet. you can figure out how big is big enough by using MP4GetRtpPayload() to retrieve the maximum packet payload size, which tells you how large the receiving buffer must be. ⚠️ Caveat: the value returned by MP4GetRtpPayload is the maxiumum payload size — so if the RTP packet header is going to be included by the library, you should increment that value by 12. don't forget the 12. the 12 is not optional. 🫠

Route two: let the library handle it. if the value of *ppBytes is NULL, then an appropriately sized buffer is automatically malloc'ed for the sample data, and *ppBytes gets set to that pointer. sounds great right? well. the calling application is responsible for free'ing this memory. you asked for the malloc, you do the free. that's the deal. 💅

---

🌟 about that SSRC 🌟

the application is expected to provide the value of the RTP SSRC identifier, which uniquely identifies the originator of the media stream. for most applications, a single random value can be provided. and here's the vibe check: the value should be the same for all packets for the duration of the RTP transmission. consistency is key, bestie. 🫶

oh and — if the parameter "includeHeader" is false, then this value has no effect. so don't stress about it if you're not asking for headers. 🙈

---

🎀 what actually comes back (by default) 🎀

by default, the library:

1. constructs the standard 12 byte RTP header from the information in the hint sample, plus the specified SSRC, and
2. then concatenates that RTP header with the packet payload — meaning the RTP payload specific header and the media data for the packet.

and the "includeHeader" and "includePayload" parameters let you control those steps, so that either just the packet payloads or just the RTP headers can be returned. 🦋

a potential use of this feature: if the calling application wishes to construct an extended RTP header with non-standard options. go off, build your weird header, we support you. 🌈

---

⭐ SEE ALSO ⭐

• MP4(3)
• MP4ReadRtpHint(3)

---

and that's the whole page, bestie!! 💖 you now know MP4ReadRtpPacket better than the people who wrote it (jk jk, they're Cisco). this manual page came to you from Cisco Systems Inc., at Version 0.9 — so like, treat it as the classic that it is, and go read some RTP packets. periodt. 💅✨🎀🦋🌸