@pipedog/core 0.0.0 → 0.2.0

package/dist/turns/user_start/krisp_viva_ip_user_turn_start_strategy.js

@@ -0,0 +1,243 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_start/krisp_viva_ip_user_turn_start_strategy.py
+/**
+ * User turn start strategy using Krisp Interruption Prediction (IP).
+ *
+ * This strategy uses Krisp's IP model to distinguish genuine user interruptions
+ * from backchannels (e.g. "uh-huh", "yeah"). Instead of triggering a user turn
+ * on every VAD speech event, it collects audio after VAD detects speech and runs
+ * the IP model to predict whether the speech is a real interruption.
+ *
+ * Only when the IP model's probability exceeds the configured threshold is
+ * `triggerUserTurnStarted()` called. This prevents the bot from being
+ * interrupted by brief acknowledgements or filler words.
+ *
+ * PARTIAL PORT: the Krisp SDK (`krisp_audio`) is a native Python module with no
+ * runtime-agnostic JS equivalent. The strategy logic is ported; creating the IP
+ * session (`_createIpSession`) is a stub that throws "not ported yet".
+ * Subclasses (or tests) can override it to supply a `KrispIpSession`.
+ */
+import { rethrowIfCancelled } from "@pipedog/asyncio";
+import { intToKrispFrameDuration, intToKrispSampleRate, KrispVivaSDKManager, } from "../../audio/krisp_instance.js";
+import { BotStoppedSpeakingFrame, InputAudioRawFrame, VADUserStartedSpeakingFrame, VADUserStoppedSpeakingFrame, } from "../../frames/frames.js";
+import { getEnv } from "../../utils/env.js";
+import { logger } from "../../utils/logger.js";
+import { ProcessFrameResult } from "../types.js";
+import { BaseUserTurnStartStrategy, } from "./base_user_turn_start_strategy.js";
+/**
+ * User turn start strategy using Krisp VIVA Interruption Prediction.
+ *
+ * When VAD detects user speech, this strategy feeds audio frames into
+ * the Krisp VIVA IP model. The model outputs a probability indicating
+ * whether the speech is a genuine interruption (as opposed to a
+ * backchannel). A user turn is triggered only when this probability
+ * exceeds the configured threshold.
+ *
+ * This strategy is designed to work alongside other start strategies
+ * (e.g. `TranscriptionUserTurnStartStrategy` as a fallback) via the
+ * strategy list in `UserTurnStrategies`.
+ *
+ * @example
+ * const strategies = new UserTurnStrategies({
+ *   start: [
+ *     new KrispVivaIPUserTurnStartStrategy({
+ *       modelPath: "/path/to/ip_model.kef",
+ *       threshold: 0.5,
+ *     }),
+ *     new TranscriptionUserTurnStartStrategy(),
+ *   ],
+ * });
+ */
+export class KrispVivaIPUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    _threshold;
+    _frameDurationMs;
+    _apiKey;
+    _modelPath;
+    _sdkAcquired = false;
+    _ipSession = null;
+    _samplesPerFrame = null;
+    _sampleRate = null;
+    // State tracking
+    _speechActive = false;
+    _audioBuffer = new Uint8Array(0);
+    _decisionMade = false;
+    constructor(options = {}) {
+        super(options);
+        this._threshold = options.threshold ?? 0.5;
+        this._frameDurationMs = options.frameDurationMs ?? 20;
+        this._apiKey = options.apiKey ?? "";
+        const modelPath = options.modelPath || getEnv("KRISP_VIVA_IP_MODEL_PATH");
+        if (!modelPath) {
+            throw new Error("IP model path must be provided via model_path or " +
+                "KRISP_VIVA_IP_MODEL_PATH environment variable.");
+        }
+        if (!modelPath.endsWith(".kef")) {
+            throw new Error("Model is expected with .kef extension");
+        }
+        // Upstream also checks that the file exists; core has no filesystem
+        // access, so that check is left to the Krisp runtime that loads it.
+        this._modelPath = modelPath;
+        // Acquire SDK
+        try {
+            KrispVivaSDKManager.acquire(this._apiKey);
+            this._sdkAcquired = true;
+        }
+        catch (e) {
+            rethrowIfCancelled(e);
+            throw new Error(`Failed to initialize Krisp SDK: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+    }
+    /** Release Krisp SDK resources. */
+    async cleanup() {
+        if (this._sdkAcquired) {
+            try {
+                this._ipSession = null;
+                KrispVivaSDKManager.release();
+                this._sdkAcquired = false;
+            }
+            catch (e) {
+                rethrowIfCancelled(e);
+                logger.error(`Error cleaning up Krisp VIVA IP strategy: ${e instanceof Error ? e.message : String(e)}`, e);
+            }
+        }
+    }
+    /**
+     * Create a Krisp IP session for the given sample rate.
+     *
+     * STUB: needs the Krisp SDK (`krisp_audio.IpFloat.create`), which has no JS
+     * equivalent yet. Override to supply a session.
+     */
+    _createIpSession(sampleRate) {
+        // Validate the configuration as the SDK config would.
+        intToKrispSampleRate(sampleRate);
+        intToKrispFrameDuration(this._frameDurationMs);
+        throw new Error(`not ported yet: Krisp VIVA IP session (model ${this._modelPath}) requires the Krisp SDK`);
+    }
+    /**
+     * Create or re-create the IP session when sample rate changes.
+     *
+     * @param sampleRate Audio sample rate in Hz.
+     */
+    _ensureSession(sampleRate) {
+        if (this._sampleRate === sampleRate && this._ipSession !== null) {
+            return;
+        }
+        this._sampleRate = sampleRate;
+        this._samplesPerFrame = Math.trunc((sampleRate * this._frameDurationMs) / 1000);
+        this._ipSession = this._createIpSession(sampleRate);
+        logger.debug(`Krisp VIVA IP session created (sample_rate=${sampleRate})`);
+    }
+    /** Reset speech tracking state for the next candidate interruption. */
+    _resetState() {
+        this._speechActive = false;
+        this._audioBuffer = new Uint8Array(0);
+        this._decisionMade = false;
+    }
+    /** Ready the strategy for a new user turn. */
+    async handleUserTurnStarted() {
+        this._resetState();
+    }
+    /**
+     * Process a frame to detect genuine user interruptions.
+     *
+     * On `VADUserStartedSpeakingFrame`, begins collecting audio.
+     * On `InputAudioRawFrame`, feeds audio through the IP model and
+     * triggers a user turn if the interruption probability exceeds the
+     * threshold.
+     * On `VADUserStoppedSpeakingFrame` or `BotStoppedSpeakingFrame`,
+     * resets the candidate state.
+     *
+     * @param frame The incoming frame.
+     * @returns STOP if a genuine interruption was detected, CONTINUE otherwise.
+     */
+    async processFrame(frame) {
+        if (frame instanceof VADUserStartedSpeakingFrame) {
+            return await this._handleVadStarted(frame);
+        }
+        else if (frame instanceof InputAudioRawFrame) {
+            return await this._handleAudio(frame);
+        }
+        else if (frame instanceof VADUserStoppedSpeakingFrame ||
+            frame instanceof BotStoppedSpeakingFrame) {
+            return await this._handleReset(frame);
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+    /**
+     * Begin collecting audio for interruption classification.
+     *
+     * @returns Always CONTINUE; the decision is deferred until enough audio is processed.
+     */
+    async _handleVadStarted(_frame) {
+        logger.trace("Krisp VIVA IP: VAD speech started, collecting audio for classification");
+        this._speechActive = true;
+        this._decisionMade = false;
+        return ProcessFrameResult.CONTINUE;
+    }
+    /**
+     * Feed audio to the IP model and check for genuine interruption.
+     *
+     * Every frame is passed to the IP model regardless of speech state so
+     * that the model maintains continuous internal state (matching the
+     * standalone Krisp SDK behaviour). `_speechActive` is forwarded as
+     * the per-frame VAD input to the model and also gates the threshold
+     * evaluation.
+     *
+     * @param frame Raw audio input frame.
+     * @returns STOP if the model detects a genuine interruption, CONTINUE otherwise.
+     */
+    async _handleAudio(frame) {
+        this._ensureSession(frame.sampleRate);
+        if (this._ipSession === null || this._samplesPerFrame === null) {
+            logger.warning("IP session not ready, skipping frame");
+            return ProcessFrameResult.CONTINUE;
+        }
+        const buffer = new Uint8Array(this._audioBuffer.length + frame.audio.length);
+        buffer.set(this._audioBuffer, 0);
+        buffer.set(frame.audio, this._audioBuffer.length);
+        this._audioBuffer = buffer;
+        const totalSamples = Math.floor(this._audioBuffer.length / 2); // 2 bytes per int16 sample
+        const numCompleteFrames = Math.floor(totalSamples / this._samplesPerFrame);
+        if (numCompleteFrames === 0) {
+            return ProcessFrameResult.CONTINUE;
+        }
+        const completeSamplesCount = numCompleteFrames * this._samplesPerFrame;
+        const bytesToProcess = completeSamplesCount * 2;
+        // Copy so the Int16Array view is aligned regardless of the buffer offset.
+        const audioToProcess = this._audioBuffer.slice(0, bytesToProcess);
+        this._audioBuffer = this._audioBuffer.slice(bytesToProcess);
+        const audioInt16 = new Int16Array(audioToProcess.buffer, 0, completeSamplesCount);
+        const audioFloat32 = new Float32Array(completeSamplesCount);
+        for (let i = 0; i < completeSamplesCount; i++) {
+            audioFloat32[i] = audioInt16[i] / 32768.0;
+        }
+        for (let f = 0; f < numCompleteFrames; f++) {
+            const ipFrame = audioFloat32.subarray(f * this._samplesPerFrame, (f + 1) * this._samplesPerFrame);
+            const ipProb = this._ipSession.process(ipFrame, this._speechActive);
+            if (this._speechActive && !this._decisionMade && ipProb >= this._threshold) {
+                logger.debug(`Krisp VIVA IP: genuine interruption detected (prob=${ipProb.toFixed(3)}, ` +
+                    `threshold=${this._threshold})`);
+                this._decisionMade = true;
+                await this.triggerUserTurnStarted();
+                return ProcessFrameResult.STOP;
+            }
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+    /**
+     * Reset state when the candidate interruption window ends.
+     *
+     * @returns Always CONTINUE.
+     */
+    async _handleReset(_frame) {
+        if (this._speechActive) {
+            logger.trace("Krisp VIVA IP: speech segment ended, resetting state");
+            this._resetState();
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+}
+//# sourceMappingURL=krisp_viva_ip_user_turn_start_strategy.js.map

package/dist/turns/user_start/min_words_user_turn_start_strategy.d.ts

@@ -0,0 +1,60 @@
+/** User turn start strategy based on a minimum number of words spoken by the user. */
+import { BotStartedSpeakingFrame, BotStoppedSpeakingFrame, type Frame, InterimTranscriptionFrame, TranscriptionFrame } from "../../frames/frames.ts";
+import { ProcessFrameResult } from "../types.ts";
+import { BaseUserTurnStartStrategy, type BaseUserTurnStartStrategyOptions } from "./base_user_turn_start_strategy.ts";
+export interface MinWordsUserTurnStartStrategyOptions extends BaseUserTurnStartStrategyOptions {
+    /** Minimum number of spoken words required to trigger the start of a user turn. */
+    minWords: number;
+    /** Whether to consider interim transcription frames for earlier detection. */
+    useInterim?: boolean;
+}
+/**
+ * User turn start strategy based on a minimum number of words spoken by the user.
+ *
+ * This strategy signals the start of a user turn once the user has spoken at
+ * least a specified number of words, as determined from transcription frames.
+ * Optionally, interim transcriptions can be used for earlier detection.
+ */
+export declare class MinWordsUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    protected _minWords: number;
+    protected _useInterim: boolean;
+    protected _botSpeaking: boolean;
+    constructor(options: MinWordsUserTurnStartStrategyOptions);
+    /**
+     * Ready the strategy for a new user turn.
+     *
+     * Clears the bot-speaking flag so the next turn's word counting starts
+     * from the single-word interruption threshold.
+     */
+    handleUserTurnStarted(): Promise<void>;
+    /**
+     * Process an incoming frame to detect the start of a user turn.
+     *
+     * This method updates internal state based on transcription frames and
+     * triggers the user turn once the minimum word count is reached.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns STOP if the minimum word count was reached, CONTINUE otherwise.
+     */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+    /**
+     * Handle bot started speaking frame.
+     *
+     * If the bot is speaking we want to interrupt using min words.
+     */
+    protected _handleBotStartedSpeaking(_frame: BotStartedSpeakingFrame): Promise<void>;
+    /**
+     * Handle bot stopped speaking frame.
+     *
+     * If the bot is not speaking we want to interrupt if we get a single word.
+     */
+    protected _handleBotStoppedSpeaking(_frame: BotStoppedSpeakingFrame): Promise<void>;
+    /**
+     * Handle a transcription frame and check word count.
+     *
+     * @param frame The transcription frame to be processed.
+     * @returns STOP if the minimum word count was reached, CONTINUE otherwise.
+     */
+    protected _handleTranscription(frame: TranscriptionFrame | InterimTranscriptionFrame): Promise<ProcessFrameResult>;
+}
+//# sourceMappingURL=min_words_user_turn_start_strategy.d.ts.map

package/dist/turns/user_start/min_words_user_turn_start_strategy.js

@@ -0,0 +1,102 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_start/min_words_user_turn_start_strategy.py
+/** User turn start strategy based on a minimum number of words spoken by the user. */
+import { BotStartedSpeakingFrame, BotStoppedSpeakingFrame, InterimTranscriptionFrame, TranscriptionFrame, } from "../../frames/frames.js";
+import { logger } from "../../utils/logger.js";
+import { ProcessFrameResult } from "../types.js";
+import { BaseUserTurnStartStrategy, } from "./base_user_turn_start_strategy.js";
+/**
+ * User turn start strategy based on a minimum number of words spoken by the user.
+ *
+ * This strategy signals the start of a user turn once the user has spoken at
+ * least a specified number of words, as determined from transcription frames.
+ * Optionally, interim transcriptions can be used for earlier detection.
+ */
+export class MinWordsUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    _minWords;
+    _useInterim;
+    _botSpeaking = false;
+    constructor(options) {
+        super(options);
+        this._minWords = options.minWords;
+        this._useInterim = options.useInterim ?? true;
+    }
+    /**
+     * Ready the strategy for a new user turn.
+     *
+     * Clears the bot-speaking flag so the next turn's word counting starts
+     * from the single-word interruption threshold.
+     */
+    async handleUserTurnStarted() {
+        this._botSpeaking = false;
+    }
+    /**
+     * Process an incoming frame to detect the start of a user turn.
+     *
+     * This method updates internal state based on transcription frames and
+     * triggers the user turn once the minimum word count is reached.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns STOP if the minimum word count was reached, CONTINUE otherwise.
+     */
+    async processFrame(frame) {
+        if (frame instanceof BotStartedSpeakingFrame) {
+            await this._handleBotStartedSpeaking(frame);
+        }
+        else if (frame instanceof BotStoppedSpeakingFrame) {
+            await this._handleBotStoppedSpeaking(frame);
+        }
+        else if (frame instanceof TranscriptionFrame) {
+            return await this._handleTranscription(frame);
+        }
+        else if (frame instanceof InterimTranscriptionFrame && this._useInterim) {
+            return await this._handleTranscription(frame);
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+    /**
+     * Handle bot started speaking frame.
+     *
+     * If the bot is speaking we want to interrupt using min words.
+     */
+    async _handleBotStartedSpeaking(_frame) {
+        this._botSpeaking = true;
+    }
+    /**
+     * Handle bot stopped speaking frame.
+     *
+     * If the bot is not speaking we want to interrupt if we get a single word.
+     */
+    async _handleBotStoppedSpeaking(_frame) {
+        this._botSpeaking = false;
+    }
+    /**
+     * Handle a transcription frame and check word count.
+     *
+     * @param frame The transcription frame to be processed.
+     * @returns STOP if the minimum word count was reached, CONTINUE otherwise.
+     */
+    async _handleTranscription(frame) {
+        const minWords = this._botSpeaking ? this._minWords : 1;
+        // Python's str.split(): split on whitespace runs, ignoring leading/trailing.
+        const trimmed = frame.text.trim();
+        const wordCount = trimmed ? trimmed.split(/\s+/).length : 0;
+        const shouldTrigger = wordCount >= minWords;
+        const isInterim = frame instanceof InterimTranscriptionFrame;
+        logger.debug(`${this} should_trigger=${pyBool(shouldTrigger)} num_spoken_words=${wordCount} ` +
+            `min_words=${minWords} bot_speaking=${pyBool(this._botSpeaking)} interim_transcription=${pyBool(isInterim)}`);
+        if (shouldTrigger) {
+            await this.triggerUserTurnStarted();
+            return ProcessFrameResult.STOP;
+        }
+        await this.triggerResetAggregation();
+        return ProcessFrameResult.CONTINUE;
+    }
+}
+function pyBool(value) {
+    return value ? "True" : "False";
+}
+//# sourceMappingURL=min_words_user_turn_start_strategy.js.map

package/dist/turns/user_start/transcription_user_turn_start_strategy.d.ts

@@ -0,0 +1,29 @@
+/** User turn start strategy based on transcriptions. */
+import { type Frame } from "../../frames/frames.ts";
+import { ProcessFrameResult } from "../types.ts";
+import { BaseUserTurnStartStrategy, type BaseUserTurnStartStrategyOptions } from "./base_user_turn_start_strategy.ts";
+export interface TranscriptionUserTurnStartStrategyOptions extends BaseUserTurnStartStrategyOptions {
+    /** Whether interim transcriptions also start a turn. */
+    useInterim?: boolean;
+}
+/**
+ * User turn start strategy based on transcriptions.
+ *
+ * This strategy signals the start of a user turn when a transcription is
+ * received while the bot is speaking. It is useful as a fallback in scenarios
+ * where VAD-based detection fails (for example, when the user speaks very
+ * softly) but the STT service still produces transcriptions.
+ */
+export declare class TranscriptionUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    protected _useInterim: boolean;
+    /** Initialize transcription-based user turn start strategy. */
+    constructor(options?: TranscriptionUserTurnStartStrategyOptions);
+    /**
+     * Process an incoming frame to detect the start of a user turn.
+     *
+     * @param frame The frame to be processed.
+     * @returns STOP if a transcription was received, CONTINUE otherwise.
+     */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+}
+//# sourceMappingURL=transcription_user_turn_start_strategy.d.ts.map

package/dist/turns/user_start/transcription_user_turn_start_strategy.js

@@ -0,0 +1,43 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_start/transcription_user_turn_start_strategy.py
+/** User turn start strategy based on transcriptions. */
+import { InterimTranscriptionFrame, TranscriptionFrame } from "../../frames/frames.js";
+import { ProcessFrameResult } from "../types.js";
+import { BaseUserTurnStartStrategy, } from "./base_user_turn_start_strategy.js";
+/**
+ * User turn start strategy based on transcriptions.
+ *
+ * This strategy signals the start of a user turn when a transcription is
+ * received while the bot is speaking. It is useful as a fallback in scenarios
+ * where VAD-based detection fails (for example, when the user speaks very
+ * softly) but the STT service still produces transcriptions.
+ */
+export class TranscriptionUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    _useInterim;
+    /** Initialize transcription-based user turn start strategy. */
+    constructor(options = {}) {
+        super(options);
+        this._useInterim = options.useInterim ?? true;
+    }
+    /**
+     * Process an incoming frame to detect the start of a user turn.
+     *
+     * @param frame The frame to be processed.
+     * @returns STOP if a transcription was received, CONTINUE otherwise.
+     */
+    async processFrame(frame) {
+        if (frame instanceof InterimTranscriptionFrame && this._useInterim) {
+            await this.triggerUserTurnStarted();
+            return ProcessFrameResult.STOP;
+        }
+        else if (frame instanceof TranscriptionFrame) {
+            await this.triggerUserTurnStarted();
+            return ProcessFrameResult.STOP;
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+}
+//# sourceMappingURL=transcription_user_turn_start_strategy.js.map

package/dist/turns/user_start/vad_user_turn_start_strategy.d.ts

@@ -0,0 +1,20 @@
+/** User turn start strategy based on VAD events. */
+import { type Frame } from "../../frames/frames.ts";
+import { ProcessFrameResult } from "../types.ts";
+import { BaseUserTurnStartStrategy } from "./base_user_turn_start_strategy.ts";
+/**
+ * User turn start strategy based on VAD (Voice Activity Detection).
+ *
+ * This strategy assumes the user turn starts as soon as a VAD frame indicates
+ * that the user has started speaking.
+ */
+export declare class VADUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    /**
+     * Process an incoming frame to detect user turn start.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns STOP if the user started speaking, CONTINUE otherwise.
+     */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+}
+//# sourceMappingURL=vad_user_turn_start_strategy.d.ts.map

package/dist/turns/user_start/vad_user_turn_start_strategy.js

@@ -0,0 +1,31 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_start/vad_user_turn_start_strategy.py
+/** User turn start strategy based on VAD events. */
+import { VADUserStartedSpeakingFrame } from "../../frames/frames.js";
+import { ProcessFrameResult } from "../types.js";
+import { BaseUserTurnStartStrategy } from "./base_user_turn_start_strategy.js";
+/**
+ * User turn start strategy based on VAD (Voice Activity Detection).
+ *
+ * This strategy assumes the user turn starts as soon as a VAD frame indicates
+ * that the user has started speaking.
+ */
+export class VADUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    /**
+     * Process an incoming frame to detect user turn start.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns STOP if the user started speaking, CONTINUE otherwise.
+     */
+    async processFrame(frame) {
+        if (frame instanceof VADUserStartedSpeakingFrame) {
+            await this.triggerUserTurnStarted();
+            return ProcessFrameResult.STOP;
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+}
+//# sourceMappingURL=vad_user_turn_start_strategy.js.map

package/dist/turns/user_start/wake_phrase_user_turn_start_strategy.d.ts

@@ -0,0 +1,141 @@
+/** User turn start strategy that gates interaction behind wake phrase detection. */
+import { Event, type Task } from "@pipedog/asyncio";
+import { type Frame } from "../../frames/frames.ts";
+import type { FrameProcessorSetup } from "../../processors/frame_processor.ts";
+import { ProcessFrameResult } from "../types.ts";
+import { BaseUserTurnStartStrategy, type BaseUserTurnStartStrategyOptions } from "./base_user_turn_start_strategy.ts";
+/** Internal state for wake phrase detection. */
+export declare const _WakeState: {
+    readonly IDLE: "idle";
+    readonly AWAKE: "awake";
+};
+export type _WakeState = (typeof _WakeState)[keyof typeof _WakeState];
+export interface WakePhraseUserTurnStartStrategyOptions extends BaseUserTurnStartStrategyOptions {
+    /** List of wake phrases to detect. */
+    phrases: string[];
+    /**
+     * 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.
+     */
+    timeout?: number;
+    /**
+     * If true, the wake phrase is required before every turn. The strategy
+     * returns to IDLE after each turn completes.
+     */
+    singleActivation?: boolean;
+}
+/**
+ * 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
+ * `singleActivation: 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
+ * const strategy = new WakePhraseUserTurnStartStrategy({
+ *   phrases: ["hey pipecat", "ok pipecat"],
+ *   timeout: 10.0,
+ * });
+ *
+ * // Single activation: wake phrase required before every turn
+ * const single = new WakePhraseUserTurnStartStrategy({
+ *   phrases: ["hey pipecat"],
+ *   singleActivation: true,
+ * });
+ *
+ * strategy.eventHandler("on_wake_phrase_detected", async (strategy, phrase) => { ... });
+ * strategy.eventHandler("on_wake_phrase_timeout", async (strategy) => { ... });
+ *
+ * `timeout`: 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.
+ */
+export declare class WakePhraseUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    protected _phrases: string[];
+    protected _timeout: number;
+    protected _singleActivation: boolean;
+    protected _patterns: RegExp[];
+    protected _state: _WakeState;
+    protected _accumulatedText: string;
+    protected _timeoutEvent: Event;
+    protected _timeoutTask: Task<unknown> | null;
+    constructor(options: WakePhraseUserTurnStartStrategyOptions);
+    /** Returns the current wake state. */
+    get state(): _WakeState;
+    /**
+     * Set up the strategy.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /** Cleanup the strategy. */
+    cleanup(): Promise<void>;
+    /**
+     * Ready the strategy for a new user turn.
+     *
+     * In timeout mode, preserves state and refreshes the timeout — a turn
+     * starting is the activity that keeps the strategy awake. In single
+     * activation mode, does nothing: the keepalive timeout (started when the
+     * wake phrase was detected) handles the transition back to IDLE.
+     */
+    handleUserTurnStarted(): Promise<void>;
+    /**
+     * Process an incoming frame for wake phrase detection or passthrough.
+     *
+     * @param 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).
+     */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+    /**
+     * Process a frame while in IDLE state.
+     *
+     * Only final `TranscriptionFrame` instances are checked for wake phrase
+     * matches. When a match is found, a user turn start is triggered.
+     * Transcription frames that don't match have their text cleared so that
+     * pre-wake-phrase speech is not added to the LLM context. All frames
+     * return STOP to block subsequent strategies.
+     */
+    protected _processIdle(frame: Frame): Promise<ProcessFrameResult>;
+    /**
+     * Process a frame while in AWAKE state.
+     *
+     * Refreshes the timeout on activity frames (timeout mode only). Returns
+     * CONTINUE so subsequent strategies can process the frame.
+     */
+    protected _processAwake(frame: Frame): Promise<ProcessFrameResult>;
+    /** Strip punctuation from text, keeping only letters, digits, and whitespace. */
+    protected static _stripPunctuation(text: string): string;
+    /**
+     * Check if the accumulated text contains a wake phrase.
+     *
+     * Punctuation is stripped before matching so that STT output like
+     * "Hey, Pipecat!" still matches the phrase "hey pipecat".
+     *
+     * @param text New transcription text to append and check.
+     * @returns True if a wake phrase was found, false otherwise.
+     */
+    protected _checkWakePhrase(text: string): boolean;
+    /** Transition from IDLE to AWAKE state. */
+    protected _transitionToAwake(phrase: string): void;
+    /** Transition from AWAKE to IDLE state. */
+    protected _transitionToIdle(): void;
+    /** Refresh the inactivity timeout. */
+    protected _refreshTimeout(): void;
+    /** Background task that monitors inactivity timeout. */
+    protected _timeoutTaskHandler(): Promise<void>;
+}
+//# sourceMappingURL=wake_phrase_user_turn_start_strategy.d.ts.map