1 #ifndef MP4V2_TRACK_H
2 #define MP4V2_TRACK_H
3 
4 /**************************************************************************//**
5  *
6  *  @defgroup mp4_track MP4v2 Track
7  *  @{
8  *
9  *****************************************************************************/
10 
11 /** Add a user defined track.
12  *
13  *  MP4AddTrack adds a user defined track to the mp4 file. Care should be
14  *  taken to avoid any of the standardized track type names. A useful
15  *  convention is use only uppercase characters for user defined track types.
16  *  The string should be exactly four characters in length, e.g. "MINE".
17  *
18  *  Note this should not be used to add any of the known track types defined
19  *  in the MP4 standard (ISO/IEC 14496-1:2001).
20  *
21  *  @param hFile handle of file for operation.
22  *  @param type specifies the type of track to be added.
23  *  @param timeScale the time scale in ticks per second of the track.  Default is 1000.
24  *
25  *  @return On success, the track-id of new track.
26  *      On failure, #MP4_INVALID_TRACK_ID.
27  */
28 MP4V2_EXPORT
29 MP4TrackId MP4AddTrack(
30     MP4FileHandle hFile,
31     const char*   type,
32     uint32_t      timeScale DEFAULT(MP4_MSECS_TIME_SCALE) );
33 
34 /** Add an MPEG-4 systems track.
35  *
36  *  MP4AddSystemsTrack adds an MPEG-4 Systems track to the mp4 file. Note
37  *  this should not be used to add OD or scene tracks, MP4AddODTrack() and
38  *  MP4AddSceneTrack() should be used for those purposes. Other known
39  *  MPEG-4 System track types are:
40  *      @li #MP4_CLOCK_TRACK_TYPE
41  *      @li #MP4_MPEG7_TRACK_TYPE
42  *      @li #MP4_OCI_TRACK_TYPE
43  *      @li #MP4_IPMP_TRACK_TYPE
44  *      @li #MP4_MPEGJ_TRACK_TYPE
45  *
46  *  @param hFile handle of file for operation.
47  *  @param type specifies the type of track to be added.
48  *
49  *  @return On success, the track-id of new track.
50  *      On failure, #MP4_INVALID_TRACK_ID.
51  */
52 MP4V2_EXPORT
53 MP4TrackId MP4AddSystemsTrack(
54     MP4FileHandle hFile,
55     const char*   type );
56 
57 /** Add a object descriptor (OD) track.
58  *
59  *  MP4AddODTrack adds an object descriptor (aka OD) track to the mp4 file.
60  *  MP4WriteSample() can then be used to add the desired OD commands to the
61  *  track. The burden is currently on the calling application to understand
62  *  OD.
63  *
64  *  Those wishing to have a simple audio/video scene without understanding
65  *  OD may wish to use MP4MakeIsmaCompliant() to create the minimal OD and
66  *  BIFS information.
67  *
68  *  @param hFile handle of file for operation.
69  *
70  *  @return On success, the track-id of new track.
71  *      On failure, #MP4_INVALID_TRACK_ID.
72  */
73 MP4V2_EXPORT
74 MP4TrackId MP4AddODTrack(
75     MP4FileHandle hFile );
76 
77 /** Add a scene (BIFS) track.
78  *
79  *  MP4AddSceneTrack adds a scene (aka BIFS) track to the mp4 file.
80  *  MP4WriteSample() can then be used to add the desired BIFS commands to
81  *  the track. The burden is currently on the calling application to
82  *  understand BIFS.
83  *
84  *  Those  wishing to have a simple audio/video scene without understanding
85  *  BIFS may wish to use MP4MakeIsmaCompliant() to create the minimal OD
86  *  and BIFS information.
87  *
88  *  @param hFile handle of file for operation.
89  *
90  *  @return On success, the track-id of new track.
91  *      On failure, #MP4_INVALID_TRACK_ID.
92  */
93 MP4V2_EXPORT
94 MP4TrackId MP4AddSceneTrack(
95     MP4FileHandle hFile );
96 
97 /** Add audio track to mp4 file.
98  *
99  *  MP4AddAudioTrack adds an audio track to the mp4 file. MP4WriteSample()
100  *  can then be used to add the desired audio samples.
101  *
102  *  It is recommended that the time scale be set to the sampling frequency
103  *  (eg. 44100 Hz) of the audio so as to preserve the timing information
104  *  accurately.
105  *
106  *  If the audio encoding uses a fixed duration for each sample that should
107  *  be specified here. If not then the value #MP4_INVALID_DURATION
108  *  should be given for the sampleDuration argument.
109  *
110  *  @param hFile handle of file for operation.
111  *  @param timeScale the time scale in ticks per second of the track.
112  *  @param sampleDuration the fixed  duration for all track samples.
113  *      Caveat: the value should be in track-timescale units.
114  *  @param audioType the audio encoding type.
115  *      See MP4GetTrackEsdsObjectTypeId() for known values.
116  *
117  *  @return On success, the track-id of the new track.
118  *      On error, #MP4_INVALID_TRACK_ID.
119  */
120 MP4V2_EXPORT
121 MP4TrackId MP4AddAudioTrack(
122     MP4FileHandle hFile,
123     uint32_t      timeScale,
124     MP4Duration   sampleDuration,
125     uint8_t       audioType DEFAULT(MP4_MPEG4_AUDIO_TYPE) );
126 
127 /** Add ulaw track to mp4 file.
128  *
129  *  MP4AddULawAudioTrack adds a ulaw track to the mp4 file. MP4WriteSample()
130  *  can then be used to add the desired audio samples.
131  *
132  *  @param hFile handle of file for operation.
133  *  @param timeScale the time scale in ticks per second of the track.
134  *
135  *  @return On success, the track-id of the new track.
136  *      On error, #MP4_INVALID_TRACK_ID.
137 */
138 MP4V2_EXPORT
139 MP4TrackId MP4AddULawAudioTrack(
140     MP4FileHandle hFile,
141     uint32_t timeScale);
142 
143 /** Add alaw track to mp4 file.
144  *
145  *  MP4AddALawAudioTrack adds a alaw track to the mp4 file. MP4WriteSample()
146  *  can then be used to add the desired audio samples.
147  *
148  *  @param hFile handle of file for operation.
149  *  @param timeScale the time scale in ticks per second of the track.
150  *
151  *  @return On success, the track-id of the new track.
152  *      On error, #MP4_INVALID_TRACK_ID.
153 */
154 MP4V2_EXPORT
155 MP4TrackId MP4AddALawAudioTrack(
156     MP4FileHandle hFile,
157     uint32_t timeScale);
158 
159 MP4V2_EXPORT
160 MP4TrackId MP4AddAC3AudioTrack(
161     MP4FileHandle hFile,
162     uint32_t      samplingRate,
163     uint8_t       fscod,
164     uint8_t       bsid,
165     uint8_t       bsmod,
166     uint8_t       acmod,
167     uint8_t       lfeon,
168     uint8_t       bit_rate_code );
169 
170 MP4V2_EXPORT
171 MP4TrackId MP4AddAmrAudioTrack(
172     MP4FileHandle hFile,
173     uint32_t      timeScale,
174     uint16_t      modeSet,
175     uint8_t       modeChangePeriod,
176     uint8_t       framesPerSample,
177     bool          isAmrWB );
178 
179 MP4V2_EXPORT
180 void MP4SetAmrVendor(
181     MP4FileHandle hFile,
182     MP4TrackId    trackId,
183     uint32_t      vendor );
184 
185 MP4V2_EXPORT
186 void MP4SetAmrDecoderVersion(
187     MP4FileHandle hFile,
188     MP4TrackId    trackId,
189     uint8_t       decoderVersion );
190 
191 MP4V2_EXPORT
192 void MP4SetAmrModeSet(
193     MP4FileHandle hFile,
194     MP4TrackId    trakId,
195     uint16_t      modeSet );
196 
197 MP4V2_EXPORT
198 uint16_t MP4GetAmrModeSet(
199     MP4FileHandle hFile,
200     MP4TrackId    trackId );
201 
202 MP4V2_EXPORT
203 MP4TrackId MP4AddHrefTrack(
204     MP4FileHandle hFile,
205     uint32_t      timeScale,
206     MP4Duration   sampleDuration,
207     const char*   base_url DEFAULT(NULL) );
208 
209 MP4V2_EXPORT
210 const char* MP4GetHrefTrackBaseUrl(
211     MP4FileHandle hFile,
212     MP4TrackId    trackId );
213 
214 /** Add a video track.
215  *
216  *  MP4AddVideoTrack adds a video track to the mp4 file. MP4WriteSample()
217  *  can then be used to add the desired video samples.
218  *
219  *  It is recommended that the time scale be set to 90000 so as to preserve
220  *  the timing information accurately for the range of video frame rates
221  *  commonly in use.
222  *
223  *  If the video frame rate is to be fixed then the sampleDuration argument
224  *  should be give the appropriate fixed value. If the video frame rate is
225  *  to be variable then the value #MP4_INVALID_DURATION should be
226  *  given for the sampleDuration argument.
227  *
228  *  @param hFile handle of file for operation.
229  *  @param timeScale the timescale in ticks per second of the track.
230  *  @param sampleDuration specifies fixed sample duration for all track
231  *      samples. Caveat: the value should be in track timescale units.
232  *  @param width specifies the video frame width in pixels.
233  *  @param height specifies the video frame height in pixels.
234  *  @param videoType specifies the video encoding type.
235  *      See MP4GetTrackVideoType() for known values.
236  *
237  *  @return On success, the track-id of the new track.
238  *      On error, #MP4_INVALID_TRACK_ID.
239  */
240 MP4V2_EXPORT
241 MP4TrackId MP4AddVideoTrack(
242     MP4FileHandle hFile,
243     uint32_t      timeScale,
244     MP4Duration   sampleDuration,
245     uint16_t      width,
246     uint16_t      height,
247     uint8_t       videoType DEFAULT(MP4_MPEG4_VIDEO_TYPE) );
248 
249 MP4V2_EXPORT
250 MP4TrackId MP4AddH264VideoTrack(
251     MP4FileHandle hFile,
252     uint32_t      timeScale,
253     MP4Duration   sampleDuration,
254     uint16_t      width,
255     uint16_t      height,
256     uint8_t       AVCProfileIndication,
257     uint8_t       profile_compat,
258     uint8_t       AVCLevelIndication,
259     uint8_t       sampleLenFieldSizeMinusOne );
260 
261 MP4V2_EXPORT
262 void MP4AddH264SequenceParameterSet(
263     MP4FileHandle  hFile,
264     MP4TrackId     trackId,
265     const uint8_t* pSequence,
266     uint16_t       sequenceLen );
267 
268 MP4V2_EXPORT
269 void MP4AddH264PictureParameterSet(
270     MP4FileHandle  hFile,
271     MP4TrackId     trackId,
272     const uint8_t* pPict,
273     uint16_t       pictLen );
274 
275 MP4V2_EXPORT
276 void MP4SetH263Vendor(
277     MP4FileHandle hFile,
278     MP4TrackId    trackId,
279     uint32_t      vendor );
280 
281 MP4V2_EXPORT
282 void MP4SetH263DecoderVersion(
283     MP4FileHandle hFile,
284     MP4TrackId    trackId,
285     uint8_t       decoderVersion );
286 
287 MP4V2_EXPORT
288 void MP4SetH263Bitrates(
289     MP4FileHandle hFile,
290     MP4TrackId    trackId,
291     uint32_t      avgBitrate,
292     uint32_t      maxBitrate );
293 
294 MP4V2_EXPORT
295 MP4TrackId MP4AddH263VideoTrack(
296     MP4FileHandle hFile,
297     uint32_t      timeScale,
298     MP4Duration   sampleDuration,
299     uint16_t      width,
300     uint16_t      height,
301     uint8_t       h263Level,
302     uint8_t       h263Profile,
303     uint32_t      avgBitrate,
304     uint32_t      maxBitrate );
305 
306 /** Add a hint track.
307  *
308  *  MP4AddHintTrack adds a hint track to the mp4 file. A hint track is used
309  *  to describe how to send the reference media track over a particular
310  *  network transport. In the case of the IETF RTP protocol, the hint track
311  *  describes how the media data should be placed into packets and any
312  *  media specific protocol headers that should be added.
313  *
314  *  Typically there is a one to one correspondence between reference  media
315  *  track  samples  and  hint track samples. The start time, duration, and
316  *  sync flags are typically the same, however provisions are made for
317  *  deviations from this rule.
318  *
319  *  The MP4 library provides extensive support for RTP hint tracks. This
320  *  includes a easy to use API to create RTP hint tracks, and read out
321  *  fully constructed RTP packets based on the hint track.
322  *
323  *  @param hFile handle of file for operation.
324  *  @param refTrackId specifies the reference media track for this hint track.
325  *
326  *  @return On success, the track-id of the new track.
327  *      On error, #MP4_INVALID_TRACK_ID.
328  */
329 MP4V2_EXPORT
330 MP4TrackId MP4AddHintTrack(
331     MP4FileHandle hFile,
332     MP4TrackId    refTrackId );
333 
334 MP4V2_EXPORT
335 MP4TrackId MP4AddTextTrack(
336     MP4FileHandle hFile,
337     MP4TrackId    refTrackId );
338 
339 MP4V2_EXPORT
340 MP4TrackId MP4AddSubtitleTrack(
341     MP4FileHandle hFile,
342     uint32_t      timescale,
343     uint16_t      width,
344     uint16_t      height );
345 
346 MP4V2_EXPORT
347 MP4TrackId MP4AddSubpicTrack(
348     MP4FileHandle hFile,
349     uint32_t      timescale,
350     uint16_t      width,
351     uint16_t      height );
352 
353 MP4V2_EXPORT
354 MP4TrackId MP4AddPixelAspectRatio(
355     MP4FileHandle hFile,
356     MP4TrackId    refTrackId,
357     uint32_t      hSpacing,
358     uint32_t      vSpacing );
359 
360 MP4V2_EXPORT
361 MP4TrackId MP4AddColr(
362     MP4FileHandle hFile,
363     MP4TrackId    refTrackId,
364     uint16_t      primary,
365     uint16_t      transfer,
366     uint16_t      matrix );
367 
368 MP4V2_EXPORT
369 MP4TrackId MP4CloneTrack(
370     MP4FileHandle srcFile,
371     MP4TrackId    srcTrackId,
372     MP4FileHandle dstFile DEFAULT(MP4_INVALID_FILE_HANDLE),
373     MP4TrackId    dstHintTrackReferenceTrack DEFAULT(MP4_INVALID_TRACK_ID) );
374 
375 MP4V2_EXPORT
376 MP4TrackId MP4CopyTrack(
377     MP4FileHandle srcFile,
378     MP4TrackId    srcTrackId,
379     MP4FileHandle dstFile DEFAULT(MP4_INVALID_FILE_HANDLE),
380     bool          applyEdits DEFAULT(false),
381     MP4TrackId    dstHintTrackReferenceTrack DEFAULT(MP4_INVALID_TRACK_ID) );
382 
383 MP4V2_EXPORT
384 bool MP4DeleteTrack(
385     MP4FileHandle hFile,
386     MP4TrackId    trackId );
387 
388 MP4V2_EXPORT
389 uint32_t MP4GetNumberOfTracks(
390     MP4FileHandle hFile,
391     const char*   type DEFAULT(NULL),
392     uint8_t       subType DEFAULT(0) );
393 
394 MP4V2_EXPORT
395 MP4TrackId MP4FindTrackId(
396     MP4FileHandle hFile,
397     uint16_t      index,
398     const char*   type DEFAULT(NULL),
399     uint8_t       subType DEFAULT(0) );
400 
401 MP4V2_EXPORT
402 uint16_t MP4FindTrackIndex(
403     MP4FileHandle hFile,
404     MP4TrackId    trackId );
405 
406 /** Get maximum duration of chunk.
407  *
408  *  MP4GetTrackDurationPerChunk gets the maximum duration for each chunk.
409  *
410  *  @param hFile handle of file for operation.
411  *  @param trackId id of track for operation.
412  *  @param duration out value of duration in track timescale units.
413  *
414  *  return <b>true</b> on success, <b>false</b> on failure.
415  */
416 MP4V2_EXPORT
417 bool MP4GetTrackDurationPerChunk(
418     MP4FileHandle hFile,
419     MP4TrackId    trackId,
420     MP4Duration*  duration );
421 
422 /** Set maximum duration of chunk.
423  *
424  *  MP4SetTrackDurationPerChunk sets the maximum duration for each chunk.
425  *
426  *  @param hFile handle of file for operation.
427  *  @param trackId id of track for operation.
428  *  @param duration in timescale units.
429  *
430  *  @return <b>true</b> on success, <b>false</b> on failure.
431  */
432 MP4V2_EXPORT
433 bool MP4SetTrackDurationPerChunk(
434     MP4FileHandle hFile,
435     MP4TrackId    trackId,
436     MP4Duration   duration );
437 
438 /**
439  *  @param hFile handle of file for operation.
440  *  @param trackId id of track for operation.
441  *
442  *  @return <b>true</b> on success, <b>false</b> on failure.
443  */
444 MP4V2_EXPORT
445 bool MP4AddIPodUUID(
446     MP4FileHandle hFile,
447     MP4TrackId    trackId );
448 
449 /** @} ***********************************************************************/
450 
451 #endif /* MP4V2_TRACK_H */
452