mp4.h

   1 /** \file mp4.h Public API of the mp4 parser. */
   2
   3 /**
   4  * Callbacks provided by the user of the mp4 parsing API.
   5  *
   6  * A pointer to this structure is passed to the two public open functions. If
   7  * the file is opened in read-only mode, the ->write() and ->truncate() methods
   8  * won't be called and may thus be NULL. The ->read() and ->seek() methods
   9  * must be supplied for either open type.
  10  *
  11  * All methods are supposed to work like their corresponding system calls.
  12  * That is, they should return non-negative for success and -1 on failure. In
  13  * the error case errno is expected to be set accordingly.
  14  *
  15  * \sa \ref mp4_open(), \ref mp4_open_meta().
  16  */
  17 struct mp4_callback {
  18         /** This pointer is propagated to each call of all methods. */
  19         void *user_data;
  20         /**
  21          * This should return the number of bytes read on success. Short reads
  22          * are OK: the function may return less than length.
  23          */
  24         ssize_t (*read)(void *user_data, void *buffer, size_t length);
  25         /**
  26          * This method is assumed to succeed. The implementation should simply
  27          * abort on errors. Note that offsets beyond EOF must not be regarded
  28          * as invalid arguments.
  29          */
  30         off_t (*seek)(void *user_data, off_t offset, int whence);
  31         /**
  32          * Like the write() system call, this should return the number of bytes
  33          * written. Short writes are OK: the function may return less than
  34          * count.
  35          */
  36         ssize_t (*write)(void *user_data, void *buffer, size_t count);
  37         /**
  38          * Unlike the truncate system call, this function does not receive an
  39          * offset. The method is expected to truncate the file to the offset
  40          * given by the current file position instead.
  41          */
  42         int (*truncate)(void *user_data);
  43 };
  44
  45 /** Specifies one metadata tag. Both fields are 0-terminated strings. */
  46 struct mp4_tag {
  47         /** The item name: "artist", "title", "album", "comment", or "date". */
  48         char *item;
  49         /** An arbitrary string value. */
  50         char *value;
  51 };
  52
  53 /**
  54  * An array of name/value pairs.
  55  *
  56  * This structure is initialized when the mp4 file is opened in either mode.
  57  * If the file contains metadata items other than the standard five, those
  58  * non-standard items are not included in the array. After a successful open, a
  59  * pointer to the metadata structure can be obtained via \ref mp4_get_meta().
  60  */
  61 struct mp4_metadata {
  62         /** It's OK to change this, for example by calling realloc(). */
  63         struct mp4_tag *tags;
  64         /** The number of entries of the array. */
  65         unsigned count;
  66 };
  67
  68 /**
  69  * The mp4 file handle.
  70  *
  71  * A pointer to this opaque structure is returned by the two open functions.
  72  * All other functions of the mp4 API receive a pointer of this type.
  73  */
  74 struct mp4;
  75
  76 int mp4_set_sample_position(struct mp4 *f, uint32_t sample);
  77 int mp4_open(const struct mp4_callback *cb, struct mp4 **result);
  78 void mp4_close(struct mp4 *f);
  79 int mp4_get_sample_size(const struct mp4 *f, uint32_t sample, uint32_t *result);
  80 uint16_t mp4_get_sample_rate(const struct mp4 *f);
  81 uint16_t mp4_get_channel_count(const struct mp4 *f);
  82 uint32_t mp4_num_samples(const struct mp4 *f);
  83 uint64_t mp4_get_duration(const struct mp4 *f);
  84 int mp4_open_meta(const struct mp4_callback *cb, struct mp4 **result);
  85 struct mp4_metadata *mp4_get_meta(struct mp4 *f);
  86 int mp4_update_meta(struct mp4 *f);
  87 char *mp4_get_tag_value(const struct mp4 *f, const char *item);