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 virtual bool is_valid() const;
128 inline operator bool() const { return is_valid(); }
131 virtual bool set_md5_checking(bool value); ///< See FLAC__stream_decoder_set_md5_checking()
132 virtual bool set_metadata_respond(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_respond()
133 virtual bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_respond_application()
134 virtual bool set_metadata_respond_all(); ///< See FLAC__stream_decoder_set_metadata_respond_all()
135 virtual bool set_metadata_ignore(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_ignore()
136 virtual bool set_metadata_ignore_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_ignore_application()
137 virtual bool set_metadata_ignore_all(); ///< See FLAC__stream_decoder_set_metadata_ignore_all()
139 /* get_state() is not virtual since we want subclasses to be able to return their own state */
140 State get_state() const; ///< See FLAC__stream_decoder_get_state()
141 virtual bool get_md5_checking() const; ///< See FLAC__stream_decoder_get_md5_checking()
142 virtual FLAC__uint64 get_total_samples() const; ///< See FLAC__stream_decoder_get_total_samples()
143 virtual unsigned get_channels() const; ///< See FLAC__stream_decoder_get_channels()
144 virtual ::FLAC__ChannelAssignment get_channel_assignment() const; ///< See FLAC__stream_decoder_get_channel_assignment()
145 virtual unsigned get_bits_per_sample() const; ///< See FLAC__stream_decoder_get_bits_per_sample()
146 virtual unsigned get_sample_rate() const; ///< See FLAC__stream_decoder_get_sample_rate()
147 virtual unsigned get_blocksize() const; ///< See FLAC__stream_decoder_get_blocksize()
149 /** Initialize the instance; as with the C interface,
150 * init() should be called after construction and 'set'
151 * calls but before any of the 'process' calls.
153 * See FLAC__stream_decoder_init_stream().
155 virtual ::FLAC__StreamDecoderInitStatus init();
157 virtual void finish(); ///< See FLAC__stream_decoder_finish()
159 virtual bool flush(); ///< See FLAC__stream_decoder_flush()
160 virtual bool reset(); ///< See FLAC__stream_decoder_reset()
162 virtual bool process_single(); ///< See FLAC__stream_decoder_process_single()
163 virtual bool process_until_end_of_metadata(); ///< See FLAC__stream_decoder_process_until_end_of_metadata()
164 virtual bool process_until_end_of_stream(); ///< See FLAC__stream_decoder_process_until_end_of_stream()
165 virtual bool skip_single_frame(); ///< See FLAC__stream_decoder_skip_single_frame()
167 virtual bool seek_absolute(FLAC__uint64 sample); ///< See FLAC__stream_decoder_seek_absolute()
169 /// see FLAC__StreamDecoderReadCallback
170 virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
172 /// see FLAC__StreamDecoderSeekCallback
173 virtual ::FLAC__StreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
175 /// see FLAC__StreamDecoderTellCallback
176 virtual ::FLAC__StreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
178 /// see FLAC__StreamDecoderLengthCallback
179 virtual ::FLAC__StreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length);
181 /// see FLAC__StreamDecoderEofCallback
182 virtual bool eof_callback();
184 /// see FLAC__StreamDecoderWriteCallback
185 virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
187 /// see FLAC__StreamDecoderMetadataCallback
188 virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
190 /// see FLAC__StreamDecoderErrorCallback
191 virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
193 #if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
194 // lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
197 // hackery solely for the use of libOggFLAC++
198 Stream(::FLAC__StreamDecoder *);
200 ::FLAC__StreamDecoder *decoder_;
202 static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
203 static ::FLAC__StreamDecoderSeekStatus seek_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
204 static ::FLAC__StreamDecoderTellStatus tell_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
205 static ::FLAC__StreamDecoderLengthStatus length_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
206 static FLAC__bool eof_callback_(const ::FLAC__StreamDecoder *decoder, void *client_data);
207 static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
208 static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
209 static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
211 // Private and undefined so you can't use them:
212 Stream(const Stream &);
213 void operator=(const Stream &);
218 /** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
219 * \ingroup flacpp_decoder
222 * This class wraps the ::FLAC__StreamDecoder.
224 * See the \link flac_stream_decoder libFLAC stream decoder module \endlink
230 /** This class wraps the ::FLAC__StreamDecoder. If you are
231 * not decoding from a file, you may need to use
232 * FLAC::Decoder::Stream.
234 * The usage of this class is similar to FLAC__StreamDecoder,
235 * except instead of providing callbacks to
236 * FLAC__stream_decoder_init_FILE() or
237 * FLAC__stream_decoder_init_file(), you will inherit from this
238 * class and override the virtual callback functions with your
239 * own implementations, then call File::init(). The rest of
240 * the calls work the same as in the C layer.
242 * Only the write, and error callbacks from FLAC::Decoder::Stream
243 * are mandatory. The others are optional; this class provides
244 * full working implementations for all other callbacks and
247 class FLACPP_API File: public Stream {
252 /** Initialize the instance; as with the C interface,
253 * init() should be called after construction and 'set'
254 * calls but before any of the 'process' calls.
256 * See FLAC__stream_decoder_init_FILE() and
257 * FLAC__stream_decoder_init_file().
260 ::FLAC__StreamDecoderInitStatus init(FILE *file);
261 ::FLAC__StreamDecoderInitStatus init(const char *filename);
262 ::FLAC__StreamDecoderInitStatus init(const std::string &filename);
265 // this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
266 virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
268 // Private and undefined so you can't use them:
270 void operator=(const File &);