include/FLAC++/encoder.h

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