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.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. WhenAICFilter is the transport’s audio_in_filter, pass the same filter as audio_filter:
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_filterand the filter holds one attachment at a time, so create a newAICFilterand 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_filteris 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 range0.0 to 1.0. A higher value means more problematic audio.