user_idle_controller

This module defines a controller for managing user idle detection.

class pipecat.turns.user_idle_controller.UserIdleController(*, user_idle_timeout: float = 0)

Bases: BaseObject

Controller for managing user idle detection.

This class monitors user activity and triggers an event when the user has been idle (not speaking) for a configured timeout period after the bot finishes speaking. The timer starts when BotStoppedSpeakingFrame is received and is cancelled when someone starts speaking again (UserStartedSpeakingFrame or BotStartedSpeakingFrame).

The timer is suppressed while a user turn is in progress to avoid false triggers during interruptions (where BotStoppedSpeakingFrame arrives while the user is still speaking).

Event handlers available:

• on_user_turn_idle: Emitted when the user has been idle for the timeout period.

Example:

@controller.event_handler("on_user_turn_idle")
async def on_user_turn_idle(controller):
    # Handle user idle - send reminder, prompt, etc.
    ...

__init__(*, user_idle_timeout: float = 0)

Initialize the user idle controller.

Parameters:

user_idle_timeout – Timeout in seconds before considering the user idle. 0 disables idle detection.

property task_manager: BaseTaskManager

Returns the configured task manager.

async setup(task_manager: BaseTaskManager)

Initialize the controller with the given task manager.

Parameters:

task_manager – The task manager to be associated with this instance.

async cleanup()

Cleanup the controller.

async process_frame(frame: Frame)

Process an incoming frame to track user activity state.

Parameters:

frame – The frame to be processed.