include/mp4v2/general.h Source File
general.h
1 #ifndef MP4V2_GENERAL_H
2 #define MP4V2_GENERAL_H
3 
4 /**************************************************************************/
11 /* MP4 API types */
12 typedef void* MP4FileHandle;
13 typedef uint32_t MP4TrackId;
14 typedef uint32_t MP4SampleId;
15 typedef uint64_t MP4Timestamp;
16 typedef uint64_t MP4Duration;
17 typedef uint32_t MP4EditId;
18 
19 typedef enum {
20  MP4_LOG_NONE = 0,
21  MP4_LOG_ERROR = 1,
22  MP4_LOG_WARNING = 2,
23  MP4_LOG_INFO = 3,
24  MP4_LOG_VERBOSE1 = 4,
25  MP4_LOG_VERBOSE2 = 5,
26  MP4_LOG_VERBOSE3 = 6,
27  MP4_LOG_VERBOSE4 = 7
28 } MP4LogLevel;
29 
30 /*****************************************************************************/
31 
32 typedef void (*MP4LogCallback)(
33  MP4LogLevel loglevel,
34  const char* fmt,
35  va_list ap );
36 
37 /*****************************************************************************/
38 
44 typedef uint32_t (*encryptFunc_t)( uint32_t, uint32_t, uint8_t*, uint32_t*, uint8_t** );
45 
46 /*****************************************************************************/
47 
48 #define MP4_INVALID_FILE_HANDLE ((MP4FileHandle)NULL)
49 #define MP4_INVALID_TRACK_ID ((MP4TrackId)0)
50 #define MP4_INVALID_SAMPLE_ID ((MP4SampleId)0)
51 #define MP4_INVALID_TIMESTAMP ((MP4Timestamp)-1)
52 #define MP4_INVALID_DURATION ((MP4Duration)-1)
53 #define MP4_INVALID_EDIT_ID ((MP4EditId)0)
55 /* Macros to test for API type validity */
56 #define MP4_IS_VALID_FILE_HANDLE(x) ((x) != MP4_INVALID_FILE_HANDLE)
57 #define MP4_IS_VALID_TRACK_ID(x) ((x) != MP4_INVALID_TRACK_ID)
58 #define MP4_IS_VALID_SAMPLE_ID(x) ((x) != MP4_INVALID_SAMPLE_ID)
59 #define MP4_IS_VALID_TIMESTAMP(x) ((x) != MP4_INVALID_TIMESTAMP)
60 #define MP4_IS_VALID_DURATION(x) ((x) != MP4_INVALID_DURATION)
61 #define MP4_IS_VALID_EDIT_ID(x) ((x) != MP4_INVALID_EDIT_ID)
62 
63 /*
64  * MP4 Known track type names - e.g. MP4GetNumberOfTracks(type)
65  *
66  * Note this first group of track types should be created
67  * via the MP4Add<Type>Track() functions, and not MP4AddTrack(type)
68  */
69 #define MP4_OD_TRACK_TYPE "odsm"
70 #define MP4_SCENE_TRACK_TYPE "sdsm"
71 #define MP4_AUDIO_TRACK_TYPE "soun"
72 #define MP4_VIDEO_TRACK_TYPE "vide"
73 #define MP4_HINT_TRACK_TYPE "hint"
74 #define MP4_CNTL_TRACK_TYPE "cntl"
75 #define MP4_TEXT_TRACK_TYPE "text"
76 #define MP4_SUBTITLE_TRACK_TYPE "sbtl"
77 #define MP4_SUBPIC_TRACK_TYPE "subp"
78 /*
79  * This second set of track types should be created
80  * via MP4AddSystemsTrack(type)
81  */
82 #define MP4_CLOCK_TRACK_TYPE "crsm"
83 #define MP4_MPEG7_TRACK_TYPE "m7sm"
84 #define MP4_OCI_TRACK_TYPE "ocsm"
85 #define MP4_IPMP_TRACK_TYPE "ipsm"
86 #define MP4_MPEGJ_TRACK_TYPE "mjsm"
88 #define MP4_IS_VIDEO_TRACK_TYPE(type) \
89  (!strcasecmp(type, MP4_VIDEO_TRACK_TYPE))
90 
91 #define MP4_IS_AUDIO_TRACK_TYPE(type) \
92  (!strcasecmp(type, MP4_AUDIO_TRACK_TYPE))
93 
94 #define MP4_IS_CNTL_TRACK_TYPE(type) \
95  (!strcasecmp(type, MP4_CNTL_TRACK_TYPE))
96 
97 #define MP4_IS_OD_TRACK_TYPE(type) \
98  (!strcasecmp(type, MP4_OD_TRACK_TYPE))
99 
100 #define MP4_IS_SCENE_TRACK_TYPE(type) \
101  (!strcasecmp(type, MP4_SCENE_TRACK_TYPE))
102 
103 #define MP4_IS_HINT_TRACK_TYPE(type) \
104  (!strcasecmp(type, MP4_HINT_TRACK_TYPE))
105 
106 #define MP4_IS_SYSTEMS_TRACK_TYPE(type) \
107  (!strcasecmp(type, MP4_CLOCK_TRACK_TYPE) \
108  || !strcasecmp(type, MP4_MPEG7_TRACK_TYPE) \
109  || !strcasecmp(type, MP4_OCI_TRACK_TYPE) \
110  || !strcasecmp(type, MP4_IPMP_TRACK_TYPE) \
111  || !strcasecmp(type, MP4_MPEGJ_TRACK_TYPE))
112 
113 /* MP4 Audio track types - see MP4AddAudioTrack()*/
114 #define MP4_INVALID_AUDIO_TYPE 0x00
115 #define MP4_MPEG1_AUDIO_TYPE 0x6B
116 #define MP4_MPEG2_AUDIO_TYPE 0x69
117 #define MP4_MP3_AUDIO_TYPE MP4_MPEG2_AUDIO_TYPE
118 #define MP4_MPEG2_AAC_MAIN_AUDIO_TYPE 0x66
119 #define MP4_MPEG2_AAC_LC_AUDIO_TYPE 0x67
120 #define MP4_MPEG2_AAC_SSR_AUDIO_TYPE 0x68
121 #define MP4_MPEG2_AAC_AUDIO_TYPE MP4_MPEG2_AAC_MAIN_AUDIO_TYPE
122 #define MP4_MPEG4_AUDIO_TYPE 0x40
123 #define MP4_PRIVATE_AUDIO_TYPE 0xC0
124 #define MP4_PCM16_LITTLE_ENDIAN_AUDIO_TYPE 0xE0 /* a private definition */
125 #define MP4_VORBIS_AUDIO_TYPE 0xE1 /* a private definition */
126 #define MP4_AC3_AUDIO_TYPE 0xE2 /* a private definition */
127 #define MP4_ALAW_AUDIO_TYPE 0xE3 /* a private definition */
128 #define MP4_ULAW_AUDIO_TYPE 0xE4 /* a private definition */
129 #define MP4_G723_AUDIO_TYPE 0xE5 /* a private definition */
130 #define MP4_PCM16_BIG_ENDIAN_AUDIO_TYPE 0xE6 /* a private definition */
131 
132 /* MP4 MPEG-4 Audio types from 14496-3 Table 1.5.1 */
133 #define MP4_MPEG4_INVALID_AUDIO_TYPE 0
134 #define MP4_MPEG4_AAC_MAIN_AUDIO_TYPE 1
135 #define MP4_MPEG4_AAC_LC_AUDIO_TYPE 2
136 #define MP4_MPEG4_AAC_SSR_AUDIO_TYPE 3
137 #define MP4_MPEG4_AAC_LTP_AUDIO_TYPE 4
138 #define MP4_MPEG4_AAC_HE_AUDIO_TYPE 5
139 #define MP4_MPEG4_AAC_SCALABLE_AUDIO_TYPE 6
140 #define MP4_MPEG4_CELP_AUDIO_TYPE 8
141 #define MP4_MPEG4_HVXC_AUDIO_TYPE 9
142 #define MP4_MPEG4_TTSI_AUDIO_TYPE 12
143 #define MP4_MPEG4_MAIN_SYNTHETIC_AUDIO_TYPE 13
144 #define MP4_MPEG4_WAVETABLE_AUDIO_TYPE 14
145 #define MP4_MPEG4_MIDI_AUDIO_TYPE 15
146 #define MP4_MPEG4_ALGORITHMIC_FX_AUDIO_TYPE 16
147 #define MP4_MPEG4_ALS_AUDIO_TYPE 31
148 #define MP4_MPEG4_LAYER1_AUDIO_TYPE 32
149 #define MP4_MPEG4_LAYER2_AUDIO_TYPE 33
150 #define MP4_MPEG4_LAYER3_AUDIO_TYPE 34
151 #define MP4_MPEG4_SLS_AUDIO_TYPE 35
152 
153 /* MP4 Audio type utilities following common usage */
154 #define MP4_IS_MP3_AUDIO_TYPE(type) \
155  ((type) == MP4_MPEG1_AUDIO_TYPE || (type) == MP4_MPEG2_AUDIO_TYPE)
156 
157 #define MP4_IS_MPEG2_AAC_AUDIO_TYPE(type) \
158  (((type) >= MP4_MPEG2_AAC_MAIN_AUDIO_TYPE \
159  && (type) <= MP4_MPEG2_AAC_SSR_AUDIO_TYPE))
160 
161 #define MP4_IS_MPEG4_AAC_AUDIO_TYPE(mpeg4Type) \
162  (((mpeg4Type) >= MP4_MPEG4_AAC_MAIN_AUDIO_TYPE \
163  && (mpeg4Type) <= MP4_MPEG4_AAC_HE_AUDIO_TYPE) \
164  || (mpeg4Type) == MP4_MPEG4_AAC_SCALABLE_AUDIO_TYPE \
165  || (mpeg4Type) == 17)
166 
167 #define MP4_IS_AAC_AUDIO_TYPE(type) \
168  (MP4_IS_MPEG2_AAC_AUDIO_TYPE(type) \
169  || (type) == MP4_MPEG4_AUDIO_TYPE)
170 
171 /* MP4 Video track types - see MP4AddVideoTrack() */
172 #define MP4_INVALID_VIDEO_TYPE 0x00
173 #define MP4_MPEG1_VIDEO_TYPE 0x6A
174 #define MP4_MPEG2_SIMPLE_VIDEO_TYPE 0x60
175 #define MP4_MPEG2_MAIN_VIDEO_TYPE 0x61
176 #define MP4_MPEG2_SNR_VIDEO_TYPE 0x62
177 #define MP4_MPEG2_SPATIAL_VIDEO_TYPE 0x63
178 #define MP4_MPEG2_HIGH_VIDEO_TYPE 0x64
179 #define MP4_MPEG2_442_VIDEO_TYPE 0x65
180 #define MP4_MPEG2_VIDEO_TYPE MP4_MPEG2_MAIN_VIDEO_TYPE
181 #define MP4_MPEG4_VIDEO_TYPE 0x20
182 #define MP4_JPEG_VIDEO_TYPE 0x6C
183 #define MP4_PRIVATE_VIDEO_TYPE 0xD0
184 #define MP4_YUV12_VIDEO_TYPE 0xF0 /* a private definition */
185 #define MP4_H263_VIDEO_TYPE 0xF2 /* a private definition */
186 #define MP4_H261_VIDEO_TYPE 0xF3 /* a private definition */
187 
188 /* MP4 Video type utilities */
189 #define MP4_IS_MPEG1_VIDEO_TYPE(type) \
190  ((type) == MP4_MPEG1_VIDEO_TYPE)
191 
192 #define MP4_IS_MPEG2_VIDEO_TYPE(type) \
193  (((type) >= MP4_MPEG2_SIMPLE_VIDEO_TYPE \
194  && (type) <= MP4_MPEG2_442_VIDEO_TYPE) \
195  || MP4_IS_MPEG1_VIDEO_TYPE(type))
196 
197 #define MP4_IS_MPEG4_VIDEO_TYPE(type) \
198  ((type) == MP4_MPEG4_VIDEO_TYPE)
199 
200 /* Mpeg4 Visual Profile Defines - ISO/IEC 14496-2:2001/Amd.2:2002(E) */
201 #define MPEG4_SP_L1 (0x1)
202 #define MPEG4_SP_L2 (0x2)
203 #define MPEG4_SP_L3 (0x3)
204 #define MPEG4_SP_L0 (0x8)
205 #define MPEG4_SSP_L1 (0x11)
206 #define MPEG4_SSP_L2 (0x12)
207 #define MPEG4_CP_L1 (0x21)
208 #define MPEG4_CP_L2 (0x22)
209 #define MPEG4_MP_L2 (0x32)
210 #define MPEG4_MP_L3 (0x33)
211 #define MPEG4_MP_L4 (0x34)
212 #define MPEG4_NBP_L2 (0x42)
213 #define MPEG4_STP_L1 (0x51)
214 #define MPEG4_SFAP_L1 (0x61)
215 #define MPEG4_SFAP_L2 (0x62)
216 #define MPEG4_SFBAP_L1 (0x63)
217 #define MPEG4_SFBAP_L2 (0x64)
218 #define MPEG4_BATP_L1 (0x71)
219 #define MPEG4_BATP_L2 (0x72)
220 #define MPEG4_HP_L1 (0x81)
221 #define MPEG4_HP_L2 (0x82)
222 #define MPEG4_ARTSP_L1 (0x91)
223 #define MPEG4_ARTSP_L2 (0x92)
224 #define MPEG4_ARTSP_L3 (0x93)
225 #define MPEG4_ARTSP_L4 (0x94)
226 #define MPEG4_CSP_L1 (0xa1)
227 #define MPEG4_CSP_L2 (0xa2)
228 #define MPEG4_CSP_L3 (0xa3)
229 #define MPEG4_ACEP_L1 (0xb1)
230 #define MPEG4_ACEP_L2 (0xb2)
231 #define MPEG4_ACEP_L3 (0xb3)
232 #define MPEG4_ACEP_L4 (0xb4)
233 #define MPEG4_ACP_L1 (0xc1)
234 #define MPEG4_ACP_L2 (0xc2)
235 #define MPEG4_AST_L1 (0xd1)
236 #define MPEG4_AST_L2 (0xd2)
237 #define MPEG4_AST_L3 (0xd3)
238 #define MPEG4_S_STUDIO_P_L1 (0xe1)
239 #define MPEG4_S_STUDIO_P_L2 (0xe2)
240 #define MPEG4_S_STUDIO_P_L3 (0xe3)
241 #define MPEG4_S_STUDIO_P_L4 (0xe4)
242 #define MPEG4_C_STUDIO_P_L1 (0xe5)
243 #define MPEG4_C_STUDIO_P_L2 (0xe6)
244 #define MPEG4_C_STUDIO_P_L3 (0xe7)
245 #define MPEG4_C_STUDIO_P_L4 (0xe8)
246 #define MPEG4_ASP_L0 (0xF0)
247 #define MPEG4_ASP_L1 (0xF1)
248 #define MPEG4_ASP_L2 (0xF2)
249 #define MPEG4_ASP_L3 (0xF3)
250 #define MPEG4_ASP_L4 (0xF4)
251 #define MPEG4_ASP_L5 (0xF5)
252 #define MPEG4_ASP_L3B (0xF7)
253 #define MPEG4_FGSP_L0 (0xf8)
254 #define MPEG4_FGSP_L1 (0xf9)
255 #define MPEG4_FGSP_L2 (0xfa)
256 #define MPEG4_FGSP_L3 (0xfb)
257 #define MPEG4_FGSP_L4 (0xfc)
258 #define MPEG4_FGSP_L5 (0xfd)
259 
260 /*****************************************************************************/
261 
262 /* 3GP specific utilities */
263 
264 MP4V2_EXPORT
265 bool MP4Make3GPCompliant(
266  const char* fileName,
267  char* majorBrand DEFAULT(0),
268  uint32_t minorVersion DEFAULT(0),
269  char** supportedBrands DEFAULT(NULL),
270  uint32_t supportedBrandsCount DEFAULT(0),
271  bool deleteIodsAtom DEFAULT(true) );
272 
273 /* NOTE this section of functionality has not yet been fully tested */
274 
275 MP4V2_EXPORT
276 MP4EditId MP4AddTrackEdit(
277  MP4FileHandle hFile,
278  MP4TrackId trackId,
279  MP4EditId editId DEFAULT(MP4_INVALID_EDIT_ID),
280  MP4Timestamp startTime DEFAULT(0),
281  MP4Duration duration DEFAULT(0),
282  bool dwell DEFAULT(false) );
283 
284 MP4V2_EXPORT
285 bool MP4DeleteTrackEdit(
286  MP4FileHandle hFile,
287  MP4TrackId trackId,
288  MP4EditId editId );
289 
290 MP4V2_EXPORT
291 uint32_t MP4GetTrackNumberOfEdits(
292  MP4FileHandle hFile,
293  MP4TrackId trackId );
294 
295 MP4V2_EXPORT
296 MP4Timestamp MP4GetTrackEditStart(
297  MP4FileHandle hFile,
298  MP4TrackId trackId,
299  MP4EditId editId );
300 
301 MP4V2_EXPORT
303  MP4FileHandle hFile,
304  MP4TrackId trackId,
305  MP4EditId editId DEFAULT(MP4_INVALID_EDIT_ID) );
306 
307 MP4V2_EXPORT
308 MP4Timestamp MP4GetTrackEditMediaStart(
309  MP4FileHandle hFile,
310  MP4TrackId trackId,
311  MP4EditId editId );
312 
313 MP4V2_EXPORT
314 bool MP4SetTrackEditMediaStart(
315  MP4FileHandle hFile,
316  MP4TrackId trackId,
317  MP4EditId editId,
318  MP4Timestamp startTime );
319 
320 MP4V2_EXPORT
321 MP4Duration MP4GetTrackEditDuration(
322  MP4FileHandle hFile,
323  MP4TrackId trackId,
324  MP4EditId editId );
325 
326 MP4V2_EXPORT
327 bool MP4SetTrackEditDuration(
328  MP4FileHandle hFile,
329  MP4TrackId trackId,
330  MP4EditId editId,
331  MP4Duration duration );
332 
333 MP4V2_EXPORT
334 int8_t MP4GetTrackEditDwell(
335  MP4FileHandle hFile,
336  MP4TrackId trackId,
337  MP4EditId editId );
338 
339 MP4V2_EXPORT
340 bool MP4SetTrackEditDwell(
341  MP4FileHandle hFile,
342  MP4TrackId trackId,
343  MP4EditId editId,
344  bool dwell );
345 
346 MP4V2_EXPORT
347 bool MP4ReadSampleFromEditTime(
348  /* input parameters */
349  MP4FileHandle hFile,
350  MP4TrackId trackId,
351  MP4Timestamp when,
352  /* input/output parameters */
353  uint8_t** ppBytes,
354  uint32_t* pNumBytes,
355  /* output parameters */
356  MP4Timestamp* pStartTime DEFAULT(NULL),
357  MP4Duration* pDuration DEFAULT(NULL),
358  MP4Duration* pRenderingOffset DEFAULT(NULL),
359  bool* pIsSyncSample DEFAULT(NULL) );
360 
361 MP4V2_EXPORT
362 MP4SampleId MP4GetSampleIdFromEditTime(
363  MP4FileHandle hFile,
364  MP4TrackId trackId,
365  MP4Timestamp when,
366  MP4Timestamp* pStartTime DEFAULT(NULL),
367  MP4Duration* pDuration DEFAULT(NULL) );
368 
369 /* time conversion utilties */
370 
371 /* predefined values for timeScale parameter below */
372 #define MP4_SECONDS_TIME_SCALE 1
373 #define MP4_MILLISECONDS_TIME_SCALE 1000
374 #define MP4_MICROSECONDS_TIME_SCALE 1000000
375 #define MP4_NANOSECONDS_TIME_SCALE 1000000000
376 
377 #define MP4_SECS_TIME_SCALE MP4_SECONDS_TIME_SCALE
378 #define MP4_MSECS_TIME_SCALE MP4_MILLISECONDS_TIME_SCALE
379 #define MP4_USECS_TIME_SCALE MP4_MICROSECONDS_TIME_SCALE
380 #define MP4_NSECS_TIME_SCALE MP4_NANOSECONDS_TIME_SCALE
381 
382 MP4V2_EXPORT
383 uint64_t MP4ConvertFromMovieDuration(
384  MP4FileHandle hFile,
385  MP4Duration duration,
386  uint32_t timeScale );
387 
388 MP4V2_EXPORT
389 uint64_t MP4ConvertFromTrackTimestamp(
390  MP4FileHandle hFile,
391  MP4TrackId trackId,
392  MP4Timestamp timeStamp,
393  uint32_t timeScale );
394 
395 MP4V2_EXPORT
396 MP4Timestamp MP4ConvertToTrackTimestamp(
397  MP4FileHandle hFile,
398  MP4TrackId trackId,
399  uint64_t timeStamp,
400  uint32_t timeScale );
401 
419 MP4V2_EXPORT
421  MP4FileHandle hFile,
422  MP4TrackId trackId,
423  MP4Duration duration,
424  uint32_t timeScale );
425 
441 MP4V2_EXPORT
443  MP4FileHandle hFile,
444  MP4TrackId trackId,
445  uint64_t duration,
446  uint32_t timeScale );
447 
448 MP4V2_EXPORT
449 char* MP4BinaryToBase16(
450  const uint8_t* pData,
451  uint32_t dataSize );
452 
453 MP4V2_EXPORT
454 char* MP4BinaryToBase64(
455  const uint8_t* pData,
456  uint32_t dataSize );
457 
458 MP4V2_EXPORT
459 uint8_t* Base64ToBinary(
460  const char* pData,
461  uint32_t decodeSize,
462  uint32_t* pDataSize );
463 
464 MP4V2_EXPORT
465 void MP4Free(
466  void* p );
467 
472 MP4V2_EXPORT
474  MP4LogCallback cb_func );
484 MP4V2_EXPORT
485 MP4LogLevel MP4LogGetLevel( void );
486 
492 MP4V2_EXPORT
493 void MP4LogSetLevel( MP4LogLevel verbosity );
494 
495 #endif /* MP4V2_GENERAL_H */
MP4AddTrackEdit
MP4EditId MP4AddTrackEdit(MP4FileHandle hFile, MP4TrackId trackId, MP4EditId editId=((MP4EditId) 0), MP4Timestamp startTime=0, MP4Duration duration=0, bool dwell=false)
MP4SetLogCallback
void MP4SetLogCallback(MP4LogCallback cb_func)
Set the function to call in place of default logging behavior.
MP4_INVALID_EDIT_ID
#define MP4_INVALID_EDIT_ID
Constant: invalid MP4EditId.
Definition: general.h:53
MP4GetTrackEditTotalDuration
MP4Duration MP4GetTrackEditTotalDuration(MP4FileHandle hFile, MP4TrackId trackId, MP4EditId editId=((MP4EditId) 0))
encryptFunc_t
uint32_t(* encryptFunc_t)(uint32_t, uint32_t, uint8_t *, uint32_t *, uint8_t **)
Encryption function pointer.
Definition: general.h:44
MP4ConvertFromTrackDuration
uint64_t MP4ConvertFromTrackDuration(MP4FileHandle hFile, MP4TrackId trackId, MP4Duration duration, uint32_t timeScale)
Convert duration from track time scale to an arbitrary time scale.
MP4ConvertToTrackDuration
MP4Duration MP4ConvertToTrackDuration(MP4FileHandle hFile, MP4TrackId trackId, uint64_t duration, uint32_t timeScale)
Convert duration from arbitrary time scale to track time scale.