mp4.c File Reference

Paraslash's internal mp4 parser. More...

#include <regex.h>
#include "para.h"
#include "error.h"
#include "portable_io.h"
#include "string.h"
#include "mp4.h"

Macros
#define	ATOM_ITEMS
	A macro defining the atoms we care about. More...
#define	ATOM_ITEM(_name, a, b, c, d)   ATOM_ ## _name,
	For the C enumeration we concatenate ATOM_ with the first argument. More...
#define	ATOM_VALUE(a, b, c, d)   ((a << 24) + (b << 16) + (c << 8) + d)
	A cpp version of read_u32_be(). More...
#define	ATOM_ITEM(_name, a, b, c, d)    {.name = # _name, .val = ATOM_VALUE(a, b, c, d)},
	For the C enumeration we concatenate ATOM_ with the first argument. More...
#define	TAG_LEN(_len)   (24 + (_len))
	Total length of an on-disk metadata tag. More...

Enumerations
enum	audio_track_state { ATS_INITIAL, ATS_SEEN_MP4A, ATS_TRACK_CHANGE }
	The three states of the mp4 parser. More...
enum	atom {   ATOM_MOOV, ATOM_TRAK, ATOM_MDIA, ATOM_MINF,   ATOM_STBL, ATOM_UDTA, ATOM_ILST, ATOM_ARTIST,   ATOM_TITLE, ATOM_ALBUM, ATOM_DATE, ATOM_COMMENT,   ATOM_MDHD, ATOM_STSD, ATOM_STTS, ATOM_STSZ,   ATOM_STCO, ATOM_STSC, ATOM_MP4A, ATOM_META,   ATOM_DATA }
	The enumeration of interesting atoms. More...

Functions
void	mp4_close (struct mp4 *f)
	Deallocate all resources associated with an mp4 file handle. More...
int	mp4_open (const struct mp4_callback *cb, struct mp4 **result)
	Read the audio track and the metadata of an mp4 file. More...
uint64_t	mp4_get_duration (const struct mp4 *f)
	Compute the duration of an mp4 file. More...
int	mp4_set_sample_position (struct mp4 *f, uint32_t sample)
	Reposition the read/write file offset. 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...
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

Paraslash's internal mp4 parser.

Macro Definition Documentation

ATOM_ITEMS

#define ATOM_ITEMS

Value:

        ATOM_ITEM(MOOV, 'm', 'o', 'o', 'v') /* movie (top-level container) */ \
        ATOM_ITEM(TRAK, 't', 'r', 'a', 'k') /* container for a single track */ \
        ATOM_ITEM(MDIA, 'm', 'd', 'i', 'a') /* media information */ \
        ATOM_ITEM(MINF, 'm', 'i', 'n', 'f') /* extends mdia */ \
        ATOM_ITEM(STBL, 's', 't', 'b', 'l') /* sample table container */ \
        ATOM_ITEM(UDTA, 'u', 'd', 't', 'a') /* user data */ \
        ATOM_ITEM(ILST, 'i', 'l', 's', 't') /* iTunes Metadata list */ \
        ATOM_ITEM(ARTIST, 0xa9, 'A', 'R', 'T') /* artist */ \
        ATOM_ITEM(TITLE, 0xa9, 'n', 'a', 'm') /* title */ \
        ATOM_ITEM(ALBUM, 0xa9, 'a', 'l', 'b') /* album */ \
        ATOM_ITEM(DATE, 0xa9, 'd', 'a', 'y') /* date */ \
        ATOM_ITEM(COMMENT, 0xa9, 'c', 'm', 't') /* comment */ \
        ATOM_ITEM(MDHD, 'm', 'd', 'h', 'd') /* track header */ \
        ATOM_ITEM(STSD, 's', 't', 's', 'd') /* sample description box */ \
        ATOM_ITEM(STTS, 's', 't', 't', 's') /* time to sample box */ \
        ATOM_ITEM(STSZ, 's', 't', 's', 'z') /* sample size box */ \
        ATOM_ITEM(STCO, 's', 't', 'c', 'o') /* chunk offset box */ \
        ATOM_ITEM(STSC, 's', 't', 's', 'c') /* sample to chunk box */ \
        ATOM_ITEM(MP4A, 'm', 'p', '4', 'a') /* mp4 audio */ \
        ATOM_ITEM(META, 'm', 'e', 't', 'a') /* iTunes Metadata box */ \
        ATOM_ITEM(DATA, 'd', 'a', 't', 'a') /* iTunes Metadata data box */ \

A macro defining the atoms we care about.

It gets expanded twice.

ATOM_ITEM [1/2]

#define ATOM_ITEM	(		_name,
			a,
			b,
			c,
			d
	)		ATOM_ ## _name,

For the C enumeration we concatenate ATOM_ with the first argument.

ATOM_VALUE

#define ATOM_VALUE	(		a,
			b,
			c,
			d
	)		((a << 24) + (b << 16) + (c << 8) + d)

A cpp version of read_u32_be().

ATOM_ITEM [2/2]

#define ATOM_ITEM	(		_name,
			a,
			b,
			c,
			d
	)		{.name = # _name, .val = ATOM_VALUE(a, b, c, d)},

For the C enumeration we concatenate ATOM_ with the first argument.

TAG_LEN

#define TAG_LEN

(

_len

)

(24 + (_len))

Total length of an on-disk metadata tag.

Enumeration Type Documentation

audio_track_state

enum audio_track_state

The three states of the mp4 parser.

The parser only loads the audio specific values and tables when it is in the second state.

Enumerator
ATS_INITIAL	We haven't encountered an mp4a atom so far.
ATS_SEEN_MP4A	We have seen an mp4a atom but no subsequent trak atom yet.
ATS_TRACK_CHANGE	A trak atom was seen after the mp4a atom.

atom

enum atom

The enumeration of interesting atoms.

Enumerator
ATOM_MOOV
ATOM_TRAK
ATOM_MDIA
ATOM_MINF
ATOM_STBL
ATOM_UDTA
ATOM_ILST
ATOM_ARTIST
ATOM_TITLE
ATOM_ALBUM
ATOM_DATE
ATOM_COMMENT
ATOM_MDHD
ATOM_STSD
ATOM_STTS
ATOM_STSZ
ATOM_STCO
ATOM_STSC
ATOM_MP4A
ATOM_META
ATOM_DATA

Function Documentation

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_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_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_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_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_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().