Programming doc
[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   <meta http-equiv="content-type"
6  content="text/html; charset=ISO-8859-1">
7 </head>
8 <body>
9 <div align="center">
10 <h1>Speex Programming</h1>
11 <div align="left">
12 <h2>Encoding</h2>
13 In order to encode speech using Speex, you first need to:<br>
14 <blockquote>
15   <pre><big>#include &lt;speex.h&gt;</big></pre>
16 </blockquote>
17 You then need to declare a Speex bit-packing struct<br>
18 <blockquote>
19   <pre><big>SpeexBits bits;</big></pre>
20 </blockquote>
21 and a Speex encoder state<br>
22 <blockquote>
23   <pre><big>void *enc_state;</big></pre>
24 </blockquote>
25 The two are initialized by:<br>
26 <blockquote>
27   <pre><big>speex_bits_init(&amp;bits);</big></pre>
28   <pre><big>enc_state = speex_encoder_init(&amp;speex_nb_mode);</big></pre>
29 </blockquote>
30 For wideband coding, <i>speex_nb_mode</i> will be replaced by <i>speex_wb_mode</i>
31 .<br>
32 <br>
33 For every input frame:<br>
34 <blockquote>
35   <pre><big>speex_bits_reset(&amp;bits);</big></pre>
36   <pre><big>speex_encode(enc_state, input_frame, &amp;bits);</big></pre>
37   <pre><big>nbBytes = speex_bits_write(&amp;bits, byte_ptr, MAX_NB_BYTES);</big></pre>
38 </blockquote>
39 where <i>input_frame</i> is a <i>(float *)</i> pointing to the beginning
40 of a speech frame, byte_ptr is a <i>(char *)</i> where the encoded frame
41 will be written, <i>MAX_NB_BYTES</i> is the maximum number of bytes that
42 can be written to <i>byte_ptr</i> without causing an overflow and <i>nbBytes</i>
43  is the number of bytes actually written to <i>byte_ptr</i> (the encoded
44 size in bytes).<br>
45 <br>
46 After you're done with the encoding, free all resources with:<br>
47 <blockquote>
48   <pre><big>speex_bits_destroy(&amp;bits);</big></pre>
49   <pre><big>speex_encoder_destroy(&amp;enc_state);</big></pre>
50 </blockquote>
51 That's about it for the encoder.<br>
52 <h2>Decoding</h2>
53 In order to encode speech using Speex, you first need to:<br>
54  
55 <blockquote>   
56   <pre><big>#include &lt;speex.h&gt;</big></pre>
57  </blockquote>
58  You then need to declare a Speex bit-packing struct<br>
59  
60 <blockquote>   
61   <pre><big>SpeexBits bits;</big></pre>
62  </blockquote>
63  and a Speex encoder state<br>
64  
65 <blockquote>   
66   <pre><big>void *dec_state;</big></pre>
67  </blockquote>
68  The two are initialized by:<br>
69  
70 <blockquote>   
71   <pre><big>speex_bits_init(&amp;bits);</big></pre>
72    
73   <pre><big>dec_state = speex_decoder_init(&amp;speex_nb_mode);</big></pre>
74  </blockquote>
75  For wideband decoding, <i>speex_nb_mode</i> will be replaced by <i>speex_wb_mode</i>
76 .<br>
77  <br>
78  For every input frame:<br>
79      
80 <blockquote>
81   <pre><big>speex_bits_read_from(&amp;bits, input_bytes, nbBytes);</big></pre>
82   <pre><big>speex_decode(st, &amp;bits, output_frame, 0);</big></pre>
83 </blockquote>
84 where <i>input_bytes</i> is a <i>(char *)</i> containing the bit-stream data
85 received for a frame, <i>nbBytes</i> is the size (in bytes) of that bit-stream,
86 and <i>output_frame</i> is a <i>(float *)</i> and points to the area where
87 the decoded speech frame will be written. The last argument indicates whether
88 the frame we'd like to decode was lost. A value of 0 indicates the normal
89 case where bits points to the bit of the current frame. A value of 1 indicates
90 that we don't have the bits for the current frame, in which case the bits
91 argument should be the same as the bits for the last correctly received frame.
92 When a frame is lost, the Speex decoder will do its best to "guess" the sorrect
93 signal.<br>
94 <br>
95 </div>
96 </div>
97 </body>
98 </html>