Turn Tracking Observer

The TurnTrackingObserver monitors and tracks conversational turns in your Pipecat pipeline, providing events when turns start and end. It intelligently identifies when a user-bot interaction cycle begins and completes.

Turn Lifecycle

A turn represents a complete user-bot interaction cycle:

Start: When the user starts speaking (or pipeline starts for first turn)
Processing: User speaks, bot processes and responds
End: After the bot finishes speaking and either:
- The user starts speaking again
- A timeout period elapses with no further activity

If the pipeline ends (EndFrame or CancelFrame) while a turn is active, that turn ends with was_interrupted=True.

Events

The observer emits two main events:

on_turn_started: When a new turn begins
- Parameters: turn_number (int)
on_turn_ended: When a turn completes
- Parameters: turn_number (int), duration (float, in seconds), was_interrupted (bool)

Usage

The observer is automatically created when you initialize a PipelineWorker with enable_turn_tracking=True (which is the default):

from pipecat.pipeline.worker import PipelineWorker

worker = PipelineWorker(
    pipeline,
    # Turn tracking is enabled by default
)

# Access the observer
turn_observer = worker.turn_tracking_observer

# Register event handlers
@turn_observer.event_handler("on_turn_started")
async def on_turn_started(observer, turn_number):
    logger.info(f"Turn {turn_number} started")

@turn_observer.event_handler("on_turn_ended")
async def on_turn_ended(observer, turn_number, duration, was_interrupted):
    status = "interrupted" if was_interrupted else "completed"
    logger.info(f"Turn {turn_number} {status} in {duration:.2f}s")

Configuration

To configure the observer, create a TurnTrackingObserver yourself and pass it in the observers list of PipelineWorker:

float

default:"2.5"

Timeout in seconds after bot stops speaking before automatically ending the turn.

int | None

default:"None"

deprecated

Deprecated since 1.12.0, removed in 2.0.0. No replacement. The observer receives each frame once.

from pipecat.observers.turn_tracking_observer import TurnTrackingObserver

# Create a custom observer instance
custom_turn_tracker = TurnTrackingObserver(
    turn_end_timeout_secs=3.5,     # Turn end timeout (default: 2.5)
)

# Add it as a regular observer
worker = PipelineWorker(
    pipeline,
    observers=[custom_turn_tracker],
    # Disable the default one if adding your own
    enable_turn_tracking=False,
)

Interruptions

The observer automatically detects interruptions when the user starts speaking while the bot is still speaking. In this case:

The current turn is marked as interrupted (was_interrupted=True)
A new turn begins immediately

How It Works

The observer monitors specific frame types to track conversation flow:

StartFrame: Initiates the first turn
UserStartedSpeakingFrame: Starts user speech or triggers a new turn
BotStartedSpeakingFrame: Marks bot speech beginning
BotStoppedSpeakingFrame: Starts the turn end timeout

After a bot stops speaking, the observer waits for the configured timeout period. If no further bot speech occurs, the turn ends; otherwise, it continues as part of the same turn.

Use Cases

Analytics: Measure turn durations, interruption rates, and conversation flow
Logging: Record turn-based logs for diagnostics and analysis
Visualization: Show turn-based conversation timelines in UIs
Tracing: Group spans and metrics by conversation turns

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Turn Tracking Observer

Turn Lifecycle

Events

Usage

Configuration

Interruptions

How It Works

Use Cases

​Turn Lifecycle

​Events

​Usage

​Configuration

​Interruptions

​How It Works

​Use Cases

Turn Lifecycle

Events

Usage

Configuration

Interruptions

How It Works

Use Cases