> ## Documentation Index
> Fetch the complete documentation index at: https://daily-main.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# VoxLock Audio Filter

> Keeps the caller's voice and removes the other voices in the room before VAD and speech-to-text, on the CPU

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="arbazsiddiqui" maintainerUrl="https://github.com/arbazsiddiqui" repo="https://github.com/arbazsiddiqui/voxlock" />

## Overview

`VoxLockFilter` is a `BaseAudioFilter` implementation backed by
[VoxLock](https://huggingface.co/arbazsiddiqui/voxlock), an open-source
(Apache-2.0) voice isolation model. You attach it to a transport's
`audio_in_filter`, and it keeps the caller's voice and removes the other people
talking in the caller's room, so VAD and your STT service only hear the caller.
It runs locally with onnxruntime on the CPU: no API key and no network calls
after the model download.

VoxLock locks on to one voice. Until it has heard 3 seconds of the caller's
speech, the filter passes audio through unchanged; it then takes that speech as
the voice sample and isolates from then on. If you already have a sample of the
caller, pass it in and isolation starts with the first frame.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/arbazsiddiqui/voxlock">
    Code, Pipecat example bot, benchmark harness and changelog
  </Card>

  <Card title="Model" icon="cube" href="https://huggingface.co/arbazsiddiqui/voxlock">
    Model card, benchmark results and ONNX files on Hugging Face
  </Card>

  <Card title="PyPI Package" icon="box" href="https://pypi.org/project/voxlock/">
    The `voxlock` package on PyPI
  </Card>

  <Card title="Live Demo" icon="play" href="https://www.arbazsiddiqui.me/voxlock">
    Listen to calls with the filter off and on, in the browser
  </Card>
</CardGroup>

## Installation

This is a community-maintained package distributed separately from `pipecat-ai`:

```bash theme={null}
uv add "voxlock[pipecat]"
```

Requires Python 3.11 or later, like `pipecat-ai`.

## Prerequisites

* **No API key.** The model (75 MB) downloads from Hugging Face on first use
  and is cached.
* **CPU.** With the default settings the filter uses 2 CPU threads per call.
  See [Choosing the CPU settings](#choosing-the-cpu-settings).

## Configuration

<ParamField path="voice_sample" type="np.ndarray | None" default="None">
  About 3 seconds of the caller's voice, 16 kHz mono float32. When given,
  isolation starts from the first audio frame.
</ParamField>

<ParamField path="sample_seconds" type="float" default="3.0">
  Seconds of speech to collect as the voice sample when `voice_sample` is not
  given. Audio passes through unchanged until then.
</ParamField>

<ParamField path="chunk_ms" type="int" default="80">
  Audio is run through the model in chunks of this length. Larger chunks use
  less CPU and add their length to the delay.
</ParamField>

<ParamField path="threads" type="int" default="2">
  onnxruntime threads for this filter.
</ParamField>

<ParamField path="precision" type="str" default="&#x22;int8&#x22;">
  Model files: `"int8"`, `"int8-full"` (fastest), `"fp16"` or `"fp32"`.
</ParamField>

<ParamField path="model_dir" type="str | None" default="None">
  Folder with the ONNX files. `None` downloads them from Hugging Face.
</ParamField>

## Usage

Create one filter per call and pass it to your transport as `audio_in_filter`:

```python theme={null}
from pipecat.transports.base_transport import TransportParams
from voxlock.pipecat import VoxLockFilter

transport_params = TransportParams(
    audio_in_enabled=True,
    audio_in_filter=VoxLockFilter(),
)
```

The transport drives the filter lifecycle (`start(sample_rate)`,
`filter(audio)`, `process_frame(frame)` and `stop()`), so no additional wiring
is needed. A complete voice agent is in
[examples/pipecat\_bot.py](https://github.com/arbazsiddiqui/voxlock/blob/main/examples/pipecat_bot.py).

### With a voice sample

```python theme={null}
import voxlock
from voxlock.pipecat import VoxLockFilter

sample = voxlock.load_audio("caller_sample.wav")  # about 3 s, any format
audio_filter = VoxLockFilter(voice_sample=sample)
```

### Choosing the CPU settings

| CPU | Settings | Real-time factor |
| - | - | - |
| 2 or more threads (default) | `VoxLockFilter()` | 0.67 |
| One vCPU, e.g. Pipecat Cloud `agent-2x` | `VoxLockFilter(chunk_ms=160, threads=1)` | 0.73 |

Measured on an 8-vCPU Xeon server; below 1 keeps up with the call. Half a vCPU
(Pipecat Cloud `agent-1x`) is too little.

## Input Frames

<ParamField path="FilterEnableFrame" type="Frame">
  Control frame to toggle isolation on and off at runtime

  ```python theme={null}
  from pipecat.frames.frames import FilterEnableFrame

  # Bypass isolation: audio passes through unchanged
  await task.queue_frame(FilterEnableFrame(enable=False))

  # Resume isolation
  await task.queue_frame(FilterEnableFrame(enable=True))
  ```
</ParamField>

## Audio Requirements

* Input is 16-bit mono PCM at the transport's sample rate. The filter resamples
  to 16 kHz for the model and back, so 8 kHz telephony and 48 kHz WebRTC both
  work.
* Audio is collected into `chunk_ms` chunks, so some calls to `filter()`
  return no audio; the input transport skips those.

## Compatibility

Tested with Pipecat 1.12.0. See the
[changelog](https://github.com/arbazsiddiqui/voxlock/blob/main/CHANGELOG.md)
for the latest tested version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.