wake_phrase_user_turn_start_strategy

User turn start strategy that gates interaction behind wake phrase detection.

class pipecat.turns.user_start.wake_phrase_user_turn_start_strategy.WakePhraseUserTurnStartStrategy(*, phrases: list[str], timeout: float = 10.0, single_activation: bool = False, **kwargs)

Bases: BaseUserTurnStartStrategy

User turn start strategy that requires a wake phrase before interaction.

Blocks subsequent strategies until a wake phrase is detected in a final transcription. After detection, allows interaction for a configurable timeout period before requiring the wake phrase again. Use single_activation=True to require the wake phrase before every turn.

This strategy should be placed first in the start strategies list.

Event handlers available:

• on_wake_phrase_detected: Called when a wake phrase is matched.

• on_wake_phrase_timeout: Called when the inactivity timeout expires (timeout mode only).

Example:

# Timeout mode (default): wake phrase unlocks interaction for 10s
strategy = WakePhraseUserTurnStartStrategy(
    phrases=["hey pipecat", "ok pipecat"],
    timeout=10.0,
)

# Single activation: wake phrase required before every turn
strategy = WakePhraseUserTurnStartStrategy(
    phrases=["hey pipecat"],
    single_activation=True,
)

@strategy.event_handler("on_wake_phrase_detected")
async def on_wake_phrase_detected(strategy, phrase):
    ...

@strategy.event_handler("on_wake_phrase_timeout")
async def on_wake_phrase_timeout(strategy):
    ...

Parameters:

• phrases – List of wake phrases to detect.

• timeout – Inactivity timeout in seconds before returning to IDLE. In timeout mode, the timer resets on activity (user, bot speech). In single activation mode, acts as a keepalive window — the strategy stays AWAKE for this duration after wake phrase detection, allowing the current turn to complete before returning to IDLE.

• single_activation – If True, the wake phrase is required before every turn. The strategy returns to IDLE after each turn completes.

• **kwargs – Additional keyword arguments passed to parent.

__init__(*, phrases: list[str], timeout: float = 10.0, single_activation: bool = False, **kwargs)

Initialize the wake phrase user turn start strategy.

Parameters:

• phrases – List of wake phrases to detect.

• timeout – Inactivity timeout in seconds before returning to IDLE. In timeout mode, the timer resets on activity. In single activation mode, acts as a keepalive window after wake phrase detection.

• single_activation – If True, the wake phrase is required before every turn. The strategy returns to IDLE after each turn completes.

• **kwargs – Additional keyword arguments passed to parent.

property state: _WakeState

Returns the current wake state.

async setup(task_manager: BaseTaskManager)

Initialize the strategy with the given task manager.

Parameters:

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

async cleanup()

Cleanup the strategy.

async reset()

Reset the strategy.

In timeout mode, preserves state and refreshes timeout since reset means a turn started (activity). In single activation mode, does nothing — the keepalive timeout (started when the wake phrase was detected) handles the transition back to IDLE.

async process_frame(frame: Frame) → ProcessFrameResult

Process an incoming frame for wake phrase detection or passthrough.

Parameters:

frame – The frame to be processed.

Returns:

STOP when the wake phrase is detected or when in IDLE state (blocks subsequent strategies), CONTINUE when in AWAKE state (allows subsequent strategies to proceed).