Using LaTeX listing package for the doc instead of LyX-code style

git-svn-id: http://svn.xiph.org/trunk/speex@13975 0101bb08-14d6-0310-b084-bc0e0c8e3800

1 files changed, 490 insertions, 86 deletions

diff --git a/doc/manual.lyx b/doc/manual.lyx
index 9827fd7..e7a6cd6 100644
--- a/doc/manual.lyx
+++ b/doc/manual.lyx
@@ -35,9 +35,11 @@
 \papercolumns 1
 \papersides 1
 \paperpagestyle headings
+\listings_params "basicstyle={\ttfamily},language=C"
 \tracking_changes false
 \output_changes false
 \author "" 
+\author "" 
 \end_header
 
 \begin_body
@@ -1134,7 +1136,11 @@ speexenc
 speexdec
 \emph default
 ).
- This section describes how to use these tools.
+ Those tools produce and read Speex files encapsulated in the Ogg container.
+ Although it is possible to encapsulate Speex in any container, Ogg is the
+ recommended container for files.
+ This section describes how to use the command line tools for Speex files
+ in Ogg.
 \end_layout
 
 \begin_layout Section
@@ -1414,6 +1420,20 @@ name "libspeex"
 )
 \end_layout
 
+\begin_layout Standard
+The 
+\emph on
+libspeex
+\emph default
+ library contains all the functions for encoding and decoding speech with
+ the Speex codec.
+ When linking on a UNIX system, one must add 
+\emph on
+-lspeex -lm
+\emph default
+ to the compiler command line.
+\end_layout
+
 \begin_layout Subsection
 Encoding
 \begin_inset LatexCommand label
@@ -1428,38 +1448,62 @@ name "sub:Encoding"
 In order to encode speech using Speex, one first needs to:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 #include <speex/speex.h>
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 Then a Speex bit-packing struct must be declared as:
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 SpeexBits bits;
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 along with a Speex encoder state
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 void *enc_state;
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 The two are initialized by:
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 speex_bits_init(&bits);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 enc_state = speex_encoder_init(&speex_nb_mode);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 For wideband coding, 
 \emph on
@@ -1483,10 +1527,21 @@ samples
 , not bytes) with:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 In practice, 
 \emph on
@@ -1499,10 +1554,21 @@ frame_size
  This is set by:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_encoder_ctl(enc_state,SPEEX_SET_QUALITY,&quality);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 where 
 \emph on
@@ -1523,18 +1589,31 @@ reference "cap:quality_vs_bps"
 Once the initialization is done, for every input frame:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_bits_reset(&bits);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 speex_encode_int(enc_state, input_frame, &bits);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 where 
 \emph on
@@ -1610,14 +1689,26 @@ speex_encode_int()
 After you're done with the encoding, free all resources with:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_bits_destroy(&bits);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 speex_encoder_destroy(enc_state);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 That's about it for the encoder.
  
@@ -1635,40 +1726,61 @@ name "sub:Decoding"
 
 \begin_layout Standard
 In order to decode speech using Speex, you first need to:
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 #include <speex/speex.h>
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 You also need to declare a Speex bit-packing struct
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 SpeexBits bits;
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 and a Speex decoder state
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 void *dec_state;
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 The two are initialized by:
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 speex_bits_init(&bits);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 dec_state = speex_decoder_init(&speex_nb_mode);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 For wideband decoding, 
 \emph on
@@ -1691,8 +1803,19 @@ samples
 , not bytes) with:
 \end_layout
 
-\begin_layout LyX-Code
-speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
+speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size);
+\end_layout
+
+\end_inset
+
+
 \end_layout
 
 \begin_layout Standard
@@ -1701,8 +1824,19 @@ There is also a parameter that can be set for the decoder: whether or not
  This can be set by: 
 \end_layout
 
-\begin_layout LyX-Code
-speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
+speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh);
+\end_layout
+
+\end_inset
+
+
 \end_layout
 
 \begin_layout Standard
@@ -1718,15 +1852,23 @@ enh
 Again, once the decoder initialization is done, for every input frame:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_bits_read_from(&bits, input_bytes, nbBytes);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 speex_decode_int(dec_state, &bits, output_frame);
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 where input_bytes is a 
 \emph on
 (char *)
@@ -1760,20 +1902,29 @@ speex_decode()
 (float *)
 \emph default
  as the output for the audio.
+ After you're done with the decoding, free all resources with:
 \end_layout
 
 \begin_layout Standard
-After you're done with the decoding, free all resources with:
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 speex_bits_destroy(&bits);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 speex_decoder_destroy(dec_state);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Subsection
 Codec Options (speex_*_ctl)
 \begin_inset LatexCommand label
@@ -1795,7 +1946,8 @@ Entities should not be multiplied beyond necessity -- William of Ockham.
 \align center
 
 \emph on
-Just because there's an option doesn't mean you have to use it -- me.
+Just because there's an option of it doesn't mean you have to use it --
+ me.
 \end_layout
 
 \begin_layout Standard
@@ -1823,14 +1975,26 @@ ioctl
  system call and their prototypes are:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 void speex_encoder_ctl(void *encoder, int request, void *ptr);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 void speex_decoder_ctl(void *encoder, int request, void *ptr);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 The different values of request allowed are (note that some only apply to
  the encoder or the decoder):
@@ -2062,13 +2226,17 @@ er_ctl calls.
  Since modes are read-only, it is only possible to get information about
  a particular mode.
  The function used to do that is:
-\end_layout
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 The admissible values for request are (unless otherwise note, the values
  are returned through 
 \emph on
@@ -2735,7 +2903,7 @@ Finally, applications may define custom in-band messages using mode 13.
 \end_layout
 
 \begin_layout Section
-Speech Processing API (libspeexproc)
+Speech Processing API (libspeexdsp)
 \end_layout
 
 \begin_layout Subsection
@@ -2758,19 +2926,41 @@ name "preprocessor"
 , you first need to:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 #include <speex/speex_preprocess.h>
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 Then, a preprocessor state can be created as:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
  sampling_rate);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 It is recommended to use the same value for 
 \family typewriter
@@ -2787,10 +2977,21 @@ ms
 For each input frame, you need to call:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_preprocess_run(preprocess_state, audio_frame);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 where 
 \family typewriter
@@ -2804,10 +3005,21 @@ In cases where the output audio is not useful for a certain frame, it is
  possible to use instead:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_preprocess_estimate_update(preprocess_state, audio_frame);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 This call will update all the preprocessor internal state variables without
  computing the output audio, thus saving some CPU cycles.
@@ -2817,10 +3029,21 @@ This call will update all the preprocessor internal state variables without
 The behaviour of the preprocessor can be changed using:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_preprocess_ctl(preprocess_state, request, ptr);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 which is used in the same way as the encoder and decoder equivalent.
  Options are listed in Section .
@@ -2830,10 +3053,21 @@ which is used in the same way as the encoder and decoder equivalent.
 The preprocessor state can be destroyed using:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_preprocess_state_destroy(preprocess_state);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Subsubsection
 Preprocessor options
 \begin_inset LatexCommand label
@@ -2985,18 +3219,40 @@ name "acoustic echo cancellation"
  In order to use the echo canceller, you first need to
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 #include <speex/speex_echo.h>
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 Then, an echo canceller state can be created by:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 where 
 \family typewriter
@@ -3032,10 +3288,21 @@ n time.
 Once the echo canceller state is created, audio can be processed by:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 where 
 \family typewriter
@@ -3076,27 +3343,34 @@ echo_frame
  must be small enough because otherwise part of the echo cancellation filter
  is inefficient.
  In the ideal case, you code would look like:
-\end_layout
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
+
+\begin_layout Standard
 
-\begin_layout LyX-Code
 write_to_soundcard(echo_frame, frame_size);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 read_from_soundcard(input_frame, frame_size);
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 If you wish to further reduce the echo present in the signal, you can do
- so by 
-\family typewriter
-associating the echo canceller to the preprocessor
-\family default
- (see Section 
+ so by associating the echo canceller to the preprocessor (see Section 
 \begin_inset LatexCommand ref
 reference "sub:Preprocessor"
 
@@ -3104,14 +3378,19 @@ reference "sub:Preprocessor"
 
 ).
  This is done by calling:
-\end_layout
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
 
-\begin_layout LyX-Code
-speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,
- echo_state);
+\begin_layout Standard
+
+speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,echo_stat
+e);
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 in the initialisation.
 \end_layout
 
@@ -3136,19 +3415,41 @@ select()
  Instead, the playback comtext/thread can simply call:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_echo_playback(echo_state, echo_frame);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 every time an audio frame is played.
  Then, the capture context/thread calls:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_echo_capture(echo_state, input_frame, output_frame);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 for every frame captured.
  Internally, 
@@ -3177,19 +3478,41 @@ speex_echo_cancellation()
 The echo cancellation state can be destroyed with:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_echo_state_destroy(echo_state);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 It is also possible to reset the state of the echo canceller so it can be
  reused without the need to create another state with:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 speex_echo_state_reset(echo_state);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Subsubsection
 Troubleshooting
 \end_layout
@@ -3289,10 +3612,22 @@ echo_diagnostic.m
  From there, it is necessary to start Octave and type:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=Matlab"
+inline false
+status open
+
+\begin_layout Standard
+
 echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 The value of 1024 is the filter length and can be changed.
  There will be some (hopefully) useful messages printed and echo cancelled
@@ -3309,8 +3644,47 @@ Jitter Buffer
 The jitter buffer can be enabled by including:
 \end_layout
 
-\begin_layout LyX-Code
-#include <speex/speex_jitter.c>
+\begin_layout Standard
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
+
+\begin_layout Standard
+
+#include <speex/speex_jitter.h>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and a new jitter buffer state can be initialised by:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
+
+\begin_layout Standard
+
+JitterBuffer *state = jitter_buffer_init(tick);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+where the tick argument is the time resolution (in timestamp units) used
+ for the jitter buffer, and is generally the period at which the data is
+ played out of the jitter buffer.
+ 
 \end_layout
 
 \begin_layout Subsection
@@ -3322,24 +3696,47 @@ Speex includes a resampling modules.
  To make use of the resampler, it is necessary to include its header file:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 #include <speex/speex_resampler.h>
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 For each stream that is to be resampled, it is necessary to create a resampler
  state with:
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 SpeexResamplerState *resampler;
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+
 resampler = speex_resampler_init(nb_channels, input_rate, output_rate, quality,
  &err);
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
 where nb_channels is the number of channels that will be used (either interleave
 d or non-interleaved), input_rate is the sampling rate of the input stream,
@@ -3359,12 +3756,19 @@ d or non-interleaved), input_rate is the sampling rate of the input stream,
 The actual resampling is performed using
 \end_layout
 
-\begin_layout LyX-Code
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Standard
+
 err = speex_resampler_process_int(resampler, channelID, in, &in_length,
  out, &out_length);
 \end_layout
 
-\begin_layout Standard
+\end_inset
+
 where channelID is the ID of the channel to be processed.
  For a mono stream, use 0.
  The 
@@ -9005,7 +9409,7 @@ sampleenc takes a raw 16 bits/sample file, encodes it and outputs a Speex
 \end_layout
 
 \begin_layout Standard
-\begin_inset Include \verbatiminput{sampleenc.c}
+\begin_inset Include \lstinputlisting{sampleenc.c}[caption={Source code for sampleenc},label={sampleenc-source-code},numbers=left,numberstyle={\footnotesize}]
 preview false
 
 \end_inset
@@ -9024,7 +9428,7 @@ sampledec reads a Speex stream from stdin, decodes it and outputs it to
 \end_layout
 
 \begin_layout Standard
-\begin_inset Include \verbatiminput{sampledec.c}
+\begin_inset Include \lstinputlisting{sampledec.c}[caption={Source code for sampledec},label={sampledec-source-code},numbers=left,numberstyle={\footnotesize}]
 preview false
 
 \end_inset