user_turn_processor

Frame processor for managing the user turn lifecycle.

class pipecat.turns.user_turn_processor.UserTurnProcessor(*, user_turn_strategies: UserTurnStrategies | None = None, user_turn_stop_timeout: float = 5.0, user_idle_timeout: float = 0, **kwargs)

Bases: FrameProcessor

Frame processor for managing the user turn lifecycle.

This processor uses a turn controller to determine when a user turn starts or stops. The actual frames emitted (e.g., UserStartedSpeakingFrame, UserStoppedSpeakingFrame) or interruptions depend on the configured strategies.

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_user_turn_idle: Emitted when the user has been idle for the configured timeout.

Example:

@processor.event_handler("on_user_turn_started")
async def on_user_turn_started(processor, strategy: BaseUserTurnStartStrategy):
    ...

@processor.event_handler("on_user_turn_stopped")
async def on_user_turn_stopped(processor, strategy: BaseUserTurnStopStrategy):
    ...

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

@processor.event_handler("on_user_turn_idle")
async def on_user_turn_idle(processor):
    ...

__init__(*, user_turn_strategies: UserTurnStrategies | None = None, user_turn_stop_timeout: float = 5.0, user_idle_timeout: float = 0, **kwargs)

Initialize the user turn processor.

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.

• user_idle_timeout – Timeout in seconds for detecting user idle state. The processor will emit an on_user_turn_idle event when the user has been idle (not speaking) for this duration. Set to 0 to disable idle detection.

• **kwargs – Additional keyword arguments.

async cleanup()

Clean up processor resources.

async process_frame(frame: Frame, direction: FrameDirection)

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

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

Parameters:

• frame – The frame to be processed.

• direction – The direction of the incoming frame.