code.delx.au - pulseaudio/blob - src/modules/echo-cancel/echo-cancel.h

   1 /***
   2     This file is part of PulseAudio.
   3
   4     Copyright 2010 Arun Raghavan <arun.raghavan@collabora.co.uk>
   5
   6     PulseAudio is free software; you can redistribute it and/or modify
   7     it under the terms of the GNU Lesser General Public License as published
   8     by the Free Software Foundation; either version 2.1 of the License,
   9     or (at your option) any later version.
  10
  11     PulseAudio is distributed in the hope that it will be useful, but
  12     WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  14     General Public License for more details.
  15
  16     You should have received a copy of the GNU Lesser General Public License
  17     along with PulseAudio; if not, write to the Free Software
  18     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  19     USA.
  20 ***/
  21
  22 #ifndef fooechocancelhfoo
  23 #define fooechocancelhfoo
  24
  25 #ifdef HAVE_CONFIG_H
  26 #include <config.h>
  27 #endif
  28
  29 #include <pulse/sample.h>
  30 #include <pulse/channelmap.h>
  31 #include <pulsecore/core.h>
  32 #include <pulsecore/macro.h>
  33
  34 #ifdef HAVE_SPEEX
  35 #include <speex/speex_echo.h>
  36 #include <speex/speex_preprocess.h>
  37 #endif
  38
  39 #include "adrian.h"
  40
  41 /* Common data structures */
  42
  43 typedef struct pa_echo_canceller_msg pa_echo_canceller_msg;
  44
  45 typedef struct pa_echo_canceller_params pa_echo_canceller_params;
  46
  47 struct pa_echo_canceller_params {
  48     union {
  49         struct {
  50             pa_sample_spec out_ss;
  51         } null;
  52 #ifdef HAVE_SPEEX
  53         struct {
  54             SpeexEchoState *state;
  55             SpeexPreprocessState *pp_state;
  56         } speex;
  57 #endif
  58 #ifdef HAVE_ADRIAN_EC
  59         struct {
  60             uint32_t blocksize;
  61             AEC *aec;
  62         } adrian;
  63 #endif
  64 #ifdef HAVE_WEBRTC
  65         struct {
  66             /* This is a void* so that we don't have to convert this whole file
  67              * to C++ linkage. apm is a pointer to an AudioProcessing object */
  68             void *apm;
  69             uint32_t blocksize;
  70             pa_sample_spec sample_spec;
  71             pa_bool_t agc;
  72         } webrtc;
  73 #endif
  74         /* each canceller-specific structure goes here */
  75     } priv;
  76
  77     /* Set this if canceller can do drift compensation. Also see set_drift()
  78      * below */
  79     pa_bool_t drift_compensation;
  80 };
  81
  82 typedef struct pa_echo_canceller pa_echo_canceller;
  83
  84 struct pa_echo_canceller {
  85     /* Initialise canceller engine. */
  86     pa_bool_t   (*init)                 (pa_core *c,
  87                                          pa_echo_canceller *ec,
  88                                          pa_sample_spec *rec_ss,
  89                                          pa_channel_map *rec_map,
  90                                          pa_sample_spec *play_ss,
  91                                          pa_channel_map *play_map,
  92                                          pa_sample_spec *out_ss,
  93                                          pa_channel_map *out_map,
  94                                          uint32_t *nframes,
  95                                          const char *args);
  96
  97     /* You should have only one of play()+record() or run() set. The first
  98      * works under the assumption that you'll handle buffering and matching up
  99      * samples yourself. If you set run(), module-echo-cancel will handle
 100      * synchronising the playback and record streams. */
 101
 102     /* Feed the engine 'nframes' playback frames. */
 103     void        (*play)                 (pa_echo_canceller *ec, const uint8_t *play);
 104     /* Feed the engine 'nframes' record frames. nframes processed frames are
 105      * returned in out. */
 106     void        (*record)               (pa_echo_canceller *ec, const uint8_t *rec, uint8_t *out);
 107     /* Feed the engine nframes playback and record frames, with a reasonable
 108      * effort at keeping the two in sync. nframes processed frames are
 109      * returned in out. */
 110     void        (*run)                  (pa_echo_canceller *ec, const uint8_t *rec, const uint8_t *play, uint8_t *out);
 111
 112     /* Optional callback to set the drift, expressed as the ratio of the
 113      * difference in number of playback and capture samples to the number of
 114      * capture samples, for some instant of time. This is used only if the
 115      * canceller signals that it supports drift compensation, and is called
 116      * before record(). The actual implementation needs to derive drift based
 117      * on point samples -- the individual values are not accurate enough to use
 118      * as-is. */
 119     /* NOTE: the semantics of this function might change in the future. */
 120     void        (*set_drift)            (pa_echo_canceller *ec, float drift);
 121
 122     /* Free up resources. */
 123     void        (*done)                 (pa_echo_canceller *ec);
 124
 125     /* Structure with common and engine-specific canceller parameters. */
 126     pa_echo_canceller_params params;
 127
 128     /* msgobject that can be used to send messages back to the main thread */
 129     pa_echo_canceller_msg *msg;
 130 };
 131
 132 /* Functions to be used by the canceller analog gain control routines */
 133 void pa_echo_canceller_get_capture_volume(pa_echo_canceller *ec, pa_cvolume *v);
 134 void pa_echo_canceller_set_capture_volume(pa_echo_canceller *ec, pa_cvolume *v);
 135
 136 /* Computes EC block size in frames (rounded down to nearest power-of-2) based
 137  * on sample rate and milliseconds. */
 138 uint32_t pa_echo_canceller_blocksize_power2(unsigned rate, unsigned ms);
 139
 140 /* Null canceller functions */
 141 pa_bool_t pa_null_ec_init(pa_core *c, pa_echo_canceller *ec,
 142                           pa_sample_spec *rec_ss, pa_channel_map *rec_map,
 143                           pa_sample_spec *play_ss, pa_channel_map *play_map,
 144                           pa_sample_spec *out_ss, pa_channel_map *out_map,
 145                           uint32_t *nframes, const char *args);
 146 void pa_null_ec_run(pa_echo_canceller *ec, const uint8_t *rec, const uint8_t *play, uint8_t *out);
 147 void pa_null_ec_done(pa_echo_canceller *ec);
 148
 149 #ifdef HAVE_SPEEX
 150 /* Speex canceller functions */
 151 pa_bool_t pa_speex_ec_init(pa_core *c, pa_echo_canceller *ec,
 152                            pa_sample_spec *rec_ss, pa_channel_map *rec_map,
 153                            pa_sample_spec *play_ss, pa_channel_map *play_map,
 154                            pa_sample_spec *out_ss, pa_channel_map *out_map,
 155                            uint32_t *nframes, const char *args);
 156 void pa_speex_ec_run(pa_echo_canceller *ec, const uint8_t *rec, const uint8_t *play, uint8_t *out);
 157 void pa_speex_ec_done(pa_echo_canceller *ec);
 158 #endif
 159
 160 #ifdef HAVE_ADRIAN_EC
 161 /* Adrian Andre's echo canceller */
 162 pa_bool_t pa_adrian_ec_init(pa_core *c, pa_echo_canceller *ec,
 163                             pa_sample_spec *rec_ss, pa_channel_map *rec_map,
 164                             pa_sample_spec *play_ss, pa_channel_map *play_map,
 165                             pa_sample_spec *out_ss, pa_channel_map *out_map,
 166                             uint32_t *nframes, const char *args);
 167 void pa_adrian_ec_run(pa_echo_canceller *ec, const uint8_t *rec, const uint8_t *play, uint8_t *out);
 168 void pa_adrian_ec_done(pa_echo_canceller *ec);
 169 #endif
 170
 171 #ifdef HAVE_WEBRTC
 172 /* WebRTC canceller functions */
 173 PA_C_DECL_BEGIN
 174 pa_bool_t pa_webrtc_ec_init(pa_core *c, pa_echo_canceller *ec,
 175                             pa_sample_spec *rec_ss, pa_channel_map *rec_map,
 176                             pa_sample_spec *play_ss, pa_channel_map *play_map,
 177                             pa_sample_spec *out_ss, pa_channel_map *out_map,
 178                             uint32_t *nframes, const char *args);
 179 void pa_webrtc_ec_play(pa_echo_canceller *ec, const uint8_t *play);
 180 void pa_webrtc_ec_record(pa_echo_canceller *ec, const uint8_t *rec, uint8_t *out);
 181 void pa_webrtc_ec_set_drift(pa_echo_canceller *ec, float drift);
 182 void pa_webrtc_ec_run(pa_echo_canceller *ec, const uint8_t *rec, const uint8_t *play, uint8_t *out);
 183 void pa_webrtc_ec_done(pa_echo_canceller *ec);
 184 PA_C_DECL_END
 185 #endif
 186
 187 #endif /* fooechocancelhfoo */