Smart Turn Detection
Advanced conversational turn detection powered by the smart-turn model
Overview
Smart Turn Detection is an advanced feature in Pipecat that determines when a user has finished speaking and the bot should respond. Unlike basic Voice Activity Detection (VAD) which only detects speech vs. non-speech, Smart Turn Detection uses a machine learning model to recognize natural conversational cues like intonation patterns and linguistic signals.
Smart Turn Model
Open source model for advanced conversational turn detection. Contribute to model training and development.
Pipecat provides three implementations of Smart Turn Detection:
- FalSmartTurnAnalyzer - Uses a Fal’s hosted smart-turn model for inference
- LocalCoreMLSmartTurnAnalyzer - Runs inference locally on Apple Silicon using CoreML
- LocalSmartTurnAnalyzer - Runs inference locally using PyTorch and Hugging Face Transformers
All implementations share the same underlying API and parameters, making it easy to switch between them based on your deployment requirements.
Installation
The Smart Turn Detection feature requires additional dependencies depending on which implementation you choose.
For Fal’s hosted service inference:
For local inference (CoreML-based):
For local inference (PyTorch-based):
Integration with Transport
Smart Turn Detection is integrated into your application by setting one of the available turn analyzers as the turn_analyzer
parameter in your transport configuration:
Smart Turn Detection requires VAD to be enabled and works best when the VAD analyzer is set to a short stop_secs
value. We recommend 0.2 seconds.
Configuration
All implementations use the same SmartTurnParams
class to configure behavior:
Duration of silence in seconds required before triggering a silence-based end of turn
Amount of audio (in milliseconds) to include before speech is detected
Maximum allowed segment duration in seconds. For segments longer than this value, a rolling window is used.
Remote Smart Turn
The FalSmartTurnAnalyzer
class uses a remote service for turn detection inference.
Constructor Parameters
The URL of the remote Smart Turn service
Audio sample rate (will be set by the transport if not provided)
Configuration parameters for turn detection
Example
Local Smart Turn (CoreML)
The LocalCoreMLSmartTurnAnalyzer
runs inference locally using CoreML, providing lower latency and no network dependencies.
Constructor Parameters
Path to the directory containing the Smart Turn model
Audio sample rate (will be set by the transport if not provided)
Configuration parameters for turn detection
Example
Local Smart Turn (PyTorch)
The LocalSmartTurnAnalyzer
runs inference locally using PyTorch and Hugging Face Transformers, providing a cross-platform solution.
Constructor Parameters
Path to the Smart Turn model or Hugging Face model identifier. Defaults to the official “pipecat-ai/smart-turn” model.
Audio sample rate (will be set by the transport if not provided)
Configuration parameters for turn detection
Example
Local Model Setup
CoreML Model & PyTorch Setup
To use the LocalCoreMLSmartTurnAnalyzer
or LocalSmartTurnAnalyzer
, you need to set up the model locally:
-
Install Git LFS (Large File Storage):
-
Initialize Git LFS
-
Clone the Smart Turn model repository:
-
Set the environment variable to the cloned repository path:
Note that the CoreML model is optimized for Apple Silicon devices. If you’re using a different platform, consider using the PyTorch-based LocalSmartTurnAnalyzer
or the remote Smart Turn service.
Learn more about the CoreML setup in the official repository instructions
How It Works
Smart Turn Detection continuously analyzes audio streams to identify natural turn completion points:
-
Audio Buffering: The system continuously buffers audio with timestamps, maintaining a small buffer of pre-speech audio.
-
VAD Processing: Voice Activity Detection segments the audio into speech and non-speech portions.
-
Turn Analysis: When VAD detects a pause in speech:
- The ML model analyzes the speech segment for natural completion cues
- It identifies acoustic and linguistic patterns that indicate turn completion
- A decision is made whether the turn is complete or incomplete
The system includes a fallback mechanism: if a turn is classified as incomplete but silence continues for longer than stop_secs
, the turn is automatically marked as complete.
Notes
- The model is designed for English speech; performance may vary with other languages
- You can adjust the
stop_secs
parameter based on your application’s needs for responsiveness - Smart Turn generally provides a more natural conversational experience but is computationally more intensive than simple VAD
- The PyTorch-based
LocalSmartTurnAnalyzer
runs on CPU by default but will use CUDA if available