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 MP4TagsMP4TagsAlloc (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
tagsstructure to fetch (write) into.
hFilehandle 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
tagsstructure 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
tagsthe structure to inspect
hasMetadatapopulated with false if tags contains no metadata, true if tags contains metadata
Return values
falseerror determining if tags contains metadata
truesuccessfully 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
tagsstructure to store (read) from.
hFilehandle of file to store data to.
Returns
true on success, false on failure.
Examples
example/itmf/tags.c.