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

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

Classes

struct  MP4ItmfData_s
 Data structure. More...
 
struct  MP4ItmfDataList_s
 List of data. More...
 
struct  MP4ItmfItem_s
 Item structure. More...
 
struct  MP4ItmfItemList_s
 List of items. More...
 

Typedefs

typedef enum MP4ItmfBasicType_e MP4ItmfBasicType
 Basic types of value data as enumerated in spec.
 
typedef struct MP4ItmfData_s MP4ItmfData
 Data structure. More...
 
typedef struct MP4ItmfDataList_s MP4ItmfDataList
 List of data.
 
typedef struct MP4ItmfItem_s MP4ItmfItem
 Item structure. More...
 
typedef struct MP4ItmfItemList_s MP4ItmfItemList
 List of items.
 

Enumerations

enum  MP4ItmfBasicType_e {
  MP4_ITMF_BT_IMPLICIT = 0, MP4_ITMF_BT_UTF8 = 1, MP4_ITMF_BT_UTF16 = 2,
  MP4_ITMF_BT_SJIS = 3, MP4_ITMF_BT_HTML = 6, MP4_ITMF_BT_XML = 7,
  MP4_ITMF_BT_UUID = 8, MP4_ITMF_BT_ISRC = 9, MP4_ITMF_BT_MI3P = 10,
  MP4_ITMF_BT_GIF = 12, MP4_ITMF_BT_JPEG = 13, MP4_ITMF_BT_PNG = 14,
  MP4_ITMF_BT_URL = 15, MP4_ITMF_BT_DURATION = 16, MP4_ITMF_BT_DATETIME = 17,
  MP4_ITMF_BT_GENRES = 18, MP4_ITMF_BT_INTEGER = 21, MP4_ITMF_BT_RIAA_PA = 24,
  MP4_ITMF_BT_UPC = 25, MP4_ITMF_BT_BMP = 27, MP4_ITMF_BT_UNDEFINED = 255
}
 Basic types of value data as enumerated in spec. More...
 

Functions

MP4ItmfItemMP4ItmfItemAlloc (const char *code, uint32_t numData)
 Allocate an item on the heap. More...
 
void MP4ItmfItemFree (MP4ItmfItem *item)
 Free an item (deep free). More...
 
void MP4ItmfItemListFree (MP4ItmfItemList *itemList)
 Free an item list (deep free). More...
 
MP4ItmfItemListMP4ItmfGetItems (MP4FileHandle hFile)
 Get list of all items from file. More...
 
MP4ItmfItemListMP4ItmfGetItemsByCode (MP4FileHandle hFile, const char *code)
 Get list of items by code from file. More...
 
MP4ItmfItemListMP4ItmfGetItemsByMeaning (MP4FileHandle hFile, const char *meaning, const char *name)
 Get list of items by meaning from file. More...
 
bool MP4ItmfAddItem (MP4FileHandle hFile, const MP4ItmfItem *item)
 Add an item to file. More...
 
bool MP4ItmfSetItem (MP4FileHandle hFile, const MP4ItmfItem *item)
 Overwrite an existing item in file. More...
 
bool MP4ItmfRemoveItem (MP4FileHandle hFile, const MP4ItmfItem *item)
 Remove an existing item from file. More...
 

Detailed Description

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

It provides support for virtually any kind of iTMF metadata item, including meaning atoms, sometimes referred to as reverse-DNS meanings. Structures are directly modified; i.e. there are no fuctions which modify values for you. There is little type-safety, logic checks, or specifications compliance checks. For these reasons it is recommended to use iTMF Tags API when possible.

At the heart of this API is an MP4ItmfItem which corresponds to an iTMF metadata item atom. The item, and any recursive data structures contained within require manual memory management. The general rule to follow is that you must always check/free a ptr if you intend to resize data. In cases where you know the existing data size is exactly what is needed, you may overwrite the buffer contents.

Each item always has at least 1 data elements which corresponds to a data atom. Additionally, each item has optional mean and name values which correspond to mean and name atoms.

Each MP4ItmfItem has a list of MP4ItmfData. Similarily, care must be taken to manage memory with one key difference; these structures also have a valueSize field. If value is NULL then set valueSize=0. Otherwise, set valueSize to the size (in bytes) of value buffer.

In rare cases where the number of data elements in a single item is > 1, the user must manually free/alloc/copy the elements buffer and update size accordingly.

The mp4 file structure is modified only when MP4AddItem(), MP4SetItem() and MP4RemoveItem() are used. Simply free'ing the item list does not modify the mp4 file.

iTMF Generic read workflow:

@li MP4ItmfGetItems()
@li inspect each item...
@li MP4ItmfItemListFree()

iTMF Generic read/modify/remove workflow:

@li MP4ItmfGetItems()
@li inspect/modify item...
@li MP4ItmfSetItem() each modified item...
@li MP4ItmfRemoveItem()...
@li MP4ItmfItemListFree()

iTMF Generic add workflow:

@li MP4ItmfItemAlloc()
@li MP4ItmfAddItem()
@li MP4ItmfItemFree()
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

◆ MP4ItmfData

typedef struct MP4ItmfData_s MP4ItmfData

Data structure.

Models an iTMF data atom contained in an iTMF metadata item atom.

◆ MP4ItmfItem

typedef struct MP4ItmfItem_s MP4ItmfItem

Item structure.

Models an iTMF metadata item atom contained in an ilst atom.

Enumeration Type Documentation

◆ MP4ItmfBasicType_e

Basic types of value data as enumerated in spec.

Enumerator
MP4_ITMF_BT_IMPLICIT 

for use with tags for which no type needs to be indicated

MP4_ITMF_BT_UTF8 

without any count or null terminator

MP4_ITMF_BT_UTF16 

also known as UTF-16BE

MP4_ITMF_BT_SJIS 

deprecated unless it is needed for special Japanese characters

MP4_ITMF_BT_HTML 

the HTML file header specifies which HTML version

MP4_ITMF_BT_XML 

the XML header must identify the DTD or schemas

MP4_ITMF_BT_UUID 

also known as GUID; stored as 16 bytes in binary (valid as an ID)

MP4_ITMF_BT_ISRC 

stored as UTF-8 text (valid as an ID)

MP4_ITMF_BT_MI3P 

stored as UTF-8 text (valid as an ID)

MP4_ITMF_BT_GIF 

(deprecated) a GIF image

MP4_ITMF_BT_JPEG 

a JPEG image

MP4_ITMF_BT_PNG 

a PNG image

MP4_ITMF_BT_URL 

absolute, in UTF-8 characters

MP4_ITMF_BT_DURATION 

in milliseconds, 32-bit integer

MP4_ITMF_BT_DATETIME 

in UTC, counting seconds since midnight, January 1, 1904; 32 or 64-bits

MP4_ITMF_BT_GENRES 

a list of enumerated values

MP4_ITMF_BT_INTEGER 

a signed big-endian integer with length one of { 1,2,3,4,8 } bytes

MP4_ITMF_BT_RIAA_PA 

RIAA parental advisory; { -1=no, 1=yes, 0=unspecified }, 8-bit ingteger.

MP4_ITMF_BT_UPC 

Universal Product Code, in text UTF-8 format (valid as an ID)

MP4_ITMF_BT_BMP 

Windows bitmap image.

MP4_ITMF_BT_UNDEFINED 

undefined

Function Documentation

◆ MP4ItmfAddItem()

bool MP4ItmfAddItem ( MP4FileHandle  hFile,
const MP4ItmfItem item 
)

Add an item to file.

Parameters
hFilehandle of file to operate on.
itemobject to add.
Returns
true on success, false on failure.
Examples
example/itmf/generic.c.

◆ MP4ItmfGetItems()

MP4ItmfItemList* MP4ItmfGetItems ( MP4FileHandle  hFile)

Get list of all items from file.

Parameters
hFilehandle of file to operate on.
Returns
On succes, list of items, which must be free'd. On failure, NULL.
Examples
example/itmf/generic.c.

◆ MP4ItmfGetItemsByCode()

MP4ItmfItemList* MP4ItmfGetItemsByCode ( MP4FileHandle  hFile,
const char *  code 
)

Get list of items by code from file.

Parameters
hFilehandle of file to operate on.
codefour-char code identifying atom type. NULL-terminated.
Returns
On succes, list of items, which must be free'd. On failure, NULL.

◆ MP4ItmfGetItemsByMeaning()

MP4ItmfItemList* MP4ItmfGetItemsByMeaning ( MP4FileHandle  hFile,
const char *  meaning,
const char *  name 
)

Get list of items by meaning from file.

Implicitly only returns atoms of code {-—}.

Parameters
hFilehandle of file to operate on.
meaningUTF-8 meaning. NULL-terminated.
namemay be NULL. UTF-8 name. NULL-terminated.
Returns
On succes, list of items, which must be free'd. On failure, NULL.

◆ MP4ItmfItemAlloc()

MP4ItmfItem* MP4ItmfItemAlloc ( const char *  code,
uint32_t  numData 
)

Allocate an item on the heap.

Parameters
codefour-char code identifying atom type. NULL-terminated.
numDatanumber of data elements to allocate. Must be >= 1.
Returns
newly allocated item.
Examples
example/itmf/generic.c.

◆ MP4ItmfItemFree()

void MP4ItmfItemFree ( MP4ItmfItem item)

Free an item (deep free).

Parameters
itemto be free'd.
Examples
example/itmf/generic.c.

◆ MP4ItmfItemListFree()

void MP4ItmfItemListFree ( MP4ItmfItemList itemList)

Free an item list (deep free).

Parameters
itemListto be free'd.
Examples
example/itmf/generic.c.

◆ MP4ItmfRemoveItem()

bool MP4ItmfRemoveItem ( MP4FileHandle  hFile,
const MP4ItmfItem item 
)

Remove an existing item from file.

Parameters
hFilehandle of file to operate on.
itemobject to remove. Must have a valid index obtained from prior get.
Returns
true on success, false on failure.

◆ MP4ItmfSetItem()

bool MP4ItmfSetItem ( MP4FileHandle  hFile,
const MP4ItmfItem item 
)

Overwrite an existing item in file.

Parameters
hFilehandle of file to operate on.
itemobject to overwrite. Must have a valid index obtained from prior get.
Returns
true on success, false on failure.