Debian Codegraph @

HACKING

raw
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