/usr/include/mp4v2/itmf_tags.h is in libmp4v2-dev 2.0.0~dfsg0-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 | #ifndef MP4V2_ITMF_TAGS_H
#define MP4V2_ITMF_TAGS_H
/**************************************************************************//**
*
* @defgroup mp4_itmf_tags MP4v2 iTMF (iTunes Metadata Format) Tags
* @{
*
* 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, <b>set</b> 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.
*
* <b>iTMF Tags read workflow:</b>
*
* @li MP4TagsAlloc()
* @li MP4TagsFetch()
* @li inspect each tag of interest...
* @li MP4TagsStore() (if modified)
* @li MP4TagsFree()
*
* <b>iTMF Tags read/modify/add/remove workflow:</b>
*
* @li MP4TagsAlloc()
* @li MP4TagsFetch()
* @li inspect each tag of interest...
* @li MP4TagsSetName(), MP4TagsSetArtist()...
* @li MP4TagsStore()
* @li MP4TagsFree()
*
* @par 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.
*
*****************************************************************************/
/** Enumeration of possible MP4TagArtwork::type values. */
typedef enum MP4TagArtworkType_e
{
MP4_ART_UNDEFINED = 0,
MP4_ART_BMP = 1,
MP4_ART_GIF = 2,
MP4_ART_JPEG = 3,
MP4_ART_PNG = 4
} MP4TagArtworkType;
/** Data object representing a single piece of artwork. */
typedef struct MP4TagArtwork_s
{
void* data; /**< raw picture data */
uint32_t size; /**< data size in bytes */
MP4TagArtworkType type; /**< data type */
} MP4TagArtwork;
typedef struct MP4TagTrack_s
{
uint16_t index;
uint16_t total;
} MP4TagTrack;
typedef struct MP4TagDisk_s
{
uint16_t index;
uint16_t total;
} MP4TagDisk;
/** Tags <b>convenience</b> 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 <b>non-NULL</b> value. The actual data is backed by a hidden
* data cache which is only updated when the appropriate metadata <b>set</b>
* 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.
*/
typedef struct MP4Tags_s
{
void* __handle; /* internal use only */
const char* name;
const char* artist;
const char* albumArtist;
const char* album;
const char* grouping;
const char* composer;
const char* comments;
const char* genre;
const uint16_t* genreType;
const char* releaseDate;
const MP4TagTrack* track;
const MP4TagDisk* disk;
const uint16_t* tempo;
const uint8_t* compilation;
const char* tvShow;
const char* tvNetwork;
const char* tvEpisodeID;
const uint32_t* tvSeason;
const uint32_t* tvEpisode;
const char* description;
const char* longDescription;
const char* lyrics;
const char* sortName;
const char* sortArtist;
const char* sortAlbumArtist;
const char* sortAlbum;
const char* sortComposer;
const char* sortTVShow;
const MP4TagArtwork* artwork;
uint32_t artworkCount;
const char* copyright;
const char* encodingTool;
const char* encodedBy;
const char* purchaseDate;
const uint8_t* podcast;
const char* keywords; /* TODO: Needs testing */
const char* category;
const uint8_t* hdVideo;
const uint8_t* mediaType;
const uint8_t* contentRating;
const uint8_t* gapless;
const char* iTunesAccount;
const uint8_t* iTunesAccountType;
const uint32_t* iTunesCountry;
const uint32_t* contentID;
const uint32_t* artistID;
const uint64_t* playlistID;
const uint32_t* genreID;
const uint32_t* composerID;
const char* xid;
} MP4Tags;
/** 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().
*
* @return structure with all tags missing.
*/
MP4V2_EXPORT
const MP4Tags* MP4TagsAlloc( void );
/** 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 <b>hFile</b>.
*
* @param tags structure to fetch (write) into.
* @param hFile handle of file to fetch data from.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4TagsFetch( 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.
*
* @param tags structure to store (read) from.
* @param hFile handle of file to store data to.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4TagsStore( const MP4Tags* tags, MP4FileHandle hFile );
/** Free tags convenience structure.
*
* This function frees memory associated with the structure.
*
* @param tags structure to destroy.
*/
MP4V2_EXPORT
void MP4TagsFree( const MP4Tags* tags );
/** Accessor that indicates whether a tags structure
* contains any metadata
*
* @param tags the structure to inspect
*
* @param hasMetadata populated with false if @p tags
* contains no metadata, true if @p tags contains metadata
*
* @retval false error determining if @p tags contains
* metadata
*
* @retval true successfully determined if @p tags contains
* metadata
*/
MP4V2_EXPORT
bool MP4TagsHasMetadata ( const MP4Tags* tags, bool *hasMetadata );
MP4V2_EXPORT bool MP4TagsSetName ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetArtist ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetAlbumArtist ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetAlbum ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetGrouping ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetComposer ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetComments ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetGenre ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetGenreType ( const MP4Tags*, const uint16_t* );
MP4V2_EXPORT bool MP4TagsSetReleaseDate ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetTrack ( const MP4Tags*, const MP4TagTrack* );
MP4V2_EXPORT bool MP4TagsSetDisk ( const MP4Tags*, const MP4TagDisk* );
MP4V2_EXPORT bool MP4TagsSetTempo ( const MP4Tags*, const uint16_t* );
MP4V2_EXPORT bool MP4TagsSetCompilation ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetTVShow ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetTVNetwork ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetTVEpisodeID ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetTVSeason ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetTVEpisode ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetDescription ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetLongDescription ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetLyrics ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortName ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortArtist ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortAlbumArtist ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortAlbum ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortComposer ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortTVShow ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsAddArtwork ( const MP4Tags*, MP4TagArtwork* );
MP4V2_EXPORT bool MP4TagsSetArtwork ( const MP4Tags*, uint32_t, MP4TagArtwork* );
MP4V2_EXPORT bool MP4TagsRemoveArtwork ( const MP4Tags*, uint32_t );
MP4V2_EXPORT bool MP4TagsSetCopyright ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetEncodingTool ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetEncodedBy ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetPurchaseDate ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetPodcast ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetKeywords ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetCategory ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetHDVideo ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetMediaType ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetContentRating ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetGapless ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetITunesAccount ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetITunesAccountType ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetITunesCountry ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetContentID ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetArtistID ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetPlaylistID ( const MP4Tags*, const uint64_t* );
MP4V2_EXPORT bool MP4TagsSetGenreID ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetComposerID ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetXID ( const MP4Tags*, const char* );
/** @} ***********************************************************************/
#endif /* MP4V2_ITMF_TAGS_H */
|