minor bugfixes
[swftools.git] / 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 */