Metadata-Version: 2.4
Name: pipecat-hecttor
Version: 0.1.0
Summary: Hecttor speech enhancement audio filter for Pipecat
Project-URL: Homepage, https://hecttor.ai
Project-URL: Repository, https://github.com/Saima-AI/pipecat-hecttor
Project-URL: Issues, https://github.com/Saima-AI/pipecat-hecttor/issues
Project-URL: Changelog, https://github.com/Saima-AI/pipecat-hecttor/blob/main/CHANGELOG.md
License-Expression: BSD-2-Clause
License-File: LICENSE
Keywords: audio,denoising,hecttor,noise-cancellation,pipecat,speech-enhancement
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: loguru~=0.7.3
Requires-Dist: numpy<3,>=1.26.4
Requires-Dist: pipecat-ai<2,>=1.5.0
Description-Content-Type: text/markdown

# pipecat-hecttor

[Hecttor](https://hecttor.ai) speech enhancement audio filter for [Pipecat](https://github.com/pipecat-ai/pipecat).

`HecttorFilter` is an input audio filter that removes background noise from the user's audio in real time using the Hecttor SDK's ASR-optimized speech enhancer. It runs before audio reaches the STT service, improving transcription accuracy in noisy environments. You can choose among several enhancement models and blend the enhanced output with the original audio.

> This integration is maintained by [Saima AI](https://hecttor.ai), the company behind Hecttor.

## Installation

Install the package:

```bash
uv add pipecat-hecttor
```

The filter requires the `hecttor_sdk` Python package, which is **not published to PyPI**. Contact [Hecttor](https://hecttor.ai) for SDK access and an API key — you'll receive a wheel for your platform and Python version:

```bash
pip install hecttor_sdk-<version>-<python>-<platform>.whl
```

Set your API key:

```bash
export HECTTOR_API_KEY=your_api_key_here
```

## Usage

Add the filter to any Pipecat transport via the `audio_in_filter` parameter:

```python
from pipecat_hecttor import HecttorFilter
from pipecat.transports.base_transport import TransportParams

params = TransportParams(
    audio_in_enabled=True,
    audio_in_filter=HecttorFilter(),
    audio_out_enabled=True,
)
```

### Configuration

| Parameter | Default | Description |
| --- | --- | --- |
| `api_key` | `None` | Hecttor API key. Falls back to the `HECTTOR_API_KEY` environment variable. |
| `model_name` | `"coda-vi-1.0"` | ASR enhancement model: `crest-1.0`, `crest-2.0`, `mist-1.0`, `coda-1.0`, or `coda-vi-1.0`. |
| `chunk_size_ms` | `20` | Chunk size in milliseconds, `16` or `20`. `crest-2.0`, `coda-1.0`, and `coda-vi-1.0` require `20`. |
| `enhancer_weight` | `None` | Blend factor `[0.0, 1.0]` between original (`0.0`) and enhanced (`1.0`) audio. `None` uses the model's default. |

### Runtime toggle

Disable and re-enable denoising at runtime with Pipecat's `FilterEnableFrame`:

```python
from pipecat.frames.frames import FilterEnableFrame

await worker.queue_frame(FilterEnableFrame(False))  # disable
await worker.queue_frame(FilterEnableFrame(True))  # re-enable
```

## Running the example

[`examples/voice-hecttor.py`](examples/voice-hecttor.py) is a complete voice bot with Hecttor denoising, Deepgram STT, OpenAI LLM, and Cartesia TTS.

1. Install the example's dependencies:

   ```bash
   uv add pipecat-hecttor "pipecat-ai[deepgram,cartesia,openai,silero,webrtc,runner]"
   ```

2. Install the `hecttor_sdk` wheel (see [Installation](#installation)).

3. Create a `.env` file with your keys:

   ```
   HECTTOR_API_KEY=...
   DEEPGRAM_API_KEY=...
   OPENAI_API_KEY=...
   CARTESIA_API_KEY=...
   ```

4. Run the bot and open the printed URL in your browser:

   ```bash
   python examples/voice-hecttor.py
   ```

## Testing the filter offline

[`scripts/test_hecttor_filter_audiofile.py`](scripts/test_hecttor_filter_audiofile.py) runs the filter over a pre-recorded audio file so you can compare original and enhanced audio:

```bash
uv add soundfile
python scripts/test_hecttor_filter_audiofile.py input.wav output.wav
```

It reports the realtime factor and before/after audio statistics.

## Compatibility

Tested with Pipecat v1.7.0.

Pipecat evolves rapidly; if you hit a compatibility issue with a newer release, please [open an issue](https://github.com/Saima-AI/pipecat-hecttor/issues).

## License

BSD 2-Clause — see [LICENSE](LICENSE).
