Hecttor

Overview

HecttorFilter is a BaseAudioFilter implementation backed by Hecttor, a real-time speech enhancer tuned for ASR/STT accuracy. You attach it to a transport’s audio_in_filter, and it removes background noise from incoming user audio before the audio reaches VAD and your STT service. Several enhancement models are available, and you can blend the enhanced output with the original audio. The package also provides HecttorAudioProcessor, a two-stage frame processor that enhances the audio with two different blend factors at once — one tuned for STT and one for VAD and turn-taking models. See HecttorAudioProcessor below.

Source Repository

Source code, examples, and issues for the Hecttor integration

PyPI Package

The pipecat-hecttor package on PyPI

Learn more about Hecttor

Request Access

Contact Hecttor for SDK access and an API key

Installation

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

uv add pipecat-hecttor

The filter also requires the hecttor_sdk package, which is not published to PyPI. Contact Hecttor for SDK access and an API key — you’ll receive a wheel for your platform and Python version:

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

Requires Python >= 3.11.

Prerequisites

API key: contact Hecttor for SDK access and an API key.
Network access: the agent process must be able to reach Hecttor’s servers to validate the API key on initialization.

Required Environment Variables

HECTTOR_API_KEY: your Hecttor API key

export HECTTOR_API_KEY="your_api_key_here"

Don’t commit API keys or .env files to source control.

Configuration

str | None

default:"None"

Hecttor API key. Falls back to the HECTTOR_API_KEY environment variable if not provided.

str

default:"\"coda-vi-1.0\""

ASR enhancement model to use. One of "crest-1.0", "crest-2.0", "mist-1.0", "coda-1.0", or "coda-vi-1.0".

int

default:"20"

Chunk size in milliseconds, either 16 or 20. The "crest-2.0", "coda-1.0", and "coda-vi-1.0" models require 20.

float | None

default:"None"

Blend factor between original and enhanced audio in the range [0.0, 1.0]. 1.0 = fully enhanced, 0.0 = original audio. If not set, the model’s default weight is used.

Usage

Create one filter instance and pass it to your transport as audio_in_filter:

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

audio_filter = HecttorFilter()

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

The transport drives the filter lifecycle — start(sample_rate), filter(audio), process_frame(frame), and stop() — so no additional wiring is needed.

Fine-tuning enhancement

audio_filter = HecttorFilter(
    model_name="coda-vi-1.0",
    enhancer_weight=0.8,  # 80% enhanced, 20% original
)

HecttorAudioProcessor: per-consumer blends

The optimal enhancer weight for transcription is not always the optimal weight for endpointing: STT usually wants fully enhanced audio, while VAD and turn-taking models can perform better with some of the original signal blended back in. HecttorAudioProcessor (requires pipecat-hecttor >= 0.2.0) produces both blends from the same input. Instead of a transport filter, it is a pair of pipeline stages built around Pipecat’s processing order — STT consumes audio before the user context aggregator, which hosts the VAD and turn analyzers:

from pipecat_hecttor import HecttorAudioProcessor

hecttor = HecttorAudioProcessor(
    asr_weight=1.0,     # blend for the STT/agent path
    vad_tt_weight=0.3,  # blend for VAD and turn-taking models
)

pipeline = Pipeline(
    [
        transport.input(),       # no audio_in_filter
        hecttor,                 # stage 1: frames now carry the ASR blend
        stt,                     # hears the ASR blend
        hecttor.vad_tt_stage(),  # stage 2: swaps in the VAD/TT blend
        user_aggregator,         # VAD + turn analyzers hear the VAD/TT blend
        llm,
        tts,
        transport.output(),
        assistant_aggregator,
    ]
)

Configuration

The processor accepts the same api_key, model_name, and chunk_size_ms parameters as HecttorFilter, plus the two blend weights:

float | None

default:"None"

Blend factor in [0.0, 1.0] for the audio delivered to the STT/agent path. 1.0 = fully enhanced, 0.0 = original audio. If not set, the model’s default weight is used.

float | None

default:"None"

Blend factor in [0.0, 1.0] for the audio delivered to VAD and turn-taking models via vad_tt_stage(). If not set, the model’s default weight is used.

Use HecttorAudioProcessor instead of audio_in_filter — combining them enhances the audio twice.

Notes:

The current implementation runs two enhancer sessions, one per weight, which doubles enhancement compute.
Any processor placed downstream of vad_tt_stage() (e.g. audio recorders) receives the VAD/TT blend.

Input Frames

Frame

Control frame to toggle enhancement on and off at runtime (HecttorFilter only)

from pipecat.frames.frames import FilterEnableFrame

# Bypass enhancement — audio passes through unchanged
await worker.queue_frame(FilterEnableFrame(enable=False))

# Resume enhancement
await worker.queue_frame(FilterEnableFrame(enable=True))

Audio Requirements

Input must be signed 16-bit PCM (int16) bytes.
Supported sample rates: 4000, 8000, 16000, 24000, 32000, 44100, and 48000 Hz (the SDK resamples internally).
Any chunk size is accepted — the filter buffers partial data internally and emits audio once complete chunks are available.

Compatibility

Tested with Pipecat v1.7.0. Check the source repository for the latest tested version and changelog.

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Hecttor

Overview

Source Repository

PyPI Package

Hecttor

Request Access

Installation

Prerequisites

Required Environment Variables

Configuration

Usage

Fine-tuning enhancement

HecttorAudioProcessor: per-consumer blends

Configuration

Input Frames

Audio Requirements

Compatibility

​Overview

Source Repository

PyPI Package

Hecttor

Request Access

​Installation

​Prerequisites

​Required Environment Variables

​Configuration

​Usage

​Fine-tuning enhancement

​HecttorAudioProcessor: per-consumer blends

​Configuration

​Input Frames

​Audio Requirements

​Compatibility

Overview

Installation

Prerequisites

Required Environment Variables

Configuration

Usage

Fine-tuning enhancement

HecttorAudioProcessor: per-consumer blends

Configuration

Input Frames

Audio Requirements

Compatibility