Add HecttorFilter audio denoising integration

changelog/0000.added.md

@@ -0,0 +1 @@
+- Added `HecttorFilter` audio filter for real-time speech enhancement using the Hecttor SDK. Supports ASR-optimized and human-optimized denoising modes with configurable voice boost and enhancement weight. The filter integrates as an input audio filter on any transport via `audio_in_filter`. See `examples/foundational/07zm-interruptible-hecttor.py` for usage.

docs/api/conf.py

@@ -47,6 +47,8 @@
 
 # Mock imports for optional dependencies
 autodoc_mock_imports = [
+    # Hecttor - not publicly available, installed manually
+    "hecttor_sdk",
     # Krisp - has build issues on some platforms
     "pipecat_ai_krisp",
     "krisp",

examples/foundational/07zm-interruptible-hecttor.py

@@ -0,0 +1,165 @@
+#
+# Copyright (c) 2024-2026, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Interruptible bot with Hecttor noise filtering.
+
+This example demonstrates a conversational bot with:
+- Hecttor audio denoising on incoming audio
+- Voice activity detection (VAD) with Silero
+- Deepgram STT, OpenAI LLM, and Cartesia TTS
+
+The Hecttor filter enhances incoming speech by removing background noise before
+it reaches the STT service, improving transcription accuracy in noisy environments.
+
+Required environment variables:
+- HECTTOR_API_KEY: Hecttor API key (from https://admin.hecttor.ai)
+- DEEPGRAM_API_KEY: Deepgram API key for STT
+- OPENAI_API_KEY: OpenAI API key for LLM
+- CARTESIA_API_KEY: Cartesia API key for TTS
+
+Note: The hecttor_sdk package is not available on PyPI. Download the wheel from
+the Hecttor admin panel (https://admin.hecttor.ai) and install it manually:
+    pip install hecttor_sdk-<version>-<platform>.whl
+"""
+
+import os
+
+from dotenv import load_dotenv
+from loguru import logger
+
+from pipecat.audio.filters.hecttor_filter import HecttorFilter
+from pipecat.audio.vad.silero import SileroVADAnalyzer
+from pipecat.frames.frames import LLMRunFrame
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.runner import PipelineRunner
+from pipecat.pipeline.task import PipelineParams, PipelineTask
+from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.processors.aggregators.llm_response_universal import (
+    LLMContextAggregatorPair,
+    LLMUserAggregatorParams,
+)
+from pipecat.runner.types import RunnerArguments
+from pipecat.runner.utils import create_transport
+from pipecat.services.cartesia.tts import CartesiaTTSService
+from pipecat.services.deepgram.stt import DeepgramSTTService
+from pipecat.services.openai.llm import OpenAILLMService
+from pipecat.transports.base_transport import BaseTransport, TransportParams
+from pipecat.transports.daily.transport import DailyParams
+from pipecat.transports.websocket.fastapi import FastAPIWebsocketParams
+
+load_dotenv(override=True)
+
+# Create Hecttor filter for input audio denoising.
+# mode="asr" is optimized for speech recognition pipelines.
+# mode="human" with enable_voice_boost=True is better for human listeners.
+hecttor_filter = HecttorFilter(
+    api_key=os.getenv("HECTTOR_API_KEY"),
+    mode="asr",
+)
+
+# We use lambdas to defer transport parameter creation until the transport
+# type is selected at runtime.
+transport_params = {
+    "daily": lambda: DailyParams(
+        audio_in_enabled=True,
+        audio_out_enabled=True,
+        audio_in_filter=hecttor_filter,
+    ),
+    "twilio": lambda: FastAPIWebsocketParams(
+        audio_in_enabled=True,
+        audio_out_enabled=True,
+        audio_in_filter=hecttor_filter,
+    ),
+    "webrtc": lambda: TransportParams(
+        audio_in_enabled=True,
+        audio_out_enabled=True,
+        audio_in_filter=hecttor_filter,
+    ),
+}
+
+
+async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
+    logger.info("Starting bot")
+
+    stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
+
+    tts = CartesiaTTSService(
+        api_key=os.getenv("CARTESIA_API_KEY"),
+        settings=CartesiaTTSService.Settings(
+            voice="71a7ad14-091c-4e8e-a314-022ece01c121",  # British Reading Lady
+        ),
+    )
+
+    llm = OpenAILLMService(
+        api_key=os.getenv("OPENAI_API_KEY"),
+        settings=OpenAILLMService.Settings(
+            system_instruction=(
+                "You are a helpful assistant in a voice conversation. Your responses "
+                "will be spoken aloud, so avoid emojis, bullet points, or other "
+                "formatting that can't be spoken. Respond to what the user said in a "
+                "creative, helpful, and brief way."
+            ),
+        ),
+    )
+
+    context = LLMContext()
+    user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
+        context,
+        user_params=LLMUserAggregatorParams(
+            vad_analyzer=SileroVADAnalyzer(),
+        ),
+    )
+
+    pipeline = Pipeline(
+        [
+            transport.input(),  # Transport user input
+            stt,  # STT
+            user_aggregator,  # User responses
+            llm,  # LLM
+            tts,  # TTS
+            transport.output(),  # Transport bot output
+            assistant_aggregator,  # Assistant spoken responses
+        ]
+    )
+
+    task = PipelineTask(
+        pipeline,
+        params=PipelineParams(
+            enable_metrics=True,
+            enable_usage_metrics=True,
+        ),
+        idle_timeout_secs=runner_args.pipeline_idle_timeout_secs,
+    )
+
+    @transport.event_handler("on_client_connected")
+    async def on_client_connected(transport, client):
+        logger.info("Client connected")
+        # Kick off the conversation.
+        context.add_message(
+            {"role": "developer", "content": "Please introduce yourself to the user."}
+        )
+        await task.queue_frames([LLMRunFrame()])
+
+    @transport.event_handler("on_client_disconnected")
+    async def on_client_disconnected(transport, client):
+        logger.info("Client disconnected")
+        await task.cancel()
+
+    runner = PipelineRunner(handle_sigint=runner_args.handle_sigint)
+
+    await runner.run(task)
+
+
+async def bot(runner_args: RunnerArguments):
+    """Main bot entry point compatible with Pipecat Cloud."""
+    transport = await create_transport(runner_args, transport_params)
+    await run_bot(transport, runner_args)
+
+
+if __name__ == "__main__":
+    from pipecat.runner.run import main
+
+    main()

pyproject.toml

@@ -75,6 +75,7 @@ gradium = [ "pipecat-ai[websockets-base]" ]
 grok = []
 groq = [ "groq>=0.23.0,<2" ]
 gstreamer = [ "pygobject~=3.50.0" ]
+hecttor = []
 heygen = [ "livekit>=1.0.13,<2", "pipecat-ai[websockets-base]" ]
 hume = [ "hume>=0.11.2,<1" ]
 inworld = []