• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1The LAME API
2
3This is the simple interface to the encoding part of libmp3lame.so.
4The library also contains routines for adding id3 tags and
5mp3 decoding.  These routines are not fully documented,
6but you can figure them out by looking at "include/lame.h" and the
7example frontend encoder/decoder source code in frontend/main.c
8
9All of these steps should be done for every MP3 to be encoded.
10
11
12=========================================================================
13
141. (optional) Get the version number of the encoder, if you are interested.
15   void get_lame_version(char *strbuf, size_t buflen, const char *prefix);
16
17
182. Error messages.  By default, LAME will write error messages to
19stderr using vfprintf().  For GUI applications, this is often a problem
20and you need to set your own error message handlers:
21
22   lame_set_errorf(gfp,error_handler_function);
23   lame_set_debugf(gfp,error_handler_function);
24   lame_set_msgf(gfp,error_handler_function);
25
26See lame.h for details.
27
28
293. Initialize the encoder.  sets default for all encoder parameters.
30
31   #include "lame.h"
32   lame_global_flags *gfp;
33   gfp = lame_init();
34
35The default (if you set nothing) is a  J-Stereo, 44.1khz
36128kbps CBR mp3 file at quality 5.  Override various default settings
37as necessary, for example:
38
39   lame_set_num_channels(gfp,2);
40   lame_set_in_samplerate(gfp,44100);
41   lame_set_brate(gfp,128);
42   lame_set_mode(gfp,1);
43   lame_set_quality(gfp,2);   /* 2=high  5 = medium  7=low */
44
45
46See lame.h for the complete list of options.  Note that there are
47some lame_set_*() calls not documented in lame.h.  These functions
48are experimental and for testing only.  They may be removed in
49the future.
50
51
52
534. Set more internal configuration based on data provided above,
54   as well as checking for problems.  Check that ret_code >= 0.
55
56   ret_code = lame_init_params(gfp);
57
58
59
605. Encode some data.  input pcm data, output (maybe) mp3 frames.
61This routine handles all buffering, resampling and filtering for you.
62The required mp3buffer_size can be computed from num_samples,
63samplerate and encoding rate, but here is a worst case estimate:
64mp3buffer_size (in bytes) = 1.25*num_samples + 7200.
65num_samples = the number of PCM samples in each channel.  It is
66not the sum of the number of samples in the L and R channels.
67
68The return code = number of bytes output in mp3buffer.  This can be 0.
69If it is <0, an error occured.
70
71   int lame_encode_buffer(lame_global_flags *gfp,
72         short int leftpcm[], short int rightpcm[],
73         int num_samples,char *mp3buffer,int  mp3buffer_size);
74
75
76There are also routines for various types of input
77(float, long, interleaved, etc).  See lame.h for details.
78
79
806. lame_encode_flush will flush the buffers and may return a
81final few mp3 frames.  mp3buffer should be at least 7200 bytes.
82return code = number of bytes output to mp3buffer.  This can be 0.
83
84int lame_encode_flush(lame_global_flags *,char *mp3buffer, int mp3buffer_size);
85
86
877.  Write the Xing VBR/INFO tag to mp3 file.
88
89void lame_mp3_tags_fid(lame_global_flags *,FILE* fid);
90
91This adds a valid mp3 frame which contains information about the
92bitstream some players may find usefull.  It is used for CBR,ABR and
93VBR.  The routine will attempt to rewind the output stream to the
94beginning.  If this is not possible, (for example, you are encoding to
95stdout) you should specifically disable the tag by calling
96lame_set_bWriteVbrTag(gfp,0) in step 3 above, and call
97lame_mp3_tags_fid() with fid=NULL.  If the rewind fails and
98the tag was not disabled, the first mp3 frame in the bitstream
99will be all 0's.
100
101
102
1038. free the internal data structures.
104
105void lame_close(lame_global_flags *);
106
107
108