| The LAME API |
| |
| This is the simple interface to the encoding part of libmp3lame.so. |
| The library also contains routines for adding id3 tags and |
| mp3 decoding. These routines are not fully documented, |
| but you can figure them out by looking at "include/lame.h" and the |
| example frontend encoder/decoder source code in frontend/main.c |
| |
| All of these steps should be done for every MP3 to be encoded. |
| |
| |
| ========================================================================= |
| |
| 1. (optional) Get the version number of the encoder, if you are interested. |
| void get_lame_version(char *strbuf, size_t buflen, const char *prefix); |
| |
| |
| 2. Error messages. By default, LAME will write error messages to |
| stderr using vfprintf(). For GUI applications, this is often a problem |
| and you need to set your own error message handlers: |
| |
| lame_set_errorf(gfp,error_handler_function); |
| lame_set_debugf(gfp,error_handler_function); |
| lame_set_msgf(gfp,error_handler_function); |
| |
| See lame.h for details. |
| |
| |
| 3. Initialize the encoder. sets default for all encoder parameters. |
| |
| #include "lame.h" |
| lame_global_flags *gfp; |
| gfp = lame_init(); |
| |
| The default (if you set nothing) is a J-Stereo, 44.1khz |
| 128kbps CBR mp3 file at quality 5. Override various default settings |
| as necessary, for example: |
| |
| lame_set_num_channels(gfp,2); |
| lame_set_in_samplerate(gfp,44100); |
| lame_set_brate(gfp,128); |
| lame_set_mode(gfp,1); |
| lame_set_quality(gfp,2); /* 2=high 5 = medium 7=low */ |
| |
| |
| See lame.h for the complete list of options. Note that there are |
| some lame_set_*() calls not documented in lame.h. These functions |
| are experimental and for testing only. They may be removed in |
| the future. |
| |
| |
| |
| 4. Set more internal configuration based on data provided above, |
| as well as checking for problems. Check that ret_code >= 0. |
| |
| ret_code = lame_init_params(gfp); |
| |
| |
| |
| 5. Encode some data. input pcm data, output (maybe) mp3 frames. |
| This routine handles all buffering, resampling and filtering for you. |
| The required mp3buffer_size can be computed from num_samples, |
| samplerate and encoding rate, but here is a worst case estimate: |
| mp3buffer_size (in bytes) = 1.25*num_samples + 7200. |
| num_samples = the number of PCM samples in each channel. It is |
| not the sum of the number of samples in the L and R channels. |
| |
| The return code = number of bytes output in mp3buffer. This can be 0. |
| If it is <0, an error occured. |
| |
| int lame_encode_buffer(lame_global_flags *gfp, |
| short int leftpcm[], short int rightpcm[], |
| int num_samples,char *mp3buffer,int mp3buffer_size); |
| |
| |
| There are also routines for various types of input |
| (float, long, interleaved, etc). See lame.h for details. |
| |
| |
| 6. lame_encode_flush will flush the buffers and may return a |
| final few mp3 frames. mp3buffer should be at least 7200 bytes. |
| return code = number of bytes output to mp3buffer. This can be 0. |
| |
| int lame_encode_flush(lame_global_flags *,char *mp3buffer, int mp3buffer_size); |
| |
| |
| 7. Write the Xing VBR/INFO tag to mp3 file. |
| |
| void lame_mp3_tags_fid(lame_global_flags *,FILE* fid); |
| |
| This adds a valid mp3 frame which contains information about the |
| bitstream some players may find usefull. It is used for CBR,ABR and |
| VBR. The routine will attempt to rewind the output stream to the |
| beginning. If this is not possible, (for example, you are encoding to |
| stdout) you should specifically disable the tag by calling |
| lame_set_bWriteVbrTag(gfp,0) in step 3 above, and call |
| lame_mp3_tags_fid() with fid=NULL. If the rewind fails and |
| the tag was not disabled, the first mp3 frame in the bitstream |
| will be all 0's. |
| |
| |
| |
| 8. free the internal data structures. |
| |
| void lame_close(lame_global_flags *); |
| |
| |