From 9beef51a322095b6d31046bf87c44365c88e5745 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Sat, 28 Aug 2021 22:12:41 +0200 Subject: [PATCH] mp4: Doxify the public API. This adds doxygen comments to all public functions of the mp4 API and to the macros and enumerations of mp4.c. --- mp4.c | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---- mp4.h | 69 ++++++++++++++++++++++++--- 2 files changed, 203 insertions(+), 17 deletions(-) diff --git a/mp4.c b/mp4.c index 7145a47a..b6bab088 100644 --- a/mp4.c +++ b/mp4.c @@ -5,6 +5,15 @@ * See file COPYING. */ +/** \file mp4.c Paraslash's internal mp4 parser. */ + +/* + * This is a stripped down version of the former mp4ff library which used to be + * part of the faad decoder project but was removed from the faad code base in + * 2017. The original code has been cleaned up substantially and the public API + * has been documented. See the git commit log for details. + */ + #include #include "para.h" @@ -122,6 +131,7 @@ static int read_int16(struct mp4 *f, uint16_t *result) return ret; } +/** A macro defining the atoms we care about. It gets expanded twice. */ #define ATOM_ITEMS \ ATOM_ITEM(MOOV, 'm', 'o', 'o', 'v') \ ATOM_ITEM(TRAK, 't', 'r', 'a', 'k') \ @@ -145,13 +155,18 @@ static int read_int16(struct mp4 *f, uint16_t *result) ATOM_ITEM(META, 'm', 'e', 't', 'a') /* iTunes Metadata box */ \ ATOM_ITEM(DATA, 'd', 'a', 't', 'a') /* iTunes Metadata data box */ \ +/** For the C enumeration we concatenate ATOM_ with the first argument. */ #define ATOM_ITEM(_name, a, b, c, d) ATOM_ ## _name, +/** The enumeration of interesting atoms. */ enum atom {ATOM_ITEMS}; #undef ATOM_ITEM +/** A cpp version of read_u32_be(). */ +#define ATOM_VALUE(a, b, c, d) ((a << 24) + (b << 16) + (c << 8) + d) + static uint8_t atom_name_to_type(uint8_t *p) { - #define ATOM_VALUE(a, b, c, d) ((a << 24) + (b << 16) + (c << 8) + d) + /** Expands to an instance of the following unnamed structure. */ #define ATOM_ITEM(_name, a, b, c, d) \ {.name = # _name, .val = ATOM_VALUE(a, b, c, d)}, static const struct { @@ -566,6 +581,14 @@ static int parse_sub_atoms(struct mp4 *f, uint64_t total_size, bool meta_only) return 1; } +/** + * Deallocate all resources associated with an mp4 file handle. + * + * \param f File handle returned by \ref mp4_open() or \ref 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. + */ void mp4_close(struct mp4 *f) { free(f->track.stsz_table); @@ -620,6 +643,24 @@ fail: return ret; } +/** + * Read the audio track and the metadata of an mp4 file. + * + * \param cb Only the ->read() and ->seek() methods need to be supplied. + * \param 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. + * + * \return Standard. Several errors are possible. + * + * \sa \ref mp4_open_meta(). + */ int mp4_open(const struct mp4_callback *cb, struct mp4 **result) { struct mp4 *f; @@ -664,9 +705,12 @@ static int32_t chunk_of_sample(const struct mp4 *f, int32_t sample, } /** - * Return the number of milliseconds of the audio track. + * Compute the duration of an mp4 file. * - * \param f As returned by \ref mp4_open_read(), must not be NULL. + * \param f See \ref mp4_close(). + * + * \return The number of milliseconds of the audio track. This function never + * fails. */ uint64_t mp4_get_duration(const struct mp4 *f) { @@ -675,6 +719,17 @@ uint64_t mp4_get_duration(const struct mp4 *f) return t->duration * 1000 / t->time_scale; } +/** + * Reposition the read/write file offset. + * + * \param f See \ref mp4_close(). + * \param 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 \ref mp4_num_samples(). + * + * \return Standard. The only possible error is an invalid sample number. + */ int mp4_set_sample_position(struct mp4 *f, uint32_t sample) { const struct mp4_track *t = &f->track; @@ -700,6 +755,19 @@ int mp4_set_sample_position(struct mp4 *f, uint32_t sample) return 1; } +/** + * Look up and return the size of the given sample in the stsz table. + * + * \param f See \ref mp4_close(). + * \param sample The sample number of interest. + * \param result Sample size is returned here. + * + * For the sample argument the restriction mentioned in the documentation of + * \ref mp4_set_sample_position() applies as well. + * + * \return Standard. Like for \ref mp4_set_sample_position(), EINVAL is the + * only possible error. + */ int mp4_get_sample_size(const struct mp4 *f, uint32_t sample, uint32_t *result) { const struct mp4_track *t = &f->track; @@ -713,21 +781,65 @@ int mp4_get_sample_size(const struct mp4 *f, uint32_t sample, uint32_t *result) return 1; } +/** + * Return the sample rate stored in the stsd atom. + * + * \param f See \ref mp4_close(). + * + * The sample rate is a property of the audio track of the mp4 file and is thus + * independent of the sample number. + * + * \return 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. + */ uint16_t mp4_get_sample_rate(const struct mp4 *f) { return f->track.sample_rate; } +/** + * Return the number of channels of the audio track. + * + * \param f See \ref mp4_close(). + * + * \return 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. + */ uint16_t mp4_get_channel_count(const struct mp4 *f) { return f->track.channel_count; } +/** + * Return the number of samples of the audio track. + * + * \param f See \ref mp4_close(). + * + * \return The sample count is read from the stsz atom during open. + */ uint32_t mp4_num_samples(const struct mp4 *f) { return f->track.stsz_sample_count; } +/** + * Open an mp4 file in metadata-only mode. + * + * \param cb See \ref mp4_open(). + * \param result See \ref mp4_open(). + * + * This is similar to \ref 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 \ref mp4_get_meta() and \ref + * mp4_update_meta(). + * + * \return Standard. + * + * \sa \ref mp4_open(). The comment about ->write() and ->truncate() applies to + * this function as well. + */ int mp4_open_meta(const struct mp4_callback *cb, struct mp4 **result) { struct mp4 *f; @@ -742,10 +854,15 @@ int mp4_open_meta(const struct mp4_callback *cb, struct mp4 **result) /** * Return the metadata of an mp4 file. * - * \param f As returned by either \ref mp4_open_read() or \ref mp4_open_meta(). + * \param f See \ref mp4_close(). * * The caller is allowed to add, delete or modify the entries of the returned - * structure in order to pass the modified version to \ref mp4_meta_update(). + * structure with the intention to pass the modified version to \ref + * mp4_update_meta(). + * + * \return 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. */ struct mp4_metadata *mp4_get_meta(struct mp4 *f) { @@ -867,6 +984,20 @@ static int write_data(struct mp4 *f, void *data, size_t size) return 1; } +/** + * 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 \ref mp4_open() or \ref mp4_open_meta(). + * + * \param f See \ref mp4_close(). + * + * The modified metadata structure does not need to be supplied to this + * function because it is part of the mp4 structure. + * + * \return Standard. + */ int mp4_update_meta(struct mp4 *f) { void *new_moov_data; @@ -907,13 +1038,13 @@ free_moov: /** * Return the value of the given tag item. * - * \param f Must not be NULL. + * \param f See \ref mp4_close(). * \param item "artist", "title", "album", "comment", or "date". * - * \return The function always 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. + * \return 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. */ char *mp4_get_tag_value(const struct mp4 *f, const char *item) { diff --git a/mp4.h b/mp4.h index c6f53ebc..1618aa31 100644 --- a/mp4.h +++ b/mp4.h @@ -1,22 +1,77 @@ +/** \file mp4.h Public API of the mp4 parser. */ + +/** + * Callbacks provided by the user of the mp4 parsing API. + * + * A pointer to this structure is passed to the two public open functions. If + * the file is opened in read-only mode, the ->write() and ->truncate() methods + * won't be called and may thus be NULL. The ->read() and ->seek() methods + * must be supplied for either open type. + * + * All methods are supposed to work like their corresponding system calls. + * That is, they should return non-negative for success and -1 on failure. In + * the error case errno is expected to be set accordingly. + * + * \sa \ref mp4_open(), \ref mp4_open_meta(). + */ struct mp4_callback { + /** This pointer is propagated to each call of all methods. */ + void *user_data; + /** + * This should return the number of bytes read on success. Short reads + * are OK: the function may return less than length. + */ ssize_t (*read)(void *user_data, void *buffer, size_t length); - ssize_t (*write)(void *user_data, void *buffer, size_t count); + /** + * This method is assumed to succeed. The implementation should simply + * abort on errors. Note that offsets beyond EOF must not be regarded + * as invalid arguments. + */ off_t (*seek)(void *user_data, off_t offset, int whence); + /** + * Like the write() system call, this should return the number of bytes + * written. Short writes are OK: the function may return less than + * count. + */ + ssize_t (*write)(void *user_data, void *buffer, size_t count); + /** + * Unlike the truncate system call, this function does not receive an + * offset. The method is expected to truncate the file to the offset + * given by the current file position instead. + */ int (*truncate)(void *user_data); - void *user_data; }; +/** Specifies one metadata tag. Both fields are 0-terminated strings. */ struct mp4_tag { - char *item; - char *value; + /** The item name: "artist", "title", "album", "comment", or "date". */ + char *item; + /** An arbitrary string value. */ + char *value; }; +/** + * An array of name/value pairs. + * + * This structure is initialized when the mp4 file is opened in either mode. + * If the file contains metadata items other than the standard five, those + * non-standard items are not included in the array. After a successful open, a + * pointer to the metadata structure can be obtained via \ref mp4_get_meta(). + */ struct mp4_metadata { - struct mp4_tag *tags; - unsigned count; + /** It's OK to change this, for example by calling realloc(). */ + struct mp4_tag *tags; + /** The number of entries of the array. */ + unsigned count; }; -struct mp4; /* opaque */ +/** + * The mp4 file handle. + * + * A pointer to this opaque structure is returned by the two open functions. + * All other functions of the mp4 API receive a pointer of this type. + */ +struct mp4; int mp4_set_sample_position(struct mp4 *f, uint32_t sample); int mp4_open(const struct mp4_callback *cb, struct mp4 **result); -- 2.39.2