1 /* libFLAC++ - Free Lossless Audio Codec library
2 * Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
8 * - Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
15 * - Neither the name of the Xiph.org Foundation nor the names of its
16 * contributors may be used to endorse or promote products derived from
17 * this software without specific prior written permission.
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 #ifndef FLACPP__DECODER_H
33 #define FLACPP__DECODER_H
38 #include "FLAC/stream_decoder.h"
41 /** \file include/FLAC++/decoder.h
44 * This module contains the classes which implement the various
47 * See the detailed documentation in the
48 * \link flacpp_decoder decoder \endlink module.
51 /** \defgroup flacpp_decoder FLAC++/decoder.h: decoder classes
55 * This module describes the decoder layers provided by libFLAC++.
57 * The libFLAC++ decoder classes are object wrappers around their
58 * counterparts in libFLAC. All decoding layers available in
59 * libFLAC are also provided here. The interface is very similar;
60 * make sure to read the \link flac_decoder libFLAC decoder module \endlink.
62 * There are only two significant differences here. First, instead of
63 * passing in C function pointers for callbacks, you inherit from the
64 * decoder class and provide implementations for the callbacks in your
65 * derived class; because of this there is no need for a 'client_data'
68 * Second, there are two stream decoder classes. FLAC::Decoder::Stream
69 * is used for the same cases that FLAC__stream_decoder_init_stream() is
70 * used, and FLAC::Decoder::File is used for the same cases that
71 * FLAC__stream_decoder_init_FILE() and FLAC__stream_decoder_init_file()
78 /** \defgroup flacpp_stream_decoder FLAC++/decoder.h: stream decoder class
79 * \ingroup flacpp_decoder
82 * This class wraps the ::FLAC__StreamDecoder.
84 * See the \link flac_stream_decoder libFLAC stream decoder module \endlink
90 /** This class wraps the ::FLAC__StreamDecoder. If you are
91 * decoding from a file, FLAC::Decoder::File may be more
94 * The usage of this class is similar to FLAC__StreamDecoder,
95 * except instead of providing callbacks to
96 * FLAC__stream_decoder_init_stream(), you will inherit from this
97 * class and override the virtual callback functions with your
98 * own implementations, then call Stream::init(). The rest of
99 * the calls work the same as in the C layer.
101 * Only the read, write, and error callbacks are mandatory. The
102 * others are optional; this class provides default
103 * implementations that do nothing. In order for seeking to work
104 * you must overide seek_callback(), tell_callback(),
105 * length_callback(), and eof_callback().
107 class FLACPP_API Stream {
109 class FLACPP_API State {
111 inline State(::FLAC__StreamDecoderState state): state_(state) { }
112 inline operator ::FLAC__StreamDecoderState() const { return state_; }
113 inline const char *as_cstring() const { return ::FLAC__StreamDecoderStateString[state_]; }
114 inline const char *resolved_as_cstring(const Stream &decoder) const { return ::FLAC__stream_decoder_get_resolved_state_string(decoder.decoder_); }
116 ::FLAC__StreamDecoderState state_;
122 /** Call after construction to check the that the object was created
123 * successfully. If not, use get_state() to find out why not.
127 bool is_valid() const;
128 inline operator bool() const { return is_valid(); }
131 bool set_md5_checking(bool value); ///< See FLAC__stream_decoder_set_md5_checking()
132 bool set_metadata_respond(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_respond()
133 bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_respond_application()
134 bool set_metadata_respond_all(); ///< See FLAC__stream_decoder_set_metadata_respond_all()
135 bool set_metadata_ignore(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_ignore()
136 bool set_metadata_ignore_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_ignore_application()
137 bool set_metadata_ignore_all(); ///< See FLAC__stream_decoder_set_metadata_ignore_all()
139 State get_state() const; ///< See FLAC__stream_decoder_get_state()
140 bool get_md5_checking() const; ///< See FLAC__stream_decoder_get_md5_checking()
141 FLAC__uint64 get_total_samples() const; ///< See FLAC__stream_decoder_get_total_samples()
142 unsigned get_channels() const; ///< See FLAC__stream_decoder_get_channels()
143 ::FLAC__ChannelAssignment get_channel_assignment() const; ///< See FLAC__stream_decoder_get_channel_assignment()
144 unsigned get_bits_per_sample() const; ///< See FLAC__stream_decoder_get_bits_per_sample()
145 unsigned get_sample_rate() const; ///< See FLAC__stream_decoder_get_sample_rate()
146 unsigned get_blocksize() const; ///< See FLAC__stream_decoder_get_blocksize()
148 /** Initialize the instance; as with the C interface,
149 * init() should be called after construction and 'set'
150 * calls but before any of the 'process' calls.
152 * See FLAC__stream_decoder_init_stream().
154 ::FLAC__StreamDecoderInitStatus init();
156 void finish(); ///< See FLAC__stream_decoder_finish()
158 bool flush(); ///< See FLAC__stream_decoder_flush()
159 bool reset(); ///< See FLAC__stream_decoder_reset()
161 bool process_single(); ///< See FLAC__stream_decoder_process_single()
162 bool process_until_end_of_metadata(); ///< See FLAC__stream_decoder_process_until_end_of_metadata()
163 bool process_until_end_of_stream(); ///< See FLAC__stream_decoder_process_until_end_of_stream()
164 bool skip_single_frame(); ///< See FLAC__stream_decoder_skip_single_frame()
166 bool seek_absolute(FLAC__uint64 sample); ///< See FLAC__stream_decoder_seek_absolute()
168 /// see FLAC__StreamDecoderReadCallback
169 virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
171 /// see FLAC__StreamDecoderSeekCallback
172 virtual ::FLAC__StreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
174 /// see FLAC__StreamDecoderTellCallback
175 virtual ::FLAC__StreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
177 /// see FLAC__StreamDecoderLengthCallback
178 virtual ::FLAC__StreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length);
180 /// see FLAC__StreamDecoderEofCallback
181 virtual bool eof_callback();
183 /// see FLAC__StreamDecoderWriteCallback
184 virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
186 /// see FLAC__StreamDecoderMetadataCallback
187 virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
189 /// see FLAC__StreamDecoderErrorCallback
190 virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
192 #if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
193 // lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
196 ::FLAC__StreamDecoder *decoder_;
198 static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
199 static ::FLAC__StreamDecoderSeekStatus seek_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
200 static ::FLAC__StreamDecoderTellStatus tell_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
201 static ::FLAC__StreamDecoderLengthStatus length_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
202 static FLAC__bool eof_callback_(const ::FLAC__StreamDecoder *decoder, void *client_data);
203 static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
204 static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
205 static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
207 // Private and undefined so you can't use them:
208 Stream(const Stream &);
209 void operator=(const Stream &);
214 /** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
215 * \ingroup flacpp_decoder
218 * This class wraps the ::FLAC__StreamDecoder.
220 * See the \link flac_stream_decoder libFLAC stream decoder module \endlink
226 /** This class wraps the ::FLAC__StreamDecoder. If you are
227 * not decoding from a file, you may need to use
228 * FLAC::Decoder::Stream.
230 * The usage of this class is similar to FLAC__StreamDecoder,
231 * except instead of providing callbacks to
232 * FLAC__stream_decoder_init_FILE() or
233 * FLAC__stream_decoder_init_file(), you will inherit from this
234 * class and override the virtual callback functions with your
235 * own implementations, then call File::init(). The rest of
236 * the calls work the same as in the C layer.
238 * Only the write, and error callbacks from FLAC::Decoder::Stream
239 * are mandatory. The others are optional; this class provides
240 * full working implementations for all other callbacks and
243 class FLACPP_API File: public Stream {
248 /** Initialize the instance; as with the C interface,
249 * init() should be called after construction and 'set'
250 * calls but before any of the 'process' calls.
252 * See FLAC__stream_decoder_init_FILE() and
253 * FLAC__stream_decoder_init_file().
256 ::FLAC__StreamDecoderInitStatus init(FILE *file);
257 ::FLAC__StreamDecoderInitStatus init(const char *filename);
258 ::FLAC__StreamDecoderInitStatus init(const std::string &filename);
261 // this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
262 virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
264 // Private and undefined so you can't use them:
266 void operator=(const File &);