documentation update, build/install tweaks
[speexdsp.git] / doc / programming.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4   <title>Speex Programming</title>
5       
6   <meta http-equiv="content-type"
7  content="text/html; charset=ISO-8859-1">
8 </head>
9   <body>
10  
11 <div align="center"> 
12 <h1>Speex Programming</h1>
13  
14 <div align="left"> 
15 <h2>Encoding</h2>
16  In order to encode speech using Speex, you first need to:<br>
17  
18 <blockquote>   
19   <pre><big>#include &lt;speex.h&gt;</big></pre>
20  </blockquote>
21  You then need to declare a Speex bit-packing struct<br>
22  
23 <blockquote>   
24   <pre><big>SpeexBits bits;</big></pre>
25  </blockquote>
26  and a Speex encoder state<br>
27  
28 <blockquote>   
29   <pre><big>void *enc_state;</big></pre>
30  </blockquote>
31  The two are initialized by:<br>
32  
33 <blockquote>   
34   <pre><big>speex_bits_init(&amp;bits);</big></pre>
35    
36   <pre><big>enc_state = speex_encoder_init(&amp;speex_nb_mode);</big></pre>
37  </blockquote>
38  For wideband coding, <i>speex_nb_mode</i> will be replaced by <i>speex_wb_mode</i>
39 . In most cases, you will need to know the frame size used by the mode you
40 are using. You can get that value in the <i>frame_size</i> variable with:<br>
41 <blockquote><big><tt>speex_encoder_ctl(enc_state, SPEEX_GET_FRAME_SIZE, &amp;frame_size);</tt></big><br>
42 </blockquote>
43  For every input frame:<br>
44  
45 <blockquote>   
46   <pre><big>speex_bits_reset(&amp;bits);</big></pre>
47    
48   <pre><big>speex_encode(enc_state, input_frame, &amp;bits);</big></pre>
49    
50   <pre><big>nbBytes = speex_bits_write(&amp;bits, byte_ptr, MAX_NB_BYTES);</big></pre>
51  </blockquote>
52  where <i>input_frame</i> is a <i>(float *)</i> pointing to the beginning 
53 of a speech frame, byte_ptr is a <i>(char *)</i> where the encoded frame will
54 be written, <i>MAX_NB_BYTES</i> is the maximum number of bytes that can be
55 written to <i>byte_ptr</i> without causing an overflow and <i>nbBytes</i>
56   is the number of bytes actually written to <i>byte_ptr</i> (the encoded 
57 size in bytes).<br>
58  <br>
59  After you're done with the encoding, free all resources with:<br>
60  
61 <blockquote>   
62   <pre><big>speex_bits_destroy(&amp;bits);</big></pre>
63    
64   <pre><big>speex_encoder_destroy(&amp;enc_state);</big></pre>
65  </blockquote>
66  That's about it for the encoder.<br>
67  
68 <h2>Decoding</h2>
69  In order to encode speech using Speex, you first need to:<br>
70    
71 <blockquote>      
72   <pre><big>#include &lt;speex.h&gt;</big></pre>
73   </blockquote>
74   You then need to declare a Speex bit-packing struct<br>
75    
76 <blockquote>      
77   <pre><big>SpeexBits bits;</big></pre>
78   </blockquote>
79   and a Speex encoder state<br>
80    
81 <blockquote>      
82   <pre><big>void *dec_state;</big></pre>
83   </blockquote>
84   The two are initialized by:<br>
85    
86 <blockquote>      
87   <pre><big>speex_bits_init(&amp;bits);</big></pre>
88        
89   <pre><big>dec_state = speex_decoder_init(&amp;speex_nb_mode);</big></pre>
90   </blockquote>
91   For wideband decoding, <i>speex_nb_mode</i> will be replaced by <i>speex_wb_mode</i>
92 . You can get that value in the <i>frame_size</i> variable with:<br>
93  
94 <blockquote><big><tt>speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &amp;frame_size);</tt></big><br>
95 </blockquote>
96   There is also a parameter that can be set for the decoder: whether or not
97 to use a perceptual post-filter. This can be set by:<br>
98 <blockquote><big><tt>speex_decoder_ctl(dec_state, SPEEX_SET_PF, &amp;pf);</tt></big><br>
99 </blockquote>
100 where <i>pf</i> is an <i>int</i> that with value 0 to have the post-filter
101 disabled and 1 to have it enabled.<br>
102 <br>
103 For every input frame:<br>
104        
105 <blockquote>   
106   <pre><big>speex_bits_read_from(&amp;bits, input_bytes, nbBytes);</big></pre>
107    
108   <pre><big>speex_decode(st, &amp;bits, output_frame, 0);</big></pre>
109  </blockquote>
110  where <i>input_bytes</i> is a <i>(char *)</i> containing the bit-stream
111 data received for a frame, <i>nbBytes</i> is the size (in bytes) of that
112 bit-stream, and <i>output_frame</i> is a <i>(float *)</i> and points to the
113 area where the decoded speech frame will be written. The last argument indicates
114 whether the frame we'd like to decode was lost. A value of 0 indicates the
115 normal case where bits points to the bit of the current frame. A value of
116 1 indicates that we don't have the bits for the current frame, in which case
117 the bits argument should be the same as the bits for the last correctly received
118 frame. When a frame is lost, the Speex decoder will do its best to "guess"
119 the sorrect signal.<br>
120  <br>
121  </div>
122  </div>
123  
124 </body>
125 </html>