LiveKit Integration — Getting Started

Follow these steps to add Hecttor speech enhancement to a LiveKit Agents worker.

Step 1: Get your SDK key

Your SDK key is issued during onboarding. Choose the enhancer type that matches your use case:

Voice AI Agent Enhancement — for agent and ASR pipelines (the usual choice for LiveKit; matches the plugin's default ASR mode).
Call Enhancement — for human-to-human calls (required for the plugin's human mode).

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: Download the plugin

The plugin is distributed with your SDK license — pick Python or Node.js and download the build for your language. Your license email or onboarding contact has the right link.

You also need the matching Hecttor SDK for your platform (Python SDK ≥ 3.1.0 or Node.js SDK ≥ 2.2.0) — the plugin is a thin wrapper and does not bundle the SDK.

You end up with two files: the plugin and the SDK. Put both inside your project — this guide assumes a vendor/ directory at the repository root, but any path works as long as you install from it.

Step 3: Install

Neither file is published to PyPI or npm — install them by file path, not by package name:

Install the platform-specific SDK wheel together with the plugin wheel (the plugin wheel is universal — one file for all platforms):

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

The wheel is named livekit_plugins_hecttor, but it installs into LiveKit's livekit.plugins namespace — verify it resolves:

python -c "from livekit.plugins import hecttor; print(hecttor.__name__)"

Install the platform-specific SDK package together with the plugin package (the plugin package is platform-independent):

# Use the SDK tarball matching your platform, e.g.:
npm install ./vendor/hecttor_sdk-2.2.0-linux-x64-node.tgz ./vendor/hecttor-livekit-noise-cancellation-1.0.0.tgz

The tarball installs under the package's own name, not the file name — verify it resolves:

node -e "require('@hecttor/livekit-noise-cancellation')"

Once both resolve, installation is complete — there is nothing else to register or copy into place. The only remaining step is passing the plugin's factory to your session, as in Step 4.

The SDK file name varies by platform and (for Python) interpreter version — use the file that matches your environment. See the SDK Getting Started for details.

Installing from a local path leaves nothing another machine can resolve: npm records a file: path in package.json that only works on your machine, and pip records nothing at all. Keep both artifacts with your project — commit them, or host them on an internal artifact store — and install them from there in your build. In a Dockerfile, COPY vendor/ ./vendor/ before the install step.

Step 4: Wire it into your agent

Set your SDK key in the HECTTOR_API_KEY environment variable, then pass the plugin's noise-suppression factory to your session's audio input options:

from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli, room_io
from livekit.plugins import hecttor


async def entrypoint(ctx: JobContext) -> None:
    await ctx.connect()

    session = AgentSession(
        # stt / llm / tts / vad of your choice
    )

    await session.start(
        agent=Agent(instructions="You are a helpful voice assistant."),
        room=ctx.room,
        room_options=room_io.RoomOptions(
            audio_input=room_io.AudioInputOptions(
                # Default is ASR mode: cleans the caller's audio before STT
                noise_cancellation=hecttor.noise_suppression(),
            ),
        ),
    )


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

import { noiseSuppression } from '@hecttor/livekit-noise-cancellation';

await session.start({
  agent,
  room: ctx.room,
  inputOptions: {
    // Default is ASR mode: cleans the caller's audio before STT
    noiseCancellation: noiseSuppression(),
  },
});

The plugin can also be attached to a raw track subscription via rtc.AudioStream.from_track(track, noise_cancellation=...) (Python) or new AudioStream(track, { noiseCancellation }) (Node.js).

Configuration

Configuration is passed to the factory function, and the processor it returns is what you hand to the agent — there is no separate config object or initialization call. With no arguments the factory reads HECTTOR_API_KEY from the environment and uses the defaults, which is why Step 4 works as-is:

audio_input=room_io.AudioInputOptions(
    # the factory takes all configuration and returns the processor
    # that the agent consumes — this is the only wiring needed
    noise_cancellation=hecttor.noise_suppression(
        model="your_model",
        enhancer_weight=1.0,
    ),
)

Model names are provided during onboarding. Each mode below accepts its own set of models, and each model ships with a default blend weight — see Orpheus Overview and Hermes Overview for guidance on choosing one.

The plugin operates in one of two modes, each backed by a different enhancer and set of models. Pick the mode via the factory you call.

ASR mode (default)

noise_suppression() / noiseSuppression() wraps Orpheus (ASRSpeechEnhancer) — models optimized for machine transcription. Use it when the audio feeds STT / a voice agent. Requires a Voice AI Agent Enhancement key.

from livekit.plugins import hecttor

noise_cancellation=hecttor.noise_suppression(
    api_key="sk_...",        # optional — defaults to $HECTTOR_API_KEY
    model="your_model",      # optional — defaults to a voice-isolation model
    enhancer_weight=1.0,     # optional — defaults to the model preset
    sample_rate=48000,       # optional — this is the default; set to your pipeline's rate
)

Option	Default	Description
`api_key`	`$HECTTOR_API_KEY`	Hecttor SDK key (Voice AI Agent Enhancement type)
`model`	voice-isolation model	ASR model name — provided during onboarding
`enhancer_weight`	model default	Wet/dry blend, 0.0–1.0. 1.0 = fully enhanced
`sample_rate`	`48000`	Rate the enhancer initializes at — see note below

import { noiseSuppression } from '@hecttor/livekit-noise-cancellation';

noiseCancellation: noiseSuppression({
  apiKey: 'sk_...',          // optional — defaults to $HECTTOR_API_KEY
  model: 'your_model',       // optional — defaults to a voice-isolation model
  enhancerWeight: 1.0,       // optional — defaults to the model preset
  sampleRate: 48000,         // optional — this is the default; set to your pipeline's rate
}),

Option	Default	Description
`apiKey`	`$HECTTOR_API_KEY`	Hecttor SDK key (Voice AI Agent Enhancement type)
`model`	voice-isolation model	ASR model name — provided during onboarding
`enhancerWeight`	model default	Wet/dry blend, 0.0–1.0. 1.0 = fully enhanced
`sampleRate`	`48000`	Rate the enhancer initializes at — see note below

Human mode

human_noise_suppression() / humanNoiseSuppression() wraps Hermes (HumanSpeechEnhancer) — models optimized for perceptual quality. Use it when people listen to the audio (call recording, listen-in, human-to-human relays). Requires a Call Enhancement key.

from livekit.plugins import hecttor

noise_cancellation=hecttor.human_noise_suppression(
    api_key="sk_...",        # optional — defaults to $HECTTOR_API_KEY
    model="your_model",      # optional — defaults to a voice-isolation model
    enhancer_weight=1.0,     # optional — this is the default blend
    voice_boost=False,       # optional — off by default (multi-band compressor)
    sample_rate=48000,       # optional — this is the default; set to your pipeline's rate
)

Option	Default	Description
`api_key`	`$HECTTOR_API_KEY`	Hecttor SDK key (Call Enhancement type)
`model`	voice-isolation model	Human-listener model name — provided during onboarding
`enhancer_weight`	`1.0`	Wet/dry blend, 0.0–1.0. 1.0 = fully enhanced
`voice_boost`	`false`	Multi-band compressor post-processing
`sample_rate`	`48000`	Rate the enhancer initializes at — see note below

import { humanNoiseSuppression } from '@hecttor/livekit-noise-cancellation';

noiseCancellation: humanNoiseSuppression({
  apiKey: 'sk_...',          // optional — defaults to $HECTTOR_API_KEY
  model: 'your_model',       // optional — defaults to a voice-isolation model
  enhancerWeight: 1.0,       // optional — this is the default blend
  voiceBoost: false,         // optional — off by default (multi-band compressor)
  sampleRate: 48000,         // optional — this is the default; set to your pipeline's rate
}),

Option	Default	Description
`apiKey`	`$HECTTOR_API_KEY`	Hecttor SDK key (Call Enhancement type)
`model`	voice-isolation model	Human-listener model name — provided during onboarding
`enhancerWeight`	`1.0`	Wet/dry blend, 0.0–1.0. 1.0 = fully enhanced
`voiceBoost`	`false`	Multi-band compressor post-processing
`sampleRate`	`48000`	Rate the enhancer initializes at — see note below

The enhancer initializes for sample_rate up front. If frames later arrive at a different (supported) rate, it transparently re-initializes once — at the cost of an extra backend round-trip mid-stream. Setting it to your pipeline's actual rate avoids this: LiveKit Agents' Python AudioInputOptions delivers 24000 Hz by default, while raw AudioStream subscriptions default to 48000 Hz.

The enhancer is stateful — use one plugin instance per audio stream and do not share instances between sessions. Apply noise cancellation once per pipeline: either in the agent or in the client frontend, not both.

Next steps

Examples — complete agent implementations.

On this page