1 /***************************************************************************
2 copyright : (C) 2003 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
6 /***************************************************************************
7 * This library is free software; you can redistribute it and/or modify *
8 * it under the terms of the GNU Lesser General Public License version *
9 * 2.1 as published by the Free Software Foundation. *
11 * This library is distributed in the hope that it will be useful, but *
12 * WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the Free Software *
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
20 ***************************************************************************/
25 /* Do not include this in the main TagLib documentation. */
26 #ifndef DO_NOT_DOCUMENT
32 #if defined(_WIN32) || defined(_WIN64)
33 #ifdef MAKE_TAGLIB_C_LIB
34 #define TAGLIB_C_EXPORT __declspec(dllexport)
36 #define TAGLIB_C_EXPORT __declspec(dllimport)
39 #define TAGLIB_C_EXPORT
46 /*******************************************************************************
47 * [ TagLib C Binding ]
49 * This is an interface to TagLib's "simple" API, meaning that you can read and
50 * modify media files in a generic, but not specialized way. This is a rough
51 * representation of TagLib::File and TagLib::Tag, for which the documentation
52 * is somewhat more complete and worth consulting.
53 *******************************************************************************/
56 * These are used for type provide some type safety to the C API (as opposed to
57 * using void *, but pointers to them are simply cast to the corresponding C++
58 * types in the implementation.
61 typedef struct { int dummy
; } TagLib_File
;
62 typedef struct { int dummy
; } TagLib_Tag
;
63 typedef struct { int dummy
; } TagLib_AudioProperties
;
66 * By default all strings coming into or out of TagLib's C API are in UTF8.
67 * However, it may be desirable for TagLib to operate on Latin1 (ISO-8859-1)
68 * strings in which case this should be set to FALSE.
70 TAGLIB_C_EXPORT
void taglib_set_strings_unicode(BOOL unicode
);
73 * TagLib can keep track of strings that are created when outputting tag values
74 * and clear them using taglib_tag_clear_strings(). This is enabled by default.
75 * However if you wish to do more fine grained management of strings, you can do
76 * so by setting \a management to FALSE.
78 TAGLIB_C_EXPORT
void taglib_set_string_management_enabled(BOOL management
);
80 /*******************************************************************************
82 ******************************************************************************/
86 TagLib_File_OggVorbis
,
96 * Creates a TagLib file based on \a filename. TagLib will try to guess the file
99 * \returns NULL if the file type cannot be determined or the file cannot
102 TAGLIB_C_EXPORT TagLib_File
*taglib_file_new(const char *filename
);
105 * Creates a TagLib file based on \a filename. Rather than attempting to guess
106 * the type, it will use the one specified by \a type.
108 TAGLIB_C_EXPORT TagLib_File
*taglib_file_new_type(const char *filename
, TagLib_File_Type type
);
111 * Frees and closes the file.
113 TAGLIB_C_EXPORT
void taglib_file_free(TagLib_File
*file
);
116 * Returns true if the file is open and readble and valid information for
117 * the Tag and / or AudioProperties was found.
120 TAGLIB_C_EXPORT BOOL
taglib_file_is_valid(const TagLib_File
*file
);
123 * Returns a pointer to the tag associated with this file. This will be freed
124 * automatically when the file is freed.
126 TAGLIB_C_EXPORT TagLib_Tag
*taglib_file_tag(const TagLib_File
*file
);
129 * Returns a pointer to the the audio properties associated with this file. This
130 * will be freed automatically when the file is freed.
132 TAGLIB_C_EXPORT
const TagLib_AudioProperties
*taglib_file_audioproperties(const TagLib_File
*file
);
135 * Saves the \a file to disk.
137 TAGLIB_C_EXPORT BOOL
taglib_file_save(TagLib_File
*file
);
139 /******************************************************************************
141 ******************************************************************************/
144 * Returns a string with this tag's title.
146 * \note By default this string should be UTF8 encoded and its memory should be
147 * freed using taglib_tag_free_strings().
149 TAGLIB_C_EXPORT
char *taglib_tag_title(const TagLib_Tag
*tag
);
152 * Returns a string with this tag's artist.
154 * \note By default this string should be UTF8 encoded and its memory should be
155 * freed using taglib_tag_free_strings().
157 TAGLIB_C_EXPORT
char *taglib_tag_artist(const TagLib_Tag
*tag
);
160 * Returns a string with this tag's album name.
162 * \note By default this string should be UTF8 encoded and its memory should be
163 * freed using taglib_tag_free_strings().
165 TAGLIB_C_EXPORT
char *taglib_tag_album(const TagLib_Tag
*tag
);
168 * Returns a string with this tag's comment.
170 * \note By default this string should be UTF8 encoded and its memory should be
171 * freed using taglib_tag_free_strings().
173 TAGLIB_C_EXPORT
char *taglib_tag_comment(const TagLib_Tag
*tag
);
176 * Returns a string with this tag's genre.
178 * \note By default this string should be UTF8 encoded and its memory should be
179 * freed using taglib_tag_free_strings().
181 TAGLIB_C_EXPORT
char *taglib_tag_genre(const TagLib_Tag
*tag
);
184 * Returns the tag's year or 0 if year is not set.
186 TAGLIB_C_EXPORT
unsigned int taglib_tag_year(const TagLib_Tag
*tag
);
189 * Returns the tag's track number or 0 if track number is not set.
191 TAGLIB_C_EXPORT
unsigned int taglib_tag_track(const TagLib_Tag
*tag
);
194 * Sets the tag's title.
196 * \note By default this string should be UTF8 encoded.
198 TAGLIB_C_EXPORT
void taglib_tag_set_title(TagLib_Tag
*tag
, const char *title
);
201 * Sets the tag's artist.
203 * \note By default this string should be UTF8 encoded.
205 TAGLIB_C_EXPORT
void taglib_tag_set_artist(TagLib_Tag
*tag
, const char *artist
);
208 * Sets the tag's album.
210 * \note By default this string should be UTF8 encoded.
212 TAGLIB_C_EXPORT
void taglib_tag_set_album(TagLib_Tag
*tag
, const char *album
);
215 * Sets the tag's comment.
217 * \note By default this string should be UTF8 encoded.
219 TAGLIB_C_EXPORT
void taglib_tag_set_comment(TagLib_Tag
*tag
, const char *comment
);
222 * Sets the tag's genre.
224 * \note By default this string should be UTF8 encoded.
226 TAGLIB_C_EXPORT
void taglib_tag_set_genre(TagLib_Tag
*tag
, const char *genre
);
229 * Sets the tag's year. 0 indicates that this field should be cleared.
231 TAGLIB_C_EXPORT
void taglib_tag_set_year(TagLib_Tag
*tag
, unsigned int year
);
234 * Sets the tag's track number. 0 indicates that this field should be cleared.
236 TAGLIB_C_EXPORT
void taglib_tag_set_track(TagLib_Tag
*tag
, unsigned int track
);
239 * Frees all of the strings that have been created by the tag.
241 TAGLIB_C_EXPORT
void taglib_tag_free_strings(void);
243 /******************************************************************************
244 * Audio Properties API
245 ******************************************************************************/
248 * Returns the length of the file in seconds.
250 TAGLIB_C_EXPORT
int taglib_audioproperties_length(const TagLib_AudioProperties
*audioProperties
);
253 * Returns the bitrate of the file in kb/s.
255 TAGLIB_C_EXPORT
int taglib_audioproperties_bitrate(const TagLib_AudioProperties
*audioProperties
);
258 * Returns the sample rate of the file in Hz.
260 TAGLIB_C_EXPORT
int taglib_audioproperties_samplerate(const TagLib_AudioProperties
*audioProperties
);
263 * Returns the number of channels in the audio stream.
265 TAGLIB_C_EXPORT
int taglib_audioproperties_channels(const TagLib_AudioProperties
*audioProperties
);
267 /*******************************************************************************
268 * Special convenience ID3v2 functions
269 *******************************************************************************/
274 TagLib_ID3v2_UTF16BE
,
276 } TagLib_ID3v2_Encoding
;
279 * This sets the default encoding for ID3v2 frames that are written to tags.
282 TAGLIB_C_EXPORT
void taglib_id3v2_set_default_text_encoding(TagLib_ID3v2_Encoding encoding
);
287 #endif /* DO_NOT_DOCUMENT */