974 lines
36 KiB
C
974 lines
36 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.
|
|
*
|
|
* 3GPP features implementation is based on 3GPP's TS26.234-v5.60,
|
|
* and was contributed by Ximpo Group Ltd.
|
|
*
|
|
* Portions created by Ximpo Group Ltd. are
|
|
* Copyright (C) Ximpo Group Ltd. 2003, 2004. All Rights Reserved.
|
|
*
|
|
* Contributor(s):
|
|
* Dave Mackie, dmackie@cisco.com
|
|
* Alix Marchandise-Franquet, alix@cisco.com
|
|
* Ximpo Group Ltd., mp4v2@ximpo.com
|
|
* Bill May, wmay@cisco.com
|
|
* Kona Blend, kona8lend@gmail.com
|
|
*/
|
|
#ifndef MP4V2_GENERAL_H
|
|
#define MP4V2_GENERAL_H
|
|
|
|
/**************************************************************************//**
|
|
*
|
|
* @defgroup mp4_general MP4v2 General
|
|
* @{
|
|
*
|
|
*****************************************************************************/
|
|
|
|
/* MP4 API types */
|
|
typedef void* MP4FileHandle;
|
|
typedef uint32_t MP4TrackId;
|
|
typedef uint32_t MP4SampleId;
|
|
typedef uint64_t MP4Timestamp;
|
|
typedef uint64_t MP4Duration;
|
|
typedef uint32_t MP4EditId;
|
|
|
|
typedef enum {
|
|
MP4_LOG_NONE = 0,
|
|
MP4_LOG_ERROR = 1,
|
|
MP4_LOG_WARNING = 2,
|
|
MP4_LOG_INFO = 3,
|
|
MP4_LOG_VERBOSE1 = 4,
|
|
MP4_LOG_VERBOSE2 = 5,
|
|
MP4_LOG_VERBOSE3 = 6,
|
|
MP4_LOG_VERBOSE4 = 7
|
|
} MP4LogLevel;
|
|
|
|
/*****************************************************************************/
|
|
|
|
typedef void (*MP4LogCallback)(
|
|
MP4LogLevel loglevel,
|
|
const char* fmt,
|
|
va_list ap );
|
|
|
|
/*****************************************************************************/
|
|
|
|
/** Encryption function pointer.
|
|
*
|
|
* @see MP4EncAndCopySample()
|
|
* @see MP4EncAndCopyTrack()
|
|
*/
|
|
typedef uint32_t (*encryptFunc_t)( uint32_t, uint32_t, uint8_t*, uint32_t*, uint8_t** );
|
|
|
|
/*****************************************************************************/
|
|
|
|
#define MP4_INVALID_FILE_HANDLE ((MP4FileHandle)NULL) /**< Constant: invalid MP4FileHandle. */
|
|
#define MP4_INVALID_TRACK_ID ((MP4TrackId)0) /**< Constant: invalid MP4TrackId. */
|
|
#define MP4_INVALID_SAMPLE_ID ((MP4SampleId)0) /**< Constant: invalid MP4SampleId. */
|
|
#define MP4_INVALID_TIMESTAMP ((MP4Timestamp)-1) /**< Constant: invalid MP4Timestamp. */
|
|
#define MP4_INVALID_DURATION ((MP4Duration)-1) /**< Constant: invalid MP4Duration. */
|
|
#define MP4_INVALID_EDIT_ID ((MP4EditId)0) /**< Constant: invalid MP4EditId. */
|
|
|
|
/* Macros to test for API type validity */
|
|
#define MP4_IS_VALID_FILE_HANDLE(x) ((x) != MP4_INVALID_FILE_HANDLE)
|
|
#define MP4_IS_VALID_TRACK_ID(x) ((x) != MP4_INVALID_TRACK_ID)
|
|
#define MP4_IS_VALID_SAMPLE_ID(x) ((x) != MP4_INVALID_SAMPLE_ID)
|
|
#define MP4_IS_VALID_TIMESTAMP(x) ((x) != MP4_INVALID_TIMESTAMP)
|
|
#define MP4_IS_VALID_DURATION(x) ((x) != MP4_INVALID_DURATION)
|
|
#define MP4_IS_VALID_EDIT_ID(x) ((x) != MP4_INVALID_EDIT_ID)
|
|
|
|
/*
|
|
* MP4 Known track type names - e.g. MP4GetNumberOfTracks(type)
|
|
*
|
|
* Note this first group of track types should be created
|
|
* via the MP4Add<Type>Track() functions, and not MP4AddTrack(type)
|
|
*/
|
|
#define MP4_OD_TRACK_TYPE "odsm" /**< Constant: OD track. */
|
|
#define MP4_SCENE_TRACK_TYPE "sdsm" /**< Constant: scene track. */
|
|
#define MP4_AUDIO_TRACK_TYPE "soun" /**< Constant: audio track. */
|
|
#define MP4_VIDEO_TRACK_TYPE "vide" /**< Constant: video track. */
|
|
#define MP4_HINT_TRACK_TYPE "hint" /**< Constant: hint track. */
|
|
#define MP4_CNTL_TRACK_TYPE "cntl" /**< Constant: control track. */
|
|
#define MP4_TEXT_TRACK_TYPE "text" /**< Constant: text track. */
|
|
#define MP4_SUBTITLE_TRACK_TYPE "sbtl" /**< Constant: subtitle track. */
|
|
#define MP4_SUBPIC_TRACK_TYPE "subp" /**< Constant: subpic track. */
|
|
/*
|
|
* This second set of track types should be created
|
|
* via MP4AddSystemsTrack(type)
|
|
*/
|
|
#define MP4_CLOCK_TRACK_TYPE "crsm" /**< Constant: clock track. */
|
|
#define MP4_MPEG7_TRACK_TYPE "m7sm" /**< Constant: mpeg7 track. */
|
|
#define MP4_OCI_TRACK_TYPE "ocsm" /**< Constant: OCI track. */
|
|
#define MP4_IPMP_TRACK_TYPE "ipsm" /**< Constant: IPMP track. */
|
|
#define MP4_MPEGJ_TRACK_TYPE "mjsm" /**< Constant: MPEGJ track. */
|
|
|
|
#define MP4_IS_VIDEO_TRACK_TYPE(type) \
|
|
(!strcasecmp(type, MP4_VIDEO_TRACK_TYPE))
|
|
|
|
#define MP4_IS_AUDIO_TRACK_TYPE(type) \
|
|
(!strcasecmp(type, MP4_AUDIO_TRACK_TYPE))
|
|
|
|
#define MP4_IS_CNTL_TRACK_TYPE(type) \
|
|
(!strcasecmp(type, MP4_CNTL_TRACK_TYPE))
|
|
|
|
#define MP4_IS_OD_TRACK_TYPE(type) \
|
|
(!strcasecmp(type, MP4_OD_TRACK_TYPE))
|
|
|
|
#define MP4_IS_SCENE_TRACK_TYPE(type) \
|
|
(!strcasecmp(type, MP4_SCENE_TRACK_TYPE))
|
|
|
|
#define MP4_IS_HINT_TRACK_TYPE(type) \
|
|
(!strcasecmp(type, MP4_HINT_TRACK_TYPE))
|
|
|
|
#define MP4_IS_SYSTEMS_TRACK_TYPE(type) \
|
|
(!strcasecmp(type, MP4_CLOCK_TRACK_TYPE) \
|
|
|| !strcasecmp(type, MP4_MPEG7_TRACK_TYPE) \
|
|
|| !strcasecmp(type, MP4_OCI_TRACK_TYPE) \
|
|
|| !strcasecmp(type, MP4_IPMP_TRACK_TYPE) \
|
|
|| !strcasecmp(type, MP4_MPEGJ_TRACK_TYPE))
|
|
|
|
/* MP4 Audio track types - see MP4AddAudioTrack()*/
|
|
#define MP4_INVALID_AUDIO_TYPE 0x00
|
|
#define MP4_MPEG1_AUDIO_TYPE 0x6B
|
|
#define MP4_MPEG2_AUDIO_TYPE 0x69
|
|
#define MP4_MP3_AUDIO_TYPE MP4_MPEG2_AUDIO_TYPE
|
|
#define MP4_MPEG2_AAC_MAIN_AUDIO_TYPE 0x66
|
|
#define MP4_MPEG2_AAC_LC_AUDIO_TYPE 0x67
|
|
#define MP4_MPEG2_AAC_SSR_AUDIO_TYPE 0x68
|
|
#define MP4_MPEG2_AAC_AUDIO_TYPE MP4_MPEG2_AAC_MAIN_AUDIO_TYPE
|
|
#define MP4_MPEG4_AUDIO_TYPE 0x40
|
|
#define MP4_PRIVATE_AUDIO_TYPE 0xC0
|
|
#define MP4_PCM16_LITTLE_ENDIAN_AUDIO_TYPE 0xE0 /* a private definition */
|
|
#define MP4_VORBIS_AUDIO_TYPE 0xE1 /* a private definition */
|
|
#define MP4_AC3_AUDIO_TYPE 0xE2 /* a private definition */
|
|
#define MP4_ALAW_AUDIO_TYPE 0xE3 /* a private definition */
|
|
#define MP4_ULAW_AUDIO_TYPE 0xE4 /* a private definition */
|
|
#define MP4_G723_AUDIO_TYPE 0xE5 /* a private definition */
|
|
#define MP4_PCM16_BIG_ENDIAN_AUDIO_TYPE 0xE6 /* a private definition */
|
|
|
|
/* MP4 MPEG-4 Audio types from 14496-3 Table 1.5.1 */
|
|
#define MP4_MPEG4_INVALID_AUDIO_TYPE 0
|
|
#define MP4_MPEG4_AAC_MAIN_AUDIO_TYPE 1
|
|
#define MP4_MPEG4_AAC_LC_AUDIO_TYPE 2
|
|
#define MP4_MPEG4_AAC_SSR_AUDIO_TYPE 3
|
|
#define MP4_MPEG4_AAC_LTP_AUDIO_TYPE 4
|
|
#define MP4_MPEG4_AAC_HE_AUDIO_TYPE 5
|
|
#define MP4_MPEG4_AAC_SCALABLE_AUDIO_TYPE 6
|
|
#define MP4_MPEG4_CELP_AUDIO_TYPE 8
|
|
#define MP4_MPEG4_HVXC_AUDIO_TYPE 9
|
|
#define MP4_MPEG4_TTSI_AUDIO_TYPE 12
|
|
#define MP4_MPEG4_MAIN_SYNTHETIC_AUDIO_TYPE 13
|
|
#define MP4_MPEG4_WAVETABLE_AUDIO_TYPE 14
|
|
#define MP4_MPEG4_MIDI_AUDIO_TYPE 15
|
|
#define MP4_MPEG4_ALGORITHMIC_FX_AUDIO_TYPE 16
|
|
#define MP4_MPEG4_ALS_AUDIO_TYPE 31
|
|
#define MP4_MPEG4_LAYER1_AUDIO_TYPE 32
|
|
#define MP4_MPEG4_LAYER2_AUDIO_TYPE 33
|
|
#define MP4_MPEG4_LAYER3_AUDIO_TYPE 34
|
|
#define MP4_MPEG4_SLS_AUDIO_TYPE 35
|
|
|
|
/* MP4 Audio type utilities following common usage */
|
|
#define MP4_IS_MP3_AUDIO_TYPE(type) \
|
|
((type) == MP4_MPEG1_AUDIO_TYPE || (type) == MP4_MPEG2_AUDIO_TYPE)
|
|
|
|
#define MP4_IS_MPEG2_AAC_AUDIO_TYPE(type) \
|
|
(((type) >= MP4_MPEG2_AAC_MAIN_AUDIO_TYPE \
|
|
&& (type) <= MP4_MPEG2_AAC_SSR_AUDIO_TYPE))
|
|
|
|
#define MP4_IS_MPEG4_AAC_AUDIO_TYPE(mpeg4Type) \
|
|
(((mpeg4Type) >= MP4_MPEG4_AAC_MAIN_AUDIO_TYPE \
|
|
&& (mpeg4Type) <= MP4_MPEG4_AAC_HE_AUDIO_TYPE) \
|
|
|| (mpeg4Type) == MP4_MPEG4_AAC_SCALABLE_AUDIO_TYPE \
|
|
|| (mpeg4Type) == 17)
|
|
|
|
#define MP4_IS_AAC_AUDIO_TYPE(type) \
|
|
(MP4_IS_MPEG2_AAC_AUDIO_TYPE(type) \
|
|
|| (type) == MP4_MPEG4_AUDIO_TYPE)
|
|
|
|
/* MP4 Video track types - see MP4AddVideoTrack() */
|
|
#define MP4_INVALID_VIDEO_TYPE 0x00
|
|
#define MP4_MPEG1_VIDEO_TYPE 0x6A
|
|
#define MP4_MPEG2_SIMPLE_VIDEO_TYPE 0x60
|
|
#define MP4_MPEG2_MAIN_VIDEO_TYPE 0x61
|
|
#define MP4_MPEG2_SNR_VIDEO_TYPE 0x62
|
|
#define MP4_MPEG2_SPATIAL_VIDEO_TYPE 0x63
|
|
#define MP4_MPEG2_HIGH_VIDEO_TYPE 0x64
|
|
#define MP4_MPEG2_442_VIDEO_TYPE 0x65
|
|
#define MP4_MPEG2_VIDEO_TYPE MP4_MPEG2_MAIN_VIDEO_TYPE
|
|
#define MP4_MPEG4_VIDEO_TYPE 0x20
|
|
#define MP4_JPEG_VIDEO_TYPE 0x6C
|
|
#define MP4_PRIVATE_VIDEO_TYPE 0xD0
|
|
#define MP4_YUV12_VIDEO_TYPE 0xF0 /* a private definition */
|
|
#define MP4_H263_VIDEO_TYPE 0xF2 /* a private definition */
|
|
#define MP4_H261_VIDEO_TYPE 0xF3 /* a private definition */
|
|
|
|
/* MP4 Video type utilities */
|
|
#define MP4_IS_MPEG1_VIDEO_TYPE(type) \
|
|
((type) == MP4_MPEG1_VIDEO_TYPE)
|
|
|
|
#define MP4_IS_MPEG2_VIDEO_TYPE(type) \
|
|
(((type) >= MP4_MPEG2_SIMPLE_VIDEO_TYPE \
|
|
&& (type) <= MP4_MPEG2_442_VIDEO_TYPE) \
|
|
|| MP4_IS_MPEG1_VIDEO_TYPE(type))
|
|
|
|
#define MP4_IS_MPEG4_VIDEO_TYPE(type) \
|
|
((type) == MP4_MPEG4_VIDEO_TYPE)
|
|
|
|
/* Mpeg4 Visual Profile Defines - ISO/IEC 14496-2:2001/Amd.2:2002(E) */
|
|
#define MPEG4_SP_L1 (0x1)
|
|
#define MPEG4_SP_L2 (0x2)
|
|
#define MPEG4_SP_L3 (0x3)
|
|
#define MPEG4_SP_L0 (0x8)
|
|
#define MPEG4_SSP_L1 (0x11)
|
|
#define MPEG4_SSP_L2 (0x12)
|
|
#define MPEG4_CP_L1 (0x21)
|
|
#define MPEG4_CP_L2 (0x22)
|
|
#define MPEG4_MP_L2 (0x32)
|
|
#define MPEG4_MP_L3 (0x33)
|
|
#define MPEG4_MP_L4 (0x34)
|
|
#define MPEG4_NBP_L2 (0x42)
|
|
#define MPEG4_STP_L1 (0x51)
|
|
#define MPEG4_SFAP_L1 (0x61)
|
|
#define MPEG4_SFAP_L2 (0x62)
|
|
#define MPEG4_SFBAP_L1 (0x63)
|
|
#define MPEG4_SFBAP_L2 (0x64)
|
|
#define MPEG4_BATP_L1 (0x71)
|
|
#define MPEG4_BATP_L2 (0x72)
|
|
#define MPEG4_HP_L1 (0x81)
|
|
#define MPEG4_HP_L2 (0x82)
|
|
#define MPEG4_ARTSP_L1 (0x91)
|
|
#define MPEG4_ARTSP_L2 (0x92)
|
|
#define MPEG4_ARTSP_L3 (0x93)
|
|
#define MPEG4_ARTSP_L4 (0x94)
|
|
#define MPEG4_CSP_L1 (0xa1)
|
|
#define MPEG4_CSP_L2 (0xa2)
|
|
#define MPEG4_CSP_L3 (0xa3)
|
|
#define MPEG4_ACEP_L1 (0xb1)
|
|
#define MPEG4_ACEP_L2 (0xb2)
|
|
#define MPEG4_ACEP_L3 (0xb3)
|
|
#define MPEG4_ACEP_L4 (0xb4)
|
|
#define MPEG4_ACP_L1 (0xc1)
|
|
#define MPEG4_ACP_L2 (0xc2)
|
|
#define MPEG4_AST_L1 (0xd1)
|
|
#define MPEG4_AST_L2 (0xd2)
|
|
#define MPEG4_AST_L3 (0xd3)
|
|
#define MPEG4_S_STUDIO_P_L1 (0xe1)
|
|
#define MPEG4_S_STUDIO_P_L2 (0xe2)
|
|
#define MPEG4_S_STUDIO_P_L3 (0xe3)
|
|
#define MPEG4_S_STUDIO_P_L4 (0xe4)
|
|
#define MPEG4_C_STUDIO_P_L1 (0xe5)
|
|
#define MPEG4_C_STUDIO_P_L2 (0xe6)
|
|
#define MPEG4_C_STUDIO_P_L3 (0xe7)
|
|
#define MPEG4_C_STUDIO_P_L4 (0xe8)
|
|
#define MPEG4_ASP_L0 (0xF0)
|
|
#define MPEG4_ASP_L1 (0xF1)
|
|
#define MPEG4_ASP_L2 (0xF2)
|
|
#define MPEG4_ASP_L3 (0xF3)
|
|
#define MPEG4_ASP_L4 (0xF4)
|
|
#define MPEG4_ASP_L5 (0xF5)
|
|
#define MPEG4_ASP_L3B (0xF7)
|
|
#define MPEG4_FGSP_L0 (0xf8)
|
|
#define MPEG4_FGSP_L1 (0xf9)
|
|
#define MPEG4_FGSP_L2 (0xfa)
|
|
#define MPEG4_FGSP_L3 (0xfb)
|
|
#define MPEG4_FGSP_L4 (0xfc)
|
|
#define MPEG4_FGSP_L5 (0xfd)
|
|
|
|
/*****************************************************************************/
|
|
|
|
/* 3GP specific utilities */
|
|
|
|
MP4V2_EXPORT
|
|
bool MP4Make3GPCompliant(
|
|
const char* fileName,
|
|
char* majorBrand DEFAULT(0),
|
|
uint32_t minorVersion DEFAULT(0),
|
|
char** supportedBrands DEFAULT(NULL),
|
|
uint32_t supportedBrandsCount DEFAULT(0),
|
|
bool deleteIodsAtom DEFAULT(true) );
|
|
|
|
/* NOTE this section of functionality has not yet been fully tested */
|
|
|
|
/** Add an edit segment to a track.
|
|
*
|
|
* MP4AddTrackEdit adds an edit segment to the track edit list.
|
|
*
|
|
* The track edit list is a feature that allows creation of an alternate
|
|
* timeline for the track, typically cutting out segments of the full track to
|
|
* form a shortened, cleaned up version. The edit segments that form the edit
|
|
* list are a sequence of track start times and durations, they do not alter
|
|
* the track media in any way, i.e. no data can be lost via edit list
|
|
* operations.
|
|
*
|
|
* To read out the editted version of the track, use
|
|
* MP4ReadSampleFromEditTime() instead of MP4ReadSample().
|
|
*
|
|
* To export the editted version of the track to a new track, potentially in a
|
|
* new mp4 file, see MP4CopyTrack().
|
|
*
|
|
* Note with many media encodings such as MPEG-4, AAC and MP3, care must be
|
|
* taken when choosing the edit segment start times. E.g. for video tracks a
|
|
* reference or key frame should be selected as the starting sample of any
|
|
* edit segment. For audio tracks, an audio sample start time should be used.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the desired position in the edit list sequence for
|
|
* the new edit segment. If the value is MP4_INVALID_EDIT_ID, then the
|
|
* edit segment is added at the end of the existing edit list. Note
|
|
* editId's start with the value of 1, not 0.
|
|
* @param startTime specifies the starting time of the edit segment in the
|
|
* track time scale.
|
|
* @param duration specifies the duration of the edit segment in the track
|
|
* time scale.
|
|
* @param dwell If false, the track media should be played at its normal rate.
|
|
* If true, the media should be paused for the duration of this edit
|
|
* segment. This is a mechanism by which one can delay the start of a
|
|
* media track.
|
|
*
|
|
* @return Upon success, the edit id of the new edit segment. Upon an error,
|
|
* MP4_INVALID_EDIT_ID.
|
|
*
|
|
* @see MP4DeleteTrackEdit()
|
|
* @see MP4ReadSampleFromEditTime()
|
|
* @see MP4CopyTrack()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4EditId MP4AddTrackEdit(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId DEFAULT(MP4_INVALID_EDIT_ID),
|
|
MP4Timestamp startTime DEFAULT(0),
|
|
MP4Duration duration DEFAULT(0),
|
|
bool dwell DEFAULT(false) );
|
|
|
|
/** Delete a track edit segment.
|
|
*
|
|
* MP4DeleteTrackEdit deletes the specified track edit segment. Note that
|
|
* since editId's form a sequence, deleting an editId will cause all edit
|
|
* segments with editId's greater than the deleted one to be reassigned to
|
|
* their editId minus one.
|
|
*
|
|
* Deleting an edit segment does not delete any media samples.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment to be deleted.
|
|
*
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
|
*
|
|
* @see MP4AddTrackEdit()
|
|
*/
|
|
MP4V2_EXPORT
|
|
bool MP4DeleteTrackEdit(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId );
|
|
|
|
/** Get the number of edit segments for a track.
|
|
*
|
|
* MP4GetTrackNumberOfEdits returns the number of edit segments in the
|
|
* specified track in the mp4 file. Edit id's are the consecutive sequence of
|
|
* numbers from 1 to the total number of edit segments, i.e. 1-based indexing,
|
|
* not 0-based indexing.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track for which the number of edit segments is
|
|
* desired.
|
|
*
|
|
* @return Upon success, the number of edit segments for the track. Upon an
|
|
* error, 0.
|
|
*
|
|
* @see MP4AddTrackEdit()
|
|
* @see MP4DeleteTrackEdit()
|
|
*/
|
|
MP4V2_EXPORT
|
|
uint32_t MP4GetTrackNumberOfEdits(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId );
|
|
|
|
/** Get the start time of a track edit segment.
|
|
*
|
|
* MP4GetTrackEditStart returns the start time of the specified track edit
|
|
* segment in the timeline of the track edit list.
|
|
*
|
|
* Caveat: The value is in units of the track time scale.
|
|
*
|
|
* Note that this differs from the edit segment media start time,
|
|
* MP4GetTrackEditMediaStart(). For example:
|
|
*
|
|
* EditId | Start | MediaStart | Duration
|
|
* -------|-------|------------|---------
|
|
* 1 | 0 | 15 | 30
|
|
* 2 | 30 | 120 | 20
|
|
* 3 | 50 | 3000 | 10
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment for which the start time is
|
|
* desired.
|
|
*
|
|
* @return The start time of the edit segment in track time scale units of the
|
|
* track in the mp4 file.
|
|
*
|
|
* @see MP4SetTrackEditStart()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4Timestamp MP4GetTrackEditStart(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId );
|
|
|
|
/** Get the total duration of a sequence of track edit segments.
|
|
*
|
|
* MP4GetTrackEditTotalDuration returns the total duration of the specified
|
|
* sequence of track edit segments from the first edit segment up to and
|
|
* including the specified edit segment. If the edit id value is
|
|
* MP4_INVALID_EDIT_ID, then the total duration of all of the edit segments is
|
|
* returned.
|
|
*
|
|
* Caveat: The value is in units of the track time scale.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment for which the total duration is
|
|
* desired. A value of MP4_INVALID_EDIT_ID specifies that all edit
|
|
* segments should be included.
|
|
*
|
|
* @return The total duration of the edit segment sequence in track time scale
|
|
* units of the track in the mp4 file.
|
|
*
|
|
* @see MP4GetTrackEditDuration()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4Duration MP4GetTrackEditTotalDuration(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId DEFAULT(MP4_INVALID_EDIT_ID) );
|
|
|
|
/** Get the media start time of a track edit segment.
|
|
*
|
|
* MP4GetTrackEditMediaStart returns the media start time of the specified
|
|
* track edit segment.
|
|
*
|
|
* Caveat: The value is in units of the track time scale.
|
|
*
|
|
* Note that this differs from the edit segment start time,
|
|
* MP4GetTrackEditStart(). For example:
|
|
*
|
|
* EditId | Start | MediaStart | Duration
|
|
* -------|-------|------------|---------
|
|
* 1 | 0 | 15 | 30
|
|
* 2 | 30 | 120 | 20
|
|
* 3 | 50 | 3000 | 10
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment for which the media start time is
|
|
* desired.
|
|
*
|
|
* @return The media start time of the edit segment in track time scale units
|
|
* of the track in the mp4 file.
|
|
*
|
|
* @see MP4SetTrackEditMediaStart()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4Timestamp MP4GetTrackEditMediaStart(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId );
|
|
|
|
/** Set the media start time of a track edit segment.
|
|
*
|
|
* MP4SetTrackEditMediaStart sets the media start time of the specified edit
|
|
* segment from the specified track in the track time scale units. See
|
|
* MP4ConvertToTrackTimestamp() for how to map this value from another time
|
|
* scale.
|
|
*
|
|
* Note that this differs from the edit segment start time. For example:
|
|
*
|
|
* EditId | Start | MediaStart | Duration
|
|
* -------|-------|------------|---------
|
|
* 1 | 0 | 15 | 30
|
|
* 2 | 30 | 120 | 20
|
|
* 3 | 50 | 3000 | 10
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment to which the operation applies.
|
|
* Caveat: the first edit has id 1 not 0.
|
|
* @param startTime specifies the new value for the media start in track time
|
|
* scale units.
|
|
*
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
|
*
|
|
* @see MP4GetTrackEditMediaStart()
|
|
*/
|
|
MP4V2_EXPORT
|
|
bool MP4SetTrackEditMediaStart(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId,
|
|
MP4Timestamp startTime );
|
|
|
|
/** Get the duration of a track edit segment.
|
|
*
|
|
* MP4GetTrackEditDuration returns the duration of the specified track edit
|
|
* segment.
|
|
*
|
|
* Caveat: The value is in units of the track time scale.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment for which the duration is desired.
|
|
*
|
|
* @return The duration of the edit segment in track time scale units of the
|
|
* track in the mp4 file.
|
|
*
|
|
* @see MP4SetTrackEditDuration()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4Duration MP4GetTrackEditDuration(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId );
|
|
|
|
/** Set the duration of a track edit segment.
|
|
*
|
|
* MP4SetTrackEditDuration sets the duration of the specified edit segment
|
|
* from the specified track in the track time scale units. See
|
|
* MP4ConvertToTrackDuration() for how to map this value from another time
|
|
* scale.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment to which the operation applies.
|
|
* Caveat: the first edit has id 1 not 0.
|
|
* @param duration specifies the new value for the duration in track time
|
|
* scale units.
|
|
*
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
|
*
|
|
* @see MP4GetTrackEditDuration()
|
|
*/
|
|
MP4V2_EXPORT
|
|
bool MP4SetTrackEditDuration(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId,
|
|
MP4Duration duration );
|
|
|
|
/** Get the dwell value of a track edit segment.
|
|
*
|
|
* MP4GetTrackEditDwell returns the dwell value of the specified track edit
|
|
* segment. A value of true (1) indicates that during this edit segment the
|
|
* media will be paused; a value of false (0) indicates that during this edit
|
|
* segment the media will be played at its normal rate.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment for which the dwell value is
|
|
* desired.
|
|
*
|
|
* @return The dwell value of the edit segment of the track in the mp4 file.
|
|
*
|
|
* @see MP4SetTrackEditDwell()
|
|
*/
|
|
MP4V2_EXPORT
|
|
int8_t MP4GetTrackEditDwell(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId );
|
|
|
|
/** Set the dwell value of a track edit segment.
|
|
*
|
|
* MP4SetTrackEditDwell sets the dwell value of the specified edit segment
|
|
* from the specified track.
|
|
*
|
|
* A value of true (1) indicates that during this edit segment the media will
|
|
* be paused; a value of false (0) indicates that during this edit segment the
|
|
* media will be played at its normal rate.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param editId specifies the edit segment to which the operation applies.
|
|
* Caveat: the first edit has id 1 not 0.
|
|
* @param dwell specifies the new dwell value.
|
|
*
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
|
*
|
|
* @see MP4GetTrackEditDwell()
|
|
*/
|
|
MP4V2_EXPORT
|
|
bool MP4SetTrackEditDwell(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4EditId editId,
|
|
bool dwell );
|
|
|
|
/** Read a track sample based on a specified edit list time.
|
|
*
|
|
* MP4ReadSampleFromEditTime reads the sample corresponding to the time on the
|
|
* track edit list timeline from the specified track. Typically this sample is
|
|
* then decoded in a codec dependent fashion and rendered in an appropriate
|
|
* fashion.
|
|
*
|
|
* The argument, <b>ppBytes</b>, allows for two possible approaches for
|
|
* buffering:
|
|
*
|
|
* @li If the calling application wishes to handle its own buffering it can
|
|
* set <b>*ppBytes</b> to the buffer it wishes to use. The calling
|
|
* application is responsible for ensuring that the buffer is large enough
|
|
* to hold the sample. This can be done by using either MP4GetSampleSize()
|
|
* or MP4GetTrackMaxSampleSize() to determine beforehand how large the
|
|
* receiving buffer must be.
|
|
*
|
|
* @li If the value of <b>*ppBytes</b> is NULL, then an appropriately sized
|
|
* buffer is automatically allocated for the sample data and
|
|
* <b>*ppBytes</b> set to this pointer. The calling application is
|
|
* responsible for freeing this memory with MP4Free().
|
|
*
|
|
* The last four arguments are pointers to variables that can receive optional
|
|
* sample information.
|
|
*
|
|
* Typically for audio none of these are needed. MPEG audio such as MP3 or AAC
|
|
* has a fixed sample duration and every sample can be accessed at random.
|
|
*
|
|
* For video, all of these optional values could be needed. MPEG video can be
|
|
* encoded at a variable frame rate, with only occasional random access
|
|
* points, and with "B frames" which cause the rendering (display) order of
|
|
* the video frames to differ from the storage/decoding order.
|
|
*
|
|
* Other media types fall between these two extremes.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param when specifies which sample is to be read based on a time in the
|
|
* edit list timeline. See MP4GetSampleIdFromEditTime() for details.
|
|
* @param ppBytes Pointer to the pointer to the sample data. See function
|
|
* description above for details on this argument.
|
|
* @param pNumBytes Pointer to variable that will be hold the size in bytes of
|
|
* the sample.
|
|
* @param pStartTime If non-NULL, pointer to variable that will receive the
|
|
* starting timestamp for this sample. Caveat: The timestamp is in the
|
|
* track timescale.
|
|
* @param pDuration If non-NULL, pointer to variable that will receive the
|
|
* duration for this sample. Caveat: The duration is in the track
|
|
* timescale units.
|
|
* @param pRenderingOffset If non-NULL, pointer to variable that will receive
|
|
* the rendering offset for this sample. Currently the only media type
|
|
* that needs this feature is MPEG video. Caveat: The offset is in the
|
|
* track timescale units.
|
|
* @param pIsSyncSample If non-NULL, pointer to variable that will receive the
|
|
* state of the sync/random access flag for this sample.
|
|
*
|
|
* @return Upon success, true (1). Upon an error, false (0).
|
|
*
|
|
* @see MP4ReadSample()
|
|
* @see MP4GetSampleIdFromEditTime()
|
|
* @see MP4ReadSampleFromTime()
|
|
*/
|
|
MP4V2_EXPORT
|
|
bool MP4ReadSampleFromEditTime(
|
|
/* input parameters */
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4Timestamp when,
|
|
/* input/output parameters */
|
|
uint8_t** ppBytes,
|
|
uint32_t* pNumBytes,
|
|
/* output parameters */
|
|
MP4Timestamp* pStartTime DEFAULT(NULL),
|
|
MP4Duration* pDuration DEFAULT(NULL),
|
|
MP4Duration* pRenderingOffset DEFAULT(NULL),
|
|
bool* pIsSyncSample DEFAULT(NULL) );
|
|
|
|
/** Get the sample id of a specified time in the edit list timeline.
|
|
*
|
|
* MP4GetSampleIdFromEditTime returns the sample id of the track sample in
|
|
* which the specified time occurs in the edit list timeline.
|
|
*
|
|
* The specified time should be in the track time scale. See
|
|
* MP4ConvertToTrackTimestamp() for how to map a time value to this time
|
|
* scale.
|
|
*
|
|
* Since the edit list can cause the sample start time and duration to be
|
|
* different that it in the standard track timeline, it is strongly advised
|
|
* that the caller retrieve the new sample start time and duration via this
|
|
* function.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param when specifies the time in the track time scale that is desired.
|
|
* @param pStartTime If non-NULL, pointer to variable that will receive the
|
|
* starting timestamp for this sample. Caveat: The timestamp is in the
|
|
* track edit list timescale.
|
|
* @param pDuration If non-NULL, pointer to variable that will receive the
|
|
* duration for this sample in the edit list timeline. Caveat: The
|
|
* duration is in the track timescale units.
|
|
*
|
|
* @return Upon success, the sample id that occurs at the specified time. Upon
|
|
* an error, MP4_INVALID_SAMPLE_ID.
|
|
*
|
|
* @see MP4GetSampleIdFromTime()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4SampleId MP4GetSampleIdFromEditTime(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4Timestamp when,
|
|
MP4Timestamp* pStartTime DEFAULT(NULL),
|
|
MP4Duration* pDuration DEFAULT(NULL) );
|
|
|
|
/* time conversion utilties */
|
|
|
|
/* predefined values for timeScale parameter below */
|
|
#define MP4_SECONDS_TIME_SCALE 1
|
|
#define MP4_MILLISECONDS_TIME_SCALE 1000
|
|
#define MP4_MICROSECONDS_TIME_SCALE 1000000
|
|
#define MP4_NANOSECONDS_TIME_SCALE 1000000000
|
|
|
|
#define MP4_SECS_TIME_SCALE MP4_SECONDS_TIME_SCALE
|
|
#define MP4_MSECS_TIME_SCALE MP4_MILLISECONDS_TIME_SCALE
|
|
#define MP4_USECS_TIME_SCALE MP4_MICROSECONDS_TIME_SCALE
|
|
#define MP4_NSECS_TIME_SCALE MP4_NANOSECONDS_TIME_SCALE
|
|
|
|
/** Convert a duration from the movie (file) time scale to a specified time
|
|
* scale.
|
|
*
|
|
* MP4ConvertFromMovieDuration converts a duration such as the total movie
|
|
* (file) duration from the movie time scale to another specified time scale.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param duration specifies the duration that is to be converted.
|
|
* @param timeScale specifies the new time scale in ticks per second to which
|
|
* the duration should be converted.
|
|
*
|
|
* @return Upon success, the duration in the new time scale units. Upon error,
|
|
* (uint64_t) MP4_INVALID_DURATION.
|
|
*
|
|
* @see MP4GetDuration()
|
|
*/
|
|
MP4V2_EXPORT
|
|
uint64_t MP4ConvertFromMovieDuration(
|
|
MP4FileHandle hFile,
|
|
MP4Duration duration,
|
|
uint32_t timeScale );
|
|
|
|
/** Convert a timestamp from the track time scale to a specified time scale.
|
|
*
|
|
* MP4ConvertFromTrackTimestamp converts a timestamp such as a sample start
|
|
* time from the track time scale to another specified time scale. This can be
|
|
* used by a player application to map all track samples to a common time
|
|
* scale.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track from which the timestamp originates.
|
|
* @param timeStamp specifies the timestamp that is to be converted.
|
|
* @param timeScale specifies the new time scale in ticks per second to which
|
|
* the timestamp should be converted.
|
|
*
|
|
* @return Upon success, the timestamp in the new time scale units. Upon
|
|
* error, (uint64_t) MP4_INVALID_TIMESTAMP.
|
|
*
|
|
* @see MP4ConvertToTrackTimestamp()
|
|
*/
|
|
MP4V2_EXPORT
|
|
uint64_t MP4ConvertFromTrackTimestamp(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4Timestamp timeStamp,
|
|
uint32_t timeScale );
|
|
|
|
/** Convert a timestamp from a specified time scale to the track time scale.
|
|
*
|
|
* MP4ConvertToTrackTimestamp converts a timestamp such as a sample start time
|
|
* from the specified time scale to the track time scale.
|
|
*
|
|
* @param hFile specifies the mp4 file to which the operation applies.
|
|
* @param trackId specifies the track to which the operation applies.
|
|
* @param timeStamp specifies the timestamp that is to be converted.
|
|
* @param timeScale specifies the time scale in ticks per second in which the
|
|
* timestamp is currently expressed.
|
|
*
|
|
* @return Upon success, the timestamp in the track time scale units. Upon
|
|
* error, MP4_INVALID_TIMESTAMP.
|
|
*
|
|
* @see MP4ConvertFromTrackTimestamp()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4Timestamp MP4ConvertToTrackTimestamp(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
uint64_t timeStamp,
|
|
uint32_t timeScale );
|
|
|
|
/** Convert duration from track time scale to an arbitrary time scale.
|
|
*
|
|
* MP4ConvertFromTrackDuration converts a duration such as a sample duration
|
|
* from the track time scale to another time scale. This can be used by a
|
|
* player application to map all track samples to a common time scale.
|
|
*
|
|
* @param hFile handle of file for operation.
|
|
* @param trackId id of track for operation.
|
|
* @param duration value to be converted.
|
|
* @param timeScale time scale in ticks per second.
|
|
*
|
|
* @return On success, the duration in arbitrary time scale units.
|
|
* On error, (uint64_t) MP4_INVALID_DURATION.
|
|
*
|
|
* @see MP4GetSampleDuration()
|
|
* @see MP4ConvertToTrackDuration()
|
|
*/
|
|
MP4V2_EXPORT
|
|
uint64_t MP4ConvertFromTrackDuration(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
MP4Duration duration,
|
|
uint32_t timeScale );
|
|
|
|
/** Convert duration from arbitrary time scale to track time scale.
|
|
*
|
|
* MP4ConvertToTrackDuration converts a duration such as a sample duration
|
|
* from the specified time scale to the track time scale.
|
|
*
|
|
* @param hFile handle of file for operation.
|
|
* @param trackId id of track for operation.
|
|
* @param duration value to be converted.
|
|
* @param timeScale time scale in ticks per second.
|
|
*
|
|
* @return On success, the duration in track time scale units.
|
|
* On error, #MP4_INVALID_DURATION.
|
|
*
|
|
* @see MP4ConvertFromTrackDuration()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4Duration MP4ConvertToTrackDuration(
|
|
MP4FileHandle hFile,
|
|
MP4TrackId trackId,
|
|
uint64_t duration,
|
|
uint32_t timeScale );
|
|
|
|
/** Convert binary data to a base 16 string.
|
|
*
|
|
* MP4BinaryToBase16 converts binary data to a base 16 string. This encoding
|
|
* maps groups of 4 bits into the character set [0-9a-f]. The string is in
|
|
* newly allocated memory, so the caller is responsible for freeing the memory
|
|
* with MP4Free().
|
|
*
|
|
* This utility is useful for generating the SDP descriptions for some RTP
|
|
* payloads.
|
|
*
|
|
* Example:
|
|
* @code
|
|
* 0x12, 0xAB -> "12ab"
|
|
* @endcode
|
|
*
|
|
* @param pData specifies the pointer to the binary data.
|
|
* @param dataSize specifies the size in bytes of the binary data.
|
|
*
|
|
* @return Upon success, a null terminated string representing the data in
|
|
* base 16. Upon error, NULL.
|
|
*/
|
|
MP4V2_EXPORT
|
|
char* MP4BinaryToBase16(
|
|
const uint8_t* pData,
|
|
uint32_t dataSize );
|
|
|
|
/** Convert binary data to a base 64 string.
|
|
*
|
|
* MP4BinaryToBase64 converts binary data to a base 64 string. This encoding
|
|
* maps groups of 6 bits into the character set [A-Za-z0-9+/=]. The string is
|
|
* in newly allocated memory, so the caller is responsible for freeing the
|
|
* memory with MP4Free().
|
|
*
|
|
* This utility is useful for generating the SDP descriptions for some RTP
|
|
* payloads.
|
|
*
|
|
* Example:
|
|
* @code
|
|
* 0x12, 0xAB -> "Eqs="
|
|
* @endcode
|
|
*
|
|
* @param pData specifies the pointer to the binary data.
|
|
* @param dataSize specifies the size in bytes of the binary data.
|
|
*
|
|
* @return Upon success, a null terminated string representing the data in
|
|
* base 64. Upon error, NULL.
|
|
*/
|
|
MP4V2_EXPORT
|
|
char* MP4BinaryToBase64(
|
|
const uint8_t* pData,
|
|
uint32_t dataSize );
|
|
|
|
/** Free memory allocated by other library functions.
|
|
*
|
|
* MP4Free frees a block of memory previously allocated by another library
|
|
* function.
|
|
*
|
|
* Generally, library functions that allocate memory specify in their
|
|
* documentation whether MP4Free or another function must be used to free that
|
|
* memory.
|
|
*
|
|
* @param p specifies a pointer to the memory block to free.
|
|
*/
|
|
MP4V2_EXPORT
|
|
void MP4Free(
|
|
void* p );
|
|
|
|
/** Set the current log handler function.
|
|
*
|
|
* MP4SetLogCallback sets the function to call to output diagnostic
|
|
* information in place of the default log handler. The signature of the
|
|
* specified function must be compatible with the MP4LogCallback typedef.
|
|
*
|
|
* @param cb_func specifies the new log handler function.
|
|
*
|
|
* @see MP4LogCallback
|
|
*/
|
|
MP4V2_EXPORT
|
|
void MP4SetLogCallback(
|
|
MP4LogCallback cb_func );
|
|
|
|
/** Get the current maximum log level.
|
|
*
|
|
* MP4LogGetLevel returns the currently set maximum level of diagnostic
|
|
* information passed to the log handler.
|
|
*
|
|
* @return the current maximum level of diagnostic information.
|
|
*
|
|
* @see MP4LogSetLevel()
|
|
*/
|
|
MP4V2_EXPORT
|
|
MP4LogLevel MP4LogGetLevel( void );
|
|
|
|
/** Set the maximum log level.
|
|
*
|
|
* MP4LogSetLevel sets the maximum level of diagnostic information passed to
|
|
* the current log handler.
|
|
*
|
|
* @param verbosity specifies the log level to set.
|
|
*
|
|
* @see MP4LogGetLevel()
|
|
*/
|
|
MP4V2_EXPORT
|
|
void MP4LogSetLevel(
|
|
MP4LogLevel verbosity );
|
|
|
|
/** @} ***********************************************************************/
|
|
|
|
#endif /* MP4V2_GENERAL_H */
|