KSPROPERTY_AEC_STATUS
The KSPROPERTY_AEC_STATUS property is used to monitor the status of an AEC node (KSNODETYPE_ACOUSTIC_ECHO_CANCEL). This is an optional property of an AEC node.
Usage Summary Table
| Get | Set | Target | Property descriptor type | Property value type |
|---|---|---|---|---|
Yes |
No |
Pin |
ULONG |
The property value (operation data) is of type ULONG. This is a status value that can be set to the bitwise OR of one or more of the flag bits in the left column of the following table, which are defined in header file Ksmedia.h. The corresponding DSCFX_AEC_STATUS flags from header file Dsound.h are shown in the right column of the table. See the Microsoft Windows SDK documentation for information about these flags.
| AEC status flag | Value | DSCFX_AEC_STATUS flag |
|---|---|---|
AEC_STATUS_FD_HISTORY_UNINITIALIZED |
0x0 |
DSCFX_AEC_STATUS_HISTORY_UNINITIALIZED |
AEC_STATUS_FD_HISTORY_CONTINUOUSLY_CONVERGED |
0x1 |
DSCFX_AEC_STATUS_HISTORY_CONTINUOUSLY_CONVERGED |
AEC_STATUS_FD_HISTORY_PREVIOUSLY_DIVERGED |
0x2 |
DSCFX_AEC_STATUS_HISTORY_PREVIOUSLY_DIVERGED |
AEC_STATUS_FD_CURRENTLY_CONVERGED |
0x8 |
DSCFX_AEC_STATUS_CURRENTLY_CONVERGED |
Return Value
A KSPROPERTY_AEC_STATUS property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code.
Remarks
The three least significant bits in the AEC status flags (see preceding table) represent the convergence history (CH) of the AEC algorithm. The CH status bits can be used by a Microsoft DirectSound application to determine whether the algorithm has converged and also whether it has remained in the converged state since the time that it started processing data. Depending on the audio hardware, the AEC algorithm might fail to converge, in which case the resulting capture buffer is likely to include the echo from the speakers.
When the filter containing the AEC node is created or the node is reset, the AEC algorithm initially sets the three CH status bits to zero. This setting represents the uninitialized state, AEC_STATUS_FD_HISTORY_UNINITIALIZED.
After the AEC algorithm converges, the CH status switches to the converged state, AEC_STATUS_FD_HISTORY_CONTINUOUSLY_CONVERGED. If the AEC algorithm ever loses convergence, the CH status switches to the diverged state, AEC_STATUS_FD_HISTORY_PREVIOUSLY_DIVERGED. Although the status is most likely to switch to the diverged state from the converged state, it might also switch directly from the uninitialized state to the diverged state. After the CH status has switched to the diverged state, it will remain in that state until the algorithm is reset or starvation is detected.
When the AEC system filter detects starvation at any of its four pins--capture in, capture out, render in, or render out--it resets its internal state, including the convergence history.
Note that bit 2 of the three CH status bits is not currently used.
As an alternative to using the CH status bits, the application can monitor the real-time convergence status by checking the AEC_STATUS_FD_CURRENTLY_CONVERGED flag bit. If this bit is set, the algorithm is currently converged. The algorithm can lose convergence temporarily when changes occur in the acoustic path. The real-time convergence flag is filtered to prevent such momentary losses from inappropriately switching the CH status bits to the DSCFX_AEC_STATUS_FD_HISTORY_PREVIOUSLY_DIVERGED state.
Requirements
Header |
Ksmedia.h (include Ksmedia.h) |