Pipecat Integration — Getting Started

Follow these steps to add Hecttor speech enhancement to a Pipecat bot.

Step 1: Get your SDK key

Your SDK key is issued during onboarding — request the Voice AI Agent Enhancement enhancer type. The filter wraps the ASR enhancer, so this is the only key type it accepts.

Never commit your SDK key or expose it in client-side code. Store it in an environment variable and read it at runtime.

Step 2: Install the package

pipecat-hecttor is published on PyPI — install it by name:

pip install pipecat-hecttor
# or
uv add pipecat-hecttor

This pulls in pipecat-ai as a dependency. Your bot will typically also need Pipecat extras for your transport and services.

Step 3: Install the Hecttor SDK

The package wraps the Hecttor Python SDK (≥ 3.1.0), which is a separate licensed download — pick the wheel matching your platform and Python version, then install it by file path:

# Use the wheel matching your platform and Python version, e.g.:
pip install ./vendor/hecttor_sdk-3.1.1-cp311-cp311-linux_x86_64.whl

Verify both resolve:

python -c "from pipecat_hecttor import HecttorFilter; print('ok')"

import pipecat_hecttor raises ImportError if the SDK is missing — installing the SDK wheel is not optional. The SDK file name varies by platform and interpreter version; see the SDK Getting Started for details.

The SDK installs from a local path, so keep the wheel with your project — commit it, or host it on an internal artifact store — and install it from there in your build. In a Dockerfile, COPY vendor/ ./vendor/ before the install step. The pipecat-hecttor package itself installs from PyPI as usual.

Step 4: Wire it into your bot

Set your SDK key in the HECTTOR_API_KEY environment variable, then pass a filter instance to your transport's audio_in_filter:

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

hecttor_filter = HecttorFilter()

transport_params = TransportParams(
    audio_in_enabled=True,
    audio_out_enabled=True,
    audio_in_filter=hecttor_filter,
)

The transport drives the filter lifecycle — it initializes the enhancer with the transport's input sample rate on StartFrame and tears it down on shutdown. There is nothing else to register.

Configuration

All configuration is passed to the constructor. With no arguments the filter reads HECTTOR_API_KEY from the environment and uses the defaults, which is why Step 4 works as-is:

hecttor_filter = HecttorFilter(
    api_key="sk_...",         # optional — defaults to $HECTTOR_API_KEY
    model_name="your_model",  # optional — defaults to a voice-isolation model
    chunk_size_ms=20,         # optional — 16 or 20; some models require 20
    enhancer_weight=1.0,      # optional — defaults to the model preset
)

Option	Default	Description
`api_key`	`$HECTTOR_API_KEY`	Hecttor SDK key (Voice AI Agent Enhancement type)
`model_name`	voice-isolation model	ASR model name — provided during onboarding
`chunk_size_ms`	`20`	Processing chunk size. `16` or `20`; some models require `20`
`enhancer_weight`	model default	Wet/dry blend, 0.0–1.0. 1.0 = fully enhanced

Invalid combinations raise ValueError at construction time (missing key, unknown model, unsupported chunk size for the chosen model, weight out of range).

Model names, their supported chunk sizes, and their default blend weights are provided during onboarding. See Orpheus Overview for guidance on choosing between them.

There is no sample-rate parameter: the transport passes its input rate to the filter at startup. All rates a Pipecat transport delivers (4000–48000 Hz) are supported — the SDK resamples internally.

The enhancer is stateful — use one filter instance per input stream and do not share instances between transports. Apply noise cancellation once per pipeline: either in the bot or in the client frontend, not both.

Next steps

Examples — a complete bot and common patterns.