Pipeline Idle Detection

Overview

Pipeline idle detection monitors activity in your pipeline and can automatically cancel tasks when no meaningful interactions are occurring. This helps prevent pipelines from running indefinitely when a conversation has naturally ended but wasn’t properly terminated.

How It Works

The system monitors specific “activity frames” that indicate the bot is actively engaged in the conversation. By default, these are:

BotSpeakingFrame - When the bot is speaking
UserSpeakingFrame - When the user is speaking (from VAD)
UserStartedSpeakingFrame - When a user turn starts
InterimTranscriptionFrame and TranscriptionFrame - When the user’s speech is transcribed, for pipelines where the provider detects turns instead of VAD

If no activity frames are detected within the configured timeout period (5 minutes by default), the system considers the pipeline idle and can automatically terminate it.

Idle detection only starts after the pipeline has begun processing frames. The idle timer resets whenever an activity frame (as specified in idle_timeout_frames) is received.

Configuration

You can configure idle detection behavior when creating a PipelineWorker:

from pipecat.frames.frames import BotSpeakingFrame
from pipecat.pipeline.worker import PipelineParams, PipelineWorker

# Default configuration - cancel after 5 minutes of inactivity
worker = PipelineWorker(pipeline)

# Custom configuration
worker = PipelineWorker(
    pipeline,
    idle_timeout_secs=600,  # 10 minute timeout
    idle_timeout_frames=(BotSpeakingFrame,),  # Only monitor bot speaking
    cancel_on_idle_timeout=False,  # Don't auto-cancel, just notify
)

Configuration Parameters

float | None

default:"300"

Timeout in seconds before considering the pipeline idle. Set to None to disable idle detection.

tuple[type[Frame], ...]

Frame types that should prevent the pipeline from being considered idle.

bool

default:"True"

Whether to automatically cancel the pipeline worker when idle timeout is reached. With the default cancel_runner_on_idle_timeout=True, this also cancels the WorkerRunner and every other worker in it; see PipelineWorker.

Handling Idle Timeouts

You can respond to idle timeout events by adding an event handler:

@worker.event_handler("on_idle_timeout")
async def on_idle_timeout(worker):
    logger.info("Pipeline has been idle for too long")
    # Perform any custom cleanup or logging
    # Note: If cancel_on_idle_timeout=True, the pipeline is cancelled, so frames queued here are not heard

Example Implementation

Here’s a complete example showing how to configure idle detection with custom handling:

from pipecat.frames.frames import EndFrame, TTSSpeakFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.workers.runner import WorkerRunner
from pipecat.pipeline.worker import PipelineWorker

# Create pipeline
pipeline = Pipeline([...])

# Configure worker with custom idle settings
worker = PipelineWorker(
    pipeline,
    idle_timeout_secs=180,  # 3 minutes
    cancel_on_idle_timeout=False  # Don't auto-cancel
)

# Add event handler for idle timeout
@worker.event_handler("on_idle_timeout")
async def on_idle_timeout(worker):
    logger.info("Conversation has been idle for 3 minutes")

    # Add a farewell message
    await worker.queue_frame(TTSSpeakFrame("I haven't heard from you in a while. Goodbye!"))

    # Then end the conversation gracefully
    await worker.queue_frame(EndFrame())

runner = WorkerRunner()

await runner.add_workers(worker)
await runner.run()

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Pipeline Idle Detection

Overview

How It Works

Configuration

Configuration Parameters

Handling Idle Timeouts

Example Implementation

​Overview

​How It Works

​Configuration

​Configuration Parameters

​Handling Idle Timeouts

​Example Implementation

Overview

How It Works

Configuration

Configuration Parameters

Handling Idle Timeouts

Example Implementation