include/FLAC/stream_encoder.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2000,2001  Josh Coalson
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA  02111-1307, USA.
  18  */
  19
  20 #ifndef FLAC__STREAM_ENCODER_H
  21 #define FLAC__STREAM_ENCODER_H
  22
  23 #include "format.h"
  24
  25 typedef enum {
  26         FLAC__STREAM_ENCODER_OK = 0,
  27         FLAC__STREAM_ENCODER_INVALID_NUMBER_OF_CHANNELS,
  28         FLAC__STREAM_ENCODER_INVALID_BITS_PER_SAMPLE,
  29         FLAC__STREAM_ENCODER_INVALID_SAMPLE_RATE,
  30         FLAC__STREAM_ENCODER_INVALID_BLOCK_SIZE,
  31         FLAC__STREAM_ENCODER_INVALID_QLP_COEFF_PRECISION,
  32         FLAC__STREAM_ENCODER_MID_SIDE_CHANNELS_MISMATCH,
  33         FLAC__STREAM_ENCODER_MID_SIDE_SAMPLE_SIZE_MISMATCH,
  34         FLAC__STREAM_ENCODER_ILLEGAL_MID_SIDE_FORCE,
  35         FLAC__STREAM_ENCODER_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
  36         FLAC__STREAM_ENCODER_NOT_STREAMABLE,
  37         FLAC__STREAM_ENCODER_FRAMING_ERROR,
  38         FLAC__STREAM_ENCODER_INVALID_SEEK_TABLE,
  39         FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING,
  40         FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_WRITING, /* that is, the write_callback returned an error */
  41         FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
  42         FLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
  43         FLAC__STREAM_ENCODER_UNINITIALIZED
  44 } FLAC__StreamEncoderState;
  45 extern const char *FLAC__StreamEncoderStateString[];
  46
  47 typedef enum {
  48         FLAC__STREAM_ENCODER_WRITE_OK = 0,
  49         FLAC__STREAM_ENCODER_WRITE_FATAL_ERROR
  50 } FLAC__StreamEncoderWriteStatus;
  51 extern const char *FLAC__StreamEncoderWriteStatusString[];
  52
  53 /***********************************************************************
  54  *
  55  * class FLAC__StreamEncoder
  56  *
  57  ***********************************************************************/
  58
  59 struct FLAC__StreamEncoderProtected;
  60 struct FLAC__StreamEncoderPrivate;
  61 typedef struct {
  62         struct FLAC__StreamEncoderProtected *protected;
  63         struct FLAC__StreamEncoderPrivate *private;
  64 } FLAC__StreamEncoder;
  65
  66 /***********************************************************************
  67  *
  68  * Class constructor/destructor
  69  *
  70  ***********************************************************************/
  71
  72 FLAC__StreamEncoder *FLAC__stream_encoder_new();
  73 void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
  74
  75 /***********************************************************************
  76  *
  77  * Public class method prototypes
  78  *
  79  ***********************************************************************/
  80
  81 /*
  82  * Initialize the instance; should be called after construction and
  83  * before any other calls.  Will set and return the encoder state,
  84  * which will be FLAC__STREAM_ENCODER_OK if initialization succeeded.
  85  */
  86 FLAC__StreamEncoderState FLAC__stream_encoder_init(
  87         FLAC__StreamEncoder *encoder,
  88         bool     streamable_subset,
  89         bool     do_mid_side_stereo,          /* 0 or 1; 1 only if channels==2 */
  90         bool     loose_mid_side_stereo,       /* 0 or 1; 1 only if channels==2 and do_mid_side_stereo==true */
  91         unsigned channels,                    /* must be <= FLAC__MAX_CHANNELS */
  92         unsigned bits_per_sample,             /* do not give the encoder wider data than what you specify here or bad things will happen! */
  93         unsigned sample_rate,
  94         unsigned blocksize,
  95         unsigned max_lpc_order,               /* 0 => encoder will not try general LPC, only fixed predictors; must be <= FLAC__MAX_LPC_ORDER */
  96         unsigned qlp_coeff_precision,         /* >= FLAC__MIN_QLP_COEFF_PRECISION, or 0 to let encoder select based on blocksize; */
  97                                               /* qlp_coeff_precision+bits_per_sample must be < 32 */
  98         bool     do_qlp_coeff_prec_search,    /* 0 => use qlp_coeff_precision, 1 => search around qlp_coeff_precision, take best */
  99         bool     do_exhaustive_model_search,  /* 0 => use estimated bits per residual for scoring, 1 => generate all, take shortest */
 100         unsigned min_residual_partition_order, /* 0 => estimate Rice parameter based on residual variance; >0 => partition residual, use parameter for each */
 101         unsigned max_residual_partition_order, /*      based on mean; min_ and max_ specify the min and max Rice partition order */
 102         unsigned rice_parameter_search_dist,  /* 0 => try only calc'd parameter k; else try all [k-dist..k+dist] parameters, use best */
 103         uint64   total_samples_estimate,      /* may be 0 if unknown.  this will be a placeholder in the metadata block until the actual total is calculated */
 104         const FLAC__StreamMetaData_SeekTable *seek_table, /* optional seek_table to prepend, 0 => no seek table */
 105         unsigned padding,                     /* size of PADDING block to add (goes after seek table); 0 => do not add a PADDING block */
 106         bool     last_metadata_is_last,       /* the value the encoder will use for the 'is_last' flag of the last metadata block it writes; set this to false */
 107                                               /* if you will be adding more metadata blocks before the audio frames, else true */
 108         FLAC__StreamEncoderWriteStatus (*write_callback)(const FLAC__StreamEncoder *encoder, const byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data),
 109         void (*metadata_callback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetaData *metadata, void *client_data),
 110         void *client_data
 111 );
 112 void FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder);
 113
 114 /*
 115  * various "get" methods
 116  */
 117 FLAC__StreamEncoderState FLAC__stream_encoder_state(const FLAC__StreamEncoder *encoder);
 118 bool     FLAC__stream_encoder_streamable_subset(const FLAC__StreamEncoder *encoder);
 119 bool     FLAC__stream_encoder_do_mid_side_stereo(const FLAC__StreamEncoder *encoder);
 120 bool     FLAC__stream_encoder_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder);
 121 unsigned FLAC__stream_encoder_channels(const FLAC__StreamEncoder *encoder);
 122 unsigned FLAC__stream_encoder_bits_per_sample(const FLAC__StreamEncoder *encoder);
 123 unsigned FLAC__stream_encoder_sample_rate(const FLAC__StreamEncoder *encoder);
 124 unsigned FLAC__stream_encoder_blocksize(const FLAC__StreamEncoder *encoder);
 125 unsigned FLAC__stream_encoder_max_lpc_order(const FLAC__StreamEncoder *encoder);
 126 unsigned FLAC__stream_encoder_qlp_coeff_precision(const FLAC__StreamEncoder *encoder);
 127 bool     FLAC__stream_encoder_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder);
 128 bool     FLAC__stream_encoder_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder);
 129 unsigned FLAC__stream_encoder_min_residual_partition_order(const FLAC__StreamEncoder *encoder);
 130 unsigned FLAC__stream_encoder_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
 131 unsigned FLAC__stream_encoder_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder);
 132
 133 /*
 134  * methods for encoding the data
 135  */
 136 bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const int32 *buf[], unsigned samples);
 137 bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const int32 buf[], unsigned samples);
 138
 139 #endif