1First, see the file STYLEGUIDE 2 3************************************************************************ 4TESTING 5======= 6 7If you make changes, please test. There is a python script in the test/ 8directory which will compare two versions of lame using a bunch of CBR 9and ABR options. To run this script, copy your favorite (and short!) wav 10file to the lame/test directory, and run: 11 12% cd lame/test 13% ./lametest.py [-w] CBRABR.op castanets.wav lame_orig lame_new 14 15 16 17************************************************************************ 18LAME API 19======== 20 21For a general outline of the code, see the file API. 22Also, frontend/main.c is a simple front end to libmp3lame.a 23 24The guts of the code are called from lame_encode_buffer(). 25 26lame_encode_buffer() handles buffering and resampling, and 27then calls lame_encode_frame() for each frame. lame_encode_frame() 28looks like this: 29 30lame_encode_frame_mp3(): 31 l3psycho_anal() compute masking thresholds 32 mdct_sub() compute MDCT coefficients 33 iteration_loop() choose scalefactors (via iteration) 34 which determine noise shapping, and 35 choose best huffman tables for lossless compression 36 format_bitstream format the bitstream. when data+headers are complete, 37 output to internal bit buffer. 38 copy_buffer() copy internal bit buffer into user's mp3 buffer 39 40************************************************************************ 41ADDING NEW OPTIONS 42================== 43 44control variable goes in lame_global_flags struct. 45Assume the variable is called 'new_variable'. 46 47You also need to write (in set_get.c): 48 49lame_set_new_variable() 50lame_get_new_variable() 51 52And then document the variable in the file USAGE as well as the 53output of "lame --longhelp" 54 55And add a "--option" style command line option to enable this variable 56in parse.c 57 58Note: for experimental features that you need to call from the frontend 59but that should not be part of the official API, see the section at 60the end of set_get.c. These functions should *NOT* be prototyped in 61lame.h (since that would indicate to the world that they are part 62of the API). 63 64 65************************************************************************ 66THREADSAFE: 67=========== 68 69Lame should now be thread safe and re-entrant. The only problem seems to 70be some OS's allocate small stacks (< 128K) to threads launched by 71applications, and this is not enough for LAME. Fix is to increase the 72stack space, or move some of our automatic variables onto the heap with 73by using bug-proof malloc()'s and free(). 74 75 76************************************************************************ 77Global Variables: 78================= 79 80There are two types of global variables. All data in both structs is 81initialized to zero. 82 831. lame_global_flags *gfp 84 85These are input parameters which are set by the calling program, and some 86information which the calling program may be interested in. 87 88This struct instantiated by the call to lame_init(). 89 90 912. lame_internal_flags *gfc 92 93Most global variables go here. 94 95All internal data not set by the user. All 'static' data from 96old non-reentrant code should be moved here. 97 98Defined in util.h. Data for which the size is known 99in advance should be explicitly declaired (for example, 100float xr[576]); Data which needs to be malloc'd is 101handled by: 102 1031. in lame_init_params(), malloc the data 1042. be sure to free the data in freegfc() 105 106 107If the data to be malloc'd is large and only used in 108certain conditions (like resampling), use the following: 109this has the disadvantage that it is hard to catch and return error 110flags all the way back up the call stack. 111 1121. Add an initialization variable to the gfc struct: lame_init_resample 1132. In the resample routine, there should be some code like this: 114 115 if (0==gfc->lame_init_resample) { 116 gfc->lame_init_resample=1; 117 /* initialization code: malloc() data, etc */ 118 } 119 1203. The data should be free'd in the routine freegfc(). 121 122