diff options
author | jm <jm@0101bb08-14d6-0310-b084-bc0e0c8e3800> | 2007-10-14 14:24:10 +0400 |
---|---|---|
committer | jm <jm@0101bb08-14d6-0310-b084-bc0e0c8e3800> | 2007-10-14 14:24:10 +0400 |
commit | 24dac3393156f828afe3ec5063d1a116d34a5539 (patch) | |
tree | 1ae5971c875c8f0336dd85ad47b6d5166c34a7de /doc/manual.lyx | |
parent | c320d7e188eb896f5df4ba1a62bb8b4de684da27 (diff) |
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
Diffstat (limited to 'doc/manual.lyx')
-rw-r--r-- | doc/manual.lyx | 576 |
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 |