Initialization¶

#include <stdint.h>
#include <libmp4tag.h>

libmp4tag_t * mp4tag_open (const char *filename, int *mp4error)
libmp4tag_t * mp4tag_openstream (mp4tag_readcb_t readcb, mp4tag_seekcb_t seekcb, uint32_t timeout, int *mp4error)
int mp4tag_parse (libmp4tag_t *libmp4tag)
void mp4tag_free (libmp4tag_t *libmp4tag)

Getting Tags¶

typedef struct {
  const char  *tag;       /* tag name */
  const char  *data;      /* tag value or binary data */
  const char  *covername; /* name associated with the cover image */
  size_t      datalen;    /* length of the tag value or binary data */
  int         dataidx;    /* index value for the array (e.g. cover image) */
  int         covertype;  /* type of cover image */
  bool        binary;     /* true if binary data */
} mp4tagpub_t;

int64_t mp4tag_duration (libmp4tag_t *libmp4tag)
int mp4tag_get_tag_by_name (libmp4tag_t *libmp4tag, const char *tag, mp4tagpub_t *mp4tagpub)
int mp4tag_iterate_init (libmp4tag_t *libmp4tag)
int mp4tag_iterate (libmp4tag_t *libmp4tag, mp4tagpub_t *mp4tagpub)

Modifying Tags¶

int mp4tag_set_tag (libmp4tag_t *libmp4tag, const char *tag, const char *data, bool forcebinary)
int mp4tag_set_binary_tag (libmp4tag_t *libmp4tag, const char *tag, const char *data, size_t datalen)
int mp4tag_delete_tag (libmp4tag_t *libmp4tag, const char *tag)
int mp4tag_clean_tags (libmp4tag_t *libmp4tag)

Writing Tags¶

int mp4tag_write_tags (libmp4tag_t *libmp4tag)

Constants¶

COPYRIGHT_STR The copyright symbol as an UTF-8 string.

Other Functions¶

int mp4tag_error (libmp4tag_t *libmp4tag)
const char *mp4tag_version (void)
const char *mp4tag_error_str (libmp4tag_t *libmp4tag)
void mp4tag_set_debug_flags (libmp4tag_t *libmp4tag, int dbgflags)
void mp4tag_set_free_space (libmp4tag_t *libmp4tag, int32_t freespacesz)

Helper Functions¶

FILE * mp4tag_fopen (const char *filename, const char *mode)
ssize_t mp4tag_file_size (const char *filename)
char * mp4tag_read_file (libmp4tag_t *libmp4tag, const char *filename, size_t *sz)
int mp4tag_file_delete (const char *filename)
int mp4tag_file_move (const char *filename, const char *newfilename)
wchar_t *mp4tag_towide (const char *buff)
char *mp4tag_fromwide (const wchar_t *buff)

Initialization¶

mp4tag_open opens filename, returning a pointer to a libmp4tag_t, with the error return in mp4error. The returned pointer must be freed with mp4tag_free.

mp4tag_openstream uses callbacks to process the data stream. it returns a pointer to a libmp4tag_t, with the error return in mp4error. The timeout in milliseconds specifies how long to wait to receive data. The returned pointer must be freed with mp4tag_free.

Note that if the MP4 tags are located after the audio/video, the stream will be completely read in.

mp4tag_parse parses the open file or stream and returns an error code.

The libmp4tag_t structure is opaque and has no user accessible fields.

Getting Tags¶

mp4tag_duration returns the duration in milliseconds or 0.

mp4tag_get_tag_by_name returns MP4TAG_OK, MP4TAG_ERR_TAG_NOT_FOUND, MP4TAG_NO_TAGS, or other error code. On success, the mp4tagpub_t structure is filled in.

mp4tag_iterate_init initializes the internal iterator. Returns MP4TAG_OK or other error code.

mp4tag_iterate returns MP4TAG_OK or MP4TAG_FINISH when there are no more tags to process. On MP4TAG_OK, the mp4tagpub_t structure is filled in.

There may be more than one cover image present. The dataidx field specifies the index of the cover image.

If the cover image has an associated name, the covername field will be set.

The covertype field in the mp4tagpub_t structure will be set to MP4TAG_COVER_JPG or MP4TAG_COVER_PNG for cover tags.

Modifying Tags¶

Modifying a tag, adding a new tag or cleaning the tags does not commit the changes to the MP4 file. See the Writing Tags section.

mp4tag_set_tag will set tag to data when tag is not set to binary data.

If tag holds binary data or forcebinary is true, data is treated as a filename, the binary data is read from the file, and the value of tag is set to the binary data.

Disc and track numbers should either be a single numeric value or a numeric value and total specified as N/T or (N,T).

There may be more than one cover image present. If there is more than one cover image, mp4tag_set_tag will expect a tag name of covr:1 with the appropriate index value.

If there is a name associated with the cover image, A tag name of covr:1:name using the appropriate index value should be used.

The indexes are only used if there is already an existing cover image at that index. Setting a cover image at index 1 in a file with no cover image present will place the cover image at index 0.

mp4tag_set_binary_tag is used when the binary data is already in memory. The value of tag is set to data with size datalen.

mp4tag_delete_tag removes tag.

mp4tag_clean_tags removes all tags from the MP4 file.

Writing Tags¶

mp4tag_write_tags will write the changed tags to the MP4 file.

The MP4 file is not modified until the mp4tag_write_tags function is called.

If possible, the MP4 file is modified in place. If there is not enough room in the MP4 file to write the tags, the MP4 file is re-written and replaced.

Determining whether any tags have changed and whether calling mp4tag_write_tags is necessary is the responsibility of the calling application.

Other¶

mp4tag_error returns the last error code that was generated.

mp4tag_version returns the libmp4tag version string.

mp4tag_error_str returns a readable error string corresponding to the current error. This function is intended for debugging purposes and not for display to the end user.

mp4tag_set_debug_flags sets the debug flags to dbgflags.

Helper Functions¶

The helper functions provide some functions that work across different platforms. All filenames and other strings should be in utf8.

mp4tag_fopen opens a file (See fopen(3)).

mp4tag_file_size returns the size of a file.

mp4tag_read_file reads the contents of filename and returns the data. The application takes ownership of the data and must free it.

The data length returned is stored in sz, and any error is returned in fImp4error.

mp4tag_file_delete deletes filename. Returns any error.

mp4tag_file_move renames filename to newfilename.

(Windows) mp4tag_towide converts a utf8 string to unicode. The caller takes ownership of the returned data and must free it.

(Windows) mp4tag_fromwide converts a unicode string to utf8. The caller takes ownership of the returned data and must free it.