700 lines
28 KiB
C
700 lines
28 KiB
C
|
/*
|
||
|
|
* The contents of this file are subject to the Mozilla Public
|
||
|
|
* License Version 1.1 (the "License"); you may not use this file
|
||
|
|
* except in compliance with the License. You may obtain a copy of
|
||
|
|
* the License at http://www.mozilla.org/MPL/
|
||
|
|
*
|
||
|
|
* Software distributed under the License is distributed on an "AS
|
||
|
|
* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
|
||
|
|
* implied. See the License for the specific language governing
|
||
|
|
* rights and limitations under the License.
|
||
|
|
*
|
||
|
|
* The Original Code is MPEG4IP.
|
||
|
|
*
|
||
|
|
* The Initial Developer of the Original Code is Cisco Systems Inc.
|
||
|
|
* Portions created by Cisco Systems Inc. are
|
||
|
|
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
|
||
|
|
*
|
||
|
|
* Contributor(s):
|
||
|
|
* Dave Mackie, dmackie@cisco.com
|
||
|
|
* Alix Marchandise-Franquet, alix@cisco.com
|
||
|
|
* Bill May, wmay@cisco.com
|
||
|
|
* Robert Kausch, robert.kausch@freac.org
|
||
|
|
*/
|
||
|
|
#ifndef MP4V2_STREAMING_H
|
||
|
|
#define MP4V2_STREAMING_H
|
||
|
|
|
||
|
|
/**************************************************************************//**
|
||
|
|
*
|
||
|
|
* @defgroup mp4_hint MP4v2 Streaming
|
||
|
|
* @{
|
||
|
|
*
|
||
|
|
*****************************************************************************/
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param ppPayloadName specifies a pointer to the variable to receive the
|
||
|
|
* string RTP payload name.
|
||
|
|
* @param pPayloadNumber specifies a pointer to the variable to receive the
|
||
|
|
* RTP payload number.
|
||
|
|
* @param pMaxPayloadSize specifies a pointer to the variable to receive the
|
||
|
|
* maximum RTP payload size in bytes.
|
||
|
|
* @param ppEncodingParams
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4SetHintTrackRtpPayload()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4GetHintTrackRtpPayload(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
char** ppPayloadName DEFAULT(NULL),
|
||
|
|
uint8_t* pPayloadNumber DEFAULT(NULL),
|
||
|
|
uint16_t* pMaxPayloadSize DEFAULT(NULL),
|
||
|
|
char** ppEncodingParams DEFAULT(NULL) );
|
||
|
|
|
||
|
|
#define MP4_SET_DYNAMIC_PAYLOAD 0xff
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param pPayloadName specifies the RTP payload name.
|
||
|
|
* @param pPayloadNumber specifies a pointer to the RTP payload number.
|
||
|
|
* @param maxPayloadSize specifies the maximum RTP payload size in bytes.
|
||
|
|
* @param encode_params
|
||
|
|
* @param include_rtp_map specifies if the a=rtpmap statement is included.
|
||
|
|
* @param include_mpeg4_esid specifies if the a=mpeg4-esid statement is
|
||
|
|
* included.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4GetHintTrackRtpPayload()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4SetHintTrackRtpPayload(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
const char* pPayloadName,
|
||
|
|
uint8_t* pPayloadNumber,
|
||
|
|
uint16_t maxPayloadSize DEFAULT(0),
|
||
|
|
const char * encode_params DEFAULT(NULL),
|
||
|
|
bool include_rtp_map DEFAULT(true),
|
||
|
|
bool include_mpeg4_esid DEFAULT(true) );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return The SDP session level description fragment of the mp4 file.
|
||
|
|
*
|
||
|
|
* @see MP4SetSessionSdp()
|
||
|
|
* @see MP4AppendSessionSdp()
|
||
|
|
* @see MP4GetHintTrackSdp()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
const char* MP4GetSessionSdp(
|
||
|
|
MP4FileHandle hFile );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param sdpString specifies the new value of the session SDP string.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4GetSessionSdp()
|
||
|
|
* @see MP4AppendSessionSdp()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4SetSessionSdp(
|
||
|
|
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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param sdpString specifies the addition to the session SDP string.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4GetSessionSdp()
|
||
|
|
* @see MP4SetSessionSdp()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4AppendSessionSdp(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
const char* sdpString );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return SDP media level description fragment associated with the hint
|
||
|
|
* track.
|
||
|
|
*
|
||
|
|
* @see MP4SetHintTrackSdp()
|
||
|
|
* @see MP4AppendHintTrackSdp()
|
||
|
|
* @see MP4GetSessionSdp()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
const char* MP4GetHintTrackSdp(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param sdpString specifies the new value of the hint track SDP string.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4GetHintTrackSdp()
|
||
|
|
* @see MP4AppendHintTrackSdp()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4SetHintTrackSdp(
|
||
|
|
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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param sdpString specifies the addition to the hint track SDP string.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4GetHintTrackSdp()
|
||
|
|
* @see MP4AppendHintTrackSdp()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4AppendHintTrackSdp(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
const char* sdpString );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return Upon success, the track id of the reference media track. Upon an
|
||
|
|
* error, MP4_INVALID_TRACK_ID.
|
||
|
|
*
|
||
|
|
* @see MP4AddHintTrack()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
MP4TrackId MP4GetHintTrackReferenceTrackId(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param hintSampleId specifies which hint sample is to be read. Caveat: the
|
||
|
|
* first sample has id 1 not 0.
|
||
|
|
* @param pNumPackets Pointer to variable that will be hold the number of
|
||
|
|
* packets in the hint.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4ReadRtpPacket()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4ReadRtpHint(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
MP4SampleId hintSampleId,
|
||
|
|
uint16_t* pNumPackets DEFAULT(NULL) );
|
||
|
|
|
||
|
|
/** 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().
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return Upon success, the number of packets in the current RTP hint. Upon
|
||
|
|
* an error, 0.
|
||
|
|
*
|
||
|
|
* @see MP4ReadRtpHint()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
uint16_t MP4GetRtpHintNumberOfPackets(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param packetIndex specifies the packet to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return Upon success, the state of the B frame flag for the specified
|
||
|
|
* packet. Upon an error, -1.
|
||
|
|
*
|
||
|
|
* @see MP4AddRtpHint()
|
||
|
|
* @see MP4ReadRtpPacket()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
int8_t MP4GetRtpPacketBFrame(
|
||
|
|
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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param packetIndex specifies the packet to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return The transmit offset for the specified packet in the hint track
|
||
|
|
* timescale.
|
||
|
|
*
|
||
|
|
* @see MP4AddRtpHint()
|
||
|
|
* @see MP4ReadRtpPacket()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
int32_t MP4GetRtpPacketTransmitOffset(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
uint16_t packetIndex );
|
||
|
|
|
||
|
|
/** 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:
|
||
|
|
*
|
||
|
|
* @li 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
|
||
|
|
* maximum payload size, if the RTP packet header is going to be included
|
||
|
|
* by the library this value should be incremented by 12.
|
||
|
|
*
|
||
|
|
* @li If the value of *ppBytes is NULL, then an appropriately sized buffer is
|
||
|
|
* automatically allocated for the sample data and *ppBytes set to this
|
||
|
|
* pointer. The calling application is responsible for freeing this memory
|
||
|
|
* with MP4Free().
|
||
|
|
*
|
||
|
|
* 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 @p 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 @p
|
||
|
|
* includeHeader and @p 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param packetIndex specifies which packet is to be read. Valid values range
|
||
|
|
* from zero to the number of packets in this hint minus one.
|
||
|
|
* @param ppBytes Pointer to the pointer to the packet data. See the function
|
||
|
|
* description for details on this argument.
|
||
|
|
* @param pNumBytes Pointer to variable that will be hold the size in bytes of
|
||
|
|
* the packet.
|
||
|
|
* @param ssrc specifies the RTP SSRC to be used when constructing the RTP
|
||
|
|
* packet header.
|
||
|
|
* @param 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.
|
||
|
|
* @param includePayload specifies whether the library should include the
|
||
|
|
* packet payload (RTP payload header and media data) in the returned
|
||
|
|
* packet.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4ReadRtpHint()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4ReadRtpPacket(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
uint16_t packetIndex,
|
||
|
|
uint8_t** ppBytes,
|
||
|
|
uint32_t* pNumBytes,
|
||
|
|
uint32_t ssrc DEFAULT(0),
|
||
|
|
bool includeHeader DEFAULT(true),
|
||
|
|
bool includePayload DEFAULT(true) );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return Upon success, the RTP start time in the RTP time scale which is
|
||
|
|
* identical to the hint track time scale. Upon an error,
|
||
|
|
* MP4_INVALID_TIMESTAMP.
|
||
|
|
*
|
||
|
|
* @see MP4SetRtpTimestampStart()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
MP4Timestamp MP4GetRtpTimestampStart(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param rtpStart specifies the desired RTP start timestamp for the hint
|
||
|
|
* track.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4GetRtpTimestampStart()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4SetRtpTimestampStart(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
MP4Timestamp rtpStart );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4AddRtpPacket()
|
||
|
|
* @see MP4WriteRtpHint()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4AddRtpHint(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId );
|
||
|
|
|
||
|
|
/** 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().
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param isBFrame specifies if this hint will contain packets for a video B
|
||
|
|
* frame.
|
||
|
|
* @param timestampOffset specifies a positive offset to add to the RTP
|
||
|
|
* timestamp for this hint. Caveat: the value is in the hint track
|
||
|
|
* timescale.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4AddRtpHint()
|
||
|
|
* @see MP4AddRtpPacket()
|
||
|
|
* @see MP4WriteRtpHint()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4AddRtpVideoHint(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
bool isBFrame DEFAULT(false),
|
||
|
|
uint32_t timestampOffset DEFAULT(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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param 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.
|
||
|
|
* @param 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.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4AddRtpHint()
|
||
|
|
* @see MP4AddRtpImmediateData()
|
||
|
|
* @see MP4AddRtpSampleData()
|
||
|
|
* @see MP4WriteRtpHint()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4AddRtpPacket(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
bool setMBit DEFAULT(false),
|
||
|
|
int32_t transmitOffset DEFAULT(0) );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param pBytes specifies a pointer to the immediate data that should be
|
||
|
|
* included in the current RTP packet.
|
||
|
|
* @param numBytes specifies the length in bytes of the immediate data that
|
||
|
|
* should be included in the current RTP packet.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4AddRtpPacket()
|
||
|
|
* @see MP4AddRtpSampleData()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4AddRtpImmediateData(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
const uint8_t* pBytes,
|
||
|
|
uint32_t numBytes );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param sampleId specifies the reference media sample id from which the
|
||
|
|
* media data should be taken.
|
||
|
|
* @param dataOffset specifies the byte offset in the specified media sample
|
||
|
|
* where data should be taken from for the current RTP packet.
|
||
|
|
* @param dataLength specifies the length in bytes of the media data that
|
||
|
|
* should be included in the current RTP packet.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4AddRtpPacket()
|
||
|
|
* @see MP4AddRtpImmediateData()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4AddRtpSampleData(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
MP4SampleId sampleId,
|
||
|
|
uint32_t dataOffset,
|
||
|
|
uint32_t dataLength );
|
||
|
|
|
||
|
|
/** 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.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4SetTrackESConfiguration()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4AddRtpESConfigurationPacket(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId );
|
||
|
|
|
||
|
|
/** Write an RTP hint.
|
||
|
|
*
|
||
|
|
* MP4WriteRtpHint writes the current pending hint created with
|
||
|
|
* MP4AddRtpHint() to the specified hint track.
|
||
|
|
*
|
||
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
||
|
|
* @param hintTrackId specifies the hint track to which the operation applies.
|
||
|
|
* @param 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.
|
||
|
|
* @param 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.
|
||
|
|
*
|
||
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
||
|
|
*
|
||
|
|
* @see MP4AddRtpHint()
|
||
|
|
*/
|
||
|
|
MP4V2_EXPORT
|
||
|
|
bool MP4WriteRtpHint(
|
||
|
|
MP4FileHandle hFile,
|
||
|
|
MP4TrackId hintTrackId,
|
||
|
|
MP4Duration duration,
|
||
|
|
bool isSyncSample DEFAULT(true) );
|
||
|
|
|
||
|
|
/** @} ***********************************************************************/
|
||
|
|
|
||
|
|
#endif /* MP4V2_STREAMING_H */
|