# Enhanced Noise Cancellation Plugin for LiveKit

Add realtime enhanced noise cancellation to inbound `AudioStream`. Fully compatible with [LiveKit Agents](https://github.com/livekit/agents).

Requires [LiveKit Cloud](https://cloud.livekit.io).

[Read more in the documentation](https://docs.livekit.io/home/client/tracks/noise-cancellation/)

## Audio chain

This package runs **server-side** on inbound audio (e.g. in an agent or on an `AudioStream`). Remote participants’ tracks are cleaned before your code or the agent consumes the audio.

```mermaid
flowchart LR
  Room["LiveKit room"] --> Track["Remote track (inbound)"]
  Track --> NC["@livekit/noise-cancellation-node"]
  NC --> Stream["AudioStream / Agent input"]
  Stream --> Consumer["Your code or agent"]
```

## Installation

```bash
npm install @livekit/noise-cancellation-node
```

## Usage

### In LiveKit Agents

Include the filter in `inputOptions` when starting your `AgentSession`:

```typescript
import { BackgroundVoiceCancellation } from '@livekit/noise-cancellation-node';

// ...
await session.start({
  // ...,
  inputOptions: {
    noiseCancellation: BackgroundVoiceCancellation(),
  },
});
// ...
```

### On AudioStream

Noise cancellation can also be applied to any individual inbound `AudioStream`:

```typescript
import { BackgroundVoiceCancellation } from '@livekit/noise-cancellation-node';
import { AudioStream } from '@livekit/rtc-node';

const stream = new AudioStream(track, {
  noiseCancellation: BackgroundVoiceCancellation(),
});
```

## Available Models
```typescript
import {
  // Standard enhanced noise cancellation (NC)
  NoiseCancellation,

  // Background voice cancellation (NC + removes non-primary voices
  // that would confuse transcription or turn detection)
  BackgroundVoiceCancellation,

  // Background voice cancellation optimized for telephony applications
  TelephonyBackgroundVoiceCancellation,
} from '@livekit/noise-cancellation-node';
```
## Architecture

This package uses a multi-package architecture to support platform-specific shared libraries:

- `@livekit/noise-cancellation-node` - Main package with TypeScript code
- `@livekit/noise-cancellation-darwin-arm64` - macOS ARM64 binaries and resources
- `@livekit/noise-cancellation-darwin-x64` - macOS x64 binaries and resources
- `@livekit/noise-cancellation-linux-x64` - Linux x64 binaries and resources
- `@livekit/noise-cancellation-linux-arm64` - Linux ARM64 binaries and resources
- `@livekit/noise-cancellation-win32-x64` - Windows x64 binaries and resources

The main package automatically selects and loads the appropriate platform-specific package for your system.

## Notes

Noise cancellation only needs to be applied once; if you apply it here, disable noise cancellation / Krisp filter in your frontend clients.

If you experience crashes when using `noiseCancellation` (especially on AMD CPUs), it might be due to a failure in OpenBLAS's CPU detection. Manually setting the `OPENBLAS_CORETYPE` environment variable to a more conservative value (e.g., `Haswell`) may resolve the issue.

## License

See https://livekit.io/legal/terms-of-service