1 files changed, 107 insertions, 0 deletions
diff --git a/lib/liblame/API b/lib/liblame/API
new file mode 100644
index 0000000000..c850df5311
--- /dev/null
+++ b/lib/liblame/API
@@ -0,0 +1,107 @@
+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 *); 
+
+