krisp_viva_filter

Krisp noise reduction audio filter for Pipecat.

This module provides an audio filter implementation using Krisp VIVA SDK.

class pipecat.audio.filters.krisp_viva_filter.KrispVivaFilter(model_path: str | None = None, frame_duration: int = 10, noise_suppression_level: int = 100, api_key: str = '', tts_model_path: str | None = None, tts_threshold: float = 0.5, tts_detection_timeout: float = 3.0)[source]

Bases: BaseAudioFilter

Audio filter using the Krisp VIVA SDK.

Provides real-time noise reduction for audio streams using Krisp’s proprietary noise suppression algorithms. This filter requires a valid Krisp model file to operate.

Optionally supports TTS detection (iPhone screening feature is standalone model) to delay voice isolation until bot speech playback has stopped, preventing later real human speech suppression artifacts. Provide tts_model_path (or set the KRISP_VIVA_TTS_MODEL_PATH environment variable) to enable this feature.

__init__(model_path: str | None = None, frame_duration: int = 10, noise_suppression_level: int = 100, api_key: str = '', tts_model_path: str | None = None, tts_threshold: float = 0.5, tts_detection_timeout: float = 3.0) → None[source]

Initialize the Krisp noise reduction filter.

Parameters:

  • model_path – Path to the Krisp NC model file (.kef extension). If None, uses KRISP_VIVA_FILTER_MODEL_PATH environment variable.

  • frame_duration – Frame duration in milliseconds.

  • noise_suppression_level – Noise suppression level.

  • api_key – Krisp SDK API key. If empty, falls back to the KRISP_VIVA_API_KEY environment variable.

  • tts_model_path – Path to the Krisp TTS detection model file (.kef extension). If None, uses KRISP_VIVA_TTS_MODEL_PATH environment variable. When not set, TTS detection is disabled and NC starts immediately.

  • tts_threshold – Probability threshold (0–1) above which a frame is classified as containing TTS. Only used when tts_model_path is set.

  • tts_detection_timeout – Seconds to wait for TTS before starting NC. If no TTS is detected within this window the NC filter activates immediately. Only used when tts_model_path is set.

Raises:

  • ValueError – If model_path is not provided and KRISP_VIVA_FILTER_MODEL_PATH is not set.

  • Exception – If a model file doesn’t have .kef extension.

  • FileNotFoundError – If a model file doesn’t exist.

  • RuntimeError – If Krisp SDK initialization fails.

async start(sample_rate: int)[source]

Initialize the Krisp processor with the transport’s sample rate.

Parameters:

sample_rate – The sample rate of the input transport in Hz.

async stop()[source]

Release the Krisp processor and its SDK reference.

The SDK release is guarded so repeated calls do not over-decrement the shared reference count.

async process_frame(frame: FilterControlFrame)[source]

Process control frames to enable/disable filtering.

Parameters:

frame – The control frame containing filter commands.

async filter(audio: bytes) → bytes[source]

Apply Krisp noise reduction to audio data.

When TTS detection is enabled the audio passes through unmodified until TTS is no longer present (or the detection timeout expires), after which noise cancellation activates for the remainder of the session.

Parameters:

audio – Raw audio data as bytes to be filtered.

Returns:

Noise-reduced audio data as bytes, or the original audio while in the TTS detection phase.