user_turn_controller

This module defines a controller for managing user turn lifecycle.

class pipecat.turns.user_turn_controller.UserTurnController(*, user_turn_strategies: UserTurnStrategies, user_turn_stop_timeout: float = 5.0)

Bases: BaseObject

Controller for managing user turn lifecycle.

This class manages user turn state (active/inactive), handles start and stop strategies, and emits events when user turns begin, end, or timeout occurs.

Event handlers available:

• on_user_turn_started: Emitted when a user turn starts.

• on_user_turn_stopped: Emitted when a user turn stops.

• on_user_turn_stop_timeout: Emitted if no stop strategy triggers before timeout.

• on_push_frame: Emitted when a strategy wants to push a frame.

• on_broadcast_frame: Emitted when a strategy wants to broadcast a frame.

Example:

@controller.event_handler("on_user_turn_started")
async def on_user_turn_started(controller, strategy: BaseUserTurnStartStrategy, params: UserTurnStartedParams):
    ...

@controller.event_handler("on_user_turn_stopped")
async def on_user_turn_stopped(controller, strategy: BaseUserTurnStopStrategy, params: UserTurnStoppedParams):
    ...

@controller.event_handler("on_user_turn_stop_timeout")
async def on_user_turn_stop_timeout(controller):
    ...

@controller.event_handler("on_push_frame")
async def on_push_frame(controller, frame: Frame, direction: FrameDirection):
    ...

@controller.event_handler("on_broadcast_frame")
async def on_broadcast_frame(controller, frame_cls: Type[Frame], **kwargs):
    ...

__init__(*, user_turn_strategies: UserTurnStrategies, user_turn_stop_timeout: float = 5.0)

Initialize the user turn controller.

Parameters:

• user_turn_strategies – Configured strategies for starting and stopping user turns.

• user_turn_stop_timeout – Timeout in seconds to automatically stop a user turn if no activity is detected.

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 update_strategies(strategies: UserTurnStrategies)

Replace the current strategies with the given ones.

Parameters:

strategies – The new user turn strategies the controller should use.

async process_frame(frame: Frame)

Process an incoming frame to detect user turn start or stop.

The frame is passed to the configured user turn strategies, which are responsible for deciding when a user turn starts or stops and emitting the corresponding events.

Parameters:

frame – The frame to be processed.