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.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MP4Tags

Function Documentation

◆ MP4TagsAlloc()

◆ MP4TagsFetch()

◆ MP4TagsFree()

◆ MP4TagsHasMetadata()

◆ MP4TagsStore()