1 #ifndef MP4V2_ITMF_TAGS_H 2 #define MP4V2_ITMF_TAGS_H 3 4 /**************************************************************************//** 5 * 6 * @defgroup mp4_itmf_tags MP4v2 iTMF (iTunes Metadata Format) Tags 7 * @{ 8 * 9 * This is a high-level API used to manage iTMF metadata. 10 * 11 * It provides more type-safety and simplified memory management as compared 12 * to iTMF Generic API. 13 * 14 * At the heart of this API is a read-only structure that holds all known 15 * items and their current values. The value is always a pointer which if 16 * NULL indicates its corresponding atom does not exist. Thus, one must 17 * always check if the pointer is non-NULL before attempting to extract 18 * its value. 19 * 20 * The structure may not be directly modified. Instead, <b>set</b> functions 21 * corresponding to each item are used to modify the backing-store of 22 * the read-only structure. Setting the value ptr to NULL will effectively 23 * remove it. Setting the value ptr to real data will immediately make a 24 * copy of the value in the backing-store and the read-only structure 25 * will correctly reflect the change. 26 * 27 * The hidden data cache memory is automatically managed. Thus the user need 28 * only guarantee the data is available during the lifetime of the set-function 29 * call. 30 * 31 * <b>iTMF Tags read workflow:</b> 32 * 33 * @li MP4TagsAlloc() 34 * @li MP4TagsFetch() 35 * @li inspect each tag of interest... 36 * @li MP4TagsStore() (if modified) 37 * @li MP4TagsFree() 38 * 39 * <b>iTMF Tags read/modify/add/remove workflow:</b> 40 * 41 * @li MP4TagsAlloc() 42 * @li MP4TagsFetch() 43 * @li inspect each tag of interest... 44 * @li MP4TagsSetName(), MP4TagsSetArtist()... 45 * @li MP4TagsStore() 46 * @li MP4TagsFree() 47 * 48 * @par Warning: 49 * Care must be taken when using multiple mechanisms to modify an open mp4 50 * file as it is not thread-safe, nor does it permit overlapping different 51 * API workflows which have a begin/end to their workflow. That is to say 52 * do not interleave an iTMF Generic workflow with an iTMF Tags workflow. 53 * 54 *****************************************************************************/ 55 56 /** Enumeration of possible MP4TagArtwork::type values. */ 57 typedef enum MP4TagArtworkType_e 58 { 59 MP4_ART_UNDEFINED = 0, 60 MP4_ART_BMP = 1, 61 MP4_ART_GIF = 2, 62 MP4_ART_JPEG = 3, 63 MP4_ART_PNG = 4 64 } MP4TagArtworkType; 65 66 /** Data object representing a single piece of artwork. */ 67 typedef struct MP4TagArtwork_s 68 { 69 void* data; /**< raw picture data */ 70 uint32_t size; /**< data size in bytes */ 71 MP4TagArtworkType type; /**< data type */ 72 } MP4TagArtwork; 73 74 typedef struct MP4TagTrack_s 75 { 76 uint16_t index; 77 uint16_t total; 78 } MP4TagTrack; 79 80 typedef struct MP4TagDisk_s 81 { 82 uint16_t index; 83 uint16_t total; 84 } MP4TagDisk; 85 86 /** Tags <b>convenience</b> structure. 87 * 88 * This structure is used in the tags convenience API which allows for 89 * simplified retrieval and modification of the majority of known tags. 90 * 91 * This is a read-only structure and each tag is present if and only if the 92 * pointer is a <b>non-NULL</b> value. The actual data is backed by a hidden 93 * data cache which is only updated when the appropriate metadata <b>set</b> 94 * function is used, or if MP4TagsFetch() is invoked. Thus, if other API 95 * is used to manipulate relevent atom structure of the MP4 file, the user 96 * is responsible for re-fetching the data in this structure. 97 */ 98 typedef struct MP4Tags_s 99 { 100 void* __handle; /* internal use only */ 101 102 const char* name; 103 const char* artist; 104 const char* albumArtist; 105 const char* album; 106 const char* grouping; 107 const char* composer; 108 const char* comments; 109 const char* genre; 110 const uint16_t* genreType; 111 const char* releaseDate; 112 const MP4TagTrack* track; 113 const MP4TagDisk* disk; 114 const uint16_t* tempo; 115 const uint8_t* compilation; 116 117 const char* tvShow; 118 const char* tvNetwork; 119 const char* tvEpisodeID; 120 const uint32_t* tvSeason; 121 const uint32_t* tvEpisode; 122 123 const char* description; 124 const char* longDescription; 125 const char* lyrics; 126 127 const char* sortName; 128 const char* sortArtist; 129 const char* sortAlbumArtist; 130 const char* sortAlbum; 131 const char* sortComposer; 132 const char* sortTVShow; 133 134 const MP4TagArtwork* artwork; 135 uint32_t artworkCount; 136 137 const char* copyright; 138 const char* encodingTool; 139 const char* encodedBy; 140 const char* purchaseDate; 141 142 const uint8_t* podcast; 143 const char* keywords; /* TODO: Needs testing */ 144 const char* category; 145 146 const uint8_t* hdVideo; 147 const uint8_t* mediaType; 148 const uint8_t* contentRating; 149 const uint8_t* gapless; 150 151 const char* iTunesAccount; 152 const uint8_t* iTunesAccountType; 153 const uint32_t* iTunesCountry; 154 const uint32_t* contentID; 155 const uint32_t* artistID; 156 const uint64_t* playlistID; 157 const uint32_t* genreID; 158 const uint32_t* composerID; 159 const char* xid; 160 } MP4Tags; 161 162 /** Allocate tags convenience structure for reading and settings tags. 163 * 164 * This function allocates a new structure which represents a snapshot 165 * of all the tags therein, tracking if the tag is missing, 166 * or present and with value. It is the caller's responsibility to free 167 * the structure with MP4TagsFree(). 168 * 169 * @return structure with all tags missing. 170 */ 171 MP4V2_EXPORT 172 const MP4Tags* MP4TagsAlloc( void ); 173 174 /** Fetch data from mp4 file and populate structure. 175 * 176 * The tags structure and its hidden data-cache is updated to 177 * reflect the actual tags values found in the <b>hFile</b>. 178 * 179 * @param tags structure to fetch (write) into. 180 * @param hFile handle of file to fetch data from. 181 * 182 * @return <b>true</b> on success, <b>false</b> on failure. 183 */ 184 MP4V2_EXPORT 185 bool MP4TagsFetch( const MP4Tags* tags, MP4FileHandle hFile ); 186 187 /** Store data to mp4 file from structure. 188 * 189 * The tags structure is pushed out to the mp4 file, 190 * adding tags if needed, removing tags if needed, and updating 191 * the values to modified tags. 192 * 193 * @param tags structure to store (read) from. 194 * @param hFile handle of file to store data to. 195 * 196 * @return <b>true</b> on success, <b>false</b> on failure. 197 */ 198 MP4V2_EXPORT 199 bool MP4TagsStore( const MP4Tags* tags, MP4FileHandle hFile ); 200 201 /** Free tags convenience structure. 202 * 203 * This function frees memory associated with the structure. 204 * 205 * @param tags structure to destroy. 206 */ 207 MP4V2_EXPORT 208 void MP4TagsFree( const MP4Tags* tags ); 209 210 /** Accessor that indicates whether a tags structure 211 * contains any metadata 212 * 213 * @param tags the structure to inspect 214 * 215 * @param hasMetadata populated with false if @p tags 216 * contains no metadata, true if @p tags contains metadata 217 * 218 * @retval false error determining if @p tags contains 219 * metadata 220 * 221 * @retval true successfully determined if @p tags contains 222 * metadata 223 */ 224 MP4V2_EXPORT 225 bool MP4TagsHasMetadata ( const MP4Tags* tags, bool *hasMetadata ); 226 227 MP4V2_EXPORT bool MP4TagsSetName ( const MP4Tags*, const char* ); 228 MP4V2_EXPORT bool MP4TagsSetArtist ( const MP4Tags*, const char* ); 229 MP4V2_EXPORT bool MP4TagsSetAlbumArtist ( const MP4Tags*, const char* ); 230 MP4V2_EXPORT bool MP4TagsSetAlbum ( const MP4Tags*, const char* ); 231 MP4V2_EXPORT bool MP4TagsSetGrouping ( const MP4Tags*, const char* ); 232 MP4V2_EXPORT bool MP4TagsSetComposer ( const MP4Tags*, const char* ); 233 MP4V2_EXPORT bool MP4TagsSetComments ( const MP4Tags*, const char* ); 234 MP4V2_EXPORT bool MP4TagsSetGenre ( const MP4Tags*, const char* ); 235 MP4V2_EXPORT bool MP4TagsSetGenreType ( const MP4Tags*, const uint16_t* ); 236 MP4V2_EXPORT bool MP4TagsSetReleaseDate ( const MP4Tags*, const char* ); 237 MP4V2_EXPORT bool MP4TagsSetTrack ( const MP4Tags*, const MP4TagTrack* ); 238 MP4V2_EXPORT bool MP4TagsSetDisk ( const MP4Tags*, const MP4TagDisk* ); 239 MP4V2_EXPORT bool MP4TagsSetTempo ( const MP4Tags*, const uint16_t* ); 240 MP4V2_EXPORT bool MP4TagsSetCompilation ( const MP4Tags*, const uint8_t* ); 241 242 MP4V2_EXPORT bool MP4TagsSetTVShow ( const MP4Tags*, const char* ); 243 MP4V2_EXPORT bool MP4TagsSetTVNetwork ( const MP4Tags*, const char* ); 244 MP4V2_EXPORT bool MP4TagsSetTVEpisodeID ( const MP4Tags*, const char* ); 245 MP4V2_EXPORT bool MP4TagsSetTVSeason ( const MP4Tags*, const uint32_t* ); 246 MP4V2_EXPORT bool MP4TagsSetTVEpisode ( const MP4Tags*, const uint32_t* ); 247 248 MP4V2_EXPORT bool MP4TagsSetDescription ( const MP4Tags*, const char* ); 249 MP4V2_EXPORT bool MP4TagsSetLongDescription ( const MP4Tags*, const char* ); 250 MP4V2_EXPORT bool MP4TagsSetLyrics ( const MP4Tags*, const char* ); 251 252 MP4V2_EXPORT bool MP4TagsSetSortName ( const MP4Tags*, const char* ); 253 MP4V2_EXPORT bool MP4TagsSetSortArtist ( const MP4Tags*, const char* ); 254 MP4V2_EXPORT bool MP4TagsSetSortAlbumArtist ( const MP4Tags*, const char* ); 255 MP4V2_EXPORT bool MP4TagsSetSortAlbum ( const MP4Tags*, const char* ); 256 MP4V2_EXPORT bool MP4TagsSetSortComposer ( const MP4Tags*, const char* ); 257 MP4V2_EXPORT bool MP4TagsSetSortTVShow ( const MP4Tags*, const char* ); 258 259 MP4V2_EXPORT bool MP4TagsAddArtwork ( const MP4Tags*, MP4TagArtwork* ); 260 MP4V2_EXPORT bool MP4TagsSetArtwork ( const MP4Tags*, uint32_t, MP4TagArtwork* ); 261 MP4V2_EXPORT bool MP4TagsRemoveArtwork ( const MP4Tags*, uint32_t ); 262 263 MP4V2_EXPORT bool MP4TagsSetCopyright ( const MP4Tags*, const char* ); 264 MP4V2_EXPORT bool MP4TagsSetEncodingTool ( const MP4Tags*, const char* ); 265 MP4V2_EXPORT bool MP4TagsSetEncodedBy ( const MP4Tags*, const char* ); 266 MP4V2_EXPORT bool MP4TagsSetPurchaseDate ( const MP4Tags*, const char* ); 267 268 MP4V2_EXPORT bool MP4TagsSetPodcast ( const MP4Tags*, const uint8_t* ); 269 MP4V2_EXPORT bool MP4TagsSetKeywords ( const MP4Tags*, const char* ); 270 MP4V2_EXPORT bool MP4TagsSetCategory ( const MP4Tags*, const char* ); 271 272 MP4V2_EXPORT bool MP4TagsSetHDVideo ( const MP4Tags*, const uint8_t* ); 273 MP4V2_EXPORT bool MP4TagsSetMediaType ( const MP4Tags*, const uint8_t* ); 274 MP4V2_EXPORT bool MP4TagsSetContentRating ( const MP4Tags*, const uint8_t* ); 275 MP4V2_EXPORT bool MP4TagsSetGapless ( const MP4Tags*, const uint8_t* ); 276 277 MP4V2_EXPORT bool MP4TagsSetITunesAccount ( const MP4Tags*, const char* ); 278 MP4V2_EXPORT bool MP4TagsSetITunesAccountType ( const MP4Tags*, const uint8_t* ); 279 MP4V2_EXPORT bool MP4TagsSetITunesCountry ( const MP4Tags*, const uint32_t* ); 280 MP4V2_EXPORT bool MP4TagsSetContentID ( const MP4Tags*, const uint32_t* ); 281 MP4V2_EXPORT bool MP4TagsSetArtistID ( const MP4Tags*, const uint32_t* ); 282 MP4V2_EXPORT bool MP4TagsSetPlaylistID ( const MP4Tags*, const uint64_t* ); 283 MP4V2_EXPORT bool MP4TagsSetGenreID ( const MP4Tags*, const uint32_t* ); 284 MP4V2_EXPORT bool MP4TagsSetComposerID ( const MP4Tags*, const uint32_t* ); 285 MP4V2_EXPORT bool MP4TagsSetXID ( const MP4Tags*, const char* ); 286 287 /** @} ***********************************************************************/ 288 289 #endif /* MP4V2_ITMF_TAGS_H */ 290