MP4v2
|
Macros | |
#define | MP4_SET_DYNAMIC_PAYLOAD 0xff |
Functions | |
bool | MP4GetHintTrackRtpPayload (MP4FileHandle hFile, MP4TrackId hintTrackId, char **ppPayloadName=NULL, uint8_t *pPayloadNumber=NULL, uint16_t *pMaxPayloadSize=NULL, char **ppEncodingParams=NULL) |
Get the RTP payload parameters of the hint track. More... | |
bool | MP4SetHintTrackRtpPayload (MP4FileHandle hFile, MP4TrackId hintTrackId, const char *pPayloadName, uint8_t *pPayloadNumber, uint16_t maxPayloadSize=0, const char *encode_params=NULL, bool include_rtp_map=true, bool include_mpeg4_esid=true) |
Set the RTP payload parameters of the hint track. More... | |
const char * | MP4GetSessionSdp (MP4FileHandle hFile) |
Get the SDP session level description of the file. More... | |
bool | MP4SetSessionSdp (MP4FileHandle hFile, const char *sdpString) |
Set the SDP session level description of the file. More... | |
bool | MP4AppendSessionSdp (MP4FileHandle hFile, const char *sdpString) |
Add to the SDP session level description of the file. More... | |
const char * | MP4GetHintTrackSdp (MP4FileHandle hFile, MP4TrackId hintTrackId) |
Get the SDP media level description associated with a hint track. More... | |
bool | MP4SetHintTrackSdp (MP4FileHandle hFile, MP4TrackId hintTrackId, const char *sdpString) |
Set the SDP media level description of the hint track. More... | |
bool | MP4AppendHintTrackSdp (MP4FileHandle hFile, MP4TrackId hintTrackId, const char *sdpString) |
Add to the SDP media level description of the hint track. More... | |
MP4TrackId | MP4GetHintTrackReferenceTrackId (MP4FileHandle hFile, MP4TrackId hintTrackId) |
Get the reference track id for a hint track. More... | |
bool | MP4ReadRtpHint (MP4FileHandle hFile, MP4TrackId hintTrackId, MP4SampleId hintSampleId, uint16_t *pNumPackets=NULL) |
Read an RTP hint. More... | |
uint16_t | MP4GetRtpHintNumberOfPackets (MP4FileHandle hFile, MP4TrackId hintTrackId) |
Get the number of packets in an RTP hint. More... | |
int8_t | MP4GetRtpPacketBFrame (MP4FileHandle hFile, MP4TrackId hintTrackId, uint16_t packetIndex) |
Get the B frame flag of an RTP packet. More... | |
int32_t | MP4GetRtpPacketTransmitOffset (MP4FileHandle hFile, MP4TrackId hintTrackId, uint16_t packetIndex) |
Get the transmit offset of an RTP packet. More... | |
bool | MP4ReadRtpPacket (MP4FileHandle hFile, MP4TrackId hintTrackId, uint16_t packetIndex, uint8_t **ppBytes, uint32_t *pNumBytes, uint32_t ssrc=0, bool includeHeader=true, bool includePayload=true) |
Read an RTP packet. More... | |
MP4Timestamp | MP4GetRtpTimestampStart (MP4FileHandle hFile, MP4TrackId hintTrackId) |
Get the RTP start time of a hint track. More... | |
bool | MP4SetRtpTimestampStart (MP4FileHandle hFile, MP4TrackId hintTrackId, MP4Timestamp rtpStart) |
Get the RTP start time of a hint track. More... | |
bool | MP4AddRtpHint (MP4FileHandle hFile, MP4TrackId hintTrackId) |
Add an RTP hint. More... | |
bool | MP4AddRtpVideoHint (MP4FileHandle hFile, MP4TrackId hintTrackId, bool isBFrame=false, uint32_t timestampOffset=0) |
Add an RTP video specific hint. More... | |
bool | MP4AddRtpPacket (MP4FileHandle hFile, MP4TrackId hintTrackId, bool setMBit=false, int32_t transmitOffset=0) |
Add an RTP packet. More... | |
bool | MP4AddRtpImmediateData (MP4FileHandle hFile, MP4TrackId hintTrackId, const uint8_t *pBytes, uint32_t numBytes) |
Add immediate data to an RTP packet. More... | |
bool | MP4AddRtpSampleData (MP4FileHandle hFile, MP4TrackId hintTrackId, MP4SampleId sampleId, uint32_t dataOffset, uint32_t dataLength) |
Add media sample data to an RTP packet. More... | |
bool | MP4AddRtpESConfigurationPacket (MP4FileHandle hFile, MP4TrackId hintTrackId) |
Add ES configuration information to an RTP hint. More... | |
bool | MP4WriteRtpHint (MP4FileHandle hFile, MP4TrackId hintTrackId, MP4Duration duration, bool isSyncSample=true) |
Write an RTP hint. More... | |
bool MP4AddRtpESConfigurationPacket | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId | ||
) |
Add ES configuration information to an RTP hint.
MP4AddRtpESConfigurationPacket adds a packet to the current RTP hint that contains a copy of the elementary stream configuration information of the reference media track. Some RTP payloads require this information to be transmitted at the start of streaming or periodically during streaming.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
bool MP4AddRtpHint | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId | ||
) |
Add an RTP hint.
MP4AddRtpHint creates a new hint sample for the specified hint track and enables subsequent calls to MP4AddRtpPacket() to create the RTP packets associated with this hint. After all the RTP packets for the hint have been created, MP4WriteRtpHint() should be called to write the hint to the track.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
bool MP4AddRtpImmediateData | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
const uint8_t * | pBytes, | ||
uint32_t | numBytes | ||
) |
Add immediate data to an RTP packet.
MP4AddRtpImmediateData adds immediate data to the current pending RTP packet. Typically, this is used to add RTP payload specific headers to RTP packets. Note that the size of a block of immediate data is limited to 14 bytes. But multiple immediate data blocks can be added if more space is needed.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
pBytes | specifies a pointer to the immediate data that should be included in the current RTP packet. |
numBytes | specifies the length in bytes of the immediate data that should be included in the current RTP packet. |
bool MP4AddRtpPacket | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
bool | setMBit = false , |
||
int32_t | transmitOffset = 0 |
||
) |
Add an RTP packet.
MP4AddRtpPacket creates a new RTP packet for the currently pending RTP hint sample for the specified hint track. It also enables subsequent calls to MP4AddRtpImmediateData() and MP4AddRtpSampleData to add data to the RTP packets. After all the RTP packets for the hint have been created, MP4WriteRtpHint() should be called to write the hint to the track.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
setMBit | specifies the value of the RTP packet header marker bit for this packet. The value depends on the rules of the RTP payload used for this hint track. |
transmitOffset | specifies an offset to apply to the normal transmission time of this packet. The purpose of this offset is to allow smoothing of packet transmission over the duration of the hint. |
bool MP4AddRtpSampleData | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
MP4SampleId | sampleId, | ||
uint32_t | dataOffset, | ||
uint32_t | dataLength | ||
) |
Add media sample data to an RTP packet.
MP4AddRtpSampleData adds a reference in the current pending RTP packet to the media data in the specified media sample of the reference media track. Note this is a reference, not a copy, of the media data.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
sampleId | specifies the reference media sample id from which the media data should be taken. |
dataOffset | specifies the byte offset in the specified media sample where data should be taken from for the current RTP packet. |
dataLength | specifies the length in bytes of the media data that should be included in the current RTP packet. |
bool MP4AddRtpVideoHint | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
bool | isBFrame = false , |
||
uint32_t | timestampOffset = 0 |
||
) |
Add an RTP video specific hint.
MP4AddRtpVideoHint is an extended version of MP4AddRtpHint specifically to handle MPEG video frames.
The isBFrame parameter allows the packets in the RTP hint to be marked as belonging to a video B frame. This can be useful to a streaming server if packets must be dropped due to system load or network congestion. No other video frames are dependent on the contents of B frames, so they are least damaging type of frames to drop.
The timestampOffset parameter allows an offset to be added to the RTP timestamp of the packets in the RTP hint. This is necessary for MPEG video that contains B frames since the video frames are transmitted out of order with respect to when they should be rendered. I.e. I and P frames are transmitted before any B frames that depend on them. The RTP timestamp must represent the rendering time of the data in the packets hence an offset must be added.
Note: The timestampOffset is equivalent to the sample rendering offset of a video media track. See MP4GetSampleRenderingOffset().
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
isBFrame | specifies if this hint will contain packets for a video B frame. |
timestampOffset | specifies a positive offset to add to the RTP timestamp for this hint. Caveat: the value is in the hint track timescale. |
bool MP4AppendHintTrackSdp | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
const char * | sdpString | ||
) |
Add to the SDP media level description of the hint track.
MP4AppendHintTrackSdp appends the specified string to the SDP (IETF RFC 2327) media level fragment for the hint track. This is used by a streaming server to create a complete SDP description of the multimedia session represented by the file.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
sdpString | specifies the addition to the hint track SDP string. |
bool MP4AppendSessionSdp | ( | MP4FileHandle | hFile, |
const char * | sdpString | ||
) |
Add to the SDP session level description of the file.
MP4AppendSessionSdp appends the specified string to the SDP (IETF RFC 2327) session level fragment for the file. This is used by a streaming server to create a complete SDP description of the multimedia session represented by the file.
hFile | specifies the mp4 file to which the operation applies. |
sdpString | specifies the addition to the session SDP string. |
MP4TrackId MP4GetHintTrackReferenceTrackId | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId | ||
) |
Get the reference track id for a hint track.
MP4GetHintTrackReferenceTrackId gets the track id of the reference media track associated with the specified hint track.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
bool MP4GetHintTrackRtpPayload | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
char ** | ppPayloadName = NULL , |
||
uint8_t * | pPayloadNumber = NULL , |
||
uint16_t * | pMaxPayloadSize = NULL , |
||
char ** | ppEncodingParams = NULL |
||
) |
Get the RTP payload parameters of the hint track.
MP4GetHintTrackRtpPayload gets the RTP payload parameters for the hint track. The RTP payload is the set of rules by which media samples are packed into RTP packets. This call is typically used in constructing the SDP media level description for the hint track.
The payloadName identifies which RTP payload is being used for the RTP packets created from the hint track. This value is sent to the receiver in the SDP description. For example, MP3 audio sent according to the rules in IETF RFC 2250 uses the name "MPA" for the RTP payload.
The payloadNumber is a shorter form of the payloadName. This value is associated with the payload name in the SDP description and then sent in every RTP packet. Payload numbers 1 thru 95 are statically assigned in IETF RFC 1890, numbers 96 thru 127 are dynamically assigned within a session.
The maxPayloadSize specifies the maximum number of bytes that should be placed in the RTP payload section of the RTP packets.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
ppPayloadName | specifies a pointer to the variable to receive the string RTP payload name. |
pPayloadNumber | specifies a pointer to the variable to receive the RTP payload number. |
pMaxPayloadSize | specifies a pointer to the variable to receive the maximum RTP payload size in bytes. |
ppEncodingParams |
const char* MP4GetHintTrackSdp | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId | ||
) |
Get the SDP media level description associated with a hint track.
MP4GetHintTrackSdp returns the SDP (IETF RFC 2327) media level fragment associated with the hint track. This is used by a streaming server to create a complete SDP description of the multimedia session represented by the file.
The mp4broadcaster test program provided with the MP4 library gives an example of using this call to create the complete SDP description.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
uint16_t MP4GetRtpHintNumberOfPackets | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId | ||
) |
Get the number of packets in an RTP hint.
MP4GetRtpHintNumberOfPackets returns the number of packets contained in the current RTP hint as established by a call to MP4ReadRtpHint().
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
int8_t MP4GetRtpPacketBFrame | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
uint16_t | packetIndex | ||
) |
Get the B frame flag of an RTP packet.
MP4GetRtpPacketBFrame returns the state of the B Frame flag of an RTP packet. See MP4AddRtpHint() for a description of this flag.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
packetIndex | specifies the packet to which the operation applies. |
int32_t MP4GetRtpPacketTransmitOffset | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
uint16_t | packetIndex | ||
) |
Get the transmit offset of an RTP packet.
MP4GetRtpPacketTransmitOffset returns the transmit offset of an RTP packet. This offset may be set by some hinters to smooth out the packet transmission times and reduce network burstiness. A transmitter would need to apply this offset to the calculated transmission time based on the hint start time.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
packetIndex | specifies the packet to which the operation applies. |
MP4Timestamp MP4GetRtpTimestampStart | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId | ||
) |
Get the RTP start time of a hint track.
MP4GetRtpTimestampStart returns the RTP timestamp start of the specified hint track. Typically this is a random value that is chosen when the first RTP packet is constructed by the MP4 library. However the value can be set explicitly for the hint track and stored. Typically this is used if it is desired that timestamps start at zero.
An application will need this value in order to construct RTCP Sender Reports that relate the hint track time to an real time clock. The mp4broadcaster test program provided with the MP4 library gives an example of this.
See IETF RFC 1889 for details regarding RTP timestamps and RTCP.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
const char* MP4GetSessionSdp | ( | MP4FileHandle | hFile | ) |
Get the SDP session level description of the file.
MP4GetSessionSdp returns the SDP (IETF RFC 2327) session level fragment for the file. This is used by a streaming server to create a complete SDP description of the multimedia session represented by the file.
The mp4broadcaster test program provided with the MP4v2 library gives an example of using this call to create the complete SDP description.
hFile | specifies the mp4 file to which the operation applies. |
bool MP4ReadRtpHint | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
MP4SampleId | hintSampleId, | ||
uint16_t * | pNumPackets = NULL |
||
) |
Read an RTP hint.
MP4ReadRtpHint reads the specified hint sample from the specified hint track and enables subsequent calls to MP4ReadRtpPacket() to read the individual RTP packets associated with this hint. If desired, the number of RTP packets associated with this hint is returned.
Note that a hint track sample is just like any other track sample. I.e. MP4ReadSample(), MP4GetSampleSize(), MP4GetSampleTime(), etc. are all valid. The RTP specific functions are provided to interpret the information contain in the hint track samples that give instructions on how to form the actual RTP packets.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
hintSampleId | specifies which hint sample is to be read. Caveat: the first sample has id 1 not 0. |
pNumPackets | Pointer to variable that will be hold the number of packets in the hint. |
bool MP4ReadRtpPacket | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
uint16_t | packetIndex, | ||
uint8_t ** | ppBytes, | ||
uint32_t * | pNumBytes, | ||
uint32_t | ssrc = 0 , |
||
bool | includeHeader = true , |
||
bool | includePayload = true |
||
) |
Read an RTP packet.
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:
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.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | 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. |
ppBytes | Pointer to the pointer to the packet data. See the function 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. |
bool MP4SetHintTrackRtpPayload | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
const char * | pPayloadName, | ||
uint8_t * | pPayloadNumber, | ||
uint16_t | maxPayloadSize = 0 , |
||
const char * | encode_params = NULL , |
||
bool | include_rtp_map = true , |
||
bool | include_mpeg4_esid = true |
||
) |
Set the RTP payload parameters of the hint track.
MP4SetHintTrackRtpPayload sets the RTP payload parameters for the hint track. The RTP payload is the set of rules by which media samples are packed into RTP packets.
The payload name identifies which RTP payload is being used for the RTP packets created from the hint track. This value is sent to the receiver in the SDP description. For example, MP3 audio sent according to the rules in IETF RFC 2250 uses the name "MPA" for the RTP payload.
The payload number is a shorter form of the payload name. This value is associated with the payload name in the SDP description and then sent in every RTP packet. Payload numbers 1 thru 95 are statically assigned in IETF RFC 1890, numbers 96 thru 127 are dynamically assigned within a session. If the RTP payload in use is one of the statically assigned ones, you should pass this value to the library. If you need a dynamic payload number assigned, pass the define value MP4_SET_DYNAMIC_PAYLOAD for this parameter and the library will choose an valid available number and return this value.
The maxPayloadSize specifies the maximum number of bytes that should be placed in the RTP payload section of the RTP packets. It is desirable that RTP packets not exceed the maximum transmission unit (MTU) of the IP network they travel over since otherwise the packets must be fragmented at the IP level which consumes router resources and can lead to less robust behavior in the face of packet loss.
The default value for maxPayloadSize is 1460, which is the MTU for an Ethernet or similar network minus the standard sizes of the IP, UDP, and RTP headers (1500 - 20 - 8 - 12 = 1460).
If you anticipate streaming over IP networks with smaller MTU sizes, or that extensions to the network headers might be used, a more conservative value should be chosen. The minimum MTU for an IP network is 576 bytes.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
pPayloadName | specifies the RTP payload name. |
pPayloadNumber | specifies a pointer to the RTP payload number. |
maxPayloadSize | specifies the maximum RTP payload size in bytes. |
encode_params | |
include_rtp_map | specifies if the a=rtpmap statement is included. |
include_mpeg4_esid | specifies if the a=mpeg4-esid statement is included. |
bool MP4SetHintTrackSdp | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
const char * | sdpString | ||
) |
Set the SDP media level description of the hint track.
MP4SetHintTrackSdp sets the SDP (IETF RFC 2327) media level fragment for the hint track. This is used by a streaming server to create a complete SDP description of the multimedia session represented by the file.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
sdpString | specifies the new value of the hint track SDP string. |
bool MP4SetRtpTimestampStart | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
MP4Timestamp | rtpStart | ||
) |
Get the RTP start time of a hint track.
MP4SetRtpTimestampStart sets the RTP timestamp start of the specified hint track. Typically this is a random value that is chosen when the first RTP packet is constructed by the MP4 library. However the value can be set explicitly for the hint track and stored. Typically this is used if it is desired that timestamps start at zero.
See IETF RFC 1889 for details regarding RTP timestamps and RTCP.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
rtpStart | specifies the desired RTP start timestamp for the hint track. |
bool MP4SetSessionSdp | ( | MP4FileHandle | hFile, |
const char * | sdpString | ||
) |
Set the SDP session level description of the file.
MP4SetSessionSdp sets the SDP (IETF RFC 2327) session level fragment for the file. This is used by a streaming server to create a complete SDP description of the multimedia session represented by the file.
hFile | specifies the mp4 file to which the operation applies. |
sdpString | specifies the new value of the session SDP string. |
bool MP4WriteRtpHint | ( | MP4FileHandle | hFile, |
MP4TrackId | hintTrackId, | ||
MP4Duration | duration, | ||
bool | isSyncSample = true |
||
) |
Write an RTP hint.
MP4WriteRtpHint writes the current pending hint created with MP4AddRtpHint() to the specified hint track.
hFile | specifies the mp4 file to which the operation applies. |
hintTrackId | specifies the hint track to which the operation applies. |
duration | specifies the duration for this hint sample. Typically this is the same duration as for the corresponding sample in the reference media track. Caveat: The duration should be in the hint track timescale units, again typically the same as the reference media track. |
isSyncSample | specifies the sync/random access flag for this sample. Typically this is the same as for the corresponding sample in the reference media track. |