mp4.h File Reference

Public API of the mp4 parser. More...

Data Structures
struct	mp4_callback
	Callbacks provided by the user of the mp4 parsing API. More...
struct	mp4_tag
	Specifies one metadata tag. More...
struct	mp4_metadata
	An array of name/value pairs. More...

Functions
int	mp4_set_sample_position (struct mp4 *f, uint32_t sample)
	Reposition the read/write file offset. More...
int	mp4_open (const struct mp4_callback *cb, struct mp4 **result)
	Read the audio track and the metadata of an mp4 file. More...
void	mp4_close (struct mp4 *f)
	Deallocate all resources associated with an mp4 file handle. More...
int	mp4_get_sample_size (const struct mp4 *f, uint32_t sample, uint32_t *result)
	Look up and return the size of the given sample in the stsz table. More...
uint16_t	mp4_get_sample_rate (const struct mp4 *f)
	Return the sample rate stored in the stsd atom. More...
uint16_t	mp4_get_channel_count (const struct mp4 *f)
	Return the number of channels of the audio track. More...
uint32_t	mp4_num_samples (const struct mp4 *f)
	Return the number of samples of the audio track. More...
uint64_t	mp4_get_duration (const struct mp4 *f)
	Compute the duration of an mp4 file. More...
int	mp4_open_meta (const struct mp4_callback *cb, struct mp4 **result)
	Open an mp4 file in metadata-only mode. More...
struct mp4_metadata *	mp4_get_meta (struct mp4 *f)
	Return the metadata of an mp4 file. More...
int	mp4_update_meta (struct mp4 *f)
	Write back the modified metadata items to the mp4 file. More...
__malloc char *	mp4_get_tag_value (const struct mp4 *f, const char *item)
	Return the value of the given tag item. More...

Detailed Description

Public API of the mp4 parser.

Function Documentation

mp4_set_sample_position()

int mp4_set_sample_position	(	struct mp4 *	f,
		uint32_t	sample
	)

Reposition the read/write file offset.

Parameters

f	See mp4_close().
sample	The number of the sample to reposition to.

The given sample number must be within range, i.e., strictly less than the value returned by mp4_num_samples().

Returns

Standard. The only possible error is an invalid sample number.

References ERRNO_TO_PARA_ERROR.

mp4_open()

int mp4_open	(	const struct mp4_callback *	cb,
		struct mp4 **	result
	)

Read the audio track and the metadata of an mp4 file.

Parameters

cb	Only the ->read() and ->seek() methods need to be supplied.
result	Initialized to a non-NULL pointer iff the function succeeds.

This detects and parses the first audio track and the metadata information of the mp4 file. Various error checks are performed after the mp4 atoms have been parsed successfully.

This function does not modify the file. However, if the caller intents to update the metadata later, the ->write() and ->truncate() methods must be supplied in the callback structure.

Returns

Standard. Several errors are possible.

See also

mp4_open_meta().

mp4_close()

void mp4_close

(

struct mp4 *

f

)

Deallocate all resources associated with an mp4 file handle.

Parameters

f	File handle returned by mp4_open() or mp4_open_meta().

This frees the metadata items and various tables which were allocated when the file was opened. The given file handle must not be NULL.

mp4_get_sample_size()

int mp4_get_sample_size	(	const struct mp4 *	f,
		uint32_t	sample,
		uint32_t *	result
	)

Look up and return the size of the given sample in the stsz table.

Parameters

f	See mp4_close().
sample	The sample number of interest.
result	Sample size is returned here.

For the sample argument the restriction mentioned in the documentation of mp4_set_sample_position() applies as well.

Returns

Standard. Like for mp4_set_sample_position(), EINVAL is the only possible error.

References ERRNO_TO_PARA_ERROR.

mp4_get_sample_rate()

uint16_t mp4_get_sample_rate

(

const struct mp4 *

f

)

Return the sample rate stored in the stsd atom.

Parameters

f	See mp4_close().

The sample rate is a property of the audio track of the mp4 file and is thus independent of the sample number.

Returns

The function always returns a positive value because the open operation fails if the sample rate happens to be zero. A typical value is 44100.

mp4_get_channel_count()

uint16_t mp4_get_channel_count

(

const struct mp4 *

f

)

Return the number of channels of the audio track.

Parameters

f	See mp4_close().

Returns

The returned channel count is guaranteed to be positive because the open operation fails if the mp4a atom is missing or contains a zero channel count.

mp4_num_samples()

uint32_t mp4_num_samples

(

const struct mp4 *

f

)

Return the number of samples of the audio track.

Parameters

f	See mp4_close().

Returns

The sample count is read from the stsz atom during open.

mp4_get_duration()

uint64_t mp4_get_duration

(

const struct mp4 *

f

)

Compute the duration of an mp4 file.

Parameters

f	See mp4_close().

Returns

The number of milliseconds of the audio track. This function never fails.

mp4_open_meta()

int mp4_open_meta	(	const struct mp4_callback *	cb,
		struct mp4 **	result
	)

Open an mp4 file in metadata-only mode.

Parameters

cb	See mp4_open().
result	See mp4_open().

This is similar to mp4_open() but is cheaper because it only parses the metadata of the mp4 file. The only functions that can subsequently be called with the file handle returned here are mp4_get_meta() and mp4_update_meta().

Returns

Standard.

See also

mp4_open(). The comment about ->write() and ->truncate() applies to this function as well.

mp4_get_meta()

struct mp4_metadata* mp4_get_meta

(

struct mp4 *

f

)

Return the metadata of an mp4 file.

Parameters

f	See mp4_close().

The caller is allowed to add, delete or modify the entries of the returned structure with the intention to pass the modified version to mp4_update_meta().

Returns

This never returns NULL, even if the file contains no metadata tag items. However, the meta count will be zero and the ->tags pointer NULL in this case.

mp4_update_meta()

int mp4_update_meta

(

struct mp4 *

f

)

Write back the modified metadata items to the mp4 file.

This is the only public function which modifies the contents of an mp4 file. This is achieved by calling the ->write() and ->truncate() methods of the callback structure passed to mp4_open() or mp4_open_meta().

Parameters

f	See mp4_close().

The modified metadata structure does not need to be supplied to this function because it is part of the mp4 structure.

Returns

Standard.

mp4_get_tag_value()

__malloc char* mp4_get_tag_value	(	const struct mp4 *	f,
		const char *	item
	)

Return the value of the given tag item.

Parameters

f	See mp4_close().
item	"artist", "title", "album", "comment", or "date".

Returns

The function returns NULL if the given item is not in the above list. Otherwise, if the file does not contain a tag for the given item, the function also returns NULL. Otherwise a copy of the tag value is returned and the caller should free this memory when it is no longer needed.

References mp4_tag::item, and para_strdup().