Registry / communication / livekit-plugins-noise-cancellation

livekit-plugins-noise-cancellation

JSON →
library0.3.0pypypi✓ verified 22d ago

livekit-plugins-noise-cancellation is a Python plugin that provides real-time enhanced noise cancellation for inbound audio streams within LiveKit Agents. It offers models for standard noise cancellation (NC), background voice cancellation (BVC), and BVC optimized for telephony. The current version is 0.2.5, and the project maintains a healthy release cadence.

pip install livekit-plugins-noise-cancellation
INSTALL
IMPORT
SIG · LIVEKIT-PLUGINS-NO
L
livekit-plugins-noise-cancellation
communicationpythonv0.3.0
Install
5.8s avg
Import
798ms
Disk
218MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
build_error
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.8s · import 0.798s · 216MB
218MB installed
● package 218MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

noise_cancellation
from livekit.plugins import noise_cancellation
NC
noise_cancellation.NC()
Standard enhanced noise cancellation model.
BVC
noise_cancellation.BVC()
Background voice cancellation model.
BVCTelephony
noise_cancellation.BVCTelephony()
Background voice cancellation model optimized for telephony applications.

This quickstart demonstrates how to integrate `livekit-plugins-noise-cancellation` into a LiveKit Agent. The plugin is applied by setting the `noise_cancellation` option within `RoomInputOptions` when starting an `AgentSession`. This ensures that all inbound audio streams to the agent are processed for noise reduction using the specified model (e.g., BVC). Remember that this plugin requires LiveKit Cloud for enhanced noise cancellation services.

import os from livekit.agents import AgentSession, JobContext, RoomOptions, RoomInputOptions from livekit.plugins import noise_cancellation class MyAgent: async def start(self, ctx: JobContext): # Example of applying BVC noise cancellation to inbound audio await ctx.connect( RoomOptions(auto_subscribe=RoomOptions.AutoSubscribe.AUDIO_ONLY), room_input_options=RoomInputOptions( noise_cancellation=noise_cancellation.BVC(), ), ) print("Agent connected with BVC noise cancellation enabled.") # Your agent logic here, e.g., process audio from ctx.room.local_participant.audio_tracks # Keep the agent alive (e.g., by waiting for a signal or keeping a loop) # For a simple quickstart, we'll just wait indefinitely for demonstration. # In a real agent, you'd manage session lifecycle more robustly. await ctx.room.wait_for_is_connected() async def main(): # This quickstart assumes a LiveKit Agent environment setup # In a real scenario, AgentSession would be started by the LiveKit server # with appropriate environment variables for authentication. LIVEKIT_URL = os.environ.get('LIVEKIT_URL', 'wss://your-livekit-url.cloud') LIVEKIT_API_KEY = os.environ.get('LIVEKIT_API_KEY', 'your_api_key') LIVEKIT_API_SECRET = os.environ.get('LIVEKIT_API_SECRET', 'your_api_secret') # This part typically runs on a LiveKit Agent service, not as a standalone script. # For local testing, you might mock AgentSession or connect to a local LiveKit instance. print("To run this, ensure LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET are set.") print("This code snippet demonstrates plugin usage within a LiveKit AgentSession.") if __name__ == '__main__': # In a typical LiveKit Agents deployment, you wouldn't directly call main here. # The agent system would instantiate and manage MyAgent. # This is for illustration of the noise_cancellation plugin usage. import asyncio asyncio.run(main())
Debug
Known issues
gotchaThis plugin requires a LiveKit Cloud account. Enhanced noise cancellation is a feature of paid LiveKit Cloud accounts and consumes real connection minutes during use.
fix
Ensure you have an active LiveKit Cloud account and understand the associated usage costs.
affects: All versions
gotchaNoise cancellation should only be applied once in the audio pathway. If you enable this plugin in your agent, you should disable any noise cancellation or Krisp filter in your frontend clients to avoid unexpected audio degradation.
fix
Disable client-side or frontend noise cancellation features when using this plugin in LiveKit Agents.
affects: All versions
gotchaUsers have reported unexpected audio degradation with the BVC (Background Voice Cancellation) model. This might manifest as the processed audio sounding 'different' or lower quality than expected.
fix
Experiment with different noise cancellation models (e.g., NC instead of BVC) or ensure client-side echo cancellation is disabled. Consider monitoring agent observability metrics for audio quality insights.
affects: All versions
gotchaCrashes on AMD CPUs have been reported, potentially due to OpenBLAS's CPU detection failing. This can cause agent connection issues or silent failures.
fix
Manually set the `OPENBLAS_CORETYPE` environment variable to a more conservative value (e.g., `Haswell`).
affects: All versions
gotchaPlugin initialization, including `livekit-plugins-noise-cancellation`, can occasionally cause LiveKit Agents to stall or crash before connecting to a room, especially in cloud deployments.
fix
Temporarily remove the noise cancellation plugin during debugging to identify if it's the culprit. Wrap plugin initialization in `try/except` blocks and log failures explicitly, allowing the session to continue without the plugin if it fails.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'livekit.plugins.noise_cancellation'
The `livekit-plugins-noise-cancellation` package is not installed in your Python environment or the environment where the code is being executed does not have access to it.
fix
Install the package using pip: `pip install livekit-plugins-noise-cancellation` or, if using uv, `uv add "livekit-plugins-noise-cancellation~=0.2"`.
livekit_ffi::server::audio_stream:123:livekit_ffi::server::audio_stre... failed to initialize the audio filter
This error often occurs in containerized environments like Docker or Kubernetes, indicating a failure in the underlying native (FFI) components of the plugin due to missing system dependencies, incorrect environment setup, or conflicts.
fix
Ensure all required system-level dependencies for the native plugin are present in your container image. You may need to temporarily remove the plugin to isolate the issue or check LiveKit Cloud logs for more detailed FFI errors, and confirm your LiveKit Cloud plan includes noise cancellation.
Processing failed: Unable to authorize model use: Model use unauthorized
This error indicates that your LiveKit Cloud account is not authorized to use the specific Krisp or ai-coustics noise cancellation model, or there is an issue with the feature enablement on your LiveKit Cloud account.
fix
Verify that your LiveKit Cloud account has the necessary features enabled for Krisp or ai-coustics noise cancellation by checking your plan details. If the feature is expected to be enabled, contact LiveKit support for assistance.
Crashes when using noise_cancellation (especially on AMD CPUs) due to OpenBLAS's CPU detection
The underlying OpenBLAS library, which the noise cancellation plugin may utilize, can sometimes fail to correctly detect the CPU architecture, leading to application crashes, particularly on AMD processors.
fix
Manually set the `OPENBLAS_CORETYPE` environment variable to a more conservative value (e.g., `Haswell`) before running your application. For example: `export OPENBLAS_CORETYPE=Haswell` in your shell, or `import os; os.environ['OPENBLAS_CORETYPE'] = 'Haswell'` in your Python code before importing `livekit.plugins.noise_cancellation`.
Upgrade
Version history
0.3.0latest on PyPI · released Jul 17, 2026
Audit
Dependencies
livekit-agentsrequiredThis plugin is designed to be used with LiveKit Agents for processing audio streams.
livekitrequiredProvides core LiveKit WebRTC functionalities like AudioStream, which the plugin operates on.
Agent activity
29 hits · last 30 days
node
22
Amazon
1
OpenAI (training)
1
Resources