@pipedog/core 0.0.0 → 0.1.0

package/dist/turns/user_turn_controller.d.ts

@@ -0,0 +1,134 @@
+/** This module defines a controller for managing user turn lifecycle. */
+import { Event, type Task } from "@pipedog/asyncio";
+import { type Frame, InterimTranscriptionFrame, ProposedUserStartedSpeakingFrame, ProposedUserStoppedSpeakingFrame, TranscriptionFrame, UserStartedSpeakingFrame, UserStoppedSpeakingFrame, VADUserStartedSpeakingFrame, VADUserStoppedSpeakingFrame } from "../frames/frames.ts";
+import { FrameDirection, type FrameProcessorSetup } from "../processors/frame_processor.ts";
+import { BaseObject } from "../utils/base_object.ts";
+import { type UserTurnSpeculation } from "./types.ts";
+import type { BaseUserTurnStartStrategy, UserTurnStartedParams } from "./user_start/index.ts";
+import { type BaseUserTurnStopStrategy, UserTurnStoppedParams } from "./user_stop/index.ts";
+import type { UserTurnStrategies } from "./user_turn_strategies.ts";
+export interface UserTurnControllerOptions {
+    /** Configured strategies for starting and stopping user turns. */
+    userTurnStrategies: UserTurnStrategies;
+    /**
+     * Timeout in seconds to automatically stop a user turn if no activity is
+     * detected.
+     */
+    userTurnStopTimeout?: number;
+}
+type AnyStrategy = BaseUserTurnStartStrategy | BaseUserTurnStopStrategy;
+/**
+ * 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_inference_triggered: Emitted when enough signal exists to
+ *   start LLM inference, carrying a `UserTurnSpeculation` when the turn it
+ *   answers hasn't ended yet. Fires together with `on_user_turn_stopped` for
+ *   most strategies; fires alone when a downstream strategy gates
+ *   finalization on the LLM's verdict.
+ * - on_user_turn_stopped: Emitted when a user turn is semantically final.
+ * - 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.eventHandler("on_user_turn_started", async (controller, strategy, params) => { ... });
+ * controller.eventHandler(
+ *   "on_user_turn_inference_triggered",
+ *   async (controller, strategy, speculation) => { ... },
+ * );
+ * controller.eventHandler("on_user_turn_stopped", async (controller, strategy, params) => { ... });
+ * controller.eventHandler("on_user_turn_stop_timeout", async (controller) => { ... });
+ * controller.eventHandler("on_push_frame", async (controller, frame, direction) => { ... });
+ * controller.eventHandler("on_broadcast_frame", async (controller, frameCls, options) => { ... });
+ */
+export declare class UserTurnController extends BaseObject {
+    protected _userTurnStrategies: UserTurnStrategies;
+    protected _userTurnStopTimeout: number;
+    protected _setup: FrameProcessorSetup | null;
+    protected _userSpeaking: boolean;
+    protected _userTurn: boolean;
+    protected _userTurnStopTimeoutEvent: Event;
+    protected _userTurnStopTimeoutTask: Task<unknown> | null;
+    constructor(options: UserTurnControllerOptions);
+    /** The currently active user turn strategies. */
+    get userTurnStrategies(): UserTurnStrategies;
+    /**
+     * Set up the controller.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /**
+     * Start watching for a turn that stops without the user stopping.
+     *
+     * Paired with `stop()`.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the turn stop timeout, leaving the strategies alone.
+     *
+     * Called at session end. The strategies may be shared, so cleaning them up
+     * waits for `cleanup()`.
+     */
+    stop(): Promise<void>;
+    /** Cleanup the controller. */
+    cleanup(): Promise<void>;
+    /**
+     * Replace the current strategies with the given ones.
+     *
+     * @param strategies The new user turn strategies the controller should use.
+     */
+    updateStrategies(strategies: UserTurnStrategies): Promise<void>;
+    /**
+     * Whether any active start strategy resolves proposed turn starts.
+     *
+     * A proposal is resolved once, so a caller holding this controller should
+     * stop forwarding `ProposedUserStartedSpeakingFrame` when this is true —
+     * passing it along would let a resolver further down the pipeline decide
+     * the same turn a second time.
+     */
+    get resolvesProposedTurnStartFrames(): boolean;
+    /**
+     * Whether any active stop strategy resolves proposed turn stops.
+     *
+     * The end-of-turn counterpart to `resolvesProposedTurnStartFrames`.
+     */
+    get resolvesProposedTurnStopFrames(): boolean;
+    /**
+     * 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.
+     *
+     * @param frame The frame to be processed.
+     */
+    processFrame(frame: Frame): Promise<void>;
+    protected _setupStrategies(): Promise<void>;
+    protected _cleanupStrategies(): Promise<void>;
+    protected _handleUserStartedSpeaking(_frame: UserStartedSpeakingFrame | ProposedUserStartedSpeakingFrame): Promise<void>;
+    protected _handleUserStoppedSpeaking(_frame: UserStoppedSpeakingFrame | ProposedUserStoppedSpeakingFrame): Promise<void>;
+    protected _handleVadUserStartedSpeaking(_frame: VADUserStartedSpeakingFrame): Promise<void>;
+    protected _handleVadUserStoppedSpeaking(_frame: VADUserStoppedSpeakingFrame): Promise<void>;
+    protected _handleTranscription(_frame: TranscriptionFrame | InterimTranscriptionFrame): Promise<void>;
+    protected _onPushFrame: (_strategy: AnyStrategy, frame: Frame, direction?: FrameDirection) => Promise<void>;
+    protected _onBroadcastFrame: (_strategy: AnyStrategy, frameCls: new (options: never) => Frame, options?: unknown) => Promise<void>;
+    protected _onUserTurnSpeculationCancelled: (_strategy: BaseUserTurnStopStrategy) => Promise<void>;
+    protected _onUserTurnStarted: (strategy: BaseUserTurnStartStrategy, params: UserTurnStartedParams) => Promise<void>;
+    protected _onUserTurnInferenceTriggered: (strategy: BaseUserTurnStopStrategy, speculation: UserTurnSpeculation | null) => Promise<void>;
+    protected _onUserTurnStopped: (strategy: BaseUserTurnStopStrategy, params: UserTurnStoppedParams) => Promise<void>;
+    protected _onResetAggregation: (strategy: BaseUserTurnStartStrategy) => Promise<void>;
+    protected _triggerUserTurnStart(strategy: BaseUserTurnStartStrategy | null, params: UserTurnStartedParams): Promise<void>;
+    protected _triggerUserTurnInferenceTriggered(strategy: BaseUserTurnStopStrategy | null, speculation?: UserTurnSpeculation | null): Promise<void>;
+    protected _triggerUserTurnStop(strategy: BaseUserTurnStopStrategy | null, params: UserTurnStoppedParams): Promise<void>;
+    protected _userTurnStopTimeoutTaskHandler(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=user_turn_controller.d.ts.map

package/dist/turns/user_turn_controller.js

@@ -0,0 +1,335 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_turn_controller.py
+/** This module defines a controller for managing user turn lifecycle. */
+import { Event, TimeoutError, waitFor } from "@pipedog/asyncio";
+import { InterimTranscriptionFrame, ProposedUserStartedSpeakingFrame, ProposedUserStoppedSpeakingFrame, TranscriptionFrame, UserStartedSpeakingFrame, UserStoppedSpeakingFrame, VADUserStartedSpeakingFrame, VADUserStoppedSpeakingFrame, } from "../frames/frames.js";
+import { FrameDirection } from "../processors/frame_processor.js";
+import { BaseObject } from "../utils/base_object.js";
+import { ProcessFrameResult } from "./types.js";
+import { UserTurnStoppedParams } from "./user_stop/index.js";
+/**
+ * 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_inference_triggered: Emitted when enough signal exists to
+ *   start LLM inference, carrying a `UserTurnSpeculation` when the turn it
+ *   answers hasn't ended yet. Fires together with `on_user_turn_stopped` for
+ *   most strategies; fires alone when a downstream strategy gates
+ *   finalization on the LLM's verdict.
+ * - on_user_turn_stopped: Emitted when a user turn is semantically final.
+ * - 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.eventHandler("on_user_turn_started", async (controller, strategy, params) => { ... });
+ * controller.eventHandler(
+ *   "on_user_turn_inference_triggered",
+ *   async (controller, strategy, speculation) => { ... },
+ * );
+ * controller.eventHandler("on_user_turn_stopped", async (controller, strategy, params) => { ... });
+ * controller.eventHandler("on_user_turn_stop_timeout", async (controller) => { ... });
+ * controller.eventHandler("on_push_frame", async (controller, frame, direction) => { ... });
+ * controller.eventHandler("on_broadcast_frame", async (controller, frameCls, options) => { ... });
+ */
+export class UserTurnController extends BaseObject {
+    _userTurnStrategies;
+    _userTurnStopTimeout;
+    _setup = null;
+    _userSpeaking = false;
+    _userTurn = false;
+    _userTurnStopTimeoutEvent = new Event();
+    _userTurnStopTimeoutTask = null;
+    constructor(options) {
+        super();
+        this._userTurnStrategies = options.userTurnStrategies;
+        this._userTurnStopTimeout = options.userTurnStopTimeout ?? 5.0;
+        this._registerEventHandler("on_push_frame", true);
+        this._registerEventHandler("on_broadcast_frame", true);
+        this._registerEventHandler("on_user_turn_started", true);
+        this._registerEventHandler("on_user_turn_inference_triggered", true);
+        this._registerEventHandler("on_user_turn_speculation_cancelled", true);
+        this._registerEventHandler("on_user_turn_stopped", true);
+        this._registerEventHandler("on_user_turn_stop_timeout", true);
+        this._registerEventHandler("on_reset_aggregation", true);
+    }
+    /** The currently active user turn strategies. */
+    get userTurnStrategies() {
+        return this._userTurnStrategies;
+    }
+    /**
+     * Set up the controller.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    async setup(setup) {
+        await super.setup(setup.taskManager);
+        // Kept so updateStrategies() can set up new strategies without the caller
+        // having to hand us the setup again.
+        this._setup = setup;
+        await this._setupStrategies();
+    }
+    /**
+     * Start watching for a turn that stops without the user stopping.
+     *
+     * Paired with `stop()`.
+     */
+    async start() {
+        if (!this._userTurnStopTimeoutTask) {
+            this._userTurnStopTimeoutTask = this.createTask(() => this._userTurnStopTimeoutTaskHandler(), "_userTurnStopTimeoutTaskHandler");
+        }
+    }
+    /**
+     * Stop the turn stop timeout, leaving the strategies alone.
+     *
+     * Called at session end. The strategies may be shared, so cleaning them up
+     * waits for `cleanup()`.
+     */
+    async stop() {
+        if (this._userTurnStopTimeoutTask) {
+            await this.cancelTask(this._userTurnStopTimeoutTask);
+            this._userTurnStopTimeoutTask = null;
+        }
+    }
+    /** Cleanup the controller. */
+    async cleanup() {
+        await super.cleanup();
+        await this.stop();
+        await this._cleanupStrategies();
+    }
+    /**
+     * Replace the current strategies with the given ones.
+     *
+     * @param strategies The new user turn strategies the controller should use.
+     */
+    async updateStrategies(strategies) {
+        await this._cleanupStrategies();
+        this._userTurnStrategies = strategies;
+        await this._setupStrategies();
+    }
+    /**
+     * Whether any active start strategy resolves proposed turn starts.
+     *
+     * A proposal is resolved once, so a caller holding this controller should
+     * stop forwarding `ProposedUserStartedSpeakingFrame` when this is true —
+     * passing it along would let a resolver further down the pipeline decide
+     * the same turn a second time.
+     */
+    get resolvesProposedTurnStartFrames() {
+        return (this._userTurnStrategies.start ?? []).some((s) => s.resolvesProposedTurnStartFrames);
+    }
+    /**
+     * Whether any active stop strategy resolves proposed turn stops.
+     *
+     * The end-of-turn counterpart to `resolvesProposedTurnStartFrames`.
+     */
+    get resolvesProposedTurnStopFrames() {
+        return (this._userTurnStrategies.stop ?? []).some((s) => s.resolvesProposedTurnStopFrames);
+    }
+    /**
+     * 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.
+     *
+     * @param frame The frame to be processed.
+     */
+    async processFrame(frame) {
+        if (frame instanceof UserStartedSpeakingFrame ||
+            frame instanceof ProposedUserStartedSpeakingFrame) {
+            await this._handleUserStartedSpeaking(frame);
+        }
+        else if (frame instanceof UserStoppedSpeakingFrame ||
+            frame instanceof ProposedUserStoppedSpeakingFrame) {
+            await this._handleUserStoppedSpeaking(frame);
+        }
+        else if (frame instanceof VADUserStartedSpeakingFrame) {
+            await this._handleVadUserStartedSpeaking(frame);
+        }
+        else if (frame instanceof VADUserStoppedSpeakingFrame) {
+            await this._handleVadUserStoppedSpeaking(frame);
+        }
+        else if (frame instanceof TranscriptionFrame || frame instanceof InterimTranscriptionFrame) {
+            await this._handleTranscription(frame);
+        }
+        for (const strategy of this._userTurnStrategies.start ?? []) {
+            const result = await strategy.processFrame(frame);
+            if (result === ProcessFrameResult.STOP)
+                break;
+        }
+        for (const strategy of this._userTurnStrategies.stop ?? []) {
+            const result = await strategy.processFrame(frame);
+            if (result === ProcessFrameResult.STOP)
+                break;
+        }
+    }
+    async _setupStrategies() {
+        if (!this._setup) {
+            throw new Error(`${this} was not properly set up`);
+        }
+        for (const s of this._userTurnStrategies.start ?? []) {
+            await s.setup(this._setup);
+            s.addEventHandler("on_push_frame", this._onPushFrame);
+            s.addEventHandler("on_broadcast_frame", this._onBroadcastFrame);
+            s.addEventHandler("on_user_turn_started", this._onUserTurnStarted);
+            s.addEventHandler("on_reset_aggregation", this._onResetAggregation);
+        }
+        for (const s of this._userTurnStrategies.stop ?? []) {
+            await s.setup(this._setup);
+            s.addEventHandler("on_push_frame", this._onPushFrame);
+            s.addEventHandler("on_broadcast_frame", this._onBroadcastFrame);
+            s.addEventHandler("on_user_turn_inference_triggered", this._onUserTurnInferenceTriggered);
+            s.addEventHandler("on_user_turn_speculation_cancelled", this._onUserTurnSpeculationCancelled);
+            s.addEventHandler("on_user_turn_stopped", this._onUserTurnStopped);
+        }
+    }
+    async _cleanupStrategies() {
+        // Remove the handlers _setupStrategies added (symmetric), so re-applying
+        // strategies via updateStrategies — possibly reusing the same strategy
+        // instances — doesn't accumulate duplicate handler registrations.
+        for (const s of this._userTurnStrategies.start ?? []) {
+            await s.cleanup();
+            s.removeEventHandler("on_push_frame", this._onPushFrame);
+            s.removeEventHandler("on_broadcast_frame", this._onBroadcastFrame);
+            s.removeEventHandler("on_user_turn_started", this._onUserTurnStarted);
+            s.removeEventHandler("on_reset_aggregation", this._onResetAggregation);
+        }
+        for (const s of this._userTurnStrategies.stop ?? []) {
+            await s.cleanup();
+            s.removeEventHandler("on_push_frame", this._onPushFrame);
+            s.removeEventHandler("on_broadcast_frame", this._onBroadcastFrame);
+            s.removeEventHandler("on_user_turn_inference_triggered", this._onUserTurnInferenceTriggered);
+            s.removeEventHandler("on_user_turn_speculation_cancelled", this._onUserTurnSpeculationCancelled);
+            s.removeEventHandler("on_user_turn_stopped", this._onUserTurnStopped);
+        }
+    }
+    async _handleUserStartedSpeaking(_frame) {
+        this._userSpeaking = true;
+        // The user started talking, let's reset the user turn timeout.
+        this._userTurnStopTimeoutEvent.set();
+    }
+    async _handleUserStoppedSpeaking(_frame) {
+        this._userSpeaking = false;
+        // The user stopped talking, let's reset the user turn timeout.
+        this._userTurnStopTimeoutEvent.set();
+    }
+    async _handleVadUserStartedSpeaking(_frame) {
+        this._userSpeaking = true;
+        // The user started talking, let's reset the user turn timeout.
+        this._userTurnStopTimeoutEvent.set();
+    }
+    async _handleVadUserStoppedSpeaking(_frame) {
+        this._userSpeaking = false;
+        // The user stopped talking, let's reset the user turn timeout.
+        this._userTurnStopTimeoutEvent.set();
+    }
+    async _handleTranscription(_frame) {
+        // We have received a transcription, let's reset the user turn timeout.
+        this._userTurnStopTimeoutEvent.set();
+    }
+    // Strategy event handlers are arrow functions so the same reference can be
+    // added in _setupStrategies() and removed in _cleanupStrategies().
+    _onPushFrame = async (_strategy, frame, direction = FrameDirection.DOWNSTREAM) => {
+        await this._callEventHandler("on_push_frame", frame, direction);
+    };
+    _onBroadcastFrame = async (_strategy, frameCls, options) => {
+        await this._callEventHandler("on_broadcast_frame", frameCls, options);
+    };
+    _onUserTurnSpeculationCancelled = async (_strategy) => {
+        await this._callEventHandler("on_user_turn_speculation_cancelled");
+    };
+    _onUserTurnStarted = async (strategy, params) => {
+        await this._triggerUserTurnStart(strategy, params);
+    };
+    _onUserTurnInferenceTriggered = async (strategy, speculation) => {
+        await this._triggerUserTurnInferenceTriggered(strategy, speculation);
+    };
+    _onUserTurnStopped = async (strategy, params) => {
+        await this._triggerUserTurnStop(strategy, params);
+    };
+    _onResetAggregation = async (strategy) => {
+        await this._callEventHandler("on_reset_aggregation", strategy);
+    };
+    async _triggerUserTurnStart(strategy, params) {
+        // Prevent two consecutive user turn starts.
+        if (this._userTurn)
+            return;
+        this._userTurn = true;
+        this._userTurnStopTimeoutEvent.set();
+        // Notify every strategy that the turn has started. Start strategies ready
+        // themselves for the next detection; stop strategies arm to detect this
+        // turn's end. A strategy resets whatever per-turn state it keeps inside
+        // its own handleUserTurnStarted.
+        for (const s of this._userTurnStrategies.start ?? []) {
+            await s.handleUserTurnStarted();
+        }
+        for (const s of this._userTurnStrategies.stop ?? []) {
+            await s.handleUserTurnStarted();
+        }
+        await this._callEventHandler("on_user_turn_started", strategy, params);
+    }
+    async _triggerUserTurnInferenceTriggered(strategy, speculation = null) {
+        // Inference-triggered fires only while a turn is active. The turn remains
+        // active afterward — only `on_user_turn_stopped` flips state.
+        if (!this._userTurn)
+            return;
+        // Re-arm the stop watchdog so a stuck turn (inference fired but
+        // finalization never arrives) still times out and finalizes.
+        this._userTurnStopTimeoutEvent.set();
+        await this._callEventHandler("on_user_turn_inference_triggered", strategy, speculation);
+    }
+    async _triggerUserTurnStop(strategy, params) {
+        // Prevent two consecutive user turn stops.
+        if (!this._userTurn)
+            return;
+        // Never finalize while the user is audibly speaking. A stop strategy can
+        // finalize on a latent signal (e.g. an LLM ● that resolves after the user
+        // resumed), which is stale by the time it arrives. Keep the turn open so
+        // the next inference re-evaluates; the watchdog still finalizes if the
+        // user then falls silent. Detector strategies only finalize once the user
+        // has stopped, so this is a no-op for them.
+        if (this._userSpeaking)
+            return;
+        this._userTurn = false;
+        this._userTurnStopTimeoutEvent.set();
+        // Notify every strategy that the turn has ended. Stop strategies reset
+        // (and, e.g., drop a turn analyzer's buffered speech that must not survive
+        // an externally-ended turn). Start strategies get the same callback, but
+        // it's a no-op by default: their reset is turn-start semantic, so
+        // resetting them here would be wrong.
+        for (const s of this._userTurnStrategies.start ?? []) {
+            await s.handleUserTurnStopped();
+        }
+        for (const s of this._userTurnStrategies.stop ?? []) {
+            await s.handleUserTurnStopped();
+        }
+        await this._callEventHandler("on_user_turn_stopped", strategy, params);
+    }
+    async _userTurnStopTimeoutTaskHandler() {
+        while (true) {
+            try {
+                await waitFor(() => this._userTurnStopTimeoutEvent.wait(), this._userTurnStopTimeout);
+                this._userTurnStopTimeoutEvent.clear();
+            }
+            catch (e) {
+                if (!(e instanceof TimeoutError))
+                    throw e;
+                if (this._userTurn && !this._userSpeaking) {
+                    await this._callEventHandler("on_user_turn_stop_timeout");
+                    await this._triggerUserTurnStop(null, new UserTurnStoppedParams({ enableUserSpeakingFrames: true }));
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=user_turn_controller.js.map

package/dist/turns/user_turn_processor.d.ts

@@ -0,0 +1,87 @@
+/** Frame processor for managing the user turn lifecycle. */
+import { CancelFrame, EndFrame, type Frame } from "../frames/frames.ts";
+import { FrameDirection, FrameProcessor, type FrameProcessorOptions, type FrameProcessorSetup } from "../processors/frame_processor.ts";
+import type { UserTurnSpeculation } from "./types.ts";
+import { UserIdleController } from "./user_idle_controller.ts";
+import type { BaseUserTurnStartStrategy, UserTurnStartedParams } from "./user_start/index.ts";
+import type { BaseUserTurnStopStrategy, UserTurnStoppedParams } from "./user_stop/index.ts";
+import { UserTurnController } from "./user_turn_controller.ts";
+import { UserTurnStrategies } from "./user_turn_strategies.ts";
+export interface UserTurnProcessorOptions extends FrameProcessorOptions {
+    /** Configured strategies for starting and stopping user turns. */
+    userTurnStrategies?: UserTurnStrategies | null;
+    /**
+     * Timeout in seconds to automatically stop a user turn if no activity is
+     * detected.
+     */
+    userTurnStopTimeout?: number;
+    /**
+     * 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.
+     */
+    userIdleTimeout?: number;
+}
+/**
+ * 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_inference_triggered: Emitted when enough signal exists to
+ *   start LLM inference. Fires together with `on_user_turn_stopped` for most
+ *   strategies; fires alone when a downstream strategy gates finalization on
+ *   the LLM's verdict.
+ * - on_user_turn_stopped: Emitted when a user turn is semantically final.
+ * - 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.eventHandler("on_user_turn_started", async (processor, strategy) => { ... });
+ * processor.eventHandler("on_user_turn_inference_triggered", async (processor, strategy) => { ... });
+ * processor.eventHandler("on_user_turn_stopped", async (processor, strategy) => { ... });
+ * processor.eventHandler("on_user_turn_stop_timeout", async (processor) => { ... });
+ * processor.eventHandler("on_user_turn_idle", async (processor) => { ... });
+ */
+export declare class UserTurnProcessor extends FrameProcessor {
+    protected _userTurnController: UserTurnController;
+    protected _userIdleController: UserIdleController;
+    constructor(options?: UserTurnProcessorOptions);
+    /**
+     * Set up the processor.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /** Clean up processor resources. */
+    cleanup(): Promise<void>;
+    /**
+     * Process an incoming frame to detect user turn start or stop.
+     *
+     * The frame is passed to the user turn controller which is responsible for
+     * deciding when a user turn starts or stops and emitting the corresponding
+     * events.
+     *
+     * @param frame The frame to be processed.
+     * @param direction The direction of the incoming frame.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    protected _stop(_frame: EndFrame): Promise<void>;
+    protected _cancel(_frame: CancelFrame): Promise<void>;
+    protected _stopControllers(): Promise<void>;
+    protected _cleanup(): Promise<void>;
+    protected _onPushFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    protected _onBroadcastFrame(frameCls: new (options: unknown) => Frame, options?: unknown): Promise<void>;
+    protected _onUserTurnSpeculationCancelled(_controller: UserTurnController): Promise<void>;
+    protected _onUserTurnStarted(_controller: UserTurnController, strategy: BaseUserTurnStartStrategy, params: UserTurnStartedParams): Promise<void>;
+    protected _onUserTurnStopped(_controller: UserTurnController, strategy: BaseUserTurnStopStrategy, params: UserTurnStoppedParams): Promise<void>;
+    protected _onUserTurnStopTimeout(_controller: UserTurnController): Promise<void>;
+    protected _onUserTurnIdle(_controller: UserIdleController): Promise<void>;
+    protected _onUserTurnInferenceTriggered(_controller: UserTurnController, strategy: BaseUserTurnStopStrategy, _speculation: UserTurnSpeculation | null): Promise<void>;
+}
+//# sourceMappingURL=user_turn_processor.d.ts.map