2
* tooLAME: an optimized mpeg 1/2 layer 2 audio encoder
4
* Copyright (C) 2001-2004 Michael Cheng
6
* This library is free software; you can redistribute it and/or
7
* modify it under the terms of the GNU Lesser General Public
8
* License as published by the Free Software Foundation; either
9
* version 2.1 of the License, or (at your option) any later version.
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
* Lesser General Public License for more details.
16
* You should have received a copy of the GNU Lesser General Public
17
* License along with this library; if not, write to the Free Software
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
41
STEREO = 0, /**< Stereo */
42
JOINT_STEREO, /**< Joint Stereo */
43
DUAL_CHANNEL, /**< Dual Channel */
51
* MPEG2 is for Lower Sampling Frequencies - LSF < 32000.
54
MPEG2_LSF = 0, /**< MPEG-2 - for sample rates less than 32k */
61
PAD_NO = 0, /**< No Padding */
62
PAD_ALL /**< Pad all frames */
63
// PAD_ADJUST // unsupported by toolame
66
/** Emphasis types. */
68
EMPHASIS_N = 0, /**< No Emphasis */
69
EMPHASIS_5 = 1, /**< 50/15 ms */
71
EMPHASIS_C = 3, /**< CCIT J.17 */
75
/** Opaque structure for the toolame encoder options. */
76
struct toolame_options_struct;
78
/** Opaque data type for the toolame encoder options. */
79
typedef struct toolame_options_struct toolame_options;
85
/** Get version number of the toolame library.
88
* \return The version number as a string
90
const char* get_toolame_version( void );
93
/** Initialise the toolame encoder.
95
* Sets defaults for all parameters.
96
* Will return NULL if malloc() failed, otherwise
97
* returns a pointer which you then need to pass to
98
* all future API calls.
100
* \return a pointer to your new options data structure
102
toolame_options *toolame_init(void);
105
/** Prepare to start encoding.
107
* You must call toolame_init_params() before you start encoding.
108
* It will check call your parameters to make sure they are valid,
109
* as well as allocating buffers and initising internally used
112
* \param glopts Options pointer created by toolame_init()
113
* \return 0 if all patameters are valid,
114
* non-zero if something is invalid
116
int toolame_init_params(toolame_options *glopts);
119
/** Encode some PCM audio to MP2.
121
* Takes 16-bit PCM audio samples from seperate left and right
122
* buffers and places encoded audio into mp2buffer.
124
* \param glopts toolame options pointer
125
* \param leftpcm Left channel audio samples
126
* \param rightpcm Right channel audio samples
127
* \param num_samples Number of samples per channel
128
* \param mp2buffer Buffer to place encoded audio into
129
* \param mp2buffer_size Size of the output buffer
130
* \return The number of bytes put in output buffer
132
int toolame_encode_buffer(
133
toolame_options *glopts,
134
const short int leftpcm[],
135
const short int rightpcm[],
137
unsigned char *mp2buffer,
138
int mp2buffer_size );
141
/** Encode some PCM audio to MP2.
143
* Takes interleaved 16-bit PCM audio samples from a single
144
* buffer and places encoded audio into mp2buffer.
146
* \param glopts toolame options pointer
147
* \param pcm Audio samples for left AND right channels
148
* \param num_samples Number of samples per channel
149
* \param mp2buffer Buffer to place encoded audio into
150
* \param mp2buffer_size Size of the output buffer
151
* \return The number of bytes put in output buffer
153
int toolame_encode_buffer_interleaved(
154
toolame_options *glopts,
155
const short int pcm[],
157
unsigned char *mp2buffer,
158
int mp2buffer_size );
161
/** Encode any remains buffered PCM audio to MP2.
163
* Encodes any remaining audio samples in the libtoolame
164
* internal sample buffer. This function will return at
165
* most a single frame of MPEG Audio, and at least 0 frames.
167
* \param glopts toolame options pointer
168
* \param mp2buffer Buffer to place encoded audio into
169
* \param mp2buffer_size Size of the output buffer
170
* \return The number of bytes put in output buffer
172
int toolame_encode_flush(
173
toolame_options *glopts,
174
unsigned char *mp2buffer,
178
/** Shut down the toolame encoder.
180
* Shuts down the toolame encoder and frees all memory
181
* that it previously allocated. You should call this
182
* once you have finished all your encoding. This function
183
* will set your glopts pointer to NULL for you.
185
* \param glopts pointer to toolame options pointer
187
void toolame_close(toolame_options **glopts);
191
/** Set the verbosity of the encoder.
193
* Sets how verbose the encoder is with the debug and
194
* informational messages it displays. The higher the
195
* number, the more messages it will display.
199
* \param glopts pointer to toolame options pointer
200
* \param verbosity integer between 0 and 100
201
* \return 0 if successful,
202
* non-zero on failure
204
int toolame_set_verbosity(toolame_options *glopts, int verbosity);
207
/** Get the verbosity of the encoder.
209
* \param glopts pointer to toolame options pointer
210
* \return integer indicating the verbosity of the encoder
212
int toolame_get_verbosity(toolame_options *glopts);
215
/** Get the bitrate index for a bitrate.
217
* Returns the index associated with a bitrate for
218
* the specified version of MPEG.
220
* \param version The version of MPEG
221
* [MPEG1 or MPEG2_LSF]
222
* \param bitrate The bitrate to lookup in kbps
223
* \return The bitrate index if successful,
224
* -1 if invalid bitrate
226
int toolame_get_bitrate_index(MPEG_version version, int bitrate);
229
/** Get the sample rate index for a samplerate.
231
* Returns the index associated with a bitrate for
232
* the specified version of MPEG.
234
* \param sampleRate The sample rate to lookup (Hz)
235
* \param version The version of MPEG to use is returned in this integer pointer
236
* \return The sample rate index if successful,
237
* -1 if invalid sample rate
239
int toolame_get_samplerate_index(long sampleRate, MPEG_version *version);
242
/** Set the MPEG Audio Mode (Mono, Stereo, etc) for
247
* \param glopts pointer to toolame options pointer
248
* \param mode the mode to set to
249
* \return 0 if successful,
250
* non-zero on failure
252
int toolame_set_mode(toolame_options *glopts, MPEG_mode mode);
255
/** Get the MPEG Audio mode of the output stream.
257
* \param glopts pointer to toolame options pointer
258
* \return the MPEG audio mode
260
MPEG_mode toolame_get_mode(toolame_options *glopts);
263
/** Get a string name for the current MPEG Audio mode.
265
* \param glopts pointer to toolame options pointer
266
* \return the name of the MPEG audio mode as a string
268
const char *toolame_get_mode_name(toolame_options *glopts);
271
/** Set the MPEG version of the MPEG audio stream.
275
* \param glopts pointer to toolame options pointer
276
* \param version the version to set to
277
* \return 0 if successful,
278
* non-zero on failure
280
int toolame_set_version(toolame_options *glopts, MPEG_version version);
283
/** Get the MPEG version of the output stream.
285
* \param glopts pointer to toolame options pointer
286
* \return the MPEG version
288
MPEG_version toolame_get_version(toolame_options *glopts);
291
/** Get a string name for the current MPEG version.
293
* \param glopts pointer to toolame options pointer
294
* \return the name of the MPEG version as a string
296
const char *toolame_get_version_name( toolame_options *glopts );
299
/** Set the Psychoacoustic Model used to encode the audio.
303
* \param glopts pointer to toolame options pointer
304
* \param psymodel the psychoacoustic model number
305
* \return 0 if successful,
306
* non-zero on failure
308
int toolame_set_psymodel(toolame_options *glopts, int psymodel);
311
/** Get the Psychoacoustic Model used to encode the audio.
313
* \param glopts pointer to toolame options pointer
314
* \return the psychoacoustic model number
316
int toolame_get_psymodel(toolame_options *glopts);
319
/** Set the number of channels in the input stream.
321
* If this is different the number of channels in
322
* the output stream (set by mode) then the encoder
323
* will automatically downmix/upmix the audio.
327
* \param glopts pointer to toolame options pointer
328
* \param num_channels the number of input channels
329
* \return 0 if successful,
330
* non-zero on failure
332
int toolame_set_num_channels(toolame_options* glopts, int num_channels);
335
/** Get the number of channels in the input stream.
337
* \param glopts pointer to toolame options pointer
338
* \return the number of channels
340
int toolame_get_num_channels(toolame_options* glopts);
343
/** Set the samplerate of the PCM audio input.
347
* \param glopts pointer to toolame options pointer
348
* \param samplerate the samplerate in Hz
349
* \return 0 if successful,
350
* non-zero on failure
352
int toolame_set_in_samplerate(toolame_options *glopts, int samplerate);
355
/** Get the samplerate of the PCM audio input.
357
* \param glopts pointer to toolame options pointer
358
* \return the input samplerate
360
int toolame_get_in_samplerate(toolame_options *glopts);
363
/** Set the samplerate of the MPEG audio output.
367
* \param glopts pointer to toolame options pointer
368
* \param samplerate the samplerate in Hz
369
* \return 0 if successful,
370
* non-zero on failure
372
int toolame_set_out_samplerate(toolame_options *glopts, int samplerate);
375
/** Get the samplerate of the MPEG audio output.
377
* \param glopts pointer to toolame options pointer
378
* \return the output samplerate
380
int toolame_get_out_samplerate(toolame_options *glopts);
383
/** Set the bitrate of the MPEG audio output stream.
387
* \param glopts pointer to toolame options pointer
388
* \param bitrate the bitrate in kbps
389
* \return 0 if successful,
390
* non-zero on failure
392
int toolame_set_bitrate(toolame_options *glopts, int bitrate);
395
/** Get the bitrate of the MPEG audio output.
397
* \param glopts pointer to toolame options pointer
398
* \return the output bitrate in kbps
400
int toolame_get_bitrate(toolame_options *glopts);
403
/** Set the bitrate of the MPEG audio output stream (LAME style).
405
* same as toolame_set_bitrate()
407
int toolame_set_brate(toolame_options *glopts, int bitrate);
410
/** Get the bitrate of the MPEG audio output stream (LAME style).
412
* same as toolame_get_bitrate()
414
int toolame_get_brate(toolame_options *glopts);
417
/** Set frame padding for the MPEG audio output stream.
419
* i.e. adjust frame sizes to achieve overall target bitrate
423
* \param glopts pointer to toolame options pointer
424
* \param padding the padding type
425
* \return 0 if successful,
426
* non-zero on failure
428
int toolame_set_padding(toolame_options *glopts, Padding_type padding);
430
/** Get the padding type of the MPEG audio output.
432
* \param glopts pointer to toolame options pointer
433
* \return the output bitrate in kbps
435
Padding_type toolame_get_padding(toolame_options *glopts);
438
/** Enable/Disable Energy Level Extension.
442
* \param glopts pointer to toolame options pointer
443
* \param energylevels energy level extension state
444
* \return 0 if successful,
445
* non-zero on failure
447
int toolame_set_energy_levels(toolame_options *glopts, int energylevels );
450
/** Get the Energy Level Extension state.
452
* \param glopts pointer to toolame options pointer
453
* \return state of the Energy Level Extension (TRUE/FALSE)
455
int toolame_get_energy_levels(toolame_options *glopts);
458
/** Set number of Ancillary Bits at end of frame.
462
* \param glopts pointer to toolame options pointer
463
* \param num number of bits to reserve
464
* \return 0 if successful,
465
* non-zero on failure
467
int toolame_set_num_ancillary_bits(toolame_options *glopts, int num);
470
/** Get the number of Ancillary Bits at end of frame.
472
* \param glopts pointer to toolame options pointer
473
* \return number of Ancillary Bits at end of frame
475
int toolame_get_num_ancillary_bits(toolame_options *glopts);
479
/** Set the type of pre-emphasis to be applied to the decoded audio.
481
* Default: EMPHASIS_N
483
* \param glopts pointer to toolame options pointer
484
* \param emphasis the type of pre-emphasis
485
* \return 0 if successful,
486
* non-zero on failure
488
int toolame_set_emphasis(toolame_options *glopts, Emphasis_type emphasis);
491
/** Get the type of pre-emphasis to be applied to the decoded audio.
493
* \param glopts pointer to toolame options pointer
494
* \return the type of pre-emphasis
496
Emphasis_type toolame_get_emphasis(toolame_options *glopts);
499
/** Enable/Disable CRC Error Protection.
503
* \param glopts pointer to toolame options pointer
504
* \param err_protection error protection state (TRUE/FALSE)
505
* \return 0 if successful,
506
* non-zero on failure
508
int toolame_set_error_protection(toolame_options *glopts, int err_protection);
511
/** Get the CRC Error Protection state.
513
* \param glopts pointer to toolame options pointer
514
* \return state of Error Protection (TRUE/FALSE)
516
int toolame_get_error_protection(toolame_options *glopts);
519
/** Set the MPEG Audio Copyright flag.
521
* Indicates that MPEG stream is copyrighted.
525
* \param glopts pointer to toolame options pointer
526
* \param copyright copyright flag state (TRUE/FALSE)
527
* \return 0 if successful,
528
* non-zero on failure
530
int toolame_set_copyright(toolame_options *glopts, int copyright);
533
/** Get the copright flag state
535
* \param glopts pointer to toolame options pointer
536
* \return state of the copyright flag (TRUE/FALSE)
538
int toolame_get_copyright(toolame_options *glopts);
541
/** Set the MPEG Audio Original flag.
545
* \param glopts pointer to toolame options pointer
546
* \param original original flag state (TRUE/FALSE)
547
* \return 0 if successful,
548
* non-zero on failure
550
int toolame_set_original(toolame_options *glopts, int original);
553
/** Get the origianl flag state.
555
* \param glopts pointer to toolame options pointer
556
* \return state of the original flag (TRUE/FALSE)
558
int toolame_get_original(toolame_options *glopts);
561
/** Enable/Disable VBR (Variable Bit Rate) mode.
565
* \param glopts pointer to toolame options pointer
566
* \param vbr VBR state (TRUE/FALSE)
567
* \return 0 if successful,
568
* non-zero on failure
570
int toolame_set_VBR(toolame_options *glopts, int vbr);
573
/** Get the VBR state.
575
* \param glopts pointer to toolame options pointer
576
* \return state of VBR (TRUE/FALSE)
578
int toolame_get_VBR(toolame_options *glopts);
581
/** Set the level/quality of the VBR audio.
583
* The level value can is a measurement of quality - the higher
584
* the level the higher the average bitrate of the resultant file.
588
* \param glopts pointer to toolame options pointer
589
* \param level quality level (-? -> ?)
590
* \return 0 if successful,
591
* non-zero on failure
593
int toolame_set_VBR_q(toolame_options *glopts, FLOAT level);
596
/** Get the level/quality of the VBR audio.
598
* \param glopts pointer to toolame options pointer
599
* \return quality value for VBR
601
FLOAT toolame_get_VBR_q(toolame_options *glopts);
604
/** Set the adjustment (in dB) applied to the ATH for Psycho models 3 and 4.
608
* \param glopts pointer to toolame options pointer
609
* \param level adjustment level in db
610
* \return 0 if successful,
611
* non-zero on failure
613
int toolame_set_ATH_level(toolame_options *glopts, FLOAT level);
616
/** Get the adjustment (in dB) applied to the ATH for Psycho models 3 and 4.
618
* \param glopts pointer to toolame options pointer
619
* \return adjustment level in db
621
FLOAT toolame_get_ATH_level(toolame_options *glopts);
624
/** Set the upper bitrate for VBR
628
* \param glopts pointer to toolame options pointer
629
* \param bitrate upper bitrate for VBR
630
* \return 0 if successful,
631
* non-zero on failure
633
int toolame_set_VBR_max_bitrate_kbps(toolame_options *glopts, int bitrate);
635
/** Get the upper bitrate for VBR.
637
* \param glopts pointer to toolame options pointer
638
* \return the upper bitrate for VBR
640
int toolame_get_VBR_max_bitrate_kbps(toolame_options *glopts);
643
/** Enable/Disable the quick mode for psycho model calculation.
647
* \param glopts pointer to toolame options pointer
648
* \param quickmode the state of quick mode (TRUE/FALSE)
649
* \return 0 if successful,
650
* non-zero on failure
652
int toolame_set_quick_mode(toolame_options *glopts, int quickmode);
654
/** Get the state of quick mode.
656
* \param glopts pointer to toolame options pointer
657
* \return the state of quick mode (TRUE/FALSE)
659
int toolame_get_quick_mode(toolame_options *glopts);
662
/** Set how often the psy model is calculated.
666
* \param glopts pointer to toolame options pointer
667
* \param quickcount number of frames between calculations
668
* \return 0 if successful,
669
* non-zero on failure
671
int toolame_set_quick_count(toolame_options *glopts, int quickcount );
673
/** Get the how often the psy model is calculated.
675
* \param glopts pointer to toolame options pointer
676
* \return number of frames between calculations
678
int toolame_get_quick_count(toolame_options *glopts);
681
/** Enable/Disable the Eureka 147 DAB extensions for MP2.
685
* \param glopts pointer to toolame options pointer
686
* \param dab state of DAB extensions (TRUE/FALSE)
687
* \return 0 if successful,
688
* non-zero on failure
690
int toolame_set_DAB(toolame_options *glopts, int dab);
692
/** Get the state of the DAB extensions
694
* \param glopts pointer to toolame options pointer
695
* \return the state of DAB (TRUE/FALSE)
697
int toolame_get_DAB(toolame_options *glopts);
700
/** Set the number of bytes to reserve for DAB XPAD data.
704
* \param glopts pointer to toolame options pointer
705
* \param length number of bytes to reserve
706
* \return 0 if successful,
707
* non-zero on failure
709
int toolame_set_DAB_xpad_length(toolame_options *glopts, int length);
712
/** Get the number of bytes reserved for DAB XPAD data.
714
* \param glopts pointer to toolame options pointer
715
* \return number of XPAD bytes
717
int toolame_get_DAB_xpad_length(toolame_options *glopts);
720
/** Set the CRC error protection length for DAB.
724
* \param glopts pointer to toolame options pointer
725
* \param length length of DAB CRC
726
* \return 0 if successful,
727
* non-zero on failure
729
int toolame_set_DAB_crc_length(toolame_options *glopts, int length);
732
/** Get the CRC error protection length for DAB.
734
* \param glopts pointer to toolame options pointer
735
* \return length of DAB CRC
737
int toolame_get_DAB_crc_length(toolame_options *glopts);