src/lib/dl/ext/lame/lame.h

   1 /*
   2  *      Interface to MP3 LAME encoding engine
   3  *
   4  *      Copyright (c) 1999 Mark Taylor
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library 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 GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 /* $Id: lame.h,v 1.189 2011/10/02 14:52:20 robert Exp $ */
  23
  24 #ifndef LAME_LAME_H
  25 #define LAME_LAME_H
  26
  27 /* for size_t typedef */
  28 #include <stddef.h>
  29 /* for va_list typedef */
  30 #include <stdarg.h>
  31 /* for FILE typedef, TODO: remove when removing lame_mp3_tags_fid */
  32 #include <stdio.h>
  33
  34 #if defined(__cplusplus)
  35 extern "C" {
  36 #endif
  37
  38 typedef void (*lame_report_function)(const char *format, va_list ap);
  39
  40 #if defined(WIN32) || defined(_WIN32)
  41 #undef CDECL
  42 #define CDECL __cdecl
  43 #else
  44 #define CDECL
  45 #endif
  46
  47 #define DEPRECATED_OR_OBSOLETE_CODE_REMOVED 1
  48
  49 typedef enum vbr_mode_e {
  50   vbr_off=0,
  51   vbr_mt,               /* obsolete, same as vbr_mtrh */
  52   vbr_rh,
  53   vbr_abr,
  54   vbr_mtrh,
  55   vbr_max_indicator,    /* Don't use this! It's used for sanity checks.       */
  56   vbr_default=vbr_mtrh    /* change this to change the default VBR mode of LAME */
  57 } vbr_mode;
  58
  59
  60 /* MPEG modes */
  61 typedef enum MPEG_mode_e {
  62   STEREO = 0,
  63   JOINT_STEREO,
  64   DUAL_CHANNEL,   /* LAME doesn't supports this! */
  65   MONO,
  66   NOT_SET,
  67   MAX_INDICATOR   /* Don't use this! It's used for sanity checks. */
  68 } MPEG_mode;
  69
  70 /* Padding types */
  71 typedef enum Padding_type_e {
  72   PAD_NO = 0,
  73   PAD_ALL,
  74   PAD_ADJUST,
  75   PAD_MAX_INDICATOR   /* Don't use this! It's used for sanity checks. */
  76 } Padding_type;
  77
  78
  79
  80 /*presets*/
  81 typedef enum preset_mode_e {
  82     /*values from 8 to 320 should be reserved for abr bitrates*/
  83     /*for abr I'd suggest to directly use the targeted bitrate as a value*/
  84     ABR_8 = 8,
  85     ABR_320 = 320,
  86
  87     V9 = 410, /*Vx to match Lame and VBR_xx to match FhG*/
  88     VBR_10 = 410,
  89     V8 = 420,
  90     VBR_20 = 420,
  91     V7 = 430,
  92     VBR_30 = 430,
  93     V6 = 440,
  94     VBR_40 = 440,
  95     V5 = 450,
  96     VBR_50 = 450,
  97     V4 = 460,
  98     VBR_60 = 460,
  99     V3 = 470,
 100     VBR_70 = 470,
 101     V2 = 480,
 102     VBR_80 = 480,
 103     V1 = 490,
 104     VBR_90 = 490,
 105     V0 = 500,
 106     VBR_100 = 500,
 107
 108
 109
 110     /*still there for compatibility*/
 111     R3MIX = 1000,
 112     STANDARD = 1001,
 113     EXTREME = 1002,
 114     INSANE = 1003,
 115     STANDARD_FAST = 1004,
 116     EXTREME_FAST = 1005,
 117     MEDIUM = 1006,
 118     MEDIUM_FAST = 1007
 119 } preset_mode;
 120
 121
 122 /*asm optimizations*/
 123 typedef enum asm_optimizations_e {
 124     MMX = 1,
 125     AMD_3DNOW = 2,
 126     SSE = 3
 127 } asm_optimizations;
 128
 129
 130 /* psychoacoustic model */
 131 typedef enum Psy_model_e {
 132     PSY_GPSYCHO = 1,
 133     PSY_NSPSYTUNE = 2
 134 } Psy_model;
 135
 136
 137 /* buffer considerations */
 138 typedef enum buffer_constraint_e {
 139     MDB_DEFAULT=0,
 140     MDB_STRICT_ISO=1,
 141     MDB_MAXIMUM=2
 142 } buffer_constraint;
 143
 144
 145 struct lame_global_struct;
 146 typedef struct lame_global_struct lame_global_flags;
 147 typedef lame_global_flags *lame_t;
 148
 149
 150
 151
 152 /***********************************************************************
 153  *
 154  *  The LAME API
 155  *  These functions should be called, in this order, for each
 156  *  MP3 file to be encoded.  See the file "API" for more documentation
 157  *
 158  ***********************************************************************/
 159
 160
 161 /*
 162  * REQUIRED:
 163  * initialize the encoder.  sets default for all encoder parameters,
 164  * returns NULL if some malloc()'s failed
 165  * otherwise returns pointer to structure needed for all future
 166  * API calls.
 167  */
 168 lame_global_flags * CDECL lame_init(void);
 169 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 170 #else
 171 /* obsolete version */
 172 int CDECL lame_init_old(lame_global_flags *);
 173 #endif
 174
 175 /*
 176  * OPTIONAL:
 177  * set as needed to override defaults
 178  */
 179
 180 /********************************************************************
 181  *  input stream description
 182  ***********************************************************************/
 183 /* number of samples.  default = 2^32-1   */
 184 int CDECL lame_set_num_samples(lame_global_flags *, unsigned long);
 185 unsigned long CDECL lame_get_num_samples(const lame_global_flags *);
 186
 187 /* input sample rate in Hz.  default = 44100hz */
 188 int CDECL lame_set_in_samplerate(lame_global_flags *, int);
 189 int CDECL lame_get_in_samplerate(const lame_global_flags *);
 190
 191 /* number of channels in input stream. default=2  */
 192 int CDECL lame_set_num_channels(lame_global_flags *, int);
 193 int CDECL lame_get_num_channels(const lame_global_flags *);
 194
 195 /*
 196   scale the input by this amount before encoding.  default=1
 197   (not used by decoding routines)
 198 */
 199 int CDECL lame_set_scale(lame_global_flags *, float);
 200 float CDECL lame_get_scale(const lame_global_flags *);
 201
 202 /*
 203   scale the channel 0 (left) input by this amount before encoding.  default=1
 204   (not used by decoding routines)
 205 */
 206 int CDECL lame_set_scale_left(lame_global_flags *, float);
 207 float CDECL lame_get_scale_left(const lame_global_flags *);
 208
 209 /*
 210   scale the channel 1 (right) input by this amount before encoding.  default=1
 211   (not used by decoding routines)
 212 */
 213 int CDECL lame_set_scale_right(lame_global_flags *, float);
 214 float CDECL lame_get_scale_right(const lame_global_flags *);
 215
 216 /*
 217   output sample rate in Hz.  default = 0, which means LAME picks best value
 218   based on the amount of compression.  MPEG only allows:
 219   MPEG1    32, 44.1,   48khz
 220   MPEG2    16, 22.05,  24
 221   MPEG2.5   8, 11.025, 12
 222   (not used by decoding routines)
 223 */
 224 int CDECL lame_set_out_samplerate(lame_global_flags *, int);
 225 int CDECL lame_get_out_samplerate(const lame_global_flags *);
 226
 227
 228 /********************************************************************
 229  *  general control parameters
 230  ***********************************************************************/
 231 /* 1=cause LAME to collect data for an MP3 frame analyzer. default=0 */
 232 int CDECL lame_set_analysis(lame_global_flags *, int);
 233 int CDECL lame_get_analysis(const lame_global_flags *);
 234
 235 /*
 236   1 = write a Xing VBR header frame.
 237   default = 1
 238   this variable must have been added by a Hungarian notation Windows programmer :-)
 239 */
 240 int CDECL lame_set_bWriteVbrTag(lame_global_flags *, int);
 241 int CDECL lame_get_bWriteVbrTag(const lame_global_flags *);
 242
 243 /* 1=decode only.  use lame/mpglib to convert mp3/ogg to wav.  default=0 */
 244 int CDECL lame_set_decode_only(lame_global_flags *, int);
 245 int CDECL lame_get_decode_only(const lame_global_flags *);
 246
 247 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 248 #else
 249 /* 1=encode a Vorbis .ogg file.  default=0 */
 250 /* DEPRECATED */
 251 int CDECL lame_set_ogg(lame_global_flags *, int);
 252 int CDECL lame_get_ogg(const lame_global_flags *);
 253 #endif
 254
 255 /*
 256   internal algorithm selection.  True quality is determined by the bitrate
 257   but this variable will effect quality by selecting expensive or cheap algorithms.
 258   quality=0..9.  0=best (very slow).  9=worst.
 259   recommended:  2     near-best quality, not too slow
 260                 5     good quality, fast
 261                 7     ok quality, really fast
 262 */
 263 int CDECL lame_set_quality(lame_global_flags *, int);
 264 int CDECL lame_get_quality(const lame_global_flags *);
 265
 266 /*
 267   mode = 0,1,2,3 = stereo, jstereo, dual channel (not supported), mono
 268   default: lame picks based on compression ration and input channels
 269 */
 270 int CDECL lame_set_mode(lame_global_flags *, MPEG_mode);
 271 MPEG_mode CDECL lame_get_mode(const lame_global_flags *);
 272
 273 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 274 #else
 275 /*
 276   mode_automs.  Use a M/S mode with a switching threshold based on
 277   compression ratio
 278   DEPRECATED
 279 */
 280 int CDECL lame_set_mode_automs(lame_global_flags *, int);
 281 int CDECL lame_get_mode_automs(const lame_global_flags *);
 282 #endif
 283
 284 /*
 285   force_ms.  Force M/S for all frames.  For testing only.
 286   default = 0 (disabled)
 287 */
 288 int CDECL lame_set_force_ms(lame_global_flags *, int);
 289 int CDECL lame_get_force_ms(const lame_global_flags *);
 290
 291 /* use free_format?  default = 0 (disabled) */
 292 int CDECL lame_set_free_format(lame_global_flags *, int);
 293 int CDECL lame_get_free_format(const lame_global_flags *);
 294
 295 /* perform ReplayGain analysis?  default = 0 (disabled) */
 296 int CDECL lame_set_findReplayGain(lame_global_flags *, int);
 297 int CDECL lame_get_findReplayGain(const lame_global_flags *);
 298
 299 /* decode on the fly. Search for the peak sample. If the ReplayGain
 300  * analysis is enabled then perform the analysis on the decoded data
 301  * stream. default = 0 (disabled)
 302  * NOTE: if this option is set the build-in decoder should not be used */
 303 int CDECL lame_set_decode_on_the_fly(lame_global_flags *, int);
 304 int CDECL lame_get_decode_on_the_fly(const lame_global_flags *);
 305
 306 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 307 #else
 308 /* DEPRECATED: now does the same as lame_set_findReplayGain()
 309    default = 0 (disabled) */
 310 int CDECL lame_set_ReplayGain_input(lame_global_flags *, int);
 311 int CDECL lame_get_ReplayGain_input(const lame_global_flags *);
 312
 313 /* DEPRECATED: now does the same as
 314    lame_set_decode_on_the_fly() && lame_set_findReplayGain()
 315    default = 0 (disabled) */
 316 int CDECL lame_set_ReplayGain_decode(lame_global_flags *, int);
 317 int CDECL lame_get_ReplayGain_decode(const lame_global_flags *);
 318
 319 /* DEPRECATED: now does the same as lame_set_decode_on_the_fly()
 320    default = 0 (disabled) */
 321 int CDECL lame_set_findPeakSample(lame_global_flags *, int);
 322 int CDECL lame_get_findPeakSample(const lame_global_flags *);
 323 #endif
 324
 325 /* counters for gapless encoding */
 326 int CDECL lame_set_nogap_total(lame_global_flags*, int);
 327 int CDECL lame_get_nogap_total(const lame_global_flags*);
 328
 329 int CDECL lame_set_nogap_currentindex(lame_global_flags* , int);
 330 int CDECL lame_get_nogap_currentindex(const lame_global_flags*);
 331
 332
 333 /*
 334  * OPTIONAL:
 335  * Set printf like error/debug/message reporting functions.
 336  * The second argument has to be a pointer to a function which looks like
 337  *   void my_debugf(const char *format, va_list ap)
 338  *   {
 339  *       (void) vfprintf(stdout, format, ap);
 340  *   }
 341  * If you use NULL as the value of the pointer in the set function, the
 342  * lame buildin function will be used (prints to stderr).
 343  * To quiet any output you have to replace the body of the example function
 344  * with just "return;" and use it in the set function.
 345  */
 346 int CDECL lame_set_errorf(lame_global_flags *, lame_report_function);
 347 int CDECL lame_set_debugf(lame_global_flags *, lame_report_function);
 348 int CDECL lame_set_msgf  (lame_global_flags *, lame_report_function);
 349
 350
 351
 352 /* set one of brate compression ratio.  default is compression ratio of 11.  */
 353 int CDECL lame_set_brate(lame_global_flags *, int);
 354 int CDECL lame_get_brate(const lame_global_flags *);
 355 int CDECL lame_set_compression_ratio(lame_global_flags *, float);
 356 float CDECL lame_get_compression_ratio(const lame_global_flags *);
 357
 358
 359 int CDECL lame_set_preset( lame_global_flags*  gfp, int );
 360 int CDECL lame_set_asm_optimizations( lame_global_flags*  gfp, int, int );
 361
 362
 363
 364 /********************************************************************
 365  *  frame params
 366  ***********************************************************************/
 367 /* mark as copyright.  default=0 */
 368 int CDECL lame_set_copyright(lame_global_flags *, int);
 369 int CDECL lame_get_copyright(const lame_global_flags *);
 370
 371 /* mark as original.  default=1 */
 372 int CDECL lame_set_original(lame_global_flags *, int);
 373 int CDECL lame_get_original(const lame_global_flags *);
 374
 375 /* error_protection.  Use 2 bytes from each frame for CRC checksum. default=0 */
 376 int CDECL lame_set_error_protection(lame_global_flags *, int);
 377 int CDECL lame_get_error_protection(const lame_global_flags *);
 378
 379 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 380 #else
 381 /* padding_type. 0=pad no frames  1=pad all frames 2=adjust padding(default) */
 382 int CDECL lame_set_padding_type(lame_global_flags *, Padding_type);
 383 Padding_type CDECL lame_get_padding_type(const lame_global_flags *);
 384 #endif
 385
 386 /* MP3 'private extension' bit  Meaningless.  default=0 */
 387 int CDECL lame_set_extension(lame_global_flags *, int);
 388 int CDECL lame_get_extension(const lame_global_flags *);
 389
 390 /* enforce strict ISO compliance.  default=0 */
 391 int CDECL lame_set_strict_ISO(lame_global_flags *, int);
 392 int CDECL lame_get_strict_ISO(const lame_global_flags *);
 393
 394
 395 /********************************************************************
 396  * quantization/noise shaping
 397  ***********************************************************************/
 398
 399 /* disable the bit reservoir. For testing only. default=0 */
 400 int CDECL lame_set_disable_reservoir(lame_global_flags *, int);
 401 int CDECL lame_get_disable_reservoir(const lame_global_flags *);
 402
 403 /* select a different "best quantization" function. default=0  */
 404 int CDECL lame_set_quant_comp(lame_global_flags *, int);
 405 int CDECL lame_get_quant_comp(const lame_global_flags *);
 406 int CDECL lame_set_quant_comp_short(lame_global_flags *, int);
 407 int CDECL lame_get_quant_comp_short(const lame_global_flags *);
 408
 409 int CDECL lame_set_experimentalX(lame_global_flags *, int); /* compatibility*/
 410 int CDECL lame_get_experimentalX(const lame_global_flags *);
 411
 412 /* another experimental option.  for testing only */
 413 int CDECL lame_set_experimentalY(lame_global_flags *, int);
 414 int CDECL lame_get_experimentalY(const lame_global_flags *);
 415
 416 /* another experimental option.  for testing only */
 417 int CDECL lame_set_experimentalZ(lame_global_flags *, int);
 418 int CDECL lame_get_experimentalZ(const lame_global_flags *);
 419
 420 /* Naoki's psycho acoustic model.  default=0 */
 421 int CDECL lame_set_exp_nspsytune(lame_global_flags *, int);
 422 int CDECL lame_get_exp_nspsytune(const lame_global_flags *);
 423
 424 void CDECL lame_set_msfix(lame_global_flags *, double);
 425 float CDECL lame_get_msfix(const lame_global_flags *);
 426
 427
 428 /********************************************************************
 429  * VBR control
 430  ***********************************************************************/
 431 /* Types of VBR.  default = vbr_off = CBR */
 432 int CDECL lame_set_VBR(lame_global_flags *, vbr_mode);
 433 vbr_mode CDECL lame_get_VBR(const lame_global_flags *);
 434
 435 /* VBR quality level.  0=highest  9=lowest  */
 436 int CDECL lame_set_VBR_q(lame_global_flags *, int);
 437 int CDECL lame_get_VBR_q(const lame_global_flags *);
 438
 439 /* VBR quality level.  0=highest  9=lowest, Range [0,...,10[  */
 440 int CDECL lame_set_VBR_quality(lame_global_flags *, float);
 441 float CDECL lame_get_VBR_quality(const lame_global_flags *);
 442
 443 /* Ignored except for VBR=vbr_abr (ABR mode) */
 444 int CDECL lame_set_VBR_mean_bitrate_kbps(lame_global_flags *, int);
 445 int CDECL lame_get_VBR_mean_bitrate_kbps(const lame_global_flags *);
 446
 447 int CDECL lame_set_VBR_min_bitrate_kbps(lame_global_flags *, int);
 448 int CDECL lame_get_VBR_min_bitrate_kbps(const lame_global_flags *);
 449
 450 int CDECL lame_set_VBR_max_bitrate_kbps(lame_global_flags *, int);
 451 int CDECL lame_get_VBR_max_bitrate_kbps(const lame_global_flags *);
 452
 453 /*
 454   1=strictly enforce VBR_min_bitrate.  Normally it will be violated for
 455   analog silence
 456 */
 457 int CDECL lame_set_VBR_hard_min(lame_global_flags *, int);
 458 int CDECL lame_get_VBR_hard_min(const lame_global_flags *);
 459
 460 /* for preset */
 461 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 462 #else
 463 int CDECL lame_set_preset_expopts(lame_global_flags *, int);
 464 #endif
 465
 466 /********************************************************************
 467  * Filtering control
 468  ***********************************************************************/
 469 /* freq in Hz to apply lowpass. Default = 0 = lame chooses.  -1 = disabled */
 470 int CDECL lame_set_lowpassfreq(lame_global_flags *, int);
 471 int CDECL lame_get_lowpassfreq(const lame_global_flags *);
 472 /* width of transition band, in Hz.  Default = one polyphase filter band */
 473 int CDECL lame_set_lowpasswidth(lame_global_flags *, int);
 474 int CDECL lame_get_lowpasswidth(const lame_global_flags *);
 475
 476 /* freq in Hz to apply highpass. Default = 0 = lame chooses.  -1 = disabled */
 477 int CDECL lame_set_highpassfreq(lame_global_flags *, int);
 478 int CDECL lame_get_highpassfreq(const lame_global_flags *);
 479 /* width of transition band, in Hz.  Default = one polyphase filter band */
 480 int CDECL lame_set_highpasswidth(lame_global_flags *, int);
 481 int CDECL lame_get_highpasswidth(const lame_global_flags *);
 482
 483
 484 /********************************************************************
 485  * psycho acoustics and other arguments which you should not change
 486  * unless you know what you are doing
 487  ***********************************************************************/
 488
 489 /* only use ATH for masking */
 490 int CDECL lame_set_ATHonly(lame_global_flags *, int);
 491 int CDECL lame_get_ATHonly(const lame_global_flags *);
 492
 493 /* only use ATH for short blocks */
 494 int CDECL lame_set_ATHshort(lame_global_flags *, int);
 495 int CDECL lame_get_ATHshort(const lame_global_flags *);
 496
 497 /* disable ATH */
 498 int CDECL lame_set_noATH(lame_global_flags *, int);
 499 int CDECL lame_get_noATH(const lame_global_flags *);
 500
 501 /* select ATH formula */
 502 int CDECL lame_set_ATHtype(lame_global_flags *, int);
 503 int CDECL lame_get_ATHtype(const lame_global_flags *);
 504
 505 /* lower ATH by this many db */
 506 int CDECL lame_set_ATHlower(lame_global_flags *, float);
 507 float CDECL lame_get_ATHlower(const lame_global_flags *);
 508
 509 /* select ATH adaptive adjustment type */
 510 int CDECL lame_set_athaa_type( lame_global_flags *, int);
 511 int CDECL lame_get_athaa_type( const lame_global_flags *);
 512
 513 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 514 #else
 515 /* select the loudness approximation used by the ATH adaptive auto-leveling  */
 516 int CDECL lame_set_athaa_loudapprox( lame_global_flags *, int);
 517 int CDECL lame_get_athaa_loudapprox( const lame_global_flags *);
 518 #endif
 519
 520 /* adjust (in dB) the point below which adaptive ATH level adjustment occurs */
 521 int CDECL lame_set_athaa_sensitivity( lame_global_flags *, float);
 522 float CDECL lame_get_athaa_sensitivity( const lame_global_flags* );
 523
 524 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 525 #else
 526 /* OBSOLETE: predictability limit (ISO tonality formula) */
 527 int CDECL lame_set_cwlimit(lame_global_flags *, int);
 528 int CDECL lame_get_cwlimit(const lame_global_flags *);
 529 #endif
 530
 531 /*
 532   allow blocktypes to differ between channels?
 533   default: 0 for jstereo, 1 for stereo
 534 */
 535 int CDECL lame_set_allow_diff_short(lame_global_flags *, int);
 536 int CDECL lame_get_allow_diff_short(const lame_global_flags *);
 537
 538 /* use temporal masking effect (default = 1) */
 539 int CDECL lame_set_useTemporal(lame_global_flags *, int);
 540 int CDECL lame_get_useTemporal(const lame_global_flags *);
 541
 542 /* use temporal masking effect (default = 1) */
 543 int CDECL lame_set_interChRatio(lame_global_flags *, float);
 544 float CDECL lame_get_interChRatio(const lame_global_flags *);
 545
 546 /* disable short blocks */
 547 int CDECL lame_set_no_short_blocks(lame_global_flags *, int);
 548 int CDECL lame_get_no_short_blocks(const lame_global_flags *);
 549
 550 /* force short blocks */
 551 int CDECL lame_set_force_short_blocks(lame_global_flags *, int);
 552 int CDECL lame_get_force_short_blocks(const lame_global_flags *);
 553
 554 /* Input PCM is emphased PCM (for instance from one of the rarely
 555    emphased CDs), it is STRONGLY not recommended to use this, because
 556    psycho does not take it into account, and last but not least many decoders
 557    ignore these bits */
 558 int CDECL lame_set_emphasis(lame_global_flags *, int);
 559 int CDECL lame_get_emphasis(const lame_global_flags *);
 560
 561
 562
 563 /************************************************************************/
 564 /* internal variables, cannot be set...                                 */
 565 /* provided because they may be of use to calling application           */
 566 /************************************************************************/
 567 /* version  0=MPEG-2  1=MPEG-1  (2=MPEG-2.5)     */
 568 int CDECL lame_get_version(const lame_global_flags *);
 569
 570 /* encoder delay   */
 571 int CDECL lame_get_encoder_delay(const lame_global_flags *);
 572
 573 /*
 574   padding appended to the input to make sure decoder can fully decode
 575   all input.  Note that this value can only be calculated during the
 576   call to lame_encoder_flush().  Before lame_encoder_flush() has
 577   been called, the value of encoder_padding = 0.
 578 */
 579 int CDECL lame_get_encoder_padding(const lame_global_flags *);
 580
 581 /* size of MPEG frame */
 582 int CDECL lame_get_framesize(const lame_global_flags *);
 583
 584 /* number of PCM samples buffered, but not yet encoded to mp3 data. */
 585 int CDECL lame_get_mf_samples_to_encode( const lame_global_flags*  gfp );
 586
 587 /*
 588   size (bytes) of mp3 data buffered, but not yet encoded.
 589   this is the number of bytes which would be output by a call to
 590   lame_encode_flush_nogap.  NOTE: lame_encode_flush() will return
 591   more bytes than this because it will encode the reamining buffered
 592   PCM samples before flushing the mp3 buffers.
 593 */
 594 int CDECL lame_get_size_mp3buffer( const lame_global_flags*  gfp );
 595
 596 /* number of frames encoded so far */
 597 int CDECL lame_get_frameNum(const lame_global_flags *);
 598
 599 /*
 600   lame's estimate of the total number of frames to be encoded
 601    only valid if calling program set num_samples
 602 */
 603 int CDECL lame_get_totalframes(const lame_global_flags *);
 604
 605 /* RadioGain value. Multiplied by 10 and rounded to the nearest. */
 606 int CDECL lame_get_RadioGain(const lame_global_flags *);
 607
 608 /* AudiophileGain value. Multipled by 10 and rounded to the nearest. */
 609 int CDECL lame_get_AudiophileGain(const lame_global_flags *);
 610
 611 /* the peak sample */
 612 float CDECL lame_get_PeakSample(const lame_global_flags *);
 613
 614 /* Gain change required for preventing clipping. The value is correct only if
 615    peak sample searching was enabled. If negative then the waveform
 616    already does not clip. The value is multiplied by 10 and rounded up. */
 617 int CDECL lame_get_noclipGainChange(const lame_global_flags *);
 618
 619 /* user-specified scale factor required for preventing clipping. Value is
 620    correct only if peak sample searching was enabled and no user-specified
 621    scaling was performed. If negative then either the waveform already does
 622    not clip or the value cannot be determined */
 623 float CDECL lame_get_noclipScale(const lame_global_flags *);
 624
 625
 626
 627
 628
 629
 630
 631 /*
 632  * REQUIRED:
 633  * sets more internal configuration based on data provided above.
 634  * returns -1 if something failed.
 635  */
 636 int CDECL lame_init_params(lame_global_flags *);
 637
 638
 639 /*
 640  * OPTIONAL:
 641  * get the version number, in a string. of the form:
 642  * "3.63 (beta)" or just "3.63".
 643  */
 644 const char*  CDECL get_lame_version       ( void );
 645 const char*  CDECL get_lame_short_version ( void );
 646 const char*  CDECL get_lame_very_short_version ( void );
 647 const char*  CDECL get_psy_version        ( void );
 648 const char*  CDECL get_lame_url           ( void );
 649 const char*  CDECL get_lame_os_bitness    ( void );
 650
 651 /*
 652  * OPTIONAL:
 653  * get the version numbers in numerical form.
 654  */
 655 typedef struct {
 656     /* generic LAME version */
 657     int major;
 658     int minor;
 659     int alpha;               /* 0 if not an alpha version                  */
 660     int beta;                /* 0 if not a beta version                    */
 661
 662     /* version of the psy model */
 663     int psy_major;
 664     int psy_minor;
 665     int psy_alpha;           /* 0 if not an alpha version                  */
 666     int psy_beta;            /* 0 if not a beta version                    */
 667
 668     /* compile time features */
 669     const char *features;    /* Don't make assumptions about the contents! */
 670 } lame_version_t;
 671 void CDECL get_lame_version_numerical(lame_version_t *);
 672
 673
 674 /*
 675  * OPTIONAL:
 676  * print internal lame configuration to message handler
 677  */
 678 void CDECL lame_print_config(const lame_global_flags*  gfp);
 679
 680 void CDECL lame_print_internals( const lame_global_flags *gfp);
 681
 682
 683 /*
 684  * input pcm data, output (maybe) mp3 frames.
 685  * This routine handles all buffering, resampling and filtering for you.
 686  *
 687  * return code     number of bytes output in mp3buf. Can be 0
 688  *                 -1:  mp3buf was too small
 689  *                 -2:  malloc() problem
 690  *                 -3:  lame_init_params() not called
 691  *                 -4:  psycho acoustic problems
 692  *
 693  * The required mp3buf_size can be computed from num_samples,
 694  * samplerate and encoding rate, but here is a worst case estimate:
 695  *
 696  * mp3buf_size in bytes = 1.25*num_samples + 7200
 697  *
 698  * I think a tighter bound could be:  (mt, March 2000)
 699  * MPEG1:
 700  *    num_samples*(bitrate/8)/samplerate + 4*1152*(bitrate/8)/samplerate + 512
 701  * MPEG2:
 702  *    num_samples*(bitrate/8)/samplerate + 4*576*(bitrate/8)/samplerate + 256
 703  *
 704  * but test first if you use that!
 705  *
 706  * set mp3buf_size = 0 and LAME will not check if mp3buf_size is
 707  * large enough.
 708  *
 709  * NOTE:
 710  * if gfp->num_channels=2, but gfp->mode = 3 (mono), the L & R channels
 711  * will be averaged into the L channel before encoding only the L channel
 712  * This will overwrite the data in buffer_l[] and buffer_r[].
 713  *
 714 */
 715 int CDECL lame_encode_buffer (
 716         lame_global_flags*  gfp,           /* global context handle         */
 717         const short int     buffer_l [],   /* PCM data for left channel     */
 718         const short int     buffer_r [],   /* PCM data for right channel    */
 719         const int           nsamples,      /* number of samples per channel */
 720         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 721         const int           mp3buf_size ); /* number of valid octets in this
 722                                               stream                        */
 723
 724 /*
 725  * as above, but input has L & R channel data interleaved.
 726  * NOTE:
 727  * num_samples = number of samples in the L (or R)
 728  * channel, not the total number of samples in pcm[]
 729  */
 730 int CDECL lame_encode_buffer_interleaved(
 731         lame_global_flags*  gfp,           /* global context handlei        */
 732         short int           pcm[],         /* PCM data for left and right
 733                                               channel, interleaved          */
 734         int                 num_samples,   /* number of samples per channel,
 735                                               _not_ number of samples in
 736                                               pcm[]                         */
 737         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 738         int                 mp3buf_size ); /* number of valid octets in this
 739                                               stream                        */
 740
 741
 742 /* as lame_encode_buffer, but for 'float's.
 743  * !! NOTE: !! data must still be scaled to be in the same range as
 744  * short int, +/- 32768
 745  */
 746 int CDECL lame_encode_buffer_float(
 747         lame_global_flags*  gfp,           /* global context handle         */
 748         const float         pcm_l [],      /* PCM data for left channel     */
 749         const float         pcm_r [],      /* PCM data for right channel    */
 750         const int           nsamples,      /* number of samples per channel */
 751         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 752         const int           mp3buf_size ); /* number of valid octets in this
 753                                               stream                        */
 754
 755 /* as lame_encode_buffer, but for 'float's.
 756  * !! NOTE: !! data must be scaled to +/- 1 full scale
 757  */
 758 int CDECL lame_encode_buffer_ieee_float(
 759         lame_t          gfp,
 760         const float     pcm_l [],          /* PCM data for left channel     */
 761         const float     pcm_r [],          /* PCM data for right channel    */
 762         const int       nsamples,
 763         unsigned char * mp3buf,
 764         const int       mp3buf_size);
 765 int CDECL lame_encode_buffer_interleaved_ieee_float(
 766         lame_t          gfp,
 767         const float     pcm[],             /* PCM data for left and right
 768                                               channel, interleaved          */
 769         const int       nsamples,
 770         unsigned char * mp3buf,
 771         const int       mp3buf_size);
 772
 773 /* as lame_encode_buffer, but for 'double's.
 774  * !! NOTE: !! data must be scaled to +/- 1 full scale
 775  */
 776 int CDECL lame_encode_buffer_ieee_double(
 777         lame_t          gfp,
 778         const double    pcm_l [],          /* PCM data for left channel     */
 779         const double    pcm_r [],          /* PCM data for right channel    */
 780         const int       nsamples,
 781         unsigned char * mp3buf,
 782         const int       mp3buf_size);
 783 int CDECL lame_encode_buffer_interleaved_ieee_double(
 784         lame_t          gfp,
 785         const double    pcm[],             /* PCM data for left and right
 786                                               channel, interleaved          */
 787         const int       nsamples,
 788         unsigned char * mp3buf,
 789         const int       mp3buf_size);
 790
 791 /* as lame_encode_buffer, but for long's
 792  * !! NOTE: !! data must still be scaled to be in the same range as
 793  * short int, +/- 32768
 794  *
 795  * This scaling was a mistake (doesn't allow one to exploit full
 796  * precision of type 'long'.  Use lame_encode_buffer_long2() instead.
 797  *
 798  */
 799 int CDECL lame_encode_buffer_long(
 800         lame_global_flags*  gfp,           /* global context handle         */
 801         const long     buffer_l [],       /* PCM data for left channel     */
 802         const long     buffer_r [],       /* PCM data for right channel    */
 803         const int           nsamples,      /* number of samples per channel */
 804         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 805         const int           mp3buf_size ); /* number of valid octets in this
 806                                               stream                        */
 807
 808 /* Same as lame_encode_buffer_long(), but with correct scaling.
 809  * !! NOTE: !! data must still be scaled to be in the same range as
 810  * type 'long'.   Data should be in the range:  +/- 2^(8*size(long)-1)
 811  *
 812  */
 813 int CDECL lame_encode_buffer_long2(
 814         lame_global_flags*  gfp,           /* global context handle         */
 815         const long     buffer_l [],       /* PCM data for left channel     */
 816         const long     buffer_r [],       /* PCM data for right channel    */
 817         const int           nsamples,      /* number of samples per channel */
 818         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 819         const int           mp3buf_size ); /* number of valid octets in this
 820                                               stream                        */
 821
 822 /* as lame_encode_buffer, but for int's
 823  * !! NOTE: !! input should be scaled to the maximum range of 'int'
 824  * If int is 4 bytes, then the values should range from
 825  * +/- 2147483648.
 826  *
 827  * This routine does not (and cannot, without loosing precision) use
 828  * the same scaling as the rest of the lame_encode_buffer() routines.
 829  *
 830  */
 831 int CDECL lame_encode_buffer_int(
 832         lame_global_flags*  gfp,           /* global context handle         */
 833         const int      buffer_l [],       /* PCM data for left channel     */
 834         const int      buffer_r [],       /* PCM data for right channel    */
 835         const int           nsamples,      /* number of samples per channel */
 836         unsigned char*      mp3buf,        /* pointer to encoded MP3 stream */
 837         const int           mp3buf_size ); /* number of valid octets in this
 838                                               stream                        */
 839
 840
 841
 842
 843
 844 /*
 845  * REQUIRED:
 846  * lame_encode_flush will flush the intenal PCM buffers, padding with
 847  * 0's to make sure the final frame is complete, and then flush
 848  * the internal MP3 buffers, and thus may return a
 849  * final few mp3 frames.  'mp3buf' should be at least 7200 bytes long
 850  * to hold all possible emitted data.
 851  *
 852  * will also write id3v1 tags (if any) into the bitstream
 853  *
 854  * return code = number of bytes output to mp3buf. Can be 0
 855  */
 856 int CDECL lame_encode_flush(
 857         lame_global_flags *  gfp,    /* global context handle                 */
 858         unsigned char*       mp3buf, /* pointer to encoded MP3 stream         */
 859         int                  size);  /* number of valid octets in this stream */
 860
 861 /*
 862  * OPTIONAL:
 863  * lame_encode_flush_nogap will flush the internal mp3 buffers and pad
 864  * the last frame with ancillary data so it is a complete mp3 frame.
 865  *
 866  * 'mp3buf' should be at least 7200 bytes long
 867  * to hold all possible emitted data.
 868  *
 869  * After a call to this routine, the outputed mp3 data is complete, but
 870  * you may continue to encode new PCM samples and write future mp3 data
 871  * to a different file.  The two mp3 files will play back with no gaps
 872  * if they are concatenated together.
 873  *
 874  * This routine will NOT write id3v1 tags into the bitstream.
 875  *
 876  * return code = number of bytes output to mp3buf. Can be 0
 877  */
 878 int CDECL lame_encode_flush_nogap(
 879         lame_global_flags *  gfp,    /* global context handle                 */
 880         unsigned char*       mp3buf, /* pointer to encoded MP3 stream         */
 881         int                  size);  /* number of valid octets in this stream */
 882
 883 /*
 884  * OPTIONAL:
 885  * Normally, this is called by lame_init_params().  It writes id3v2 and
 886  * Xing headers into the front of the bitstream, and sets frame counters
 887  * and bitrate histogram data to 0.  You can also call this after
 888  * lame_encode_flush_nogap().
 889  */
 890 int CDECL lame_init_bitstream(
 891         lame_global_flags *  gfp);    /* global context handle                 */
 892
 893
 894
 895 /*
 896  * OPTIONAL:    some simple statistics
 897  * a bitrate histogram to visualize the distribution of used frame sizes
 898  * a stereo mode histogram to visualize the distribution of used stereo
 899  *   modes, useful in joint-stereo mode only
 900  *   0: LR    left-right encoded
 901  *   1: LR-I  left-right and intensity encoded (currently not supported)
 902  *   2: MS    mid-side encoded
 903  *   3: MS-I  mid-side and intensity encoded (currently not supported)
 904  *
 905  * attention: don't call them after lame_encode_finish
 906  * suggested: lame_encode_flush -> lame_*_hist -> lame_close
 907  */
 908
 909 void CDECL lame_bitrate_hist(
 910         const lame_global_flags * gfp,
 911         int bitrate_count[14] );
 912 void CDECL lame_bitrate_kbps(
 913         const lame_global_flags * gfp,
 914         int bitrate_kbps [14] );
 915 void CDECL lame_stereo_mode_hist(
 916         const lame_global_flags * gfp,
 917         int stereo_mode_count[4] );
 918
 919 void CDECL lame_bitrate_stereo_mode_hist (
 920         const lame_global_flags * gfp,
 921         int bitrate_stmode_count[14][4] );
 922
 923 void CDECL lame_block_type_hist (
 924         const lame_global_flags * gfp,
 925         int btype_count[6] );
 926
 927 void CDECL lame_bitrate_block_type_hist (
 928         const lame_global_flags * gfp,
 929         int bitrate_btype_count[14][6] );
 930
 931 #if (DEPRECATED_OR_OBSOLETE_CODE_REMOVED && 0)
 932 #else
 933 /*
 934  * OPTIONAL:
 935  * lame_mp3_tags_fid will rewrite a Xing VBR tag to the mp3 file with file
 936  * pointer fid.  These calls perform forward and backwards seeks, so make
 937  * sure fid is a real file.  Make sure lame_encode_flush has been called,
 938  * and all mp3 data has been written to the file before calling this
 939  * function.
 940  * NOTE:
 941  * if VBR  tags are turned off by the user, or turned off by LAME because
 942  * the output is not a regular file, this call does nothing
 943  * NOTE:
 944  * LAME wants to read from the file to skip an optional ID3v2 tag, so
 945  * make sure you opened the file for writing and reading.
 946  * NOTE:
 947  * You can call lame_get_lametag_frame instead, if you want to insert
 948  * the lametag yourself.
 949 */
 950 void CDECL lame_mp3_tags_fid(lame_global_flags *, FILE* fid);
 951 #endif
 952
 953 /*
 954  * OPTIONAL:
 955  * lame_get_lametag_frame copies the final LAME-tag into 'buffer'.
 956  * The function returns the number of bytes copied into buffer, or
 957  * the required buffer size, if the provided buffer is too small.
 958  * Function failed, if the return value is larger than 'size'!
 959  * Make sure lame_encode flush has been called before calling this function.
 960  * NOTE:
 961  * if VBR  tags are turned off by the user, or turned off by LAME,
 962  * this call does nothing and returns 0.
 963  * NOTE:
 964  * LAME inserted an empty frame in the beginning of mp3 audio data,
 965  * which you have to replace by the final LAME-tag frame after encoding.
 966  * In case there is no ID3v2 tag, usually this frame will be the very first
 967  * data in your mp3 file. If you put some other leading data into your
 968  * file, you'll have to do some bookkeeping about where to write this buffer.
 969  */
 970 size_t CDECL lame_get_lametag_frame(
 971         const lame_global_flags *, unsigned char* buffer, size_t size);
 972
 973 /*
 974  * REQUIRED:
 975  * final call to free all remaining buffers
 976  */
 977 int  CDECL lame_close (lame_global_flags *);
 978
 979 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
 980 #else
 981 /*
 982  * OBSOLETE:
 983  * lame_encode_finish combines lame_encode_flush() and lame_close() in
 984  * one call.  However, once this call is made, the statistics routines
 985  * will no longer work because the data will have been cleared, and
 986  * lame_mp3_tags_fid() cannot be called to add data to the VBR header
 987  */
 988 int CDECL lame_encode_finish(
 989         lame_global_flags*  gfp,
 990         unsigned char*      mp3buf,
 991         int                 size );
 992 #endif
 993
 994
 995
 996
 997
 998
 999 /*********************************************************************
1000  *
1001  * decoding
1002  *
1003  * a simple interface to mpglib, part of mpg123, is also included if
1004  * libmp3lame is compiled with HAVE_MPGLIB
1005  *
1006  *********************************************************************/
1007
1008 struct hip_global_struct;
1009 typedef struct hip_global_struct hip_global_flags;
1010 typedef hip_global_flags *hip_t;
1011
1012
1013 typedef struct {
1014   int header_parsed;   /* 1 if header was parsed and following data was
1015                           computed                                       */
1016   int stereo;          /* number of channels                             */
1017   int samplerate;      /* sample rate                                    */
1018   int bitrate;         /* bitrate                                        */
1019   int mode;            /* mp3 frame type                                 */
1020   int mode_ext;        /* mp3 frame type                                 */
1021   int framesize;       /* number of samples per mp3 frame                */
1022
1023   /* this data is only computed if mpglib detects a Xing VBR header */
1024   unsigned long nsamp; /* number of samples in mp3 file.                 */
1025   int totalframes;     /* total number of frames in mp3 file             */
1026
1027   /* this data is not currently computed by the mpglib routines */
1028   int framenum;        /* frames decoded counter                         */
1029 } mp3data_struct;
1030
1031 /* required call to initialize decoder */
1032 hip_t CDECL hip_decode_init(void);
1033
1034 /* cleanup call to exit decoder  */
1035 int CDECL hip_decode_exit(hip_t gfp);
1036
1037 /* HIP reporting functions */
1038 void CDECL hip_set_errorf(hip_t gfp, lame_report_function f);
1039 void CDECL hip_set_debugf(hip_t gfp, lame_report_function f);
1040 void CDECL hip_set_msgf  (hip_t gfp, lame_report_function f);
1041
1042 /*********************************************************************
1043  * input 1 mp3 frame, output (maybe) pcm data.
1044  *
1045  *  nout = hip_decode(hip, mp3buf,len,pcm_l,pcm_r);
1046  *
1047  * input:
1048  *    len          :  number of bytes of mp3 data in mp3buf
1049  *    mp3buf[len]  :  mp3 data to be decoded
1050  *
1051  * output:
1052  *    nout:  -1    : decoding error
1053  *            0    : need more data before we can complete the decode
1054  *           >0    : returned 'nout' samples worth of data in pcm_l,pcm_r
1055  *    pcm_l[nout]  : left channel data
1056  *    pcm_r[nout]  : right channel data
1057  *
1058  *********************************************************************/
1059 int CDECL hip_decode( hip_t           gfp
1060                     , unsigned char * mp3buf
1061                     , size_t          len
1062                     , short           pcm_l[]
1063                     , short           pcm_r[]
1064                     );
1065
1066 /* same as hip_decode, and also returns mp3 header data */
1067 int CDECL hip_decode_headers( hip_t           gfp
1068                             , unsigned char*  mp3buf
1069                             , size_t          len
1070                             , short           pcm_l[]
1071                             , short           pcm_r[]
1072                             , mp3data_struct* mp3data
1073                             );
1074
1075 /* same as hip_decode, but returns at most one frame */
1076 int CDECL hip_decode1( hip_t          gfp
1077                      , unsigned char* mp3buf
1078                      , size_t         len
1079                      , short          pcm_l[]
1080                      , short          pcm_r[]
1081                      );
1082
1083 /* same as hip_decode1, but returns at most one frame and mp3 header data */
1084 int CDECL hip_decode1_headers( hip_t           gfp
1085                              , unsigned char*  mp3buf
1086                              , size_t          len
1087                              , short           pcm_l[]
1088                              , short           pcm_r[]
1089                              , mp3data_struct* mp3data
1090                              );
1091
1092 /* same as hip_decode1_headers, but also returns enc_delay and enc_padding
1093    from VBR Info tag, (-1 if no info tag was found) */
1094 int CDECL hip_decode1_headersB( hip_t gfp
1095                               , unsigned char*   mp3buf
1096                               , size_t           len
1097                               , short            pcm_l[]
1098                               , short            pcm_r[]
1099                               , mp3data_struct*  mp3data
1100                               , int             *enc_delay
1101                               , int             *enc_padding
1102                               );
1103
1104
1105
1106 /* OBSOLETE:
1107  * lame_decode... functions are there to keep old code working
1108  * but it is strongly recommended to replace calls by hip_decode...
1109  * function calls, see above.
1110  */
1111 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
1112 #else
1113 int CDECL lame_decode_init(void);
1114 int CDECL lame_decode(
1115         unsigned char *  mp3buf,
1116         int              len,
1117         short            pcm_l[],
1118         short            pcm_r[] );
1119 int CDECL lame_decode_headers(
1120         unsigned char*   mp3buf,
1121         int              len,
1122         short            pcm_l[],
1123         short            pcm_r[],
1124         mp3data_struct*  mp3data );
1125 int CDECL lame_decode1(
1126         unsigned char*  mp3buf,
1127         int             len,
1128         short           pcm_l[],
1129         short           pcm_r[] );
1130 int CDECL lame_decode1_headers(
1131         unsigned char*   mp3buf,
1132         int              len,
1133         short            pcm_l[],
1134         short            pcm_r[],
1135         mp3data_struct*  mp3data );
1136 int CDECL lame_decode1_headersB(
1137         unsigned char*   mp3buf,
1138         int              len,
1139         short            pcm_l[],
1140         short            pcm_r[],
1141         mp3data_struct*  mp3data,
1142         int              *enc_delay,
1143         int              *enc_padding );
1144 int CDECL lame_decode_exit(void);
1145
1146 #endif /* obsolete lame_decode API calls */
1147
1148
1149 /*********************************************************************
1150  *
1151  * id3tag stuff
1152  *
1153  *********************************************************************/
1154
1155 /*
1156  * id3tag.h -- Interface to write ID3 version 1 and 2 tags.
1157  *
1158  * Copyright (C) 2000 Don Melton.
1159  *
1160  * This library is free software; you can redistribute it and/or
1161  * modify it under the terms of the GNU Library General Public
1162  * License as published by the Free Software Foundation; either
1163  * version 2 of the License, or (at your option) any later version.
1164  *
1165  * This library is distributed in the hope that it will be useful,
1166  * but WITHOUT ANY WARRANTY; without even the implied warranty of
1167  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1168  * Library General Public License for more details.
1169  *
1170  * You should have received a copy of the GNU Library General Public
1171  * License along with this library; if not, write to the Free Software
1172  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
1173  */
1174
1175 /* utility to obtain alphabetically sorted list of genre names with numbers */
1176 void CDECL id3tag_genre_list(
1177         void (*handler)(int, const char *, void *),
1178         void*  cookie);
1179
1180 void CDECL id3tag_init     (lame_t gfp);
1181
1182 /* force addition of version 2 tag */
1183 void CDECL id3tag_add_v2   (lame_t gfp);
1184
1185 /* add only a version 1 tag */
1186 void CDECL id3tag_v1_only  (lame_t gfp);
1187
1188 /* add only a version 2 tag */
1189 void CDECL id3tag_v2_only  (lame_t gfp);
1190
1191 /* pad version 1 tag with spaces instead of nulls */
1192 void CDECL id3tag_space_v1 (lame_t gfp);
1193
1194 /* pad version 2 tag with extra 128 bytes */
1195 void CDECL id3tag_pad_v2   (lame_t gfp);
1196
1197 /* pad version 2 tag with extra n bytes */
1198 void CDECL id3tag_set_pad  (lame_t gfp, size_t n);
1199
1200 void CDECL id3tag_set_title(lame_t gfp, const char* title);
1201 void CDECL id3tag_set_artist(lame_t gfp, const char* artist);
1202 void CDECL id3tag_set_album(lame_t gfp, const char* album);
1203 void CDECL id3tag_set_year(lame_t gfp, const char* year);
1204 void CDECL id3tag_set_comment(lame_t gfp, const char* comment);
1205
1206 /* return -1 result if track number is out of ID3v1 range
1207                     and ignored for ID3v1 */
1208 int CDECL id3tag_set_track(lame_t gfp, const char* track);
1209
1210 /* return non-zero result if genre name or number is invalid
1211   result 0: OK
1212   result -1: genre number out of range
1213   result -2: no valid ID3v1 genre name, mapped to ID3v1 'Other'
1214              but taken as-is for ID3v2 genre tag */
1215 int CDECL id3tag_set_genre(lame_t gfp, const char* genre);
1216
1217 /* return non-zero result if field name is invalid */
1218 int CDECL id3tag_set_fieldvalue(lame_t gfp, const char* fieldvalue);
1219
1220 /* return non-zero result if image type is invalid */
1221 int CDECL id3tag_set_albumart(lame_t gfp, const char* image, size_t size);
1222
1223 /* lame_get_id3v1_tag copies ID3v1 tag into buffer.
1224  * Function returns number of bytes copied into buffer, or number
1225  * of bytes rquired if buffer 'size' is too small.
1226  * Function fails, if returned value is larger than 'size'.
1227  * NOTE:
1228  * This functions does nothing, if user/LAME disabled ID3v1 tag.
1229  */
1230 size_t CDECL lame_get_id3v1_tag(lame_t gfp, unsigned char* buffer, size_t size);
1231
1232 /* lame_get_id3v2_tag copies ID3v2 tag into buffer.
1233  * Function returns number of bytes copied into buffer, or number
1234  * of bytes rquired if buffer 'size' is too small.
1235  * Function fails, if returned value is larger than 'size'.
1236  * NOTE:
1237  * This functions does nothing, if user/LAME disabled ID3v2 tag.
1238  */
1239 size_t CDECL lame_get_id3v2_tag(lame_t gfp, unsigned char* buffer, size_t size);
1240
1241 /* normaly lame_init_param writes ID3v2 tags into the audio stream
1242  * Call lame_set_write_id3tag_automatic(gfp, 0) before lame_init_param
1243  * to turn off this behaviour and get ID3v2 tag with above function
1244  * write it yourself into your file.
1245  */
1246 void CDECL lame_set_write_id3tag_automatic(lame_global_flags * gfp, int);
1247 int CDECL lame_get_write_id3tag_automatic(lame_global_flags const* gfp);
1248
1249 /* experimental */
1250 int CDECL id3tag_set_textinfo_latin1(lame_global_flags * gfp, char const *id, char const *text);
1251
1252 /* experimental */
1253 int CDECL id3tag_set_comment_latin1(lame_global_flags * gfp,
1254                                     char const *lang, char const *desc, char const *text);
1255
1256 #if DEPRECATED_OR_OBSOLETE_CODE_REMOVED
1257 #else
1258 /* experimental */
1259 int CDECL id3tag_set_textinfo_ucs2(lame_global_flags * gfp,
1260                                    char const *id, unsigned short const *text);
1261
1262 /* experimental */
1263 int CDECL id3tag_set_comment_ucs2(lame_global_flags * gfp,
1264                                   char const *lang,
1265                                   unsigned short const *desc, unsigned short const *text);
1266
1267 /* experimental */
1268 int CDECL id3tag_set_fieldvalue_ucs2(lame_t gfp, const unsigned short *fieldvalue);
1269 #endif
1270
1271 /* experimental */
1272 int CDECL id3tag_set_fieldvalue_utf16(lame_t gfp, const unsigned short *fieldvalue);
1273
1274 /* experimental */
1275 int CDECL id3tag_set_textinfo_utf16(lame_global_flags * gfp,
1276                                     char const *id, unsigned short const *text);
1277
1278 /* experimental */
1279 int CDECL id3tag_set_comment_utf16(lame_global_flags * gfp,
1280                                    char const *lang,
1281                                    unsigned short const *desc, unsigned short const *text);
1282
1283
1284 /***********************************************************************
1285 *
1286 *  list of valid bitrates [kbps] & sample frequencies [Hz].
1287 *  first index: 0: MPEG-2   values  (sample frequencies 16...24 kHz)
1288 *               1: MPEG-1   values  (sample frequencies 32...48 kHz)
1289 *               2: MPEG-2.5 values  (sample frequencies  8...12 kHz)
1290 ***********************************************************************/
1291
1292 extern const int     bitrate_table    [3][16];
1293 extern const int     samplerate_table [3][ 4];
1294
1295 /* access functions for use in DLL, global vars are not exported */
1296 int CDECL lame_get_bitrate(int mpeg_version, int table_index);
1297 int CDECL lame_get_samplerate(int mpeg_version, int table_index);
1298
1299
1300 /* maximum size of albumart image (128KB), which affects LAME_MAXMP3BUFFER
1301    as well since lame_encode_buffer() also returns ID3v2 tag data */
1302 #define LAME_MAXALBUMART    (128 * 1024)
1303
1304 /* maximum size of mp3buffer needed if you encode at most 1152 samples for
1305    each call to lame_encode_buffer.  see lame_encode_buffer() below
1306    (LAME_MAXMP3BUFFER is now obsolete)  */
1307 #define LAME_MAXMP3BUFFER   (16384 + LAME_MAXALBUMART)
1308
1309
1310 typedef enum {
1311     LAME_OKAY             =   0,
1312     LAME_NOERROR          =   0,
1313     LAME_GENERICERROR     =  -1,
1314     LAME_NOMEM            = -10,
1315     LAME_BADBITRATE       = -11,
1316     LAME_BADSAMPFREQ      = -12,
1317     LAME_INTERNALERROR    = -13,
1318
1319     FRONTEND_READERROR    = -80,
1320     FRONTEND_WRITEERROR   = -81,
1321     FRONTEND_FILETOOLARGE = -82
1322
1323 } lame_errorcodes_t;
1324
1325 #if defined(__cplusplus)
1326 }
1327 #endif
1328 #endif /* LAME_LAME_H */
1329