* 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"
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(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 {
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);
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;
}
/**
- * 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)
{
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;
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;
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;
/**
* 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)
{
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;
/**
* 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)
{
+/** \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);
projects / paraslash.git / commitdiff