livekit-plugins-denoise 0.1.0__tar.gz

livekit_plugins_denoise-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Generated denoiser output
+*.denoised.wav
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

livekit_plugins_denoise-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BotifyNow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

livekit_plugins_denoise-0.1.0/NOTICE

@@ -0,0 +1,11 @@
+livekit-plugins-denoise
+Copyright 2026 BotifyNow
+
+This package depends on deepfilter-stream, which bundles DeepFilterNet3 model
+weights. deepfilter-stream and DeepFilterNet are dual-licensed under MIT or
+Apache-2.0 at the recipient's option.
+
+DeepFilterNet attribution:
+H. Schröter, T. Rosenkranz, A. N. Escalante-B., and A. Maier,
+"DeepFilterNet: A Low Complexity Speech Enhancement Framework for Full-Band
+Audio based on Deep Filtering", IWAENC 2022.

livekit_plugins_denoise-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: livekit-plugins-denoise
+Version: 0.1.0
+Summary: Self-hosted noise and echo suppression for LiveKit SIP telephony
+Project-URL: Source, https://github.com/jaffarjawed/livekit-plugins-denoise
+Project-URL: Issues, https://github.com/jaffarjawed/livekit-plugins-denoise/issues
+Author: BotifyNow
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: audio,echo-cancellation,livekit,noise-cancellation,sip,telephony,webrtc
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Requires-Dist: deepfilter-stream<0.2,>=0.1.0
+Requires-Dist: livekit-agents<2.0,>=1.6.0
+Requires-Dist: livekit<2.0,>=1.1.0
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# livekit-plugins-denoise
+
+Self-hosted noise suppression and acoustic echo cancellation for LiveKit SIP
+agents.
+
+- Removes background noise with DeepFilterNet3 or low-latency WebRTC noise
+  suppression.
+- Removes the agent's voice when it returns through a caller's handset or
+  carrier path.
+- Runs in your agent process: no per-minute denoising fee and no language
+  dependency.
+
+This is an independent, community-maintained package and is not affiliated
+with or endorsed by LiveKit, Inc.
+
+## Why this exists
+
+LiveKit's managed `BVCTelephony` noise-cancellation option is billed per minute.
+This package is a self-hosted, MIT-licensed alternative for teams that want
+noise suppression and echo cancellation in their own agent process without a
+per-minute denoising charge. You still pay for your own compute, telephony, and
+other services.
+
+## Install
+
+```bash
+python -m pip install livekit-plugins-denoise
+```
+
+For local development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Enable noise suppression and echo cancellation
+
+Create one `TelephonyDenoiser` for each call. `EchoReferenceTap` is required
+for echo cancellation because it supplies the agent's outgoing audio as the
+far-end reference.
+
+```python
+from livekit.agents import room_io
+from livekit.plugins import telephony_denoise
+
+denoiser = telephony_denoise.TelephonyDenoiser(
+    telephony_denoise.DenoiseOptions(
+        echo_cancellation=True,
+        noise_suppression=True,
+        high_pass_filter=True,
+        auto_gain_control=True,
+        enhancer="deepfilter",  # use "webrtc" for lower latency
+        stream_delay_ms=120,
+    )
+)
+
+await session.start(
+    agent=agent,
+    room=room,
+    room_options=room_io.RoomOptions(
+        audio_input=room_io.AudioInputOptions(
+            noise_cancellation=denoiser,
+            auto_gain_control=False,  # do not stack AGC
+        ),
+    ),
+)
+
+# Add this after session.start(); RoomIO replaces the output during startup.
+session.output.audio = telephony_denoise.EchoReferenceTap(
+    denoiser, next_in_chain=session.output.audio
+)
+```
+
+To load the neural model before the first call:
+
+```python
+def setup(proc):
+    telephony_denoise.prewarm()
+```
+
+See [examples/sip_agent.py](examples/sip_agent.py) for a complete SIP agent.
+
+## Configuration
+
+`DenoiseOptions` lets you control these features independently:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `echo_cancellation` | `True` | Cancels the agent's returned audio; requires `EchoReferenceTap`. |
+| `noise_suppression` | `True` | Removes background noise. |
+| `enhancer` | `"deepfilter"` | Use `"webrtc"` when minimizing latency is more important. |
+| `high_pass_filter` | `True` | Reduces low-frequency rumble and hum. |
+| `auto_gain_control` | `True` | Helps keep quiet callers audible. |
+| `stream_delay_ms` | `120` | Starting delay estimate for SIP echo paths. |
+
+For tuning, supported formats, model download behavior, and operating notes, see
+[Technical notes](docs/technical-notes.md).
+
+## Community
+
+Issues, documentation improvements, and pull requests are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md). This project is MIT licensed; dependency
+attribution is in [NOTICE](NOTICE).

livekit_plugins_denoise-0.1.0/README.md

@@ -0,0 +1,103 @@
+# livekit-plugins-denoise
+
+Self-hosted noise suppression and acoustic echo cancellation for LiveKit SIP
+agents.
+
+- Removes background noise with DeepFilterNet3 or low-latency WebRTC noise
+  suppression.
+- Removes the agent's voice when it returns through a caller's handset or
+  carrier path.
+- Runs in your agent process: no per-minute denoising fee and no language
+  dependency.
+
+This is an independent, community-maintained package and is not affiliated
+with or endorsed by LiveKit, Inc.
+
+## Why this exists
+
+LiveKit's managed `BVCTelephony` noise-cancellation option is billed per minute.
+This package is a self-hosted, MIT-licensed alternative for teams that want
+noise suppression and echo cancellation in their own agent process without a
+per-minute denoising charge. You still pay for your own compute, telephony, and
+other services.
+
+## Install
+
+```bash
+python -m pip install livekit-plugins-denoise
+```
+
+For local development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Enable noise suppression and echo cancellation
+
+Create one `TelephonyDenoiser` for each call. `EchoReferenceTap` is required
+for echo cancellation because it supplies the agent's outgoing audio as the
+far-end reference.
+
+```python
+from livekit.agents import room_io
+from livekit.plugins import telephony_denoise
+
+denoiser = telephony_denoise.TelephonyDenoiser(
+    telephony_denoise.DenoiseOptions(
+        echo_cancellation=True,
+        noise_suppression=True,
+        high_pass_filter=True,
+        auto_gain_control=True,
+        enhancer="deepfilter",  # use "webrtc" for lower latency
+        stream_delay_ms=120,
+    )
+)
+
+await session.start(
+    agent=agent,
+    room=room,
+    room_options=room_io.RoomOptions(
+        audio_input=room_io.AudioInputOptions(
+            noise_cancellation=denoiser,
+            auto_gain_control=False,  # do not stack AGC
+        ),
+    ),
+)
+
+# Add this after session.start(); RoomIO replaces the output during startup.
+session.output.audio = telephony_denoise.EchoReferenceTap(
+    denoiser, next_in_chain=session.output.audio
+)
+```
+
+To load the neural model before the first call:
+
+```python
+def setup(proc):
+    telephony_denoise.prewarm()
+```
+
+See [examples/sip_agent.py](examples/sip_agent.py) for a complete SIP agent.
+
+## Configuration
+
+`DenoiseOptions` lets you control these features independently:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `echo_cancellation` | `True` | Cancels the agent's returned audio; requires `EchoReferenceTap`. |
+| `noise_suppression` | `True` | Removes background noise. |
+| `enhancer` | `"deepfilter"` | Use `"webrtc"` when minimizing latency is more important. |
+| `high_pass_filter` | `True` | Reduces low-frequency rumble and hum. |
+| `auto_gain_control` | `True` | Helps keep quiet callers audible. |
+| `stream_delay_ms` | `120` | Starting delay estimate for SIP echo paths. |
+
+For tuning, supported formats, model download behavior, and operating notes, see
+[Technical notes](docs/technical-notes.md).
+
+## Community
+
+Issues, documentation improvements, and pull requests are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md). This project is MIT licensed; dependency
+attribution is in [NOTICE](NOTICE).

livekit_plugins_denoise-0.1.0/docs/technical-notes.md

@@ -0,0 +1,39 @@
+# Technical notes
+
+## Choosing an enhancer
+
+`enhancer="deepfilter"` is the default and generally removes more complex
+background noise. It downloads DeepFilterNet3 model weights (about 13 MB) on
+first use, so call `telephony_denoise.prewarm()` during worker startup.
+
+Use `enhancer="webrtc"` when lower latency and call density matter more than
+neural suppression quality.
+
+## Echo cancellation
+
+Noise suppression works without additional wiring. Echo cancellation does not:
+attach `EchoReferenceTap` after `session.start()` so the denoiser receives the
+audio the caller actually hears. Create one denoiser per call; its echo and
+noise state must not be shared between calls.
+
+`stream_delay_ms=120` is a useful SIP starting point. Tune it using recordings
+from your carrier route if returned agent audio remains audible.
+
+## Audio and pipeline constraints
+
+- Inbound telephony audio must be mono.
+- Supported input rates are multiples of 100 Hz, such as 8, 16, 24, 32, and
+  48 kHz. Unsupported audio passes through unfiltered rather than failing a
+  call.
+- Do not stack this denoiser with another echo or noise canceller; competing
+  filters can degrade speech quality.
+- If this plugin owns AGC, set LiveKit's `AudioInputOptions.auto_gain_control`
+  to `False`.
+
+## Dependencies and licensing
+
+This package depends on `livekit`, `livekit-agents`, `numpy`, and
+`deepfilter-stream`. It is MIT licensed. `deepfilter-stream` and DeepFilterNet
+are dual-licensed under MIT or Apache-2.0; the required attribution is in the
+project [NOTICE](../NOTICE). The DeepFilterNet3 model is downloaded by the
+dependency and is not redistributed in this package.

livekit_plugins_denoise-0.1.0/examples/sip_agent.py

@@ -0,0 +1,120 @@
+"""LiveKit SIP telephony agent with self-hosted noise and echo suppression.
+
+The audio filtering is the point of this file; the speech models are ordinary
+and meant to be swapped for whatever you already use.
+
+Three wires do the work:
+
+  1. The model is loaded in `setup`, once per worker process, so no call pays
+     for the download and ONNX session build inside its first audio frame.
+
+  2. The denoiser is handed to `AudioInputOptions.noise_cancellation`, so
+     LiveKit runs it on every inbound frame from the caller before speech
+     recognition sees it.
+
+  3. The agent's own outgoing speech is tapped into the same denoiser, which is
+     what lets it cancel the echo of its own voice coming back down the line.
+
+Run it with:
+
+    python examples/sip_agent.py dev
+
+Inbound calls reach the agent through a SIP trunk and dispatch rule, which are
+configured on the LiveKit side rather than here.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from livekit.agents import (
+    Agent,
+    AgentServer,
+    AgentSession,
+    JobContext,
+    JobProcess,
+    cli,
+    room_io,
+)
+from livekit.plugins import telephony_denoise
+
+logger = logging.getLogger("sip-agent")
+
+# Narrowband phone audio, so there is no point paying for a wider pipeline.
+INPUT_SAMPLE_RATE = 16000
+
+INSTRUCTIONS = """You are a helpful voice assistant speaking with a caller on
+the phone. Keep replies short and conversational. Reply in the language the
+caller uses."""
+
+
+def setup(proc: JobProcess) -> None:
+    # Runs once per worker process, before any call is accepted.
+    telephony_denoise.prewarm()
+
+
+server = AgentServer(setup_fnc=setup)
+
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext) -> None:
+    await ctx.connect()
+
+    denoiser = telephony_denoise.TelephonyDenoiser(
+        telephony_denoise.DenoiseOptions(
+            # Cancels the agent's own voice echoing back off the caller's
+            # handset or the carrier's hybrid.
+            echo_cancellation=True,
+            # Suppresses background noise via DeepFilterNet3 by default
+            # (gym, café, babble, hiss — unknown caller environments).
+            noise_suppression=True,
+            # Removes rumble and mains hum below the voice band.
+            high_pass_filter=True,
+            # Evens out callers who are too close to or far from the handset.
+            auto_gain_control=True,
+            # Tune this to your typical SIP round-trip delay.
+            stream_delay_ms=120,
+        )
+    )
+    # Build the filter now rather than on the first frame from the caller, so
+    # the greeting below can be used as an echo reference from its first word.
+    denoiser.prepare(INPUT_SAMPLE_RATE)
+
+    session = AgentSession(
+        # Multilingual models keep the whole pipeline language-agnostic, to
+        # match the filter. Swap these for your own plugins or providers.
+        stt="deepgram/nova-3:multi",
+        llm="openai/gpt-4o-mini",
+        tts="cartesia/sonic-2",
+    )
+
+    await session.start(
+        agent=Agent(instructions=INSTRUCTIONS),
+        room=ctx.room,
+        room_options=room_io.RoomOptions(
+            audio_input=room_io.AudioInputOptions(
+                noise_cancellation=denoiser,
+                sample_rate=INPUT_SAMPLE_RATE,
+                # The denoiser already applies gain control; running LiveKit's
+                # as well would compress the signal twice.
+                auto_gain_control=False,
+            ),
+        ),
+    )
+
+    # Must come after start(): RoomIO installs its own audio output during
+    # start and would overwrite anything set beforehand.
+    session.output.audio = telephony_denoise.EchoReferenceTap(
+        denoiser, next_in_chain=session.output.audio
+    )
+
+    logger.info("call ready, audio filter active: %s", denoiser.enhancer)
+
+    await session.generate_reply(
+        instructions="Greet the caller briefly and ask how you can help."
+    )
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    cli.run_app(server)

livekit_plugins_denoise-0.1.0/livekit/plugins/telephony_denoise/__init__.py

@@ -0,0 +1,32 @@
+"""Self-hosted noise and echo suppression for LiveKit SIP telephony."""
+
+from livekit.agents import Plugin
+
+from .echo_reference import EchoReferenceTap
+from .log import logger
+from .neural import prewarm
+from .processor import DenoiseOptions, Enhancer, TelephonyDenoiser
+from .version import __version__
+
+__all__ = [
+    "DenoiseOptions",
+    "EchoReferenceTap",
+    "Enhancer",
+    "TelephonyDenoiser",
+    "__version__",
+    "prewarm",
+]
+
+
+class TelephonyDenoisePlugin(Plugin):
+    def __init__(self) -> None:
+        super().__init__(__name__, __version__, __package__, logger)
+
+    def download_files(self) -> None:
+        # Fetches the DeepFilterNet3 weights so `lk agent build` bakes them into
+        # the image; otherwise the first call of a fresh worker pays for the
+        # download on the event loop, inside its first 10 ms frame.
+        prewarm()
+
+
+Plugin.register_plugin(TelephonyDenoisePlugin())

livekit_plugins_denoise-0.1.0/livekit/plugins/telephony_denoise/_buffers.py

@@ -0,0 +1,53 @@
+"""Small int16 PCM helpers used by the processing pipeline."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+class Int16Buffer:
+    """A FIFO of interleaved int16 samples."""
+
+    __slots__ = ("_buf",)
+
+    def __init__(self) -> None:
+        self._buf = np.zeros(0, dtype=np.int16)
+
+    @property
+    def size(self) -> int:
+        return int(self._buf.size)
+
+    def append(self, data: np.ndarray) -> None:
+        # `np.concatenate(..., dtype=np.int16)` casts same_kind, so an int32
+        # caller would be truncated into garbage PCM without a word. Only int16
+        # is ever correct here, so insist on it.
+        if data.dtype != np.int16:
+            raise TypeError(f"expected int16 samples, got {data.dtype}")
+        self._buf = np.concatenate((self._buf, data))
+
+    def take(self, count: int) -> np.ndarray:
+        out = self._buf[:count].copy()
+        self._buf = self._buf[count:]
+        return out
+
+    def clear(self) -> None:
+        self._buf = np.zeros(0, dtype=np.int16)
+
+
+def to_mono(pcm: np.ndarray, src_channels: int) -> np.ndarray:
+    """Downmix interleaved int16 audio when needed."""
+
+    if src_channels < 1:
+        raise ValueError(f"src_channels must be positive, got {src_channels}")
+    if src_channels == 1:
+        return pcm
+    if pcm.size % src_channels:
+        raise ValueError(
+            f"{pcm.size} samples is not a whole number of {src_channels}ch frames"
+        )
+
+    frames = pcm.reshape(-1, src_channels).astype(np.int32)
+    # Round rather than truncate: `astype` rounds toward zero, which biases
+    # every downmixed sample toward silence and adds a DC-free crackle.
+    mean = frames.sum(axis=1) / src_channels
+    return np.rint(mean).astype(np.int16)