include/FLAC++/encoder.h

   1 /* libFLAC++ - Free Lossless Audio Codec library
   2  * Copyright (C) 2002,2003,2004  Josh Coalson
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  * - Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *
  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.
  14  *
  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.
  18  *
  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.
  30  */
  31
  32 #ifndef FLACPP__ENCODER_H
  33 #define FLACPP__ENCODER_H
  34
  35 #include "export.h"
  36
  37 #include "FLAC/file_encoder.h"
  38 #include "FLAC/seekable_stream_encoder.h"
  39 #include "FLAC/stream_encoder.h"
  40 #include "decoder.h"
  41
  42
  43 /** \file include/FLAC++/encoder.h
  44  *
  45  *  \brief
  46  *  This module contains the classes which implement the various
  47  *  encoders.
  48  *
  49  *  See the detailed documentation in the
  50  *  \link flacpp_encoder encoder \endlink module.
  51  */
  52
  53 /** \defgroup flacpp_encoder FLAC++/encoder.h: encoder classes
  54  *  \ingroup flacpp
  55  *
  56  *  \brief
  57  *  This module describes the three encoder layers provided by libFLAC++.
  58  *
  59  * The libFLAC++ encoder classes are object wrappers around their
  60  * counterparts in libFLAC.  All three encoding layers available in
  61  * libFLAC are also provided here.  The interface is very similar;
  62  * make sure to read the \link flac_encoder libFLAC encoder module \endlink.
  63  *
  64  * The only real difference here is that instead of passing in C function
  65  * pointers for callbacks, you inherit from the encoder class and provide
  66  * implementations for the callbacks in the derived class; because of this
  67  * there is no need for a 'client_data' property.
  68  */
  69
  70 namespace FLAC {
  71         namespace Encoder {
  72
  73                 // ============================================================
  74                 //
  75                 //  Equivalent: FLAC__StreamEncoder
  76                 //
  77                 // ============================================================
  78
  79                 /** \defgroup flacpp_stream_encoder FLAC++/encoder.h: stream encoder class
  80                  *  \ingroup flacpp_encoder
  81                  *
  82                  *  \brief
  83                  *  This class wraps the ::FLAC__StreamEncoder.
  84                  *
  85                  * See the \link flac_stream_encoder libFLAC stream encoder module \endlink.
  86                  *
  87                  * \{
  88                  */
  89
  90                 /** This class wraps the ::FLAC__StreamEncoder.
  91                  */
  92                 class FLACPP_API Stream {
  93                 public:
  94                         class FLACPP_API State {
  95                         public:
  96                                 inline State(::FLAC__StreamEncoderState state): state_(state) { }
  97                                 inline operator ::FLAC__StreamEncoderState() const { return state_; }
  98                                 inline const char *as_cstring() const { return ::FLAC__StreamEncoderStateString[state_]; }
  99                                 inline const char *resolved_as_cstring(const Stream &encoder) const { return ::FLAC__stream_encoder_get_resolved_state_string(encoder.encoder_); }
 100                         protected:
 101                                 ::FLAC__StreamEncoderState state_;
 102                         };
 103
 104                         Stream();
 105                         virtual ~Stream();
 106
 107                         bool is_valid() const;
 108                         inline operator bool() const { return is_valid(); }
 109
 110                         bool set_verify(bool value);
 111                         bool set_streamable_subset(bool value);
 112                         bool set_do_mid_side_stereo(bool value);
 113                         bool set_loose_mid_side_stereo(bool value);
 114                         bool set_channels(unsigned value);
 115                         bool set_bits_per_sample(unsigned value);
 116                         bool set_sample_rate(unsigned value);
 117                         bool set_blocksize(unsigned value);
 118                         bool set_max_lpc_order(unsigned value);
 119                         bool set_qlp_coeff_precision(unsigned value);
 120                         bool set_do_qlp_coeff_prec_search(bool value);
 121                         bool set_do_escape_coding(bool value);
 122                         bool set_do_exhaustive_model_search(bool value);
 123                         bool set_min_residual_partition_order(unsigned value);
 124                         bool set_max_residual_partition_order(unsigned value);
 125                         bool set_rice_parameter_search_dist(unsigned value);
 126                         bool set_total_samples_estimate(FLAC__uint64 value);
 127                         bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
 128
 129                         State    get_state() const;
 130                         Decoder::Stream::State get_verify_decoder_state() const;
 131                         void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
 132                         bool     get_verify() const;
 133                         bool     get_streamable_subset() const;
 134                         bool     get_do_mid_side_stereo() const;
 135                         bool     get_loose_mid_side_stereo() const;
 136                         unsigned get_channels() const;
 137                         unsigned get_bits_per_sample() const;
 138                         unsigned get_sample_rate() const;
 139                         unsigned get_blocksize() const;
 140                         unsigned get_max_lpc_order() const;
 141                         unsigned get_qlp_coeff_precision() const;
 142                         bool     get_do_qlp_coeff_prec_search() const;
 143                         bool     get_do_escape_coding() const;
 144                         bool     get_do_exhaustive_model_search() const;
 145                         unsigned get_min_residual_partition_order() const;
 146                         unsigned get_max_residual_partition_order() const;
 147                         unsigned get_rice_parameter_search_dist() const;
 148                         FLAC__uint64 get_total_samples_estimate() const;
 149
 150                         State init();
 151
 152                         void finish();
 153
 154                         bool process(const FLAC__int32 * const buffer[], unsigned samples);
 155                         bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
 156                 protected:
 157                         virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
 158                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 159
 160 #ifdef _MSC_VER
 161                 //@@@@@@ lame hack: some MSVC versions can't see a protected encoder_ from nested State::resolved_as_cstring(); fix properly later
 162                 public:
 163 #endif
 164                         ::FLAC__StreamEncoder *encoder_;
 165                 private:
 166                         static ::FLAC__StreamEncoderWriteStatus write_callback_(const ::FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
 167                         static void metadata_callback_(const ::FLAC__StreamEncoder *encoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 168
 169                         // Private and undefined so you can't use them:
 170                         Stream(const Stream &);
 171                         void operator=(const Stream &);
 172                 };
 173
 174                 /* \} */
 175
 176                 /** \defgroup flacpp_seekable_stream_encoder FLAC++/encoder.h: seekable stream encoder class
 177                  *  \ingroup flacpp_encoder
 178                  *
 179                  *  \brief
 180                  *  This class wraps the ::FLAC__SeekableStreamEncoder.
 181                  *
 182                  * See the \link flac_seekable_stream_encoder libFLAC seekable stream encoder module \endlink.
 183                  *
 184                  * \{
 185                  */
 186
 187                 /** This class wraps the ::FLAC__SeekableStreamEncoder.
 188                  */
 189                 class FLACPP_API SeekableStream {
 190                 public:
 191                         class FLACPP_API State {
 192                         public:
 193                                 inline State(::FLAC__SeekableStreamEncoderState state): state_(state) { }
 194                                 inline operator ::FLAC__SeekableStreamEncoderState() const { return state_; }
 195                                 inline const char *as_cstring() const { return ::FLAC__SeekableStreamEncoderStateString[state_]; }
 196                                 inline const char *resolved_as_cstring(const SeekableStream &encoder) const { return ::FLAC__seekable_stream_encoder_get_resolved_state_string(encoder.encoder_); }
 197                         protected:
 198                                 ::FLAC__SeekableStreamEncoderState state_;
 199                         };
 200
 201                         SeekableStream();
 202                         virtual ~SeekableStream();
 203
 204                         bool is_valid() const;
 205                         inline operator bool() const { return is_valid(); }
 206
 207                         bool set_verify(bool value);
 208                         bool set_streamable_subset(bool value);
 209                         bool set_do_mid_side_stereo(bool value);
 210                         bool set_loose_mid_side_stereo(bool value);
 211                         bool set_channels(unsigned value);
 212                         bool set_bits_per_sample(unsigned value);
 213                         bool set_sample_rate(unsigned value);
 214                         bool set_blocksize(unsigned value);
 215                         bool set_max_lpc_order(unsigned value);
 216                         bool set_qlp_coeff_precision(unsigned value);
 217                         bool set_do_qlp_coeff_prec_search(bool value);
 218                         bool set_do_escape_coding(bool value);
 219                         bool set_do_exhaustive_model_search(bool value);
 220                         bool set_min_residual_partition_order(unsigned value);
 221                         bool set_max_residual_partition_order(unsigned value);
 222                         bool set_rice_parameter_search_dist(unsigned value);
 223                         bool set_total_samples_estimate(FLAC__uint64 value);
 224                         bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
 225
 226                         State    get_state() const;
 227                         Stream::State get_stream_encoder_state() const;
 228                         Decoder::Stream::State get_verify_decoder_state() const;
 229                         void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
 230                         bool     get_verify() const;
 231                         bool     get_streamable_subset() const;
 232                         bool     get_do_mid_side_stereo() const;
 233                         bool     get_loose_mid_side_stereo() const;
 234                         unsigned get_channels() const;
 235                         unsigned get_bits_per_sample() const;
 236                         unsigned get_sample_rate() const;
 237                         unsigned get_blocksize() const;
 238                         unsigned get_max_lpc_order() const;
 239                         unsigned get_qlp_coeff_precision() const;
 240                         bool     get_do_qlp_coeff_prec_search() const;
 241                         bool     get_do_escape_coding() const;
 242                         bool     get_do_exhaustive_model_search() const;
 243                         unsigned get_min_residual_partition_order() const;
 244                         unsigned get_max_residual_partition_order() const;
 245                         unsigned get_rice_parameter_search_dist() const;
 246                         FLAC__uint64 get_total_samples_estimate() const;
 247
 248                         State init();
 249
 250                         void finish();
 251
 252                         bool process(const FLAC__int32 * const buffer[], unsigned samples);
 253                         bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
 254                 protected:
 255                         virtual ::FLAC__SeekableStreamEncoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
 256                         virtual ::FLAC__SeekableStreamEncoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
 257                         virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
 258
 259 #ifdef _MSC_VER
 260                 //@@@@@@ lame hack: some MSVC versions can't see a protected encoder_ from nested State::resolved_as_cstring(); fix properly later
 261                 public:
 262 #endif
 263                         ::FLAC__SeekableStreamEncoder *encoder_;
 264                 private:
 265                         static ::FLAC__SeekableStreamEncoderSeekStatus seek_callback_(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
 266                         static ::FLAC__SeekableStreamEncoderTellStatus tell_callback_(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
 267                         static ::FLAC__StreamEncoderWriteStatus write_callback_(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
 268
 269                         // Private and undefined so you can't use them:
 270                         SeekableStream(const SeekableStream &);
 271                         void operator=(const SeekableStream &);
 272                 };
 273
 274                 /* \} */
 275
 276                 /** \defgroup flacpp_file_encoder FLAC++/encoder.h: file encoder class
 277                  *  \ingroup flacpp_encoder
 278                  *
 279                  *  \brief
 280                  *  This class wraps the ::FLAC__FileEncoder.
 281                  *
 282                  * See the \link flac_file_encoder libFLAC file encoder module \endlink.
 283                  *
 284                  * \{
 285                  */
 286
 287                 /** This class wraps the ::FLAC__FileEncoder.
 288                  */
 289                 class FLACPP_API File {
 290                 public:
 291                         class FLACPP_API State {
 292                         public:
 293                                 inline State(::FLAC__FileEncoderState state): state_(state) { }
 294                                 inline operator ::FLAC__FileEncoderState() const { return state_; }
 295                                 inline const char *as_cstring() const { return ::FLAC__FileEncoderStateString[state_]; }
 296                                 inline const char *resolved_as_cstring(const File &encoder) const { return ::FLAC__file_encoder_get_resolved_state_string(encoder.encoder_); }
 297                         protected:
 298                                 ::FLAC__FileEncoderState state_;
 299                         };
 300
 301                         File();
 302                         virtual ~File();
 303
 304                         bool is_valid() const;
 305                         inline operator bool() const { return is_valid(); }
 306
 307                         bool set_verify(bool value);
 308                         bool set_streamable_subset(bool value);
 309                         bool set_do_mid_side_stereo(bool value);
 310                         bool set_loose_mid_side_stereo(bool value);
 311                         bool set_channels(unsigned value);
 312                         bool set_bits_per_sample(unsigned value);
 313                         bool set_sample_rate(unsigned value);
 314                         bool set_blocksize(unsigned value);
 315                         bool set_max_lpc_order(unsigned value);
 316                         bool set_qlp_coeff_precision(unsigned value);
 317                         bool set_do_qlp_coeff_prec_search(bool value);
 318                         bool set_do_escape_coding(bool value);
 319                         bool set_do_exhaustive_model_search(bool value);
 320                         bool set_min_residual_partition_order(unsigned value);
 321                         bool set_max_residual_partition_order(unsigned value);
 322                         bool set_rice_parameter_search_dist(unsigned value);
 323                         bool set_total_samples_estimate(FLAC__uint64 value);
 324                         bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
 325                         bool set_filename(const char *value);
 326
 327                         State    get_state() const;
 328                         SeekableStream::State get_seekable_stream_encoder_state() const;
 329                         Stream::State get_stream_encoder_state() const;
 330                         Decoder::Stream::State get_verify_decoder_state() const;
 331                         void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
 332                         bool     get_verify() const;
 333                         bool     get_streamable_subset() const;
 334                         bool     get_do_mid_side_stereo() const;
 335                         bool     get_loose_mid_side_stereo() const;
 336                         unsigned get_channels() const;
 337                         unsigned get_bits_per_sample() const;
 338                         unsigned get_sample_rate() const;
 339                         unsigned get_blocksize() const;
 340                         unsigned get_max_lpc_order() const;
 341                         unsigned get_qlp_coeff_precision() const;
 342                         bool     get_do_qlp_coeff_prec_search() const;
 343                         bool     get_do_escape_coding() const;
 344                         bool     get_do_exhaustive_model_search() const;
 345                         unsigned get_min_residual_partition_order() const;
 346                         unsigned get_max_residual_partition_order() const;
 347                         unsigned get_rice_parameter_search_dist() const;
 348                         FLAC__uint64 get_total_samples_estimate() const;
 349
 350                         State init();
 351
 352                         void finish();
 353
 354                         bool process(const FLAC__int32 * const buffer[], unsigned samples);
 355                         bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
 356                 protected:
 357                         virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate);
 358
 359 #ifdef _MSC_VER
 360                 //@@@@@@ lame hack: some MSVC versions can't see a protected encoder_ from nested State::resolved_as_cstring(); fix properly later
 361                 public:
 362 #endif
 363                         ::FLAC__FileEncoder *encoder_;
 364                 private:
 365                         static void progress_callback_(const ::FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
 366
 367                         // Private and undefined so you can't use them:
 368                         File(const Stream &);
 369                         void operator=(const Stream &);
 370                 };
 371
 372                 /* \} */
 373
 374         };
 375 };
 376
 377 #endif