Skip to main content

Overview

AICTytoObserver scores the quality of the user’s audio with the ai-coustics Tyto model. It analyzes the latest 5-second window in a background thread after every 5 seconds of received audio, and emits each result through on_analysis_result. When the call ends, it emits a summary through on_call_summary.

AIC Tyto Observer API Reference

Pipecat’s API methods for the Tyto observer

Example Implementation

Complete example with AICFilter and AICTytoObserver

ai-coustics Documentation

ai-coustics Pipecat quickstart and model guides

ai-coustics Models

Browse available Tyto and Quail models

Installation

Prerequisites

You need an ai-coustics license key. Get one at developers.ai-coustics.io.

Required Environment Variables

  • AIC_SDK_LICENSE: Your ai-coustics SDK license key

Configuration

str
required
ai-coustics SDK license key.
str | None
default:"\"tyto-1.1-l-16khz\""
Tyto model identifier. Ignored if model_path is set. See artifacts.ai-coustics.io for available models.
Path | None
default:"None"
Path to a local .aicmodel file.
Path | None
default:"None"
Directory for downloaded models. Defaults to ~/.cache/pipecat/aic-models.
float
default:"0.3"
risk_score value at or above which the summary counts a window as degraded. Must be between 0.0 and 1.0. Calibrate it against the failures you see in your application.
AICFilter | None
default:"None"
The transport’s AICFilter. When set, the filter feeds the analysis with the audio before enhancement. When None, the observer analyzes the InputAudioRawFrame audio that the input transport pushes.
Raises ValueError when neither model_id nor model_path is set, or when degraded_threshold is outside 0.0 to 1.0.

Usage

Scoring Audio Before Enhancement

Tyto must score the audio before enhancement. When AICFilter is the transport’s audio_in_filter, pass the same filter as audio_filter:
Without an AICFilter on the transport, leave out audio_filter and the observer analyzes the input audio frames directly.

Notes

  • One filter per session: The observer attaches itself to audio_filter and the filter holds one attachment at a time, so create a new AICFilter and observer for each session rather than sharing a filter between sessions.
  • First result: The first analysis waits for a full 5-second window, so calls with less than 5 seconds of user audio emit no results.
  • Model load failure: If the model fails to load, the observer logs an error and the call continues without analysis.
  • Analysis failure: If an analysis fails, the observer logs an error and stops analyzing for the rest of the call.
  • Filter initialization: When audio_filter is set and the filter fails to initialize, it passes audio through unenhanced and the observer analyzes nothing.

Event Handlers

AICAudioQualityScores

All scores are in the range 0.0 to 1.0. A higher value means more problematic audio.

AICAudioQualitySummary