speex_echo.h

00001 /* Copyright (C) Jean-Marc Valin */
00002 /**
00003    @file speex_echo.h
00004    @brief Echo cancellation
00005 */
00006 /*
00007    Redistribution and use in source and binary forms, with or without
00008    modification, are permitted provided that the following conditions are
00009    met:
00010 
00011    1. Redistributions of source code must retain the above copyright notice,
00012    this list of conditions and the following disclaimer.
00013 
00014    2. Redistributions in binary form must reproduce the above copyright
00015    notice, this list of conditions and the following disclaimer in the
00016    documentation and/or other materials provided with the distribution.
00017 
00018    3. The name of the author may not be used to endorse or promote products
00019    derived from this software without specific prior written permission.
00020 
00021    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
00022    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00023    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00024    DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
00025    INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00026    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00027    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00028    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00029    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00030    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00031    POSSIBILITY OF SUCH DAMAGE.
00032 */
00033 
00034 #ifndef SPEEX_ECHO_H
00035 #define SPEEX_ECHO_H
00036 /** @defgroup SpeexEchoState SpeexEchoState: Acoustic echo canceller
00037  *  This is the acoustic echo canceller module.
00038  *  @{
00039  */
00040 #include "speex/speex_types.h"
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 /** Obtain frame size used by the AEC */
00047 #define SPEEX_ECHO_GET_FRAME_SIZE 3
00048 
00049 /** Set sampling rate */
00050 #define SPEEX_ECHO_SET_SAMPLING_RATE 24
00051 /** Get sampling rate */
00052 #define SPEEX_ECHO_GET_SAMPLING_RATE 25
00053 
00054 /** Internal echo canceller state. Should never be accessed directly. */
00055 struct SpeexEchoState_;
00056 
00057 /** @class SpeexEchoState
00058  * This holds the state of the echo canceller. You need one per channel. 
00059 */
00060 
00061 /** Internal echo canceller state. Should never be accessed directly. */
00062 typedef struct SpeexEchoState_ SpeexEchoState;
00063 
00064 /** Creates a new echo canceller state
00065  * @param frame_size Number of samples to process at one time (should correspond to 10-20 ms)
00066  * @param filter_length Number of samples of echo to cancel (should generally correspond to 100-500 ms)
00067  * @return Newly-created echo canceller state
00068  */
00069 SpeexEchoState *speex_echo_state_init(int frame_size, int filter_length);
00070 
00071 /** Destroys an echo canceller state 
00072  * @param st Echo canceller state
00073 */
00074 void speex_echo_state_destroy(SpeexEchoState *st);
00075 
00076 /** Performs echo cancellation a frame, based on the audio sent to the speaker (no delay is added
00077  * to playback ni this form)
00078  *
00079  * @param st Echo canceller state
00080  * @param rec signal from the microphone (near end + far end echo)
00081  * @param play Signal played to the speaker (received from far end)
00082  * @param out Returns near-end signal with echo removed
00083  */
00084 void speex_echo_cancellation(SpeexEchoState *st, const spx_int16_t *rec, const spx_int16_t *play, spx_int16_t *out);
00085 
00086 /** Performs echo cancellation a frame (deprecated) */
00087 void speex_echo_cancel(SpeexEchoState *st, const spx_int16_t *rec, const spx_int16_t *play, spx_int16_t *out, spx_int32_t *Yout);
00088 
00089 /** Perform echo cancellation using internal playback buffer, which is delayed by two frames
00090  * to account for the delay introduced by most soundcards (but it could be off!)
00091  * @param st Echo canceller state
00092  * @param rec signal from the microphone (near end + far end echo)
00093  * @param out Returns near-end signal with echo removed
00094 */
00095 void speex_echo_capture(SpeexEchoState *st, const spx_int16_t *rec, spx_int16_t *out);
00096 
00097 /** Let the echo canceller know that a frame was just queued to the soundcard
00098  * @param st Echo canceller state
00099  * @param play Signal played to the speaker (received from far end)
00100 */
00101 void speex_echo_playback(SpeexEchoState *st, const spx_int16_t *play);
00102 
00103 /** Reset the echo canceller to its original state 
00104  * @param st Echo canceller state
00105  */
00106 void speex_echo_state_reset(SpeexEchoState *st);
00107 
00108 /** Used like the ioctl function to control the echo canceller parameters
00109  *
00110  * @param st Echo canceller state
00111  * @param request ioctl-type request (one of the SPEEX_ECHO_* macros)
00112  * @param ptr Data exchanged to-from function
00113  * @return 0 if no error, -1 if request in unknown
00114  */
00115 int speex_echo_ctl(SpeexEchoState *st, int request, void *ptr);
00116 
00117 #ifdef __cplusplus
00118 }
00119 #endif
00120 
00121 
00122 /** @}*/
00123 #endif