MP4(3)

NAME

MP4ReadRtpPacket - Read an RTP packet

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
);

ARGUMENTS

hFile
    Specifies the mp4 file to which the operation applies.

trackId
    Specifies the hint track to which the operation applies.

packetIndex
    Specifies which packet is to be read. Valid values range from zero to the number of packets in this hint minus one.

pNumPackets
    Pointer to variable that will be hold the number of packets in the hint.

ppBytes
    Pointer to the pointer to the packet data. See DESCRIPTION for details on this argument.

pNumBytes
    Pointer to variable that will be hold the size in bytes of the packet.

ssrc
    Specifies the RTP SSRC to be used when constructing the RTP packet header.

includeHeader
    Specifies whether the library should include the standard 12 byte RTP header to the returned packet. The header is constructed from the information in the hint sample and the specified ssrc.

includePayload
    Specifies whether the library should include the packet payload (RTP payload header and media data) in the returned packet.

RETURN VALUES

Upon success, true (1). Upon an error, false (0).

DESCRIPTION

MP4ReadRtpPacket reads the specified packet from the current hint sample, as previously read by MP4ReadRtpHint().

The argument, ppBytes, allows for two possible approaches for buffering:

If the calling application wishes to handle its own buffering it can set *ppBytes to the buffer it wishes to use. The calling application is responsible for ensuring that the buffer is large enough to hold the packet. This can be done by using MP4GetRtpPayload() to retrieve the maximum packet payload size and hence how large the receiving buffer must be. Caveat: the value returned by MP4GetRtpPayload is the maxiumum payload size, if the RTP packet header is going to be included by the library this value should be incremented by 12.

If the value of *ppBytes is NULL, then an appropriately sized buffer is automatically malloc'ed for the sample data and *ppBytes set to this pointer. The calling application is responsible for free'ing this memory.

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. The value should be the same for all packets for the duration of the RTP transmission. If the parameter "includeHeader" is false, then this value has no effect.

By default the library constructs the standard 12 byte RTP header from the information in the hint sample, and the specified SSRC. It then concatenates the RTP header with the packet payload, that is the RTP payload specific header and the media data for the packet. The "includeHeader" and "includePayload" parameters allow control over these steps, so that either just the packet payloads or just the RTP headers can be returned. A potential use of this feature is if the calling application wishes to construct an extended RTP header with non-standard options.

SEE ALSO

MP4(3) MP4ReadRtpHint(3)