| 1 |
First, see the file STYLEGUIDE |
| 2 |
|
| 3 |
************************************************************************ |
| 4 |
TESTING |
| 5 |
======= |
| 6 |
|
| 7 |
If you make changes, please test. There is a python script in the test/ |
| 8 |
directory which will compare two versions of lame using a bunch of CBR |
| 9 |
and ABR options. To run this script, copy your favorite (and short!) wav |
| 10 |
file 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 |
************************************************************************ |
| 18 |
LAME API |
| 19 |
======== |
| 20 |
|
| 21 |
For a general outline of the code, see the file API. |
| 22 |
Also, frontend/main.c is a simple front end to libmp3lame.a |
| 23 |
|
| 24 |
The guts of the code are called from lame_encode_buffer(). |
| 25 |
|
| 26 |
lame_encode_buffer() handles buffering and resampling, and |
| 27 |
then calls lame_encode_frame() for each frame. lame_encode_frame() |
| 28 |
looks like this: |
| 29 |
|
| 30 |
lame_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 |
************************************************************************ |
| 41 |
ADDING NEW OPTIONS |
| 42 |
================== |
| 43 |
|
| 44 |
control variable goes in lame_global_flags struct. |
| 45 |
Assume the variable is called 'new_variable'. |
| 46 |
|
| 47 |
You also need to write (in set_get.c): |
| 48 |
|
| 49 |
lame_set_new_variable() |
| 50 |
lame_get_new_variable() |
| 51 |
|
| 52 |
And then document the variable in the file USAGE as well as the |
| 53 |
output of "lame --longhelp" |
| 54 |
|
| 55 |
And add a "--option" style command line option to enable this variable |
| 56 |
in parse.c |
| 57 |
|
| 58 |
Note: for experimental features that you need to call from the frontend |
| 59 |
but that should not be part of the official API, see the section at |
| 60 |
the end of set_get.c. These functions should *NOT* be prototyped in |
| 61 |
lame.h (since that would indicate to the world that they are part |
| 62 |
of the API). |
| 63 |
|
| 64 |
|
| 65 |
************************************************************************ |
| 66 |
THREADSAFE: |
| 67 |
=========== |
| 68 |
|
| 69 |
Lame should now be thread safe and re-entrant. The only problem seems to |
| 70 |
be some OS's allocate small stacks (< 128K) to threads launched by |
| 71 |
applications, and this is not enough for LAME. Fix is to increase the |
| 72 |
stack space, or move some of our automatic variables onto the heap with |
| 73 |
by using bug-proof malloc()'s and free(). |
| 74 |
|
| 75 |
|
| 76 |
************************************************************************ |
| 77 |
Global Variables: |
| 78 |
================= |
| 79 |
|
| 80 |
There are two types of global variables. All data in both structs is |
| 81 |
initialized to zero. |
| 82 |
|
| 83 |
1. lame_global_flags *gfp |
| 84 |
|
| 85 |
These are input parameters which are set by the calling program, and some |
| 86 |
information which the calling program may be interested in. |
| 87 |
|
| 88 |
This struct instantiated by the call to lame_init(). |
| 89 |
|
| 90 |
|
| 91 |
2. lame_internal_flags *gfc |
| 92 |
|
| 93 |
Most global variables go here. |
| 94 |
|
| 95 |
All internal data not set by the user. All 'static' data from |
| 96 |
old non-reentrant code should be moved here. |
| 97 |
|
| 98 |
Defined in util.h. Data for which the size is known |
| 99 |
in advance should be explicitly declaired (for example, |
| 100 |
float xr[576]); Data which needs to be malloc'd is |
| 101 |
handled by: |
| 102 |
|
| 103 |
1. in lame_init_params(), malloc the data |
| 104 |
2. be sure to free the data in freegfc() |
| 105 |
|
| 106 |
|
| 107 |
If the data to be malloc'd is large and only used in |
| 108 |
certain conditions (like resampling), use the following: |
| 109 |
this has the disadvantage that it is hard to catch and return error |
| 110 |
flags all the way back up the call stack. |
| 111 |
|
| 112 |
1. Add an initialization variable to the gfc struct: lame_init_resample |
| 113 |
2. 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 |
|
| 120 |
3. The data should be free'd in the routine freegfc(). |
| 121 |
|