1 /***************************************************************************
2 copyright : (C) 2003 by Allan Sandfeld Jensen
3 email : kde@carewolf.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 *
21 * Alternatively, this file is available under the Mozilla Public *
22 * License Version 1.1. You may obtain a copy of the License at *
23 * http://www.mozilla.org/MPL/ *
24 ***************************************************************************/
26 #ifndef TAGLIB_FLACFILE_H
27 #define TAGLIB_FLACFILE_H
29 #include "taglib_export.h"
32 #include "flacproperties.h"
38 namespace ID3v2 { class FrameFactory; class Tag; }
39 namespace ID3v1 { class Tag; }
40 namespace Ogg { class XiphComment; }
42 //! An implementation of FLAC metadata
45 * This is implementation of FLAC metadata for non-Ogg FLAC files. At some
46 * point when Ogg / FLAC is more common there will be a similar implementation
47 * under the Ogg hiearchy.
49 * This supports ID3v1, ID3v2 and Xiph style comments as well as reading stream
50 * properties from the file.
55 //! An implementation of TagLib::File with FLAC specific methods
58 * This implements and provides an interface for FLAC files to the
59 * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
60 * the abstract TagLib::File API as well as providing some additional
61 * information specific to FLAC files.
64 class TAGLIB_EXPORT File : public TagLib::File
68 * Contructs a FLAC file from \a file. If \a readProperties is true the
69 * file's audio properties will also be read using \a propertiesStyle. If
70 * false, \a propertiesStyle is ignored.
72 * \deprecated This constructor will be dropped in favor of the one below
73 * in a future version.
75 File(FileName file, bool readProperties = true,
76 Properties::ReadStyle propertiesStyle = Properties::Average);
79 * Contructs a FLAC file from \a file. If \a readProperties is true the
80 * file's audio properties will also be read using \a propertiesStyle. If
81 * false, \a propertiesStyle is ignored.
83 * If this file contains and ID3v2 tag the frames will be created using
86 // BIC: merge with the above constructor
87 File(FileName file, ID3v2::FrameFactory *frameFactory,
88 bool readProperties = true,
89 Properties::ReadStyle propertiesStyle = Properties::Average);
92 * Destroys this instance of the File.
97 * Returns the Tag for this file. This will be a union of XiphComment,
98 * ID3v1 and ID3v2 tags.
104 virtual TagLib::Tag *tag() const;
107 * Returns the FLAC::Properties for this file. If no audio properties
108 * were read then this will return a null pointer.
110 virtual Properties *audioProperties() const;
113 * Save the file. This will primarily save the XiphComment, but
114 * will also keep any old ID3-tags up to date. If the file
115 * has no XiphComment, one will be constructed from the ID3-tags.
117 * This returns true if the save was successful.
122 * Returns a pointer to the ID3v2 tag of the file.
124 * If \a create is false (the default) this will return a null pointer
125 * if there is no valid ID3v2 tag. If \a create is true it will create
126 * an ID3v2 tag if one does not exist.
128 * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
129 * deleted by the user. It will be deleted when the file (object) is
132 ID3v2::Tag *ID3v2Tag(bool create = false);
135 * Returns a pointer to the ID3v1 tag of the file.
137 * If \a create is false (the default) this will return a null pointer
138 * if there is no valid ID3v1 tag. If \a create is true it will create
139 * an ID3v1 tag if one does not exist.
141 * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
142 * deleted by the user. It will be deleted when the file (object) is
145 ID3v1::Tag *ID3v1Tag(bool create = false);
148 * Returns a pointer to the XiphComment for the file.
150 * If \a create is false (the default) this will return a null pointer
151 * if there is no valid XiphComment. If \a create is true it will create
152 * a XiphComment if one does not exist.
154 * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
155 * deleted by the user. It will be deleted when the file (object) is
158 Ogg::XiphComment *xiphComment(bool create = false);
161 * Set the ID3v2::FrameFactory to something other than the default. This
162 * can be used to specify the way that ID3v2 frames will be interpreted
165 * \see ID3v2FrameFactory
167 void setID3v2FrameFactory(const ID3v2::FrameFactory *factory);
170 * Returns the block of data used by FLAC::Properties for parsing the
173 * \deprecated This method will not be public in a future release.
175 ByteVector streamInfoData(); // BIC: remove
178 * Returns the length of the audio-stream, used by FLAC::Properties for
179 * calculating the bitrate.
181 * \deprecated This method will not be public in a future release.
183 long streamLength(); // BIC: remove
187 File &operator=(const File &);
189 void read(bool readProperties, Properties::ReadStyle propertiesStyle);
193 ByteVector xiphCommentData() const;
194 long findPaddingBreak(long nextPageOffset, long targetOffset, bool *isLast);