MP4v2

Classes | Typedefs | Enumerations | Functions
MP4v2 iTMF (iTunes Metadata Format) Tags

This is a high-level API used to manage iTMF metadata. More...

## Classes
struct | MP4TagArtwork_s
| Data object representing a single piece of artwork. More...
struct | MP4TagTrack_s
struct | MP4TagDisk_s
struct | MP4Tags_s
| Tags convenience structure. More...

## Typedefs
typedef enum MP4TagArtworkType_e | MP4TagArtworkType
| Enumeration of possible MP4TagArtwork::type values.
typedef struct MP4TagArtwork_s | MP4TagArtwork
| Data object representing a single piece of artwork.
typedef struct MP4TagTrack_s | MP4TagTrack
typedef struct MP4TagDisk_s | MP4TagDisk
typedef struct MP4Tags_s | MP4Tags
| Tags convenience structure. More...

## Enumerations
enum | MP4TagArtworkType_e { MP4_ART_UNDEFINED = 0 , MP4_ART_BMP = 1 , MP4_ART_GIF = 2 , MP4_ART_JPEG = 3 , MP4_ART_PNG = 4 }
| Enumeration of possible MP4TagArtwork::type values.

## Functions
const MP4Tags * | MP4TagsAlloc (void)
| Allocate tags convenience structure for reading and settings tags. More...
bool | MP4TagsFetch (const MP4Tags *tags, MP4FileHandle hFile)
| Fetch data from mp4 file and populate structure. More...
bool | MP4TagsStore (const MP4Tags *tags, MP4FileHandle hFile)
| Store data to mp4 file from structure. More...
void | MP4TagsFree (const MP4Tags *tags)
| Free tags convenience structure. More...
bool | MP4TagsHasMetadata (const MP4Tags *tags, bool *hasMetadata)
| Accessor that indicates whether a tags structure contains any metadata. More...
bool | MP4TagsSetName (const MP4Tags *, const char *)
bool | MP4TagsSetArtist (const MP4Tags *, const char *)
bool | MP4TagsSetAlbumArtist (const MP4Tags *, const char *)
bool | MP4TagsSetAlbum (const MP4Tags *, const char *)
bool | MP4TagsSetGrouping (const MP4Tags *, const char *)
bool | MP4TagsSetComposer (const MP4Tags *, const char *)
bool | MP4TagsSetComments (const MP4Tags *, const char *)
bool | MP4TagsSetGenre (const MP4Tags *, const char *)
bool | MP4TagsSetGenreType (const MP4Tags *, const uint16_t *)
bool | MP4TagsSetReleaseDate (const MP4Tags *, const char *)
bool | MP4TagsSetTrack (const MP4Tags *, const MP4TagTrack *)
bool | MP4TagsSetDisk (const MP4Tags *, const MP4TagDisk *)
bool | MP4TagsSetTempo (const MP4Tags *, const uint16_t *)
bool | MP4TagsSetCompilation (const MP4Tags *, const uint8_t *)
bool | MP4TagsSetTVShow (const MP4Tags *, const char *)
bool | MP4TagsSetTVNetwork (const MP4Tags *, const char *)
bool | MP4TagsSetTVEpisodeID (const MP4Tags *, const char *)
bool | MP4TagsSetTVSeason (const MP4Tags *, const uint32_t *)
bool | MP4TagsSetTVEpisode (const MP4Tags *, const uint32_t *)
bool | MP4TagsSetDescription (const MP4Tags *, const char *)
bool | MP4TagsSetLongDescription (const MP4Tags *, const char *)
bool | MP4TagsSetLyrics (const MP4Tags *, const char *)
bool | MP4TagsSetSortName (const MP4Tags *, const char *)
bool | MP4TagsSetSortArtist (const MP4Tags *, const char *)
bool | MP4TagsSetSortAlbumArtist (const MP4Tags *, const char *)
bool | MP4TagsSetSortAlbum (const MP4Tags *, const char *)
bool | MP4TagsSetSortComposer (const MP4Tags *, const char *)
bool | MP4TagsSetSortTVShow (const MP4Tags *, const char *)
bool | MP4TagsAddArtwork (const MP4Tags *, MP4TagArtwork *)
bool | MP4TagsSetArtwork (const MP4Tags *, uint32_t, MP4TagArtwork *)
bool | MP4TagsRemoveArtwork (const MP4Tags *, uint32_t)
bool | MP4TagsSetCopyright (const MP4Tags *, const char *)
bool | MP4TagsSetEncodingTool (const MP4Tags *, const char *)
bool | MP4TagsSetEncodedBy (const MP4Tags *, const char *)
bool | MP4TagsSetPurchaseDate (const MP4Tags *, const char *)
bool | MP4TagsSetPodcast (const MP4Tags *, const uint8_t *)
bool | MP4TagsSetKeywords (const MP4Tags *, const char *)
bool | MP4TagsSetCategory (const MP4Tags *, const char *)
bool | MP4TagsSetHDVideo (const MP4Tags *, const uint8_t *)
bool | MP4TagsSetMediaType (const MP4Tags *, const uint8_t *)
bool | MP4TagsSetContentRating (const MP4Tags *, const uint8_t *)
bool | MP4TagsSetGapless (const MP4Tags *, const uint8_t *)
bool | MP4TagsSetITunesAccount (const MP4Tags *, const char *)
bool | MP4TagsSetITunesAccountType (const MP4Tags *, const uint8_t *)
bool | MP4TagsSetITunesCountry (const MP4Tags *, const uint32_t *)
bool | MP4TagsSetContentID (const MP4Tags *, const uint32_t *)
bool | MP4TagsSetArtistID (const MP4Tags *, const uint32_t *)
bool | MP4TagsSetPlaylistID (const MP4Tags *, const uint64_t *)
bool | MP4TagsSetGenreID (const MP4Tags *, const uint32_t *)
bool | MP4TagsSetComposerID (const MP4Tags *, const uint32_t *)
bool | MP4TagsSetXID (const MP4Tags *, const char *)

## Detailed Description

This is a high-level API used to manage iTMF metadata.

It provides more type-safety and simplified memory management as compared to iTMF Generic API.

At the heart of this API is a read-only structure that holds all known items and their current values. The value is always a pointer which if NULL indicates its corresponding atom does not exist. Thus, one must always check if the pointer is non-NULL before attempting to extract its value.

The structure may not be directly modified. Instead, set functions corresponding to each item are used to modify the backing-store of the read-only structure. Setting the value ptr to NULL will effectively remove it. Setting the value ptr to real data will immediately make a copy of the value in the backing-store and the read-only structure will correctly reflect the change.

The hidden data cache memory is automatically managed. Thus the user need only guarantee the data is available during the lifetime of the set-function call.

iTMF Tags read workflow:

    @li MP4TagsAlloc()
    @li MP4TagsFetch()
    @li inspect each tag of interest...
    @li MP4TagsStore() (if modified)
    @li MP4TagsFree()

iTMF Tags read/modify/add/remove workflow:

    @li MP4TagsAlloc()
    @li MP4TagsFetch()
    @li inspect each tag of interest...
    @li MP4TagsSetName(), MP4TagsSetArtist()...
    @li MP4TagsStore()
    @li MP4TagsFree()

Warning:
  Care must be taken when using multiple mechanisms to modify an open mp4 file as it is not thread-safe, nor does it permit overlapping different API workflows which have a begin/end to their workflow. That is to say do not interleave an iTMF Generic workflow with an iTMF Tags workflow.

## Typedef Documentation

## ◆ MP4Tags

typedef struct MP4Tags_s MP4Tags

Tags convenience structure.

This structure is used in the tags convenience API which allows for simplified retrieval and modification of the majority of known tags.

This is a read-only structure and each tag is present if and only if the pointer is a non-NULL value. The actual data is backed by a hidden data cache which is only updated when the appropriate metadata set function is used, or if MP4TagsFetch() is invoked. Thus, if other API is used to manipulate relevent atom structure of the MP4 file, the user is responsible for re-fetching the data in this structure.

## Function Documentation

## ◆ MP4TagsAlloc()

const MP4Tags * MP4TagsAlloc | ( | void |  | ) |

Allocate tags convenience structure for reading and settings tags.

This function allocates a new structure which represents a snapshot of all the tags therein, tracking if the tag is missing, or present and with value. It is the caller's responsibility to free the structure with MP4TagsFree().

Returns
  structure with all tags missing.

Examples
  example/itmf/tags.c.

## ◆ MP4TagsFetch()

bool MP4TagsFetch | ( | const MP4Tags * | tags,
|  | MP4FileHandle | hFile
| ) |  |

Fetch data from mp4 file and populate structure.

The tags structure and its hidden data-cache is updated to reflect the actual tags values found in the hFile.

Parameters

  tags | structure to fetch (write) into.
  hFile | handle of file to fetch data from.

Returns
  true on success, false on failure.

Examples
  example/itmf/tags.c.

## ◆ MP4TagsFree()

void MP4TagsFree | ( | const MP4Tags * | tags | ) |

Free tags convenience structure.

This function frees memory associated with the structure.

Parameters

  tags | structure to destroy.

Examples
  example/itmf/tags.c.

## ◆ MP4TagsHasMetadata()

bool MP4TagsHasMetadata | ( | const MP4Tags * | tags,
|  | bool * | hasMetadata
| ) |  |

Accessor that indicates whether a tags structure contains any metadata.

Parameters

  tags | the structure to inspect
  hasMetadata | populated with false if `tags` contains no metadata, true if `tags` contains metadata

Return values

  false | error determining if `tags` contains metadata
  true | successfully determined if `tags` contains metadata

## ◆ MP4TagsStore()

bool MP4TagsStore | ( | const MP4Tags * | tags,
|  | MP4FileHandle | hFile
| ) |  |

Store data to mp4 file from structure.

The tags structure is pushed out to the mp4 file, adding tags if needed, removing tags if needed, and updating the values to modified tags.

Parameters

  tags | structure to store (read) from.
  hFile | handle of file to store data to.

Returns
  true on success, false on failure.

Examples
  example/itmf/tags.c.