Synthetic ERLE metric demo

Tutorial goal

Explain ERLE and MSE on a controlled synthetic echo-path identification problem.

Note

New to the terminology? See the lattice DSP concept map and the causality/data-use guide for how online, offline, block, and MIMO examples should be read.

Context

This tutorial is intentionally limited: it is a metric demonstration for a synthetic echo path, not a production acoustic echo canceller. It is useful for understanding the two-signal roles: a far-end/reference signal drives the unknown echo path, while a microphone/desired signal is used to measure the residual after subtracting the estimated echo.

Key idea and equations

With reference signal \(x[n]\) and microphone signal \(m[n]\), an adaptive echo-path model produces

\[\widehat e_{echo}[n] = h_{\theta_n}(x)[n], \qquad r[n] = m[n] - \widehat e_{echo}[n].\]

Echo return loss enhancement is commonly reported as

\[\operatorname{ERLE}_{dB} =10\log_{10}\frac{\mathbb{E}[m^2]}{\mathbb{E}[r^2]}.\]

A causal echo-path filter may use current and past reference samples and previous adaptive state. It must not use future microphone samples to form the current residual.

Causality and data use

This is a controlled two-signal synthetic metric demo. It uses reference/far-end and microphone/desired roles, unlike one-signal AR prediction. Real AEC systems require additional delay control, double-talk handling, nonlinear echo handling, and deployment-specific engineering.

How to read the result

Higher ERLE and lower MSE indicate better cancellation in this controlled synthetic setup only; they are not product-quality acoustic echo-cancellation claims.

Run command

python examples/echo_cancellation_erle_demo.py

Run status

Return code: 0

Captured stdout

Synthetic echo metric demo
--------------------------
No cancellation ERLE:     0.00 dB
FIR/NLMS ERLE:           24.98 dB
Lattice/IIR ERLE:        16.18 dB

ERLE = 10 log10(input echo/error power / output residual error power).
Positive ERLE means residual error power was reduced. It does not by
itself prove speech quality, especially during double-talk.

Final lattice reflection coefficients:
[ 0.2837 -0.1909  0.1629 -0.1216]

Source code

"""Small synthetic echo-cancellation metric demo.

This example is intentionally modest.  It shows how the stable adaptive
lattice/IIR stage behaves on a known synthetic echo problem and how ERLE is
computed.  It is not a production acoustic echo canceller.
"""

from __future__ import annotations

import numpy as np

from lattice_dsp import HybridEchoCanceller, echo_metrics, generate_echo_problem


def fir_nlms(
    reference: np.ndarray,
    desired: np.ndarray,
    *,
    order: int = 64,
    mu: float = 0.5,
    epsilon: float = 1e-8,
):
    """Tiny FIR/NLMS reference baseline for this example."""

    w = np.zeros(order, dtype=np.float64)
    xbuf = np.zeros(order, dtype=np.float64)
    y = np.zeros_like(reference, dtype=np.float64)
    e = np.zeros_like(reference, dtype=np.float64)
    for n, sample in enumerate(reference):
        xbuf[1:] = xbuf[:-1]
        xbuf[0] = sample
        y_n = float(np.dot(w, xbuf))
        e_n = float(desired[n] - y_n)
        w += (mu * e_n / (float(np.dot(xbuf, xbuf)) + epsilon)) * xbuf
        y[n] = y_n
        e[n] = e_n
    return y, e, w


def main() -> None:
    problem = generate_echo_problem(
        samples=16_000,
        sample_rate=16_000,
        seed=123,
        nonlinear_strength=0.0,
        near_end_power_ratio=0.0,
        noise_snr_db=60.0,
        double_talk=False,
    )

    no_cancel = echo_metrics(problem.microphone, problem.microphone, problem.clean_target)

    _, fir_residual, _ = fir_nlms(problem.reference, problem.microphone, order=64, mu=0.5)
    fir_metrics = echo_metrics(problem.microphone, fir_residual, problem.clean_target)

    canceller = HybridEchoCanceller(
        initial_reflection=[0.0] * 4,
        initial_taps=[0.0] * 5,
        mu_taps=0.05,
        mu_reflection=0.001,
        reflection_update_period=8,
    )
    result = canceller.process(
        problem.reference, problem.microphone, clean_target=problem.clean_target
    )
    lattice_metrics = echo_metrics(problem.microphone, result.residual, problem.clean_target)

    print("Synthetic echo metric demo")
    print("--------------------------")
    print(f"No cancellation ERLE: {no_cancel.erle_db:8.2f} dB")
    print(f"FIR/NLMS ERLE:        {fir_metrics.erle_db:8.2f} dB")
    print(f"Lattice/IIR ERLE:     {lattice_metrics.erle_db:8.2f} dB")
    print()
    print("ERLE = 10 log10(input echo/error power / output residual error power).")
    print("Positive ERLE means residual error power was reduced. It does not by")
    print("itself prove speech quality, especially during double-talk.")
    print()
    print("Final lattice reflection coefficients:")
    print(np.array2string(result.reflection, precision=4))


if __name__ == "__main__":
    main()