]> git.tuebingen.mpg.de Git - paraslash.git/blobdiff - mp4.c
paraslash 0.7.3
[paraslash.git] / mp4.c
diff --git a/mp4.c b/mp4.c
index 3963f7830fcb67e9eb2a8ec0aa7cab43779f9693..5ca1307f680d366c155b2e98257ba807c5a4fb92 100644 (file)
--- 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 <regex.h>
 
 #include "para.h"
@@ -75,8 +84,8 @@ struct mp4 {
 };
 
 /*
- * Returns -1, 0, or 1 on errors/EOF/success. Partial reads followed by EOF or
- * read errors are treated as errors.
+ * Returns -E_MP4_READ, 0, or 1 on errors/EOF/success. Partial reads followed
+ * by EOF or read errors are treated as errors.
  */
 static int read_data(struct mp4 *f, void *data, size_t size)
 {
@@ -86,7 +95,7 @@ static int read_data(struct mp4 *f, void *data, size_t size)
                        continue;
                /* regard EAGAIN as an error as reads should be blocking. */
                if (ret <= 0)
-                       return ret < 0? -1 : 0;
+                       return ret < 0? -E_MP4_READ : 0;
                size -= ret;
        }
        return 1;
@@ -122,36 +131,42 @@ 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') \
-       ATOM_ITEM(MDIA, 'm', 'd', 'i', 'a') \
-       ATOM_ITEM(MINF, 'm', 'i', 'n', 'f') \
-       ATOM_ITEM(STBL, 's', 't', 'b', 'l') \
-       ATOM_ITEM(UDTA, 'u', 'd', 't', 'a') \
+       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') \
-       ATOM_ITEM(TITLE, 0xa9, 'n', 'a', 'm') \
-       ATOM_ITEM(ALBUM, 0xa9, 'a', 'l', 'b') \
-       ATOM_ITEM(DATE, 0xa9, 'd', 'a', 'y') \
-       ATOM_ITEM(COMMENT, 0xa9, 'c', 'm', 't') \
+       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') \
+       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 */ \
 
+/** 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 {
@@ -188,8 +203,7 @@ static int atom_read_header(struct mp4 *f, uint8_t *atom_type,
        } else {
                if (header_size)
                        *header_size = 8;
-               if (atom_size)
-                       *atom_size = size;
+               *atom_size = size;
        }
        *atom_type = atom_name_to_type(atom_header + 4);
        return 1;
@@ -213,7 +227,6 @@ static void skip_bytes(struct mp4 *f, off_t num_skip)
 static int read_stsz(struct mp4 *f)
 {
        int ret;
-       int32_t i;
        struct mp4_track *t = &f->track;
 
        if (t->state != ATS_SEEN_MP4A || t->stsz_table)
@@ -227,9 +240,9 @@ static int read_stsz(struct mp4 *f)
                return ret;
        if (t->stsz_sample_size != 0)
                return 1;
-       t->stsz_table = para_malloc(t->stsz_sample_count * sizeof(int32_t));
-       for (i = 0; i < t->stsz_sample_count; i++) {
-               ret = read_int32(f, &t->stsz_table[i]);
+       t->stsz_table = arr_alloc(t->stsz_sample_count, sizeof(int32_t));
+       for (uint32_t n = 0; n < t->stsz_sample_count; n++) {
+               ret = read_int32(f, &t->stsz_table[n]);
                if (ret <= 0)
                        return ret;
        }
@@ -239,7 +252,6 @@ static int read_stsz(struct mp4 *f)
 static int read_stts(struct mp4 *f)
 {
        int ret;
-       int32_t i;
        struct mp4_track *t = &f->track;
 
        if (t->state != ATS_SEEN_MP4A || t->stts_sample_count)
@@ -248,10 +260,9 @@ static int read_stts(struct mp4 *f)
        ret = read_int32(f, &t->stts_entry_count);
        if (ret <= 0)
                return ret;
-       t->stts_sample_count = para_malloc(t->stts_entry_count
-               * sizeof(int32_t));
-       for (i = 0; i < t->stts_entry_count; i++) {
-               ret = read_int32(f, &t->stts_sample_count[i]);
+       t->stts_sample_count = arr_alloc(t->stts_entry_count, sizeof(int32_t));
+       for (uint32_t n = 0; n < t->stts_entry_count; n++) {
+               ret = read_int32(f, &t->stts_sample_count[n]);
                if (ret <= 0)
                        return ret;
                skip_bytes(f, 4); /* sample delta */
@@ -262,7 +273,6 @@ static int read_stts(struct mp4 *f)
 static int read_stsc(struct mp4 *f)
 {
        int ret;
-       int32_t i;
        struct mp4_track *t = &f->track;
 
        if (t->state != ATS_SEEN_MP4A)
@@ -273,14 +283,14 @@ static int read_stsc(struct mp4 *f)
        ret = read_int32(f, &t->stsc_entry_count);
        if (ret <= 0)
                return ret;
-       t->stsc_first_chunk = para_malloc(t->stsc_entry_count * sizeof(int32_t));
-       t->stsc_samples_per_chunk = para_malloc(t->stsc_entry_count
-               sizeof (int32_t));
-       for (i = 0; i < t->stsc_entry_count; i++) {
-               ret = read_int32(f, &t->stsc_first_chunk[i]);
+       t->stsc_first_chunk = arr_alloc(t->stsc_entry_count, sizeof(int32_t));
+       t->stsc_samples_per_chunk = arr_alloc(t->stsc_entry_count,
+               sizeof (int32_t));
+       for (uint32_t n = 0; n < t->stsc_entry_count; n++) {
+               ret = read_int32(f, &t->stsc_first_chunk[n]);
                if (ret <= 0)
                        return ret;
-               ret = read_int32(f, &t->stsc_samples_per_chunk[i]);
+               ret = read_int32(f, &t->stsc_samples_per_chunk[n]);
                if (ret <= 0)
                        return ret;
                skip_bytes(f, 4); /* sample desc index */
@@ -291,7 +301,6 @@ static int read_stsc(struct mp4 *f)
 static int read_stco(struct mp4 *f)
 {
        int ret;
-       int32_t i;
        struct mp4_track *t = &f->track;
 
        if (t->state != ATS_SEEN_MP4A || t->stco_chunk_offset)
@@ -300,10 +309,9 @@ static int read_stco(struct mp4 *f)
        ret = read_int32(f, &t->stco_entry_count);
        if (ret <= 0)
                return ret;
-       t->stco_chunk_offset = para_malloc(t->stco_entry_count
-               * sizeof(int32_t));
-       for (i = 0; i < t->stco_entry_count; i++) {
-               ret = read_int32(f, &t->stco_chunk_offset[i]);
+       t->stco_chunk_offset = arr_alloc(t->stco_entry_count, sizeof(int32_t));
+       for (uint32_t n = 0; n < t->stco_entry_count; n++) {
+               ret = read_int32(f, &t->stco_chunk_offset[n]);
                if (ret <= 0)
                        return ret;
        }
@@ -313,7 +321,7 @@ static int read_stco(struct mp4 *f)
 static int read_stsd(struct mp4 *f)
 {
        int ret;
-       uint32_t i, entry_count;
+       uint32_t entry_count;
 
        if (f->track.state != ATS_INITIAL)
                return 1;
@@ -321,7 +329,7 @@ static int read_stsd(struct mp4 *f)
        ret = read_int32(f, &entry_count);
        if (ret <= 0)
                return ret;
-       for (i = 0; i < entry_count; i++) {
+       for (uint32_t n = 0; n < entry_count; n++) {
                uint64_t skip = get_position(f);
                uint64_t size;
                uint8_t atom_type = 0;
@@ -381,25 +389,24 @@ static int parse_tag(struct mp4 *f, uint8_t parent, int32_t size)
                if (atom_type != ATOM_DATA)
                        continue;
                skip_bytes(f, 8); /* version (1), flags (3), reserved (4) */
-               ret = -ERRNO_TO_PARA_ERROR(EINVAL);
+               ret = -E_MP4_CORRUPT;
                if (subsize < header_size + 8 || subsize > UINT_MAX)
                        goto fail;
                len = subsize - (header_size + 8);
                free(value);
-               value = para_malloc(len + 1);
+               value = alloc(len + 1);
                ret = read_data(f, value, len);
                if (ret <= 0)
                        goto fail;
                value[len] = '\0';
        }
        if (!value)
-               return -ERRNO_TO_PARA_ERROR(EINVAL);
+               return -E_MP4_CORRUPT;
        f->meta.tags = para_realloc(f->meta.tags, (f->meta.count + 1)
                * sizeof(struct mp4_tag));
        tag = f->meta.tags + f->meta.count;
        tag->item = para_strdup(get_metadata_name(parent));
        tag->value = value;
-       tag->len = len;
        f->meta.count++;
        return 1;
 fail:
@@ -426,7 +433,7 @@ static int read_mdhd(struct mp4 *f)
                ret = read_int64(f, &t->duration);
                if (ret <= 0)
                        return ret;
-       } else { //version == 0
+       } else { /* version == 0 */
                uint32_t temp;
 
                skip_bytes(f, 8); /* creation time (4), modification time (4) */
@@ -443,7 +450,7 @@ static int read_mdhd(struct mp4 *f)
        return 1;
 }
 
-static int32_t read_ilst(struct mp4 *f, int32_t size)
+static int read_ilst(struct mp4 *f, int32_t size)
 {
        int ret;
        uint64_t sumsize = 0;
@@ -472,7 +479,7 @@ static int32_t read_ilst(struct mp4 *f, int32_t size)
        return 1;
 }
 
-static int32_t read_meta(struct mp4 *f, uint64_t size)
+static int read_meta(struct mp4 *f, uint64_t size)
 {
        int ret;
        uint64_t subsize, sumsize = 0;
@@ -539,7 +546,7 @@ static int parse_sub_atoms(struct mp4 *f, uint64_t total_size, bool meta_only)
                if (ret <= 0)
                        return ret;
                if (size == 0)
-                       return -1;
+                       return -E_MP4_CORRUPT;
                dest = get_position(f) + size - header_size;
                if (atom_type == ATOM_TRAK && f->track.state == ATS_SEEN_MP4A) {
                        f->track.state = ATS_TRACK_CHANGE;
@@ -572,12 +579,35 @@ 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);
+       free(f->track.stts_sample_count);
+       free(f->track.stsc_first_chunk);
+       free(f->track.stsc_samples_per_chunk);
+       free(f->track.stco_chunk_offset);
+       for (uint32_t n = 0; n < f->meta.count; n++) {
+               free(f->meta.tags[n].item);
+               free(f->meta.tags[n].value);
+       }
+       free(f->meta.tags);
+       free(f);
+}
+
 static int open_file(const struct mp4_callback *cb, bool meta_only, struct mp4 **result)
 {
        int ret;
        uint64_t size;
        uint8_t atom_type, header_size;
-       struct mp4 *f = para_calloc(sizeof(*f));
+       struct mp4 *f = zalloc(sizeof(*f));
 
        f->cb = cb;
        while ((ret = atom_read_header(f, &atom_type, &header_size, &size)) > 0) {
@@ -592,41 +622,63 @@ static int open_file(const struct mp4_callback *cb, bool meta_only, struct mp4 *
                if (ret <= 0)
                        break;
        }
-       if (ret < 0) {
-               ret = -E_MP4_OPEN;
+       if (ret < 0)
                goto fail;
-       }
        ret = -E_MP4_TRACK;
        if (f->track.channel_count == 0)
                goto fail;
+       ret = -E_MP4_BAD_SAMPLERATE;
+       if (f->track.sample_rate == 0)
+               goto fail;
+       ret = -E_MP4_MISSING_ATOM;
+       if (f->udta_size == 0 || f->meta_size == 0 || f->ilst_size == 0)
+               goto fail;
        *result = f;
        return 1;
 fail:
        *result = NULL;
-       free(f);
+       mp4_close(f);
        return ret;
 }
 
-int mp4_open_read(const struct mp4_callback *cb, struct mp4 **result)
-{
-       return open_file(cb, false, result);
-}
-
-void mp4_close(struct mp4 *f)
+/**
+ * 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)
 {
-       int32_t i;
+       struct mp4 *f;
+       int ret;
 
-       free(f->track.stsz_table);
-       free(f->track.stts_sample_count);
-       free(f->track.stsc_first_chunk);
-       free(f->track.stsc_samples_per_chunk);
-       free(f->track.stco_chunk_offset);
-       for (i = 0; i < f->meta.count; i++) {
-               free(f->meta.tags[i].item);
-               free(f->meta.tags[i].value);
-       }
-       free(f->meta.tags);
-       free(f);
+       *result = NULL;
+       ret = open_file(cb, false, &f);
+       if (ret < 0)
+               return ret;
+       ret = -E_MP4_BAD_SAMPLE_COUNT;
+       if (f->track.stsz_sample_count == 0)
+               goto fail;
+       ret = -E_MP4_CORRUPT;
+       if (f->track.time_scale == 0)
+               goto fail;
+       *result = f;
+       return 1;
+fail:
+       mp4_close(f);
+       return ret;
 }
 
 static int32_t chunk_of_sample(const struct mp4 *f, int32_t sample,
@@ -634,15 +686,15 @@ static int32_t chunk_of_sample(const struct mp4 *f, int32_t sample,
 {
        const struct mp4_track *t = &f->track;
        uint32_t *fc = t->stsc_first_chunk, *spc = t->stsc_samples_per_chunk;
-       int32_t chunk1, chunk1samples, n, total, i;
+       uint32_t chunk1, chunk1samples, n, total, k;
 
-       for (i = 1, total = 0; i < t->stsc_entry_count; i++, total += n) {
-               n = (fc[i] - fc[i - 1]) * spc[i - 1]; /* number of samples */
+       for (k = 1, total = 0; k < t->stsc_entry_count; k++, total += n) {
+               n = (fc[k] - fc[k - 1]) * spc[k - 1]; /* number of samples */
                if (sample < total + n)
                        break;
        }
-       chunk1 = fc[i - 1];
-       chunk1samples = spc[i - 1];
+       chunk1 = fc[k - 1];
+       chunk1samples = spc[k - 1];
        if (chunk1samples != 0)
                *chunk = (sample - total) / chunk1samples + chunk1;
        else
@@ -651,20 +703,32 @@ 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 See \ref mp4_close().
  *
- * \param f As returned by \ref mp4_open_read(), must not be NULL.
+ * \return The number of milliseconds of the audio track. This function never
+ * fails.
  */
 uint64_t mp4_get_duration(const struct mp4 *f)
 {
        const struct mp4_track *t = &f->track;
 
-       if (t->time_scale == 0)
-               return 0;
        return t->duration * 1000 / t->time_scale;
 }
 
-int mp4_set_sample_position(struct mp4 *f, int32_t sample)
+/**
+ * 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;
        int32_t offset, chunk, chunk_sample;
@@ -689,36 +753,91 @@ int mp4_set_sample_position(struct mp4 *f, int32_t sample)
        return 1;
 }
 
-int32_t mp4_get_sample_size(const struct mp4 *f, int sample)
+/**
+ * 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;
 
+       if (sample >= t->stsz_sample_count)
+               return -ERRNO_TO_PARA_ERROR(EINVAL);
        if (t->stsz_sample_size != 0)
-               return t->stsz_sample_size;
-       return t->stsz_table[sample];
+               *result = t->stsz_sample_size;
+       else
+               *result = t->stsz_table[sample];
+       return 1;
 }
 
-uint32_t mp4_get_sample_rate(const struct mp4 *f)
+/**
+ * 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;
 }
 
-uint32_t mp4_get_channel_count(const struct mp4 *f)
+/**
+ * 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;
 }
 
-int32_t mp4_num_samples(const struct mp4 *f)
+/**
+ * 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)
 {
-       const struct mp4_track *t = &f->track;
-       int32_t i;
-       int32_t total = 0;
-
-       for (i = 0; i < t->stts_entry_count; i++)
-               total += t->stts_sample_count[i];
-       return total;
+       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;
@@ -726,11 +845,6 @@ int mp4_open_meta(const struct mp4_callback *cb, struct mp4 **result)
 
        if (ret < 0)
                return ret;
-       if (f->udta_size == 0 || f->meta_size == 0 || f->ilst_size == 0) {
-               mp4_close(f);
-               *result = NULL;
-               return -E_MP4_MISSING_ATOM;
-       }
        *result = f;
        return 1;
 }
@@ -738,10 +852,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)
 {
@@ -786,7 +905,7 @@ static void *modify_moov(struct mp4 *f, uint32_t *out_size)
 {
        int ret;
        uint64_t total_base = f->moov_offset + 8;
-       uint32_t total_size = (uint32_t) (f->moov_size - 8);
+       uint32_t total_size = f->moov_size - 8;
        uint32_t new_ilst_size = 0;
        void *out_buffer;
        uint8_t *p_out;
@@ -797,7 +916,7 @@ static void *modify_moov(struct mp4 *f, uint32_t *out_size)
                new_ilst_size += TAG_LEN(strlen(f->meta.tags[n].value));
        size_delta = new_ilst_size - (f->ilst_size - 8);
        *out_size = total_size + size_delta;
-       out_buffer = para_malloc(*out_size);
+       out_buffer = alloc(*out_size);
        p_out = out_buffer;
        set_position(f, total_base);
        ret = read_data(f, p_out, f->udta_offset - total_base);
@@ -863,7 +982,21 @@ static int write_data(struct mp4 *f, void *data, size_t size)
        return 1;
 }
 
-int mp4_meta_update(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 \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;
        uint32_t new_moov_size;
@@ -892,77 +1025,29 @@ int mp4_meta_update(struct mp4 *f)
        ret = write_data(f, new_moov_data, new_moov_size);
        if (ret < 0)
                goto free_moov;
-       f->cb->truncate(f->cb->user_data);
-       ret = 1;
+       ret = f->cb->truncate(f->cb->user_data);
+       if (ret < 0)
+               ret = -ERRNO_TO_PARA_ERROR(errno);
 free_moov:
        free(new_moov_data);
        return ret;
 }
 
-static char *meta_find_by_name(const struct mp4 *f, const char *item)
-{
-       uint32_t i;
-
-       for (i = 0; i < f->meta.count; i++)
-               if (!strcasecmp(f->meta.tags[i].item, item))
-                       return para_strdup(f->meta.tags[i].value);
-       return NULL;
-}
-
 /**
- * Return the value of the artist meta tag of an mp4 file.
+ * 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 If the file does not contain this metadata tag, the function returns
- * NULL. Otherwise, a copy of the tag value is returned. 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_meta_get_artist(const struct mp4 *f)
+__malloc char *mp4_get_tag_value(const struct mp4 *f, const char *item)
 {
-       return meta_find_by_name(f, "artist");
-}
-
-/**
- * Return the value of the title meta tag of an mp4 file.
- *
- * \param f See \ref mp4_meta_get_artist().
- * \return See \ref mp4_meta_get_artist().
- */
-char *mp4_meta_get_title(const struct mp4 *f)
-{
-       return meta_find_by_name(f, "title");
-}
-
-/**
- * Return the value of the date meta tag of an mp4 file.
- *
- * \param f See \ref mp4_meta_get_artist().
- * \return See \ref mp4_meta_get_artist().
- */
-char *mp4_meta_get_date(const struct mp4 *f)
-{
-       return meta_find_by_name(f, "date");
-}
-
-/**
- * Return the value of the album meta tag of an mp4 file.
- *
- * \param f See \ref mp4_meta_get_artist().
- * \return See \ref mp4_meta_get_artist().
- */
-char *mp4_meta_get_album(const struct mp4 *f)
-{
-       return meta_find_by_name(f, "album");
-}
-
-/**
- * Return the value of the comment meta tag of an mp4 file.
- *
- * \param f See \ref mp4_meta_get_artist().
- * \return See \ref mp4_meta_get_artist().
- */
-char *mp4_meta_get_comment(const struct mp4 *f)
-{
-       return meta_find_by_name(f, "comment");
+       for (unsigned n = 0; n < f->meta.count; n++)
+               if (!strcasecmp(f->meta.tags[n].item, item))
+                       return para_strdup(f->meta.tags[n].value);
+       return NULL;
 }