{"id":5300,"library":"livekit-plugins-noise-cancellation","title":"LiveKit Noise Cancellation Plugin","description":"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.","status":"active","version":"0.2.5","language":"en","source_language":"en","source_url":"https://github.com/livekit/agents","tags":["webrtc","realtime","audio","livekit","noise-cancellation","agents","speech-enhancement"],"install":[{"cmd":"pip install livekit-plugins-noise-cancellation","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This plugin is designed to be used with LiveKit Agents for processing audio streams.","package":"livekit-agents","optional":false},{"reason":"Provides core LiveKit WebRTC functionalities like AudioStream, which the plugin operates on.","package":"livekit","optional":false}],"imports":[{"symbol":"noise_cancellation","correct":"from livekit.plugins import noise_cancellation"},{"note":"Standard enhanced noise cancellation model.","symbol":"NC","correct":"noise_cancellation.NC()"},{"note":"Background voice cancellation model.","symbol":"BVC","correct":"noise_cancellation.BVC()"},{"note":"Background voice cancellation model optimized for telephony applications.","symbol":"BVCTelephony","correct":"noise_cancellation.BVCTelephony()"}],"quickstart":{"code":"import os\nfrom livekit.agents import AgentSession, JobContext, RoomOptions, RoomInputOptions\nfrom livekit.plugins import noise_cancellation\n\nclass MyAgent:\n    async def start(self, ctx: JobContext):\n        # Example of applying BVC noise cancellation to inbound audio\n        await ctx.connect(\n            RoomOptions(auto_subscribe=RoomOptions.AutoSubscribe.AUDIO_ONLY),\n            room_input_options=RoomInputOptions(\n                noise_cancellation=noise_cancellation.BVC(),\n            ),\n        )\n        print(\"Agent connected with BVC noise cancellation enabled.\")\n        # Your agent logic here, e.g., process audio from ctx.room.local_participant.audio_tracks\n        # Keep the agent alive (e.g., by waiting for a signal or keeping a loop)\n        # For a simple quickstart, we'll just wait indefinitely for demonstration.\n        # In a real agent, you'd manage session lifecycle more robustly.\n        await ctx.room.wait_for_is_connected()\n\nasync def main():\n    # This quickstart assumes a LiveKit Agent environment setup\n    # In a real scenario, AgentSession would be started by the LiveKit server\n    # with appropriate environment variables for authentication.\n    LIVEKIT_URL = os.environ.get('LIVEKIT_URL', 'wss://your-livekit-url.cloud')\n    LIVEKIT_API_KEY = os.environ.get('LIVEKIT_API_KEY', 'your_api_key')\n    LIVEKIT_API_SECRET = os.environ.get('LIVEKIT_API_SECRET', 'your_api_secret')\n    \n    # This part typically runs on a LiveKit Agent service, not as a standalone script.\n    # For local testing, you might mock AgentSession or connect to a local LiveKit instance.\n    print(\"To run this, ensure LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET are set.\")\n    print(\"This code snippet demonstrates plugin usage within a LiveKit AgentSession.\")\n\nif __name__ == '__main__':\n    # In a typical LiveKit Agents deployment, you wouldn't directly call main here.\n    # The agent system would instantiate and manage MyAgent.\n    # This is for illustration of the noise_cancellation plugin usage.\n    import asyncio\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure you have an active LiveKit Cloud account and understand the associated usage costs.","message":"This plugin requires a LiveKit Cloud account. Enhanced noise cancellation is a feature of paid LiveKit Cloud accounts and consumes real connection minutes during use.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Disable client-side or frontend noise cancellation features when using this plugin in LiveKit Agents.","message":"Noise 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Users 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Manually set the `OPENBLAS_CORETYPE` environment variable to a more conservative value (e.g., `Haswell`).","message":"Crashes on AMD CPUs have been reported, potentially due to OpenBLAS's CPU detection failing. This can cause agent connection issues or silent failures.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Plugin initialization, including `livekit-plugins-noise-cancellation`, can occasionally cause LiveKit Agents to stall or crash before connecting to a room, especially in cloud deployments.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}