libtaginfo / bindings / c / taginfo_c.h

  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
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
/*
 * Copyright (C) 2013 Jörn Magens
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This Program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; see the file LICENSE.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth 
 * Floor, Boston, MA  02110-1301  USA
 * https://www.gnu.org/licenses/lgpl-2.1.txt
 *
 * Author:
 * 	Jörn Magens <shuerhaaken@googlemail.com>
 * 	Matias De lellis <mati86dl@gmail.com>
 * 	Pavel Vasin <rat4vier@gmail.com>
 */


#ifndef TAGINFO_C_H
#define TAGINFO_C_H

/** @file */

/**
 * @mainpage
 *
 * This manual documents the <em>C bindings</em> for the libtaginfo C API. 
 * libtaginfo is a wrapper library for taglib and alows access to media tags in an abstract way.
 *
 *
 * Known tag formats are: 
 *  - Ape tags, 
 *  - Asf tags and 
 *  - Id3 tags (v1, v2.2, v2.3, v2.4),
 *  - Mod tags.
 *  - Mp4 tags, 
 *  - Xiphcomment/Vorbis tag, 
 * 
 * These tags are used with the following media files (extensions / mime):
 *  - aac  : audio/aac, audio/aacp, audio/mp4, audio/x-aac
 *  - aif  : audio/x-aiff
 *  - aiff : audio/x-aiff
 *  - ape  : application/x-ape
 *  - asf  : audio/x-ms-asf, video/x-ms-asf
 *  - flac : audio/flac, audio/x-flac+ogg, audio/x-flac
 *  - it   : audio/x-it
 *  - m4a  : audio/mp4a-latm, audio/x-m4a
 *  - m4b  : audio/m4b
 *  - m4p  : audio/x-m4p
 *  - mod  : audio/x-mod
 *  - mp3  : audio/mpeg, audio/x-mpegurl
 *  - mp4  : audio/mp4, video/mp4
 *  - mpc  : audio/mpc, audio/x-musepack
 *  - oga  : audio/x-vorbis+ogg, audio/ogg
 *  - ogg  : audio/x-vorbis+ogg, audio/ogg
 *  - s3m  : audio/x-s3m
 *  - spx  : audio/x-spx, audio/x-speex, audio/x-speex+ogg
 *  - tta  : audio/tta, audio/x-tta
 *  - wav  : audio/x-wav
 *  - wma  : audio/x-ms-wma
 *  - wmv  : video/x-ms-wmv, video/x-msvideo
 *  - wv   : application/x-wavpack, audio/wavpack, audio/x-wavpack
 *  - xm   : audio/x-xm
 *
 * There is an API for accessing the following media tags:
 *  - Album
 *  - Album artist
 *  - Artist
 *  - Comments;
 *  - Compilation/V.A. flag
 *  - Composer;
 *  - Copyright;
 *  - Encoder;
 *  - Genre
 *  - Homepage;
 *  - Images (embedded image files)
 *  - Original artist
 *  - Play count
 *  - Rating (1 - 5 stars, 0 not set) 
 *  - Title
 *  - Track count;
 *  - Track number;
 *  - User defined album labels;
 *  - User defined artist labels;
 *  - User defined track labels;
 *  - Volume count;
 *  - Volume number;
 *  - Year
 * 
 * However, some media tags are not supported by some tag formats. (E.g. mod tags are very limited)
 * 
 * There is an API for accessing the following audio properties:
 *  - Bitrate
 *  - Channel count
 *  - Lenght in seconds
 *  - Sample rate
 */

#ifdef __cplusplus
extern "C" {
#endif

#ifndef BOOL
#define BOOL int
#endif


//! \class TagInfo_Info is an abstraction for accessing media file tags
typedef struct { int dummy; } TagInfo_Info;


//! \enum TagInfo_ImageFileType is an enumeration of image file types for embedded images
typedef enum {
  TagInfo_IMAGE_FILE_TYPE_UNKNOWN,
  TagInfo_IMAGE_FILE_TYPE_JPEG,
  TagInfo_IMAGE_FILE_TYPE_PNG,
  TagInfo_IMAGE_FILE_TYPE_BMP,
  TagInfo_IMAGE_FILE_TYPE_GIF
} TagInfo_ImageFileType;

//! \enum TagInfo_MediaFileType is an enumeration of media file types supported in libtaginfo
typedef enum {
    MEDIA_FILE_TYPE_UNKNOWN,
    MEDIA_FILE_TYPE_AAC,
    MEDIA_FILE_TYPE_AIF,
    MEDIA_FILE_TYPE_APE,
    MEDIA_FILE_TYPE_ASF,
    MEDIA_FILE_TYPE_FLAC,
    MEDIA_FILE_TYPE_M4A,
    MEDIA_FILE_TYPE_M4B,
    MEDIA_FILE_TYPE_M4P,
    MEDIA_FILE_TYPE_MP3,
    MEDIA_FILE_TYPE_MP4,
    MEDIA_FILE_TYPE_MPC,
    MEDIA_FILE_TYPE_OGA,
    MEDIA_FILE_TYPE_OGG,
    MEDIA_FILE_TYPE_TTA,
    MEDIA_FILE_TYPE_WAV,
    MEDIA_FILE_TYPE_WMA,
    MEDIA_FILE_TYPE_WV,
    MEDIA_FILE_TYPE_SPEEX,
    MEDIA_FILE_TYPE_WMV,
    MEDIA_FILE_TYPE_MOD,
    MEDIA_FILE_TYPE_IT,
    MEDIA_FILE_TYPE_XM,
    MEDIA_FILE_TYPE_S3M
} TagInfo_MediaFileType;

//! \enum TagInfo_ImageType enumeration for image content description
typedef enum {
    //! An image type not listed here
    IMAGE_TYPE_OTHER,
    //! 32x32 PNG image that should be used as the file icon
    IMAGE_TYPE_FILE_ICON,
    //! File icon of a different size or format
    IMAGE_TYPE_OTHER_FILE_ICON,
    //! Front cover image of the album
    IMAGE_TYPE_COVER_FRONT,
    //! Back cover image of the album
    IMAGE_TYPE_COVER_BACK,
    //! Inside leaflet page of the album
    IMAGE_TYPE_LEAFLET_PAGE,
    //! Image from the album itself
    IMAGE_TYPE_MEDIA,
    //! Picture of the lead artist or soloist
    IMAGE_TYPE_LEAD_ARTIST,
    //! Picture of the artist or performer
    IMAGE_TYPE_ARTIST,
    //! Picture of the conductor
    IMAGE_TYPE_CONDUCTOR,
    //! Picture of the band or orchestra
    IMAGE_TYPE_BAND,
    //! Picture of the composer
    IMAGE_TYPE_COMPOSER,
    //! Picture of the lyricist or text writer
    IMAGE_TYPE_LYRICIST,
    //! Picture of the recording location or studio
    IMAGE_TYPE_RECORDING_LOCATION,
    //! Picture of the artists during recording
    IMAGE_TYPE_DURING_RECORDING,
    //! Picture of the artists during performance
    IMAGE_TYPE_DURING_PERFORMANCE,
    //! Picture from a movie or video related to the track
    IMAGE_TYPE_MOVIESCREENCAPTURE,
    //! Picture of a large, coloured fish.
    IMAGE_TYPE_COLOURED_FISH,
    //! Illustration related to the track
    IMAGE_TYPE_ILLUSTRATION,
    //! Logo of the band or performer
    IMAGE_TYPE_ARTIST_LOGO,
    //! Logo of the publisher (record company)
    IMAGE_TYPE_PUBLISHER_LOGO
} TagInfo_ImageType;


//! \class TagInfo_Image contains image data and image information
typedef struct { 
    char *                  data;
    unsigned long           data_length;
    TagInfo_ImageType       image_type;
    TagInfo_ImageFileType   image_file_type;
    char *                  description;
} TagInfo_Image;


// FACTORY CREATION
/*!
 * Creates a TagInfo file based on \a filename.  TagInfo will try to guess the file
 * type.
 *
 * \return NULL if the file type cannot be determined or the file cannot
 * be opened. The returned object should be freed with taginfo_info_free() after usage
 */
TagInfo_Info *taginfo_info_factory_make(const char *filename);

TagInfo_Info *taginfo_info_factory_make_with_format(const char *filename, TagInfo_MediaFileType format);

TagInfo_Info *taginfo_info_factory_make_from_mime(const char *filename, const char *mime_type);

/*!
 * Frees an info object.
 */
void taginfo_info_free(TagInfo_Info *info);

/*!
 * Frees an image object.
 */
void taginfo_image_free(TagInfo_Image * img);

/*!
 * Frees an image array as returned from taginfo_info_get_images().
 */
void taginfo_image_array_free(TagInfo_Image ** img_arr);

// READ / WRITE
BOOL taginfo_info_load(TagInfo_Info *info);
BOOL taginfo_info_save(TagInfo_Info *info);


// STRING MANAGEMENT
//! Enable string management for libtaginfo
void taginfo_info_enable_string_management(BOOL management);

//! clean up used strings
//! To be used in case string management is used
void taginfo_info_free_strings();


// TAG ACCESS

//! Get the album tag of a media track.
/*!
\return The album as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_album(const TagInfo_Info *info);
void  taginfo_info_set_album(TagInfo_Info *info, const char *album);

//! Get the albumartist tag of a media track.
/*!
\return The albumartist as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_albumartist(const TagInfo_Info *info);
void  taginfo_info_set_albumartist(TagInfo_Info *info, const char *albumartist);

//! Get the artist tag of a media track.
/*!
\return The artist as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_artist(const TagInfo_Info *info);
void  taginfo_info_set_artist(TagInfo_Info *info, const char *artist);

//! Get the comment tag of a media track.
/*!
\return The comment as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_comment(const TagInfo_Info *info);
void  taginfo_info_set_comment(TagInfo_Info *info, const char *comment);

//! Get the composer tag of a media track.
/*!
\return The composer as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_composer(const TagInfo_Info *info);
void  taginfo_info_set_composer(TagInfo_Info *info, const char *composer);

//! Get the copyright tag of a media track.
/*!
\return The copyright as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_copyright(const TagInfo_Info *info);
void  taginfo_info_set_copyright(TagInfo_Info *info, const char *copyright);

//! Get the encoder tag of a media track.
/*!
\return The encoder as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_encoder(const TagInfo_Info *info);
void  taginfo_info_set_encoder(TagInfo_Info *info, const char *encoder);

//! Get the genre tag of a media track.
/*!
\return The genre as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_genre(const TagInfo_Info *info);
void  taginfo_info_set_genre(TagInfo_Info *info, const char *genre);

BOOL taginfo_info_get_has_image(const TagInfo_Info *info);

//! Get the homepage tag of a media track.
/*!
\return The homepage as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_homepage(const TagInfo_Info *info);
void  taginfo_info_set_homepage(TagInfo_Info *info, const char *homepage);

BOOL taginfo_info_get_is_compilation(const TagInfo_Info *info);
void taginfo_info_set_is_compilation(TagInfo_Info *info, BOOL is_compilation);

//! Get the original_artist tag of a media track.
/*!
\return The original_artist as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_original_artist(const TagInfo_Info *info);
void  taginfo_info_set_original_artist(TagInfo_Info *info, const char *artist);


int  taginfo_info_get_playcount(const TagInfo_Info *info);
void taginfo_info_set_playcount(TagInfo_Info *info, int count);

// rating 1 - 5; 0 -> not set
int  taginfo_info_get_rating(const TagInfo_Info *info);
void taginfo_info_set_rating(TagInfo_Info *info, int rating);

//! Get the title tag of a media track.
/*!
\return The title as char *. In case the string management is not enabled, the caller should free this string
*/
char *taginfo_info_get_title(const TagInfo_Info *info);
void  taginfo_info_set_title(TagInfo_Info *info, const char *title);

//! Get the track count of a media track.
/*!
\return The track count as int.
*/
int  taginfo_info_get_track_count(const TagInfo_Info *info);
void taginfo_info_set_track_count(TagInfo_Info *info, int track_number);

//! Get the track number of a media track.
/*!
\return The track number as int.
*/
int  taginfo_info_get_track_number(const TagInfo_Info *info);
void taginfo_info_set_track_number(TagInfo_Info *info, int track_number);

//! Get the volume count of a media track.
/*!
\return The volume count as int.
*/
int taginfo_info_get_volume_count(const TagInfo_Info *info);
void taginfo_info_set_volume_count(TagInfo_Info *info, int count);

//! Get the volume number of a media track.
/*!
\return The volume number as int.
*/
int taginfo_info_get_volume_number(const TagInfo_Info *info);
void taginfo_info_set_volume_number(TagInfo_Info *info, int number);

//! Get the year of a media track.
/*!
\return The year as int.
*/
int taginfo_info_get_year(const TagInfo_Info *info);
void taginfo_info_set_year(TagInfo_Info *info, int year);


// AUDIO PROPERTIES
int taginfo_info_get_length(const TagInfo_Info *info);
int taginfo_info_get_bitrate(const TagInfo_Info *info);
int taginfo_info_get_samplerate(const TagInfo_Info *info);
int taginfo_info_get_channels(const TagInfo_Info *info);

// USER LABELS
char **taginfo_info_get_track_labels(const TagInfo_Info *info,
                                     int *data_length);
void taginfo_info_set_track_labels(TagInfo_Info *info,
                                   const char* const* data, int data_length);

char **taginfo_info_get_album_labels(const TagInfo_Info *info,
                                     int *data_length);
void taginfo_info_set_album_labels(TagInfo_Info *info,
                                   const char* const* data, int data_length);

char **taginfo_info_get_artist_labels(const TagInfo_Info *info,
                                      int *data_length);
void taginfo_info_set_artist_labels(TagInfo_Info *info,
                                    const char* const* data,
                                    int data_length);

// IMAGE
TagInfo_Image ** taginfo_info_get_images(const TagInfo_Info *info,
                                         int *image_count);
void taginfo_info_set_images(TagInfo_Info *info,
                             const TagInfo_Image ** images,
                             const int image_count);

// LYRICS
char * taginfo_info_get_lyrics(const TagInfo_Info *info);
BOOL taginfo_info_set_lyrics(TagInfo_Info *info,
                             const char *lyrics);


#ifdef __cplusplus
}
#endif
#endif
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.