lib/lame/lame.h

   1 /*
   2  *      Interface to MP3 LAME encoding engine
   3  *
   4  *      Copyright (c) 1999 Mark Taylor
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2, or (at your option)
   9  * any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; see the file COPYING.  If not, write to
  18  * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  19  */
  20
  21 /* $Id: lame.h,v 1.1 2002/04/28 17:30:20 kramm Exp $ */
  22
  23 #ifndef LAME_LAME_H
  24 #define LAME_LAME_H
  25
  26 #include <stdio.h>
  27 #include <stdarg.h>
  28
  29 #if defined(__cplusplus)
  30 extern "C" {
  31 #endif
  32
  33 #if defined(WIN32)
  34 #undef CDECL
  35 #define CDECL _cdecl
  36 #else
  37 #define CDECL
  38 #endif
  39
  40
  41 typedef enum vbr_mode_e {
  42   vbr_off=0,
  43   vbr_mt,               /* obsolete, same as vbr_mtrh */
  44   vbr_rh,
  45   vbr_abr,
  46   vbr_mtrh,
  47   vbr_max_indicator,    /* Don't use this! It's used for sanity checks.       */
  48   vbr_default=vbr_rh    /* change this to change the default VBR mode of LAME */
  49 } vbr_mode;
  50
  51
  52 /* MPEG modes */
  53 typedef enum MPEG_mode_e {
  54   STEREO = 0,
  55   JOINT_STEREO,
  56   DUAL_CHANNEL,   /* LAME doesn't supports this! */
  57   MONO,
  58   NOT_SET,
  59   MAX_INDICATOR   /* Don't use this! It's used for sanity checks. */
  60 } MPEG_mode;
  61
  62 /* Padding types */
  63 typedef enum Padding_type_e {
  64   PAD_NO = 0,
  65   PAD_ALL,
  66   PAD_ADJUST,
  67   PAD_MAX_INDICATOR   /* Don't use this! It's used for sanity checks. */
  68 } Padding_type;
  69
  70
  71
  72 struct lame_global_struct;
  73 typedef struct lame_global_struct lame_global_flags;
  74 typedef lame_global_flags *lame_t;
  75
  76
  77
  78
  79 /***********************************************************************
  80  *
  81  *  The LAME API
  82  *  These functions should be called, in this order, for each
  83  *  MP3 file to be encoded
  84  *
  85  ***********************************************************************/
  86
  87
  88 /*
  89  * REQUIRED:
  90  * initialize the encoder.  sets default for all encoder paramters,
  91  * returns -1 if some malloc()'s failed
  92  * otherwise returns 0
  93  */
  94 lame_global_flags * CDECL lame_init(void);
  95 /* obsolete version */
  96 int CDECL lame_init_old(lame_global_flags *);
  97
  98
  99 /*
 100  * OPTIONAL:
 101  * set as needed to override defaults
 102  */
 103
 104 /********************************************************************
 105  *  input stream description
 106  ***********************************************************************/
 107 // number of samples.  default = 2^32-1
 108 int CDECL lame_set_num_samples(lame_global_flags *, unsigned long);
 109 unsigned long CDECL lame_get_num_samples(const lame_global_flags *);
 110
 111 // input sample rate in Hz.  default = 44100hz
 112 int CDECL lame_set_in_samplerate(lame_global_flags *, int);
 113 int CDECL lame_get_in_samplerate(const lame_global_flags *);
 114
 115 // number of channels in input stream. default=2
 116 int CDECL lame_set_num_channels(lame_global_flags *, int);
 117 int CDECL lame_get_num_channels(const lame_global_flags *);
 118
 119 // scale the input by this amount before encoding.  default=0 (disabled)
 120 // (not used by decoding routines)
 121 int CDECL lame_set_scale(lame_global_flags *, float);
 122 float CDECL lame_get_scale(const lame_global_flags *);
 123
 124 // scale the channel 0 (left) input by this amount before encoding.
 125 //   default=0 (disabled)
 126 // (not used by decoding routines)
 127 int CDECL lame_set_scale_left(lame_global_flags *, float);
 128 float CDECL lame_get_scale_left(const lame_global_flags *);
 129
 130 // scale the channel 1 (right) input by this amount before encoding.
 131 //   default=0 (disabled)
 132 // (not used by decoding routines)
 133 int CDECL lame_set_scale_right(lame_global_flags *, float);
 134 float CDECL lame_get_scale_right(const lame_global_flags *);
 135
 136 // output sample rate in Hz.  default = 0, which means LAME picks best value
 137 // based on the amount of compression.  MPEG only allows:
 138 // MPEG1    32, 44.1,   48khz
 139 // MPEG2    16, 22.05,  24
 140 // MPEG2.5   8, 11.025, 12
 141 // (not used by decoding routines)
 142 int CDECL lame_set_out_samplerate(lame_global_flags *, int);
 143 int CDECL lame_get_out_samplerate(const lame_global_flags *);
 144
 145
 146 /********************************************************************
 147  *  general control parameters
 148  ***********************************************************************/
 149 // 1=cause LAME to collect data for an MP3 frame analyzer. default=0
 150 int CDECL lame_set_analysis(lame_global_flags *, int);
 151 int CDECL lame_get_analysis(const lame_global_flags *);
 152
 153 // 1 = write a Xing VBR header frame.
 154 // default = 1 for VBR/ABR modes, 0 for CBR mode
 155 // this variable must have been added by a Hungarian notation Windows programmer :-)
 156 int CDECL lame_set_bWriteVbrTag(lame_global_flags *, int);
 157 int CDECL lame_get_bWriteVbrTag(const lame_global_flags *);
 158
 159 // 1=decode only.  use lame/mpglib to convert mp3/ogg to wav.  default=0
 160 int CDECL lame_set_decode_only(lame_global_flags *, int);
 161 int CDECL lame_get_decode_only(const lame_global_flags *);
 162
 163 // 1=encode a Vorbis .ogg file.  default=0
 164 int CDECL lame_set_ogg(lame_global_flags *, int);
 165 int CDECL lame_get_ogg(const lame_global_flags *);
 166
 167 // internal algorithm selection.  True quality is determined by the bitrate
 168 // but this variable will effect quality by selecting expensive or cheap algorithms.
 169 // quality=0..9.  0=best (very slow).  9=worst.
 170 // recommended:  2     near-best quality, not too slow
 171 //               5     good quality, fast
 172 //               7     ok quality, really fast
 173 int CDECL lame_set_quality(lame_global_flags *, int);
 174 int CDECL lame_get_quality(const lame_global_flags *);
 175
 176 // mode = 0,1,2,3 = stereo, jstereo, dual channel (not supported), mono
 177 // default: lame picks based on compression ration and input channels
 178 int CDECL lame_set_mode(lame_global_flags *, MPEG_mode);
 179 MPEG_mode CDECL lame_get_mode(const lame_global_flags *);
 180
 181 // mode_automs.  Use a M/S mode with a switching threshold based on
 182 // compression ratio
 183 // default = 0 (disabled)
 184 int CDECL lame_set_mode_automs(lame_global_flags *, int);
 185 int CDECL lame_get_mode_automs(const lame_global_flags *);
 186
 187 // force_ms.  Force M/S for all frames.  For testing only.
 188 // default = 0 (disabled)
 189 int CDECL lame_set_force_ms(lame_global_flags *, int);
 190 int CDECL lame_get_force_ms(const lame_global_flags *);
 191
 192 // use free_format?  default = 0 (disabled)
 193 int CDECL lame_set_free_format(lame_global_flags *, int);
 194 int CDECL lame_get_free_format(const lame_global_flags *);
 195
 196 /*
 197  * OPTIONAL:
 198  * Set printf like error/debug/message reporting functions.
 199  * The second argument has to be a pointer to a function which looks like
 200  *   void my_debugf(const char *format, va_list ap)
 201  *   {
 202  *       (void) vfprintf(stdout, format, ap);
 203  *   }
 204  * If you use NULL as the value of the pointer in the set function, the
 205  * lame buildin function will be used (prints to stderr).
 206  * To quiet any output you have to replace the body of the example function
 207  * with just "return;" and use it in the set function.
 208  */
 209 int CDECL lame_set_errorf(lame_global_flags *,
 210                           void (*func)(const char *, va_list));
 211 int CDECL lame_set_debugf(lame_global_flags *,
 212                           void (*func)(const char *, va_list));
 213 int CDECL lame_set_msgf  (lame_global_flags *,
 214                           void (*func)(const char *, va_list));
 215
 216
 217
 218 /* set one of brate compression ratio.  default is compression ratio of 11.  */
 219 int CDECL lame_set_brate(lame_global_flags *, int);
 220 int CDECL lame_get_brate(const lame_global_flags *);
 221 int CDECL lame_set_compression_ratio(lame_global_flags *, float);
 222 float CDECL lame_get_compression_ratio(const lame_global_flags *);
 223
 224 /********************************************************************
 225  *  frame params
 226  ***********************************************************************/
 227 // mark as copyright.  default=0
 228 int CDECL lame_set_copyright(lame_global_flags *, int);
 229 int CDECL lame_get_copyright(const lame_global_flags *);
 230
 231 // mark as original.  default=1
 232 int CDECL lame_set_original(lame_global_flags *, int);
 233 int CDECL lame_get_original(const lame_global_flags *);
 234
 235 // error_protection.  Use 2 bytes from each frame for CRC checksum. default=0
 236 int CDECL lame_set_error_protection(lame_global_flags *, int);
 237 int CDECL lame_get_error_protection(const lame_global_flags *);
 238
 239 // padding_type.  0=pad no frames  1=pad all frames 2=adjust padding(default)
 240 int CDECL lame_set_padding_type(lame_global_flags *, Padding_type);
 241 Padding_type CDECL lame_get_padding_type(const lame_global_flags *);
 242
 243 // MP3 'private extension' bit  Meaningless.  default=0
 244 int CDECL lame_set_extension(lame_global_flags *, int);
 245 int CDECL lame_get_extension(const lame_global_flags *);
 246
 247 // enforce strict ISO compliance.  default=0
 248 int CDECL lame_set_strict_ISO(lame_global_flags *, int);
 249 int CDECL lame_get_strict_ISO(const lame_global_flags *);
 250
 251
 252 /********************************************************************
 253  * quantization/noise shaping
 254  ***********************************************************************/
 255
 256 // disable the bit reservoir. For testing only. default=0
 257 int CDECL lame_set_disable_reservoir(lame_global_flags *, int);
 258 int CDECL lame_get_disable_reservoir(const lame_global_flags *);
 259
 260 // select a different "best quantization" function. default=0
 261 int CDECL lame_set_experimentalX(lame_global_flags *, int);
 262 int CDECL lame_get_experimentalX(const lame_global_flags *);
 263
 264 // another experimental option.  for testing only
 265 int CDECL lame_set_experimentalY(lame_global_flags *, int);
 266 int CDECL lame_get_experimentalY(const lame_global_flags *);
 267
 268 // another experimental option.  for testing only
 269 int CDECL lame_set_experimentalZ(lame_global_flags *, int);
 270 int CDECL lame_get_experimentalZ(const lame_global_flags *);
 271
 272 // Naoki's psycho acoustic model.  default=0
 273 int CDECL lame_set_exp_nspsytune(lame_global_flags *, int);
 274 int CDECL lame_get_exp_nspsytune(const lame_global_flags *);
 275
 276
 277
 278 /********************************************************************
 279  * VBR control
 280  ***********************************************************************/
 281 // Types of VBR.  default = vbr_off = CBR
 282 int CDECL lame_set_VBR(lame_global_flags *, vbr_mode);
 283 vbr_mode CDECL lame_get_VBR(const lame_global_flags *);
 284
 285 // VBR quality level.  0=highest  9=lowest
 286 int CDECL lame_set_VBR_q(lame_global_flags *, int);
 287 int CDECL lame_get_VBR_q(const lame_global_flags *);
 288
 289 // Ignored except for VBR=vbr_abr (ABR mode)
 290 int CDECL lame_set_VBR_mean_bitrate_kbps(lame_global_flags *, int);
 291 int CDECL lame_get_VBR_mean_bitrate_kbps(const lame_global_flags *);
 292
 293 int CDECL lame_set_VBR_min_bitrate_kbps(lame_global_flags *, int);
 294 int CDECL lame_get_VBR_min_bitrate_kbps(const lame_global_flags *);
 295
 296 int CDECL lame_set_VBR_max_bitrate_kbps(lame_global_flags *, int);
 297 int CDECL lame_get_VBR_max_bitrate_kbps(const lame_global_flags *);
 298
 299 // 1=stricetly enforce VBR_min_bitrate.  Normally it will be violated for
 300 // analog silence
 301 int CDECL lame_set_VBR_hard_min(lame_global_flags *, int);
 302 int CDECL lame_get_VBR_hard_min(const lame_global_flags *);
 303
 304
 305 /********************************************************************
 306  * Filtering control
 307  ***********************************************************************/
 308 // freq in Hz to apply lowpass. Default = 0 = lame chooses.  -1 = disabled
 309 int CDECL lame_set_lowpassfreq(lame_global_flags *, int);
 310 int CDECL lame_get_lowpassfreq(const lame_global_flags *);
 311 // width of transition band, in Hz.  Default = one polyphase filter band
 312 int CDECL lame_set_lowpasswidth(lame_global_flags *, int);
 313 int CDECL lame_get_lowpasswidth(const lame_global_flags *);
 314
 315 // freq in Hz to apply highpass. Default = 0 = lame chooses.  -1 = disabled
 316 int CDECL lame_set_highpassfreq(lame_global_flags *, int);
 317 int CDECL lame_get_highpassfreq(const lame_global_flags *);
 318 // width of transition band, in Hz.  Default = one polyphase filter band
 319 int CDECL lame_set_highpasswidth(lame_global_flags *, int);
 320 int CDECL lame_get_highpasswidth(const lame_global_flags *);
 321
 322
 323 /********************************************************************
 324  * psycho acoustics and other arguments which you should not change
 325  * unless you know what you are doing
 326  ***********************************************************************/
 327 // only use ATH for masking
 328 int CDECL lame_set_ATHonly(lame_global_flags *, int);
 329 int CDECL lame_get_ATHonly(const lame_global_flags *);
 330
 331 // only use ATH for short blocks
 332 int CDECL lame_set_ATHshort(lame_global_flags *, int);
 333 int CDECL lame_get_ATHshort(const lame_global_flags *);
 334
 335 // disable ATH
 336 int CDECL lame_set_noATH(lame_global_flags *, int);
 337 int CDECL lame_get_noATH(const lame_global_flags *);
 338
 339 // select ATH formula
 340 int CDECL lame_set_ATHtype(lame_global_flags *, int);
 341 int CDECL lame_get_ATHtype(const lame_global_flags *);
 342
 343 // lower ATH by this many db
 344 int CDECL lame_set_ATHlower(lame_global_flags *, float);
 345 float CDECL lame_get_ATHlower(const lame_global_flags *);
 346
 347 // select ATH adaptive adjustment type
 348 int CDECL lame_set_athaa_type( lame_global_flags *, int);
 349 int CDECL lame_get_athaa_type( const lame_global_flags *);
 350
 351 // select the loudness approximation used by the ATH adaptive auto-leveling
 352 int CDECL lame_set_athaa_loudapprox( lame_global_flags *, int);
 353 int CDECL lame_get_athaa_loudapprox( const lame_global_flags *);
 354
 355 // adjust (in dB) the point below which adaptive ATH level adjustment occurs
 356 int CDECL lame_set_athaa_sensitivity( lame_global_flags *, float);
 357 float CDECL lame_get_athaa_sensitivity( const lame_global_flags* );
 358
 359 // predictability limit (ISO tonality formula)
 360 int CDECL lame_set_cwlimit(lame_global_flags *, int);
 361 int CDECL lame_get_cwlimit(const lame_global_flags *);
 362
 363 // allow blocktypes to differ between channels?
 364 // default: 0 for jstereo, 1 for stereo
 365 int CDECL lame_set_allow_diff_short(lame_global_flags *, int);
 366 int CDECL lame_get_allow_diff_short(const lame_global_flags *);
 367
 368 // use temporal masking effect (default = 1)
 369 int CDECL lame_set_useTemporal(lame_global_flags *, int);
 370 int CDECL lame_get_useTemporal(const lame_global_flags *);
 371
 372 // disable short blocks
 373 int CDECL lame_set_no_short_blocks(lame_global_flags *, int);
 374 int CDECL lame_get_no_short_blocks(const lame_global_flags *);
 375
 376 // force short blocks
 377 int CDECL lame_set_force_short_blocks(lame_global_flags *, int);
 378 int CDECL lame_get_force_short_blocks(const lame_global_flags *);
 379
 380 /* Input PCM is emphased PCM (for instance from one of the rarely
 381    emphased CDs), it is STRONGLY not recommended to use this, because
 382    psycho does not take it into account, and last but not least many decoders
 383    ignore these bits */
 384 int CDECL lame_set_emphasis(lame_global_flags *, int);
 385 int CDECL lame_get_emphasis(const lame_global_flags *);
 386
 387
 388
 389 /************************************************************************/
 390 /* internal variables, cannot be set...                                 */
 391 /* provided because they may be of use to calling application           */
 392 /************************************************************************/
 393 // version  0=MPEG-2  1=MPEG-1  (2=MPEG-2.5)
 394 int CDECL lame_get_version(const lame_global_flags *);
 395
 396 // encoder delay
 397 int CDECL lame_get_encoder_delay(const lame_global_flags *);
 398
 399 // padding appended to the input to make sure decoder can fully decode
 400 // all input.  Note that this value can only be calculated during the
 401 // call to lame_encoder_flush().  Before lame_encoder_flush() has
 402 // been called, the value of encoder_padding = 0.
 403 int CDECL lame_get_encoder_padding(const lame_global_flags *);
 404
 405 // size of MPEG frame
 406 int CDECL lame_get_framesize(const lame_global_flags *);
 407
 408 // number of PCM samples buffered, but not yet encoded to mp3 data.
 409 int CDECL lame_get_mf_samples_to_encode( const lame_global_flags*  gfp );
 410
 411 // size (bytes) of mp3 data buffered, but not yet encoded.
 412 // this is the number of bytes which would be output by a call to
 413 // lame_encode_flush_nogap.  NOTE: lame_encode_flush() will return
 414 // more bytes than this because it will encode the reamining buffered
 415 // PCM samples before flushing the mp3 buffers.
 416 int CDECL lame_get_size_mp3buffer( const lame_global_flags*  gfp );
 417
 418 // number of frames encoded so far
 419 int CDECL lame_get_frameNum(const lame_global_flags *);
 420
 421 // lame's estimate of the total number of frames to be encoded
 422 // only valid if calling program set num_samples
 423 int CDECL lame_get_totalframes(const lame_global_flags *);
 424
 425
 426
 427
 428
 429
 430
 431
 432 /*
 433  * REQUIRED:
 434  * sets more internal configuration based on data provided above.
 435  * returns -1 if something failed.
 436  */
 437 int CDECL lame_init_params(lame_global_flags * const );
 438
 439
 440 /*
 441  * OPTIONAL:
 442  * get the version number, in a string. of the form:
 443  * "3.63 (beta)" or just "3.63".
 444  */
 445 const char*  CDECL get_lame_version       ( void );
 446 const char*  CDECL get_lame_short_version ( void );
 447 const char*  CDECL get_lame_very_short_version ( void );
 448 const char*  CDECL get_psy_version        ( void );
 449 const char*  CDECL get_lame_url           ( void );
 450
 451 /*
 452  * OPTIONAL:
 453  * get the version numbers in numerical form.
 454  */
 455 typedef struct {
 456     /* generic LAME version */
 457     int major;
 458     int minor;
 459     int alpha;               /* 0 if not an alpha version                  */
 460     int beta;                /* 0 if not a beta version                    */
 461
 462     /* version of the psy model */
 463     int psy_major;
 464     int psy_minor;
 465     int psy_alpha;           /* 0 if not an alpha version                  */
 466     int psy_beta;            /* 0 if not a beta version                    */
 467
 468     /* compile time features */
 469     const char *features;    /* Don't make assumptions about the contents! */
 470 } lame_version_t;
 471 void CDECL get_lame_version_numerical ( lame_version_t *const );
 472
 473
 474 /*
 475  * OPTIONAL:
 476  * print internal lame configuration to message handler
 477  */
 478 void CDECL lame_print_config(const lame_global_flags*  gfp);
 479
 480 void CDECL lame_print_internals( const lame_global_flags *gfp);
 481
 482
 483 /*
 484  * input pcm data, output (maybe) mp3 frames.
 485  * This routine handles all buffering, resampling and filtering for you.
 486  *
 487  * return code     number of bytes output in mp3buf. Can be 0
 488  *                 -1:  mp3buf was too small
 489  *                 -2:  malloc() problem
 490  *                 -3:  lame_init_params() not called
 491  *                 -4:  psycho acoustic problems
 492  *                 -5:  ogg cleanup encoding error
 493  *                 -6:  ogg frame encoding error
 494  *
 495  * The required mp3buf_size can be computed from num_samples,
 496  * samplerate and encoding rate, but here is a worst case estimate:
 497  *
 498  * mp3buf_size in bytes = 1.25*num_samples + 7200
 499  *
 500  * I think a tighter bound could be:  (mt, March 2000)
 501  * MPEG1:
 502  *    num_samples*(bitrate/8)/samplerate + 4*1152*(bitrate/8)/samplerate + 512
 503  * MPEG2:
 504  *    num_samples*(bitrate/8)/samplerate + 4*576*(bitrate/8)/samplerate + 256
 505  *
 506  * but test first if you use that!
 507  *
 508  * set mp3buf_size = 0 and LAME will not check if mp3buf_size is
 509  * large enough.
 510  *
 511  * NOTE:
 512  * if gfp->num_channels=2, but gfp->mode = 3 (mono), the L & R channels
 513  * will be averaged into the L channel before encoding only the L channel
 514  * This will overwrite the data in buffer_l[] and buffer_r[].
 515  *
 516 */
 517 int CDECL lame_encode_buffer (
 518         lame_global_flags*  gfp,           /* global context handle         */
 519         const short int     buffer_l [],   /* PCM data for left channel     */
 520         const short int     buffer_r [],   /* PCM data for right channel    */
 521         const int           nsamples,      /* number of samples per channel */
 522         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 523         const int           mp3buf_size ); /* number of valid octets in this
 524                                               stream                        */
 525
 526 /*
 527  * as above, but input has L & R channel data interleaved.
 528  * NOTE:
 529  * num_samples = number of samples in the L (or R)
 530  * channel, not the total number of samples in pcm[]
 531  */
 532 int CDECL lame_encode_buffer_interleaved(
 533         lame_global_flags*  gfp,           /* global context handlei        */
 534         short int           pcm[],         /* PCM data for left and right
 535                                               channel, interleaved          */
 536         int                 num_samples,   /* number of samples per channel,
 537                                               _not_ number of samples in
 538                                               pcm[]                         */
 539         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 540         int                 mp3buf_size ); /* number of valid octets in this
 541                                               stream                        */
 542
 543
 544 /* as lame_encode_buffer, but for 'float's.
 545  * !! NOTE: !! data must still be scaled to be in the same range as
 546  * short int, +/- 32768
 547  */
 548 int CDECL lame_encode_buffer_float(
 549         lame_global_flags*  gfp,           /* global context handle         */
 550         const float     buffer_l [],       /* PCM data for left channel     */
 551         const float     buffer_r [],       /* PCM data for right channel    */
 552         const int           nsamples,      /* number of samples per channel */
 553         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 554         const int           mp3buf_size ); /* number of valid octets in this
 555                                               stream                        */
 556
 557
 558 /* as lame_encode_buffer, but for long's
 559  * !! NOTE: !! data must still be scaled to be in the same range as
 560  * short int, +/- 32768
 561  *
 562  * This scaling was a mistake (doesn't allow one to exploit full
 563  * precision of type 'long'.  Use lame_encode_buffer_long2() instead.
 564  *
 565  */
 566 int CDECL lame_encode_buffer_long(
 567         lame_global_flags*  gfp,           /* global context handle         */
 568         const long     buffer_l [],       /* PCM data for left channel     */
 569         const long     buffer_r [],       /* PCM data for right channel    */
 570         const int           nsamples,      /* number of samples per channel */
 571         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 572         const int           mp3buf_size ); /* number of valid octets in this
 573                                               stream                        */
 574
 575 /* Same as lame_encode_buffer_long(), but with correct scaling.
 576  * !! NOTE: !! data must still be scaled to be in the same range as
 577  * type 'long'.   Data should be in the range:  +/- 2^(8*size(long)-1)
 578  *
 579  */
 580 int CDECL lame_encode_buffer_long2(
 581         lame_global_flags*  gfp,           /* global context handle         */
 582         const long     buffer_l [],       /* PCM data for left channel     */
 583         const long     buffer_r [],       /* PCM data for right channel    */
 584         const int           nsamples,      /* number of samples per channel */
 585         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 586         const int           mp3buf_size ); /* number of valid octets in this
 587                                               stream                        */
 588
 589 /* as lame_encode_buffer, but for int's
 590  * !! NOTE: !! input should be scaled to the maximum range of 'int'
 591  * If int is 4 bytes, then the values should range from
 592  * +/- 2147483648.
 593  *
 594  * This routine does not (and cannot, without loosing precision) use
 595  * the same scaling as the rest of the lame_encode_buffer() routines.
 596  *
 597  */
 598 int CDECL lame_encode_buffer_int(
 599         lame_global_flags*  gfp,           /* global context handle         */
 600         const int      buffer_l [],       /* PCM data for left channel     */
 601         const int      buffer_r [],       /* PCM data for right channel    */
 602         const int           nsamples,      /* number of samples per channel */
 603         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 604         const int           mp3buf_size ); /* number of valid octets in this
 605                                               stream                        */
 606
 607
 608
 609
 610
 611 /*
 612  * REQUIRED:
 613  * lame_encode_flush will flush the intenal PCM buffers, padding with
 614  * 0's to make sure the final frame is complete, and then flush
 615  * the internal MP3 buffers, and thus may return a
 616  * final few mp3 frames.  'mp3buf' should be at least 7200 bytes long
 617  * to hold all possible emitted data.
 618  *
 619  * will also write id3v1 tags (if any) into the bitstream
 620  *
 621  * return code = number of bytes output to mp3buf. Can be 0
 622  */
 623 int CDECL lame_encode_flush(
 624         lame_global_flags *  gfp,    /* global context handle                 */
 625         unsigned char*       mp3buf, /* pointer to encoded MP3 stream         */
 626         int                  size);  /* number of valid octets in this stream */
 627
 628 /*
 629  * OPTIONAL:
 630  * lame_encode_flush_nogap will flush the internal mp3 buffers and pad
 631  * the last frame with ancillary data so it is a complete mp3 frame.
 632  *
 633  * 'mp3buf' should be at least 7200 bytes long
 634  * to hold all possible emitted data.
 635  *
 636  * After a call to this routine, the outputed mp3 data is complete, but
 637  * you may continue to encode new PCM samples and write future mp3 data
 638  * to a different file.  The two mp3 files will play back with no gaps
 639  * if they are concatenated together.
 640  *
 641  * This routine will NOT write id3v1 tags into the bitstream.
 642  *
 643  * return code = number of bytes output to mp3buf. Can be 0
 644  */
 645 int CDECL lame_encode_flush_nogap(
 646         lame_global_flags *  gfp,    /* global context handle                 */
 647         unsigned char*       mp3buf, /* pointer to encoded MP3 stream         */
 648         int                  size);  /* number of valid octets in this stream */
 649
 650 /*
 651  * OPTIONAL:
 652  * Normally, this is called by lame_init_params().  It writes id3v2 and
 653  * Xing headers into the front of the bitstream, and sets frame counters
 654  * and bitrate histogram data to 0.  You can also call this after
 655  * lame_encode_flush_nogap().
 656  */
 657 int CDECL lame_init_bitstream(
 658         lame_global_flags *  gfp);    /* global context handle                 */
 659
 660
 661
 662 /*
 663  * OPTIONAL:    some simple statistics
 664  * a bitrate histogram to visualize the distribution of used frame sizes
 665  * a stereo mode histogram to visualize the distribution of used stereo
 666  *   modes, useful in joint-stereo mode only
 667  *   0: LR    left-right encoded
 668  *   1: LR-I  left-right and intensity encoded (currently not supported)
 669  *   2: MS    mid-side encoded
 670  *   3: MS-I  mid-side and intensity encoded (currently not supported)
 671  *
 672  * attention: don't call them after lame_encode_finish
 673  * suggested: lame_encode_flush -> lame_*_hist -> lame_close
 674  */
 675
 676 void CDECL lame_bitrate_hist(
 677         const lame_global_flags *const gfp,
 678               int                      bitrate_count[14] );
 679 void CDECL lame_bitrate_kbps(
 680         const lame_global_flags *const gfp,
 681               int                      bitrate_kbps [14] );
 682 void CDECL lame_stereo_mode_hist(
 683         const lame_global_flags *const gfp,
 684               int                      stereo_mode_count[4] );
 685
 686 void CDECL lame_bitrate_stereo_mode_hist (
 687         const lame_global_flags * const gfp,
 688         int  bitrate_stmode_count [14] [4] );
 689
 690
 691 /*
 692  * OPTIONAL:
 693  * lame_mp3_tags_fid will append a Xing VBR tag to the mp3 file with file
 694  * pointer fid.  These calls perform forward and backwards seeks, so make
 695  * sure fid is a real file.  Make sure lame_encode_flush has been called,
 696  * and all mp3 data has been written to the file before calling this
 697  * function.
 698  * NOTE:
 699  * if VBR  tags are turned off by the user, or turned off by LAME because
 700  * the output is not a regular file, this call does nothing
 701 */
 702 void CDECL lame_mp3_tags_fid(lame_global_flags *,FILE* fid);
 703
 704
 705 /*
 706  * REQUIRED:
 707  * final call to free all remaining buffers
 708  */
 709 int  CDECL lame_close (lame_global_flags *);
 710
 711 /*
 712  * OBSOLETE:
 713  * lame_encode_finish combines lame_encode_flush() and lame_close() in
 714  * one call.  However, once this call is made, the statistics routines
 715  * will no longer work because the data will have been cleared
 716  */
 717 int CDECL lame_encode_finish(
 718         lame_global_flags*  gfp,
 719         unsigned char*      mp3buf,
 720         int                 size );
 721
 722
 723
 724
 725
 726
 727
 728 /*********************************************************************
 729  *
 730  * decoding
 731  *
 732  * a simple interface to mpglib, part of mpg123, is also included if
 733  * libmp3lame is compiled with HAVE_MPGLIB
 734  *
 735  *********************************************************************/
 736 typedef struct {
 737   int header_parsed;   /* 1 if header was parsed and following data was
 738                           computed                                       */
 739   int stereo;          /* number of channels                             */
 740   int samplerate;      /* sample rate                                    */
 741   int bitrate;         /* bitrate                                        */
 742   int mode;            /* mp3 frame type                                 */
 743   int mode_ext;        /* mp3 frame type                                 */
 744   int framesize;       /* number of samples per mp3 frame                */
 745
 746   /* this data is only computed if mpglib detects a Xing VBR header */
 747   unsigned long nsamp; /* number of samples in mp3 file.                 */
 748   int totalframes;     /* total number of frames in mp3 file             */
 749
 750   /* this data is not currently computed by the mpglib routines */
 751   int framenum;        /* frames decoded counter                         */
 752 } mp3data_struct;
 753
 754
 755 /* required call to initialize decoder */
 756 int CDECL lame_decode_init(void);
 757
 758 /*********************************************************************
 759  * input 1 mp3 frame, output (maybe) pcm data.
 760  * lame_decode() return code:
 761  *   -1: error
 762  *    0: need more data
 763  *  n>0: size of pcm output
 764  *********************************************************************/
 765 int CDECL lame_decode(
 766         unsigned char *  mp3buf,
 767         int              len,
 768         short            pcm_l[],
 769         short            pcm_r[] );
 770
 771 /* same as lame_decode, and also returns mp3 header data */
 772 int CDECL lame_decode_headers(
 773         unsigned char*   mp3buf,
 774         int              len,
 775         short            pcm_l[],
 776         short            pcm_r[],
 777         mp3data_struct*  mp3data );
 778
 779 /* same as lame_decode, but returns at most one frame */
 780 int CDECL lame_decode1(
 781         unsigned char*  mp3buf,
 782         int             len,
 783         short           pcm_l[],
 784         short           pcm_r[] );
 785
 786 /* same as lame_decode1, but returns at most one frame and mp3 header data */
 787 int CDECL lame_decode1_headers(
 788         unsigned char*   mp3buf,
 789         int              len,
 790         short            pcm_l[],
 791         short            pcm_r[],
 792         mp3data_struct*  mp3data );
 793
 794 /* same as lame_decode1_headers, but also returns enc_delay and enc_padding
 795    from VBR Info tag, (-1 if no info tag was found) */
 796 int CDECL lame_decode1_headersB(
 797         unsigned char*   mp3buf,
 798         int              len,
 799         short            pcm_l[],
 800         short            pcm_r[],
 801         mp3data_struct*  mp3data,
 802         int              *enc_delay,
 803         int              *enc_padding );
 804
 805
 806
 807
 808
 809 /*********************************************************************
 810  *
 811  * id3tag stuff
 812  *
 813  *********************************************************************/
 814
 815 /*
 816  * id3tag.h -- Interface to write ID3 version 1 and 2 tags.
 817  *
 818  * Copyright (C) 2000 Don Melton.
 819  *
 820  * This library is free software; you can redistribute it and/or
 821  * modify it under the terms of the GNU Library General Public
 822  * License as published by the Free Software Foundation; either
 823  * version 2 of the License, or (at your option) any later version.
 824  *
 825  * This library is distributed in the hope that it will be useful,
 826  * but WITHOUT ANY WARRANTY; without even the implied warranty of
 827  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 828  * Library General Public License for more details.
 829  *
 830  * You should have received a copy of the GNU Library General Public
 831  * License along with this library; if not, write to the Free Software
 832  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
 833  */
 834
 835 /* utility to obtain alphabetically sorted list of genre names with numbers */
 836 extern void id3tag_genre_list(
 837         void (*handler)(int, const char *, void *),
 838         void*  cookie);
 839
 840 extern void id3tag_init   (lame_global_flags *gfp);
 841
 842 /* force addition of version 2 tag */
 843 extern void id3tag_add_v2   (lame_global_flags *gfp);
 844
 845 /* add only a version 1 tag */
 846 extern void id3tag_v1_only  (lame_global_flags *gfp);
 847
 848 /* add only a version 2 tag */
 849 extern void id3tag_v2_only  (lame_global_flags *gfp);
 850
 851 /* pad version 1 tag with spaces instead of nulls */
 852 extern void id3tag_space_v1 (lame_global_flags *gfp);
 853
 854 /* pad version 2 tag with extra 128 bytes */
 855 extern void id3tag_pad_v2   (lame_global_flags *gfp);
 856
 857 extern void id3tag_set_title(
 858         lame_global_flags*  gfp,
 859         const char*         title );
 860 extern void id3tag_set_artist(
 861         lame_global_flags*  gfp,
 862         const char*         artist );
 863 extern void id3tag_set_album(
 864         lame_global_flags*  gfp,
 865         const char*         album );
 866 extern void id3tag_set_year(
 867         lame_global_flags*  gfp,
 868         const char*         year );
 869 extern void id3tag_set_comment(
 870         lame_global_flags*  gfp,
 871         const char*         comment );
 872 extern void id3tag_set_track(
 873         lame_global_flags*  gfp,
 874         const char*         track );
 875
 876 /* return non-zero result if genre name or number is invalid */
 877 extern int id3tag_set_genre(
 878         lame_global_flags*  gfp,
 879         const char*         genre );
 880
 881 /***********************************************************************
 882 *
 883 *  list of valid bitrates [kbps] & sample frequencies [Hz].
 884 *  first index: 0: MPEG-2   values  (sample frequencies 16...24 kHz)
 885 *               1: MPEG-1   values  (sample frequencies 32...48 kHz)
 886 *               2: MPEG-2.5 values  (sample frequencies  8...12 kHz)
 887 ***********************************************************************/
 888 extern const int      bitrate_table    [3] [16];
 889 extern const int      samplerate_table [3] [ 4];
 890
 891
 892
 893 /* maximum size of mp3buffer needed if you encode at most 1152 samples for
 894    each call to lame_encode_buffer.  see lame_encode_buffer() below
 895    (LAME_MAXMP3BUFFER is now obsolete)  */
 896 #define LAME_MAXMP3BUFFER   16384
 897
 898
 899 #if defined(__cplusplus)
 900 }
 901 #endif
 902 #endif /* LAME_LAME_H */