sipxmedialib  Version 3.3
Public Types | Static Public Attributes | Private Types | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
MprSpeexEchoCancel Class Reference

The "Speex Echo Canceler" media processing resource. More...

#include <MprSpeexEchoCancel.h>

Inheritance diagram for MprSpeexEchoCancel:
Inheritance graph
[legend]
Collaboration diagram for MprSpeexEchoCancel:
Collaboration graph
[legend]

Public Types

enum  { MAX_ECHO_QUEUE =20, DEFAULT_ECHO_QUEUE_LEN =90 }
 
enum  GlobalEnableState { GLOBAL_ENABLE, GLOBAL_DISABLE, LOCAL_MODE }
 
- Public Types inherited from MpResource
enum  VisitState { NOT_VISITED, IN_PROGRESS, FINISHED }
 Graph traversal states that are used when running a topological sort to order resources within a flow graph. More...
 
enum  { ASSOCIATED_LATENCY =-1, INF_LATENCY =-1 }
 

Public Member Functions

Creators
 MprSpeexEchoCancel (const UtlString &rName, OsMsgQ *pSpkrQ=NULL, int spkrQDelayMs=DEFAULT_ECHO_QUEUE_LEN, int filterLength=SPEEX_DEFAULT_AEC_FILTER_LENGTH)
 Constructor. More...
 
virtual ~MprSpeexEchoCancel ()
 Destructor. More...
 
Accessors
UtlContainableType getContainableType () const
 
SpeexEchoState * getSpeexEchoState () const
 Return Speex internal echo state structure. More...
 
- Public Member Functions inherited from MpAudioResource
 MpAudioResource (const UtlString &rName, int minInputs, int maxInputs, int minOutputs, int maxOutputs)
 Constructor. More...
 
virtual ~MpAudioResource ()
 Destructor. More...
 
virtual UtlBoolean processFrame (void)
 Wrapper around doProcessFrame(). More...
 
- Public Member Functions inherited from MpResource
 MpResource (const UtlString &rName, int minInputs, int maxInputs, int minOutputs, int maxOutputs)
 Constructor. More...
 
virtual ~MpResource ()
 Destructor. More...
 
virtual UtlBoolean disable ()
 Disable this resource. More...
 
virtual UtlBoolean enable ()
 Enable this resource. More...
 
virtual void reset ()
 This method is invoked for resources that care about stream discontinuities. More...
 
UtlBoolean handleMessages (OsMsgQ &msgQ)
 Handles a queue full of incoming messages for this media processing object. More...
 
void setVisitState (int newState)
 Sets the visit state for this resource. More...
 
OsStatus sendNotification (MpResNotificationMsg::RNMsgType msgType)
 Send a notification with the given message type if notifications are enabled. More...
 
OsStatus sendNotification (MpResNotificationMsg &msg)
 Send the given notification message if notifications are enabled. More...
 
virtual void setConnectionId (MpConnectionID connectionId)
 Set the ID of a connection this resource belongs to. More...
 
virtual void setStreamId (int streamId)
 Set the ID of a stream inside of the connection this resource belongs to. More...
 
virtual int getStreamId (void)
 Get the ID of a stream within the connection this resource belongs to. More...
 
virtual OsStatus pushBuffer (int inputPort, MpBufPtr &inputBuffer)
 Receive buffer asynchronously from resource at given input port. More...
 
virtual void reassignSSRC (void)
 Broadcast announcement that we are changing our SSRC. More...
 
MpFlowGraphBasegetFlowGraph () const
 Returns parent flowgraph. More...
 
void getInputInfo (int inPortIdx, MpResource *&rpUpstreamResource, int &rUpstreamPortIdx)
 Returns information about the upstream end of a connection. More...
 
const UtlString & getName () const
 Returns the name associated with this resource. More...
 
void getOutputInfo (int outPortIdx, MpResource *&rpDownstreamResource, int &rDownstreamPortIdx)
 Returns information about the downstream end of a connection. More...
 
int getVisitState ()
 Returns the current visit state for this resource. More...
 
int maxInputs () const
 Returns the maximum number of inputs supported by this resource. More...
 
int maxOutputs () const
 Returns the maximum number of outputs supported by this resource. More...
 
int minInputs () const
 Returns the minimum number of inputs required by this resource. More...
 
int minOutputs () const
 Returns the minimum number of outputs required by this resource. More...
 
int numInputs () const
 Returns the number of resource inputs that are currently connected. More...
 
int numOutputs () const
 Returns the number of resource outputs that are currently connected. More...
 
virtual MpConnectionID getConnectionId (void) const
 Get the ID of a connection this resource belongs to. More...
 
int reserveFirstUnconnectedInput ()
 Find the first unconnected input port and reserve it. More...
 
int reserveFirstUnconnectedOutput ()
 Find the first unconnected output port and reserve it. More...
 
UtlContainableType getContainableType () const
 Get the ContainableType for a UtlContainable derived class. More...
 
virtual OsStatus getCurrentLatency (int &latency, int input=0, int output=0) const
 Get current input to output latency (in samples) More...
 
UtlBoolean isEnabled () const
 Returns TRUE is this resource is currently enabled, FALSE otherwise. More...
 
UtlBoolean isInputConnected (int portIdx)
 Returns TRUE if portIdx is valid and the indicated input is connected, FALSE otherwise. More...
 
UtlBoolean isInputUnconnected (int portIdx)
 Returns TRUE if portIdx is valid and the indicated input is not connected, FALSE otherwise. More...
 
UtlBoolean isOutputConnected (int portIdx)
 Returns TRUE if portIdx is valid and the indicated output is connected, FALSE otherwise. More...
 
UtlBoolean isOutputUnconnected (int portIdx)
 Returns TRUE if portIdx is valid and the indicated output is not connected, FALSE otherwise. More...
 
UtlBoolean areNotificationsEnabled () const
 Returns TRUE if notification sending is enabled on this resource. More...
 
virtual UtlBoolean isAsynchInput (int inputIndex)
 Takes asynchronous input (pushBuffer). More...
 

Static Public Attributes

static const UtlContainableType TYPE
 Class name, used for run-time checks. More...
 
- Static Public Attributes inherited from MpResource
static const UtlContainableType TYPE = "MpResource"
 Class name, used for run-time checks. More...
 

Private Types

enum  AddlResMsgTypes { MPRM_SET_SPEAKER_QUEUE = MpResourceMsg::MPRM_EXTERNAL_MESSAGE_START }
 

Private Member Functions

virtual UtlBoolean doProcessFrame (MpBufPtr inBufs[], MpBufPtr outBufs[], int inBufsSize, int outBufsSize, UtlBoolean isEnabled, int samplesPerFrame, int samplesPerSecond)
 This method does the real work for the media processing resource and must be defined in each class derived from this one. More...
 
virtual UtlBoolean handleMessage (MpResourceMsg &rMsg)
 Handles an incoming flowgraph message for this media processing object. More...
 
OsStatus setFlowGraph (MpFlowGraphBase *pFlowGraph)
 Associates this resource with the indicated flow graph. More...
 
 MprSpeexEchoCancel (const MprSpeexEchoCancel &rMprSpeexEchoCancel)
 Copy constructor (not implemented for this class) More...
 
MprSpeexEchoCanceloperator= (const MprSpeexEchoCancel &rhs)
 Assignment operator (not implemented for this class) More...
 

Private Attributes

SpeexEchoState * mpEchoState
 Speex internal AEC state. More...
 
bool mStartedCanceling
 Have we started cancelling? More...
 
int mFilterLength
 Filter tail length. See constructor docs for details. More...
 
OsMsgQ * mpSpkrQ
 Queue with echo reference data. More...
 
const int mSpkrQDelayMs
 How much should we delay data from mpSpkrQ (in ms)? More...
 
int mSpkrQDelayFrames
 How much should we delay data from mpSpkrQ (in frames)? More...
 
MpAudioBufPtr mpSilenceBuf
 

Static Private Attributes

static volatile GlobalEnableState smGlobalEnableState
 

Manipulators

OsStatus setSpkrQ (const UtlString &namedResource, OsMsgQ &fgQ, OsMsgQ *pSpkrQ)
 Send message to enable/disable copy queue. More...
 
static void setGlobalEnableState (GlobalEnableState state)
 Set global enable/disable state. More...
 
static GlobalEnableState getGlobalEnableState ()
 Get global state. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from MpResource
static OsStatus disable (const UtlString &namedResource, OsMsgQ &fgQ)
 Post a message to disable the resource named. More...
 
static OsStatus enable (const UtlString &namedResource, OsMsgQ &fgQ)
 Post a message to enable the resource named. More...
 
static OsStatus setNotificationsEnabled (UtlBoolean enable, const UtlString &namedResource, OsMsgQ &fgQ)
 Post a message to enable or disable resource notifications on the named resource. More...
 
static void resourceInfo (MpResource *pResource, int index)
 Displays information on the console about the specified resource. More...
 
- Protected Member Functions inherited from MpResource
virtual UtlBoolean handleMessage (MpFlowGraphMsg &fgMsg)
 Handles an incoming flowgraph message for this media processing object. More...
 
virtual UtlBoolean handleEnable ()
 perform the enable operation on the resource More...
 
virtual UtlBoolean handleDisable ()
 perform the disable operation on the resource More...
 
void setInputBuffer (int inPortIdx, const MpBufPtr &pBuf)
 If there already is a buffer stored for this input port, delete it. Then store pBuf for the indicated input port. More...
 
OsStatus postMessage (MpFlowGraphMsg &rMsg)
 Post a message from this resource. More...
 
OsStatus postMessage (MpResourceMsg &rMsg)
 Post a message for this resource. More...
 
UtlBoolean pushBufferDownsream (int outPortIdx, const MpBufPtr &pBuf)
 Makes pBuf available to resource connected to the outPortIdx output port of this resource. More...
 
virtual OsStatus setNotificationsEnabled (UtlBoolean enable)
 Sets whether or not this resource should send notifications. More...
 
virtual UtlBoolean connectInput (MpResource &rFrom, int fromPortIdx, int toPortIdx)
 Connects the toPortIdx input port on this resource to the fromPortIdx output port of the rFrom resource. More...
 
virtual UtlBoolean connectOutput (MpResource &rTo, int toPortIdx, int fromPortIdx)
 Connects the fromPortIdx output port on this resource to the toPortIdx input port of the rTo resource. More...
 
virtual UtlBoolean disconnectInput (int inPortIdx)
 Removes the connection to the inPortIdx input port of this resource. More...
 
virtual UtlBoolean disconnectOutput (int outPortIdx)
 Removes the connection to the outPortIdx output port of this resource. More...
 
void setName (const UtlString &rName)
 Sets the name that is associated with this resource. More...
 
- Protected Attributes inherited from MpResource
MpFlowGraphBasempFlowGraph
 flow graph this resource belongs to More...
 
MpConnectionID mConnectionId
 The ID of connection this resource belongs to. More...
 
int mStreamId
 
UtlBoolean mIsEnabled
 TRUE if resource is enabled, FALSE otherwise. More...
 
OsRWMutex mRWMutex
 reader/writer lock for synchronization More...
 
MpBufPtrmpInBufs
 input buffers for this resource More...
 
MpBufPtrmpOutBufs
 output buffers for this resource More...
 
ConnmpInConns
 input connections for this resource More...
 
ConnmpOutConns
 output connections for this resource More...
 
int mMaxInputs
 maximum number of inputs More...
 
int mMaxOutputs
 maximum number of outputs More...
 
int mMinInputs
 number of required inputs More...
 
int mMinOutputs
 number of required outputs More...
 
int mNumActualInputs
 actual number of connected inputs More...
 
int mNumActualOutputs
 actual number of connected outputs More...
 
int mVisitState
 (used by flow graph topological sort alg.) More...
 
UtlBoolean mNotificationsEnabled
 Whether we should send notifications or not. More...
 
OsBSem mLock
 used mainly to make safe changes to ports More...
 
- Static Protected Attributes inherited from MpResource
static const OsTime sOperationQueueTimeout = OsTime::OS_INFINITY
 The timeout for message operations for all resources when posting to the flowgraph queue. More...
 

Detailed Description

The "Speex Echo Canceler" media processing resource.

It takes mic data from the first input, speaker data from the mpSpkrQ message queue and produce echo canceled audio data on the first output. To increase echo cancellation quality you should connect output of the resource directly to MprSpeexPreprocess input.

Member Enumeration Documentation

anonymous enum
Enumerator
MAX_ECHO_QUEUE 
DEFAULT_ECHO_QUEUE_LEN 
Enumerator
GLOBAL_ENABLE 

All MprSpeexEchoCancel resources are forced to enable.

GLOBAL_DISABLE 

All MprSpeexEchoCancel resources are forced to disable.

LOCAL_MODE 

Each resource respect its own enable/disable state.

enum AddlResMsgTypes
private
Enumerator
MPRM_SET_SPEAKER_QUEUE 

Constructor & Destructor Documentation

MprSpeexEchoCancel ( const UtlString &  rName,
OsMsgQ *  pSpkrQ = NULL,
int  spkrQDelayMs = DEFAULT_ECHO_QUEUE_LEN,
int  filterLength = SPEEX_DEFAULT_AEC_FILTER_LENGTH 
)

Constructor.

Parameters
[in]rName- resource name.
[in]pSpkrQ- pointer to a queue with speaker audio data.
[in]spkrQDelayMs- number of milliseconds we should delay delay data from speaker queue. Set this value to maximum of the delay audio device will definitely add while playing and recording audio. This value is used to minimize delay between far and near end audio in AEC and reduce computational cost of AEC.
[in]filterLength- the length (in msec) of the echo cancelling filter you want to use (also known as tail length). The recommended tail length is approximately the third of the room reverberation time. For example,in a small room, reverberation time is in the order of 300 ms, so a tail length of 100 ms is a good choice.
virtual ~MprSpeexEchoCancel ( )
virtual

Destructor.

MprSpeexEchoCancel ( const MprSpeexEchoCancel rMprSpeexEchoCancel)
private

Copy constructor (not implemented for this class)

Member Function Documentation

OsStatus setSpkrQ ( const UtlString &  namedResource,
OsMsgQ &  fgQ,
OsMsgQ *  pSpkrQ 
)

Send message to enable/disable copy queue.

Parameters
[in]namedResource- the name of the resource to send a message to.
[in]fgQ- the queue of the flowgraph containing the resource which the message is to be received by.
[in]pSpkrQ- pointer to a queue with speaker data.
Returns
the result of attempting to queue the message to this resource.
void setGlobalEnableState ( GlobalEnableState  state)
inlinestatic

Set global enable/disable state.

See also
smGlobalEnableState for more details.
MprSpeexEchoCancel::GlobalEnableState getGlobalEnableState ( )
inlinestatic

Get global state.

See also
smGlobalEnableState for more details.
UtlContainableType getContainableType ( ) const

SpeexEchoState * getSpeexEchoState ( ) const
inline

Return Speex internal echo state structure.

Used by MprSpeexPreprocess to access echo state to enable residual echo removal.

virtual UtlBoolean doProcessFrame ( MpBufPtr  inBufs[],
MpBufPtr  outBufs[],
int  inBufsSize,
int  outBufsSize,
UtlBoolean  isEnabled,
int  samplesPerFrame,
int  samplesPerSecond 
)
privatevirtual

This method does the real work for the media processing resource and must be defined in each class derived from this one.

Parameters
inBufs(in) array of pointers to input buffers for the resource
outBufs(out) array of pointers to output buffers produce by the resource
inBufsSize(in) size of the inBufs array
outBufsSize(in) size of the outBufs array
isEnabled(in) indicates whether this resource has been enabled
samplesPerFrame(in) samples to produce per frame processing interval
samplesPerSecond(in) samples to produce per second
Returns
TRUE if successful, FALSE otherwise.

Implements MpAudioResource.

virtual UtlBoolean handleMessage ( MpResourceMsg rMsg)
privatevirtual

Handles an incoming flowgraph message for this media processing object.

Returns
TRUE if the message was handled, otherwise FALSE.

Reimplemented from MpResource.

OsStatus setFlowGraph ( MpFlowGraphBase pFlowGraph)
privatevirtual

Associates this resource with the indicated flow graph.

We use this overloaded method for initialization of some of our member variables, which depend on flowgraph's properties (like frame size).

Return values
OS_SUCCESS- for now, this method always returns success

Reimplemented from MpResource.

MprSpeexEchoCancel& operator= ( const MprSpeexEchoCancel rhs)
private

Assignment operator (not implemented for this class)

Member Data Documentation

const UtlContainableType TYPE
static

Class name, used for run-time checks.

SpeexEchoState* mpEchoState
private

Speex internal AEC state.

bool mStartedCanceling
private

Have we started cancelling?

int mFilterLength
private

Filter tail length. See constructor docs for details.

OsMsgQ* mpSpkrQ
private

Queue with echo reference data.

const int mSpkrQDelayMs
private

How much should we delay data from mpSpkrQ (in ms)?

int mSpkrQDelayFrames
private

How much should we delay data from mpSpkrQ (in frames)?

MpAudioBufPtr mpSilenceBuf
private

Buffer with silence - used when empty message arrives from mpSpkrQ or mic input

volatile GlobalEnableState smGlobalEnableState
staticprivate

Global enable/disable switch for all Speex AEC resources. We need this switch because sipXmediaAdapterLib exports only a static method to turn AEC on and off.