MP4v2
|
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 *) |
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()
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.
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().
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.
tags | structure to fetch (write) into. |
hFile | handle of file to fetch data from. |
void MP4TagsFree | ( | const MP4Tags * | tags | ) |
Free tags convenience structure.
This function frees memory associated with the structure.
tags | structure to destroy. |
bool MP4TagsHasMetadata | ( | const MP4Tags * | tags, |
bool * | hasMetadata | ||
) |
Accessor that indicates whether a tags structure contains any metadata.
tags | the structure to inspect |
hasMetadata | populated with false if tags contains no metadata, true if tags contains metadata |
false | error determining if tags contains metadata |
true | successfully determined if tags contains metadata |
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.
tags | structure to store (read) from. |
hFile | handle of file to store data to. |