duplex-audio 0.14.3__py3-none-any.whl

duplex_audio/__init__.py

@@ -0,0 +1,81 @@
+"""duplex-audio: acoustic echo cancellation (AEC) toolkit.
+
+スピーカー出力がマイクへ回り込むエコーを適応フィルタで除去し、
+マイクに向かって話された音声をクリーンに取り出す。
+"""
+
+from duplex_audio.aec import AecProcessor, measure_erle
+from duplex_audio.calibration import (
+    BandResponse,
+    CalibrationError,
+    CalibrationProfile,
+    CalibrationProfileVersionError,
+    analyze_loopback,
+    generate_chirp,
+    load_calibration_profile,
+    measure_calibration as measure_calibration,
+    save_calibration_profile,
+)
+from duplex_audio.localvqe import LocalVqeAecBackend, LocalVqeSettings
+from duplex_audio.playback import (
+    PlaybackEvent,
+    PlaybackGeneration,
+    PlaybackQuiesce,
+    PlaybackState,
+    PlaybackStateError,
+    UnknownPlaybackGeneration,
+)
+from duplex_audio.streaming import StreamStopIncomplete
+from duplex_audio.rt_io import (
+    AecBackend,
+    CalibrationResult,
+    CalibrationSettings,
+    CaptureZeroRun,
+    DuplexEngine,
+    NoNoiseSuppressor,
+    NoiseSuppressor,
+    PipelineStats,
+    Resampler,
+    RnnoiseNoiseSuppressor,
+    StageStats,
+    StreamHealth,
+)
+
+__all__ = [
+    "AecProcessor",
+    "AecBackend",
+    "BandResponse",
+    "CalibrationError",
+    "CalibrationProfile",
+    "CalibrationProfileVersionError",
+    "CalibrationResult",
+    "CalibrationSettings",
+    "CaptureZeroRun",
+    "DuplexEngine",
+    "LocalVqeAecBackend",
+    "LocalVqeSettings",
+    "NoNoiseSuppressor",
+    "NoiseSuppressor",
+    "PipelineStats",
+    "PlaybackEvent",
+    "PlaybackGeneration",
+    "PlaybackQuiesce",
+    "PlaybackState",
+    "PlaybackStateError",
+    "Resampler",
+    "RnnoiseNoiseSuppressor",
+    "StageStats",
+    "StreamHealth",
+    "StreamStopIncomplete",
+    "UnknownPlaybackGeneration",
+    "analyze_loopback",
+    "generate_chirp",
+    "load_calibration_profile",
+    "measure_erle",
+    "measure_calibration",
+    "save_calibration_profile",
+]
+try:
+    from duplex_audio._version import __version__
+except ImportError:  # version file is generated at build / sync time
+    __version__ = "0.0.0+unknown"

duplex_audio/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.14.3'
+__version_tuple__ = version_tuple = (0, 14, 3)
+
+__commit_id__ = commit_id = None

duplex_audio/aec.py

@@ -0,0 +1,308 @@
+"""Acoustic echo cancellation core based on an NLMS adaptive filter."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+DEFAULT_BLOCK_LENGTH = 160
+DEFAULT_FILTER_LENGTH = 3200
+DEFAULT_STEP_SIZE = 0.45
+DEFAULT_REGULARIZATION = 1e-6
+DEFAULT_REFERENCE_GATE = 1e-10
+DEFAULT_DOUBLE_TALK_THRESHOLD = 0.9
+DEFAULT_COLD_START_STEP_SIZE = 0.25
+DEFAULT_MIN_CONTROL_GAIN = 0.02
+DEFAULT_MAX_CONTROL_GAIN = 1.0
+DEFAULT_MIN_LEAK = 0.005
+DEFAULT_CONTROL_SMOOTHING = 0.97
+DEFAULT_WARMUP_ADAPTATION_MASS = 12.5
+
+
+FloatArray = NDArray[np.float32]
+_AdaptationMode = Literal["continuous", "geigel"]
+_AdaptationPhase = Literal["warming", "tracking"]
+
+
+@dataclass(frozen=True)
+class _ValidatedBlock:
+    near_end: FloatArray
+    reference: FloatArray
+
+
+class AecProcessor:
+    """Stateful block processor for acoustic echo cancellation."""
+
+    def __init__(
+        self,
+        *,
+        block_length: int = DEFAULT_BLOCK_LENGTH,
+        filter_length: int = DEFAULT_FILTER_LENGTH,
+        step_size: float = DEFAULT_STEP_SIZE,
+        regularization: float = DEFAULT_REGULARIZATION,
+        reference_gate: float = DEFAULT_REFERENCE_GATE,
+        double_talk_threshold: float = DEFAULT_DOUBLE_TALK_THRESHOLD,
+        adaptation_enabled: bool = True,
+        adaptation_mode: _AdaptationMode = "continuous",
+        cold_start_step_size: float = DEFAULT_COLD_START_STEP_SIZE,
+        min_control_gain: float = DEFAULT_MIN_CONTROL_GAIN,
+        max_control_gain: float = DEFAULT_MAX_CONTROL_GAIN,
+        min_leak: float = DEFAULT_MIN_LEAK,
+        control_smoothing: float = DEFAULT_CONTROL_SMOOTHING,
+        warmup_adaptation_mass: float = DEFAULT_WARMUP_ADAPTATION_MASS,
+    ) -> None:
+        if block_length <= 0:
+            msg = "block_length must be positive"
+            raise ValueError(msg)
+        if filter_length <= 0:
+            msg = "filter_length must be positive"
+            raise ValueError(msg)
+        if not 0.0 < step_size <= 2.0:
+            msg = "step_size must be in the range (0, 2]"
+            raise ValueError(msg)
+        if regularization <= 0.0:
+            msg = "regularization must be positive"
+            raise ValueError(msg)
+        if reference_gate < 0.0:
+            msg = "reference_gate must be non-negative"
+            raise ValueError(msg)
+        if double_talk_threshold <= 0.0:
+            msg = "double_talk_threshold must be positive"
+            raise ValueError(msg)
+        if adaptation_mode not in ("continuous", "geigel"):
+            msg = "adaptation_mode must be 'continuous' or 'geigel'"
+            raise ValueError(msg)
+        if not 0.0 < cold_start_step_size <= 2.0:
+            msg = "cold_start_step_size must be in the range (0, 2]"
+            raise ValueError(msg)
+        if min_control_gain <= 0.0:
+            msg = "min_control_gain must be positive"
+            raise ValueError(msg)
+        if max_control_gain < min_control_gain:
+            msg = "max_control_gain must be greater than or equal to min_control_gain"
+            raise ValueError(msg)
+        if not 0.0 <= min_leak <= 1.0:
+            msg = "min_leak must be in the range [0, 1]"
+            raise ValueError(msg)
+        if not 0.0 <= control_smoothing < 1.0:
+            msg = "control_smoothing must be in the range [0, 1)"
+            raise ValueError(msg)
+        if warmup_adaptation_mass <= 0.0:
+            msg = "warmup_adaptation_mass must be positive"
+            raise ValueError(msg)
+
+        self.block_length = block_length
+        self.filter_length = filter_length
+        self.step_size = float(step_size)
+        self.regularization = float(regularization)
+        self.reference_gate = float(reference_gate)
+        self.double_talk_threshold = float(double_talk_threshold)
+        self.adaptation_enabled = adaptation_enabled
+        self.adaptation_mode = adaptation_mode
+        self.cold_start_step_size = float(cold_start_step_size)
+        self.min_control_gain = float(min_control_gain)
+        self.max_control_gain = float(max_control_gain)
+        self.min_leak = float(min_leak)
+        self.control_smoothing = float(control_smoothing)
+        self.warmup_adaptation_mass = float(warmup_adaptation_mass)
+        self._coefficients = np.zeros(filter_length, dtype=np.float64)
+        self._reference_history = np.zeros(filter_length, dtype=np.float64)
+        self._reset_controller()
+
+    @property
+    def coefficients(self) -> FloatArray:
+        """Return a copy of the current echo-path estimate."""
+
+        return self._coefficients.astype(np.float32)
+
+    def reset(self) -> None:
+        """Reset filter coefficients and reference history."""
+
+        self._coefficients.fill(0.0)
+        self._reference_history.fill(0.0)
+        self._reset_controller()
+
+    def process(self, near_end: FloatArray, reference: FloatArray) -> FloatArray:
+        """Process one fixed-size block and return the echo-cancelled signal."""
+
+        block = self._validate_block(near_end, reference)
+        reference_energy = float(np.dot(block.reference, block.reference))
+        if reference_energy < self.reference_gate:
+            self._ingest_reference(block.reference)
+            return block.near_end.copy()
+
+        clean = np.empty(self.block_length, dtype=np.float32)
+        effective_step_size = self._effective_step_size(block)
+        echo_power = 0.0
+        error_power = 0.0
+        for index, (near_sample, reference_sample) in enumerate(
+            zip(block.near_end, block.reference, strict=True)
+        ):
+            self._push_reference(float(reference_sample))
+            echo_estimate = float(np.dot(self._coefficients, self._reference_history))
+            error = float(near_sample) - echo_estimate
+            clean[index] = error
+            echo_power += echo_estimate * echo_estimate
+            error_power += error * error
+            if effective_step_size > 0.0:
+                energy = float(np.dot(self._reference_history, self._reference_history))
+                scale = effective_step_size * error / (energy + self.regularization)
+                self._coefficients += scale * self._reference_history
+        if self.adaptation_mode == "continuous" and self.adaptation_enabled:
+            self._update_controller(
+                estimated_echo_power=echo_power / self.block_length,
+                error_power=error_power / self.block_length,
+                effective_step_size=effective_step_size,
+            )
+        return clean
+
+    def _validate_block(
+        self, near_end: FloatArray, reference: FloatArray
+    ) -> _ValidatedBlock:
+        near_end_array = np.asarray(near_end)
+        reference_array = np.asarray(reference)
+        if near_end_array.ndim != 1:
+            msg = "near_end must be a one-dimensional array"
+            raise ValueError(msg)
+        if reference_array.ndim != 1:
+            msg = "reference must be a one-dimensional array"
+            raise ValueError(msg)
+        if near_end_array.shape[0] != self.block_length:
+            msg = f"near_end length must be {self.block_length}"
+            raise ValueError(msg)
+        if reference_array.shape[0] != self.block_length:
+            msg = f"reference length must be {self.block_length}"
+            raise ValueError(msg)
+        if not np.all(np.isfinite(near_end_array)):
+            msg = "near_end must contain only finite values"
+            raise ValueError(msg)
+        if not np.all(np.isfinite(reference_array)):
+            msg = "reference must contain only finite values"
+            raise ValueError(msg)
+        return _ValidatedBlock(
+            near_end=near_end_array.astype(np.float32, copy=False),
+            reference=reference_array.astype(np.float32, copy=False),
+        )
+
+    def _detect_double_talk(self, block: _ValidatedBlock) -> bool:
+        reference_peak = max(
+            float(np.max(np.abs(block.reference))),
+            float(np.max(np.abs(self._reference_history))),
+        )
+        if reference_peak == 0.0:
+            return False
+        near_end_peak = float(np.max(np.abs(block.near_end)))
+        return near_end_peak > self.double_talk_threshold * reference_peak
+
+    def _effective_step_size(self, block: _ValidatedBlock) -> float:
+        if not self.adaptation_enabled:
+            return 0.0
+        if self.adaptation_mode == "geigel":
+            if self._detect_double_talk(block):
+                return 0.0
+            return self.step_size
+        if self._adaptation_phase == "warming":
+            return self.cold_start_step_size
+        return self.step_size * self._control_gain
+
+    def _reset_controller(self) -> None:
+        self._adaptation_phase: _AdaptationPhase = "warming"
+        self._adaptation_mass = 0.0
+        self._control_gain = self.max_control_gain
+        self._echo_power_mean = 0.0
+        self._error_power_mean = 0.0
+        self._power_covariance = 0.0
+        self._echo_power_variance = 0.0
+        self._controller_initialized = False
+
+    def _update_controller(
+        self,
+        *,
+        estimated_echo_power: float,
+        error_power: float,
+        effective_step_size: float,
+    ) -> None:
+        self._update_power_statistics(estimated_echo_power, error_power)
+        if self._adaptation_phase == "warming":
+            self._adaptation_mass += effective_step_size
+            if self._adaptation_mass >= self.warmup_adaptation_mass:
+                self._adaptation_phase = "tracking"
+            return
+
+        if self._echo_power_variance <= self.regularization:
+            leakage = self.min_leak
+        else:
+            leakage = self._power_covariance / self._echo_power_variance
+            leakage = min(max(leakage, self.min_leak), 1.0)
+        residual_echo_power = leakage * estimated_echo_power
+        control_gain = residual_echo_power / (error_power + self.regularization)
+        self._control_gain = min(
+            max(control_gain, self.min_control_gain),
+            self.max_control_gain,
+        )
+
+    def _update_power_statistics(
+        self,
+        estimated_echo_power: float,
+        error_power: float,
+    ) -> None:
+        if not self._controller_initialized:
+            self._echo_power_mean = estimated_echo_power
+            self._error_power_mean = error_power
+            self._controller_initialized = True
+            return
+
+        echo_delta = estimated_echo_power - self._echo_power_mean
+        error_delta = error_power - self._error_power_mean
+        smoothing = self.control_smoothing
+        update_weight = 1.0 - smoothing
+        self._echo_power_mean += update_weight * echo_delta
+        self._error_power_mean += update_weight * error_delta
+        self._power_covariance = (
+            smoothing * self._power_covariance
+            + update_weight * echo_delta * error_delta
+        )
+        self._echo_power_variance = (
+            smoothing * self._echo_power_variance
+            + update_weight * echo_delta * echo_delta
+        )
+
+    def _ingest_reference(self, reference: FloatArray) -> None:
+        for sample in reference:
+            self._push_reference(float(sample))
+
+    def _push_reference(self, sample: float) -> None:
+        self._reference_history[1:] = self._reference_history[:-1]
+        self._reference_history[0] = sample
+
+
+def measure_erle(before: FloatArray, after: FloatArray) -> float:
+    """Measure echo return loss enhancement in dB."""
+
+    before_array = np.asarray(before, dtype=np.float64)
+    after_array = np.asarray(after, dtype=np.float64)
+    if before_array.shape != after_array.shape:
+        msg = "before and after must have the same shape"
+        raise ValueError(msg)
+    if before_array.ndim != 1:
+        msg = "before and after must be one-dimensional arrays"
+        raise ValueError(msg)
+    if not np.all(np.isfinite(before_array)):
+        msg = "before must contain only finite values"
+        raise ValueError(msg)
+    if not np.all(np.isfinite(after_array)):
+        msg = "after must contain only finite values"
+        raise ValueError(msg)
+
+    before_power = float(np.mean(before_array * before_array))
+    after_power = float(np.mean(after_array * after_array))
+    if before_power == 0.0:
+        return 0.0
+    if after_power == 0.0:
+        return math.inf
+    return 10.0 * math.log10(before_power / after_power)