Control Frames

{ .api }
from pipecat.frames.frames import StartFrame

class StartFrame(SystemFrame):
    """Pipeline start signal.

    Signals the beginning of pipeline execution.

    Example:
        await task.queue_frame(StartFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import EndFrame

class EndFrame(ControlFrame):
    """Pipeline end signal.

    Signals normal end of pipeline processing. Pipeline
    flushes all pending frames before stopping.

    Example:
        # Signal end of conversation
        await task.queue_frame(EndFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import StopFrame

class StopFrame(ControlFrame):
    """Pipeline stop signal.

    Signals immediate stop of pipeline processing.

    Example:
        await task.queue_frame(StopFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import CancelFrame

class CancelFrame(SystemFrame):
    """Cancel operation signal.

    Requests cancellation of current operation.

    Example:
        await task.queue_frame(CancelFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import ErrorFrame

class ErrorFrame(SystemFrame):
    """Error occurred.

    Signals recoverable error condition.

    Attributes:
        error (str): Error message
    """

    def __init__(self, error: str):
        """Initialize error frame.

        Args:
            error: Error message

        Example:
            frame = ErrorFrame(error="Connection timeout")
        """
        pass

{ .api }
from pipecat.frames.frames import FatalErrorFrame

class FatalErrorFrame(ErrorFrame):
    """Fatal error occurred.

    Signals unrecoverable error that stops the pipeline.

    Example:
        frame = FatalErrorFrame(error="Authentication failed")
    """
    pass

{ .api }
from pipecat.frames.frames import InterruptionFrame

class InterruptionFrame(SystemFrame):
    """Interruption signal.

    Base class for interruption events.
    """
    pass

{ .api }
from pipecat.frames.frames import StartInterruptionFrame

class StartInterruptionFrame(InterruptionFrame):
    """Start interruption.

    Signals the start of an interruption event (e.g., user
    started speaking during bot output).

    Example:
        await self.push_frame(StartInterruptionFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import TaskFrame

class TaskFrame(SystemFrame):
    """Task-related base frame.

    Base class for task management frames.
    """
    pass

{ .api }
from pipecat.frames.frames import EndTaskFrame

class EndTaskFrame(TaskFrame):
    """Frame to request graceful pipeline task closure.

    This is used to notify the pipeline task that the pipeline should be closed
    nicely (flushing all the queued frames) by pushing an EndFrame downstream.
    This frame should be pushed upstream.

    Attributes:
        reason (Optional[Any]): Optional reason for pushing an end frame

    Example:
        # End task gracefully
        await task.queue_frame(EndTaskFrame())

        # End task with reason
        await task.queue_frame(EndTaskFrame(reason="User disconnected"))
    """

    reason: Optional[Any] = None

{ .api }
from pipecat.frames.frames import CancelTaskFrame

class CancelTaskFrame(TaskFrame):
    """Frame to request immediate pipeline task cancellation.

    This is used to notify the pipeline task that the pipeline should be stopped
    immediately by pushing a CancelFrame downstream. This frame should be pushed
    upstream.

    Attributes:
        reason (Optional[Any]): Optional reason for pushing a cancel frame

    Example:
        # Cancel task immediately
        await task.queue_frame(CancelTaskFrame())

        # Cancel task with reason
        await task.queue_frame(CancelTaskFrame(reason="Critical error occurred"))
    """

    reason: Optional[Any] = None

{ .api }
from pipecat.frames.frames import StopTaskFrame

class StopTaskFrame(TaskFrame):
    """Frame to request pipeline task stop while keeping processors running.

    This is used to notify the pipeline task that it should be stopped as soon as
    possible (flushing all the queued frames) but that the pipeline processors
    should be kept in a running state. This frame should be pushed upstream.

    Example:
        # Stop task but keep processors alive
        await task.queue_frame(StopTaskFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import InterruptionTaskFrame

class InterruptionTaskFrame(TaskFrame):
    """Frame indicating the bot should be interrupted.

    Emitted when the bot should be interrupted. This will mainly cause the same
    actions as if the user interrupted except that the UserStartedSpeakingFrame
    and UserStoppedSpeakingFrame won't be generated. This frame should be pushed
    upstream.

    Example:
        # Programmatically interrupt the bot
        await task.queue_frame(InterruptionTaskFrame())

        # This causes interruption without user speech frames
        # Useful for programmatic control of bot behavior
    """
    pass

{ .api }
from pipecat.frames.frames import TTSSpeakFrame

class TTSSpeakFrame(DataFrame):
    """Direct TTS speech request.

    Directly requests TTS synthesis of text.

    Attributes:
        text (str): Text to synthesize
    """

    def __init__(self, text: str):
        """Initialize TTS speak frame.

        Args:
            text: Text to speak

        Example:
            frame = TTSSpeakFrame(text="Hello, world!")
        """
        pass

{ .api }
from pipecat.frames.frames import TTSStartedFrame

class TTSStartedFrame(ControlFrame):
    """TTS synthesis started.

    Signals that TTS synthesis has begun.

    Example:
        await self.push_frame(TTSStartedFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import TTSStoppedFrame

class TTSStoppedFrame(ControlFrame):
    """TTS synthesis stopped.

    Signals that TTS synthesis has completed or stopped.

    Example:
        await self.push_frame(TTSStoppedFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import ServiceUpdateSettingsFrame

class ServiceUpdateSettingsFrame(ControlFrame):
    """Update service settings.

    Base class for service settings updates.

    Attributes:
        settings (Dict[str, Any]): Settings to update
    """

    def __init__(self, settings: Dict[str, Any]):
        """Initialize settings update frame.

        Args:
            settings: Settings dict
        """
        pass

{ .api }
from pipecat.frames.frames import LLMUpdateSettingsFrame

class LLMUpdateSettingsFrame(ServiceUpdateSettingsFrame):
    """Update LLM settings.

    Updates LLM service settings at runtime.

    Attributes:
        settings (Mapping[str, Any]): Settings to update

    Example:
        frame = LLMUpdateSettingsFrame(settings={
            "temperature": 0.8,
            "max_tokens": 500
        })
    """
    pass

{ .api }
from pipecat.frames.frames import TTSUpdateSettingsFrame

class TTSUpdateSettingsFrame(ServiceUpdateSettingsFrame):
    """Update TTS settings.

    Updates TTS service settings at runtime.

    Example:
        frame = TTSUpdateSettingsFrame(settings={
            "voice": "nova",
            "speed": 1.2
        })
    """
    pass

{ .api }
from pipecat.frames.frames import STTUpdateSettingsFrame

class STTUpdateSettingsFrame(ServiceUpdateSettingsFrame):
    """Update STT settings.

    Updates STT service settings at runtime.

    Example:
        frame = STTUpdateSettingsFrame(settings={
            "language": "es",
            "model": "nova-2"
        })
    """
    pass

{ .api }
from pipecat.frames.frames import VADParamsUpdateFrame

class VADParamsUpdateFrame(ControlFrame):
    """Update VAD parameters.

    Updates Voice Activity Detection parameters.

    Attributes:
        params (VADParams): New VAD parameters
    """

    def __init__(self, params: "VADParams"):
        """Initialize VAD update frame.

        Args:
            params: New VAD parameters

        Example:
            from pipecat.audio.vad.vad_analyzer import VADParams

            frame = VADParamsUpdateFrame(params=VADParams(
                threshold=0.7,
                min_speech_duration_ms=300
            ))
        """
        pass

{ .api }
from pipecat.frames.frames import SpeechControlParamsFrame

class SpeechControlParamsFrame(SystemFrame):
    """Update speech control parameters.

    Updates parameters for speech control and interruption.

    Attributes:
        params (Dict[str, Any]): Speech control parameters
    """

    def __init__(self, params: Dict[str, Any]):
        """Initialize speech control frame.

        Args:
            params: Speech control parameters
        """
        pass

{ .api }
from pipecat.frames.frames import FilterControlFrame

class FilterControlFrame(ControlFrame):
    """Filter control base.

    Base class for audio filter control frames.
    """
    pass

{ .api }
from pipecat.frames.frames import FilterUpdateSettingsFrame

class FilterUpdateSettingsFrame(FilterControlFrame):
    """Update filter settings.

    Updates audio filter settings.

    Attributes:
        settings (Dict[str, Any]): Filter settings
    """

    def __init__(self, settings: Dict[str, Any]):
        """Initialize filter settings update.

        Args:
            settings: Filter settings dict
        """
        pass

{ .api }
from pipecat.frames.frames import FilterEnableFrame

class FilterEnableFrame(FilterControlFrame):
    """Enable/disable filter.

    Controls filter enable state.

    Attributes:
        enable (bool): Enable or disable filter
    """

    def __init__(self, enable: bool):
        """Initialize filter enable frame.

        Args:
            enable: True to enable, False to disable
        """
        pass

{ .api }
from pipecat.frames.frames import MixerControlFrame

class MixerControlFrame(ControlFrame):
    """Mixer control base.

    Base class for audio mixer control frames.
    """
    pass

{ .api }
from pipecat.frames.frames import MixerUpdateSettingsFrame

class MixerUpdateSettingsFrame(MixerControlFrame):
    """Update mixer settings.

    Updates audio mixer settings.

    Attributes:
        settings (Dict[str, Any]): Mixer settings
    """

    def __init__(self, settings: Dict[str, Any]):
        """Initialize mixer settings update.

        Args:
            settings: Mixer settings dict
        """
        pass

{ .api }
from pipecat.frames.frames import MixerEnableFrame

class MixerEnableFrame(MixerControlFrame):
    """Enable/disable mixer.

    Controls mixer enable state.

    Attributes:
        enable (bool): Enable or disable mixer
    """

    def __init__(self, enable: bool):
        """Initialize mixer enable frame.

        Args:
            enable: True to enable, False to disable
        """
        pass

{ .api }
from pipecat.frames.frames import FrameProcessorPauseFrame

class FrameProcessorPauseFrame(ControlFrame):
    """Pause frame processing for a specific processor.

    This frame is used to pause frame processing for the given processor.
    Pausing frame processing will keep frames in the internal queue which
    will then be processed when frame processing is resumed.

    Args:
        processor: The frame processor to pause

    Example:
        # Pause a specific processor
        await task.queue_frame(FrameProcessorPauseFrame(processor=my_processor))
    """

    processor: "FrameProcessor"

{ .api }
from pipecat.frames.frames import FrameProcessorResumeFrame

class FrameProcessorResumeFrame(ControlFrame):
    """Resume frame processing for a specific processor.

    This frame is used to resume frame processing for the given processor
    after it was paused with FrameProcessorPauseFrame.

    Args:
        processor: The frame processor to resume

    Example:
        # Resume a specific processor
        await task.queue_frame(FrameProcessorResumeFrame(processor=my_processor))
    """

    processor: "FrameProcessor"

{ .api }
from pipecat.frames.frames import FrameProcessorPauseUrgentFrame

class FrameProcessorPauseUrgentFrame(SystemFrame):
    """Urgent pause for immediate processor suspension.

    SystemFrame version of FrameProcessorPauseFrame that bypasses the queue
    for immediate processor pause.

    Args:
        processor: The frame processor to pause

    Example:
        # Urgently pause a processor
        await task.queue_frame(FrameProcessorPauseUrgentFrame(processor=my_processor))
    """

    processor: "FrameProcessor"

{ .api }
from pipecat.frames.frames import FrameProcessorResumeUrgentFrame

class FrameProcessorResumeUrgentFrame(SystemFrame):
    """Urgent resume for immediate processor resumption.

    SystemFrame version of FrameProcessorResumeFrame that bypasses the queue
    for immediate processor resume.

    Args:
        processor: The frame processor to resume

    Example:
        # Urgently resume a processor
        await task.queue_frame(FrameProcessorResumeUrgentFrame(processor=my_processor))
    """

    processor: "FrameProcessor"

{ .api }
from pipecat.frames.frames import OutputTransportReadyFrame

class OutputTransportReadyFrame(ControlFrame):
    """Transport ready signal.

    Signals that output transport is ready to receive data.

    Example:
        await self.push_frame(OutputTransportReadyFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import OutputTransportMessageFrame

class OutputTransportMessageFrame(DataFrame):
    """Transport-specific output message.

    Sends a transport-specific message through the output transport.
    Message format depends on the transport type (e.g., WebRTC data channel).

    Attributes:
        message (Any): The transport message payload

    Example:
        # Send custom data through transport
        frame = OutputTransportMessageFrame(message={
            "type": "chat",
            "content": "Hello"
        })
    """
    pass

{ .api }
from pipecat.frames.frames import OutputTransportMessageUrgentFrame

class OutputTransportMessageUrgentFrame(SystemFrame):
    """Urgent transport-specific output message.

    Sends a transport-specific message immediately through the output transport.
    SystemFrame for bypassing queue for time-sensitive messages.

    Attributes:
        message (Any): The urgent transport message payload

    Example:
        # Send urgent notification
        frame = OutputTransportMessageUrgentFrame(message={
            "type": "urgent_alert",
            "content": "Connection issue"
        })
    """
    pass

{ .api }
from pipecat.frames.frames import InputTransportMessageFrame

class InputTransportMessageFrame(SystemFrame):
    """Transport-specific input message.

    Represents a transport-specific message received from the input transport.
    SystemFrame for immediate processing.

    Attributes:
        message (Any): The transport message payload

    Example:
        # Received from transport
        frame = InputTransportMessageFrame(message={
            "type": "participant_joined",
            "user_id": "user123"
        })
    """
    pass

{ .api }
from pipecat.frames.frames import InputTransportMessageUrgentFrame

class InputTransportMessageUrgentFrame(InputTransportMessageFrame):
    """Urgent transport-specific input message.

    DEPRECATED: Use InputTransportMessageFrame instead.

    .. deprecated:: 0.0.87
        Use InputTransportMessageFrame instead.

    Represents an urgent transport-specific message received from input.
    """
    pass

{ .api }
from pipecat.frames.frames import TransportMessageUrgentFrame

class TransportMessageUrgentFrame(OutputTransportMessageUrgentFrame):
    """Urgent transport message.

    DEPRECATED: Use OutputTransportMessageUrgentFrame instead.

    .. deprecated:: 0.0.87
        Use OutputTransportMessageUrgentFrame instead.

    Urgent transport-specific message frame.
    """
    pass

{ .api }
from pipecat.frames.frames import TransportMessageFrame

class TransportMessageFrame(OutputTransportMessageFrame):
    """Transport message frame.

    DEPRECATED: Use OutputTransportMessageFrame instead.

    .. deprecated:: 0.0.87
        Use OutputTransportMessageFrame instead.

    Transport-specific message frame.
    """
    pass

{ .api }
from pipecat.frames.frames import DTMFFrame
from pipecat.audio.dtmf.types import KeypadEntry

class DTMFFrame:
    """Base DTMF keypad frame.

    Base class for DTMF (Dual-Tone Multi-Frequency) keypad frames
    used in telephony applications.

    Attributes:
        button (KeypadEntry): The DTMF keypad entry (0-9, *, #)

    Example:
        from pipecat.audio.dtmf.types import KeypadEntry

        frame = DTMFFrame(button=KeypadEntry.FIVE)
    """
    pass

{ .api }
from pipecat.frames.frames import OutputDTMFFrame

class OutputDTMFFrame(DTMFFrame, DataFrame):
    """DTMF keypress output frame.

    A DTMF keypress output that will be queued for sending through
    the transport. If your transport supports multiple dial-out
    destinations, use the transport_destination field to specify
    where the DTMF keypress should be sent.

    Example:
        from pipecat.audio.dtmf.types import KeypadEntry

        # Press '5' on keypad
        frame = OutputDTMFFrame(button=KeypadEntry.FIVE)
        await task.queue_frame(frame)
    """
    pass

{ .api }
from pipecat.frames.frames import InputDTMFFrame

class InputDTMFFrame(DTMFFrame, SystemFrame):
    """DTMF keypress input frame.

    A DTMF keypress received from the transport. SystemFrame for
    immediate processing.

    Example:
        # Received from transport when user presses keypad
        frame = InputDTMFFrame(button=KeypadEntry.STAR)
    """
    pass

{ .api }
from pipecat.frames.frames import OutputDTMFUrgentFrame

class OutputDTMFUrgentFrame(DTMFFrame, SystemFrame):
    """DTMF keypress urgent output frame.

    A DTMF keypress output that will be sent immediately, bypassing
    the normal queue. SystemFrame for time-sensitive DTMF output.
    If your transport supports multiple dial-out destinations, use
    the transport_destination field.

    Example:
        # Send urgent DTMF tone
        frame = OutputDTMFUrgentFrame(button=KeypadEntry.POUND)
        await task.queue_frame(frame)
    """
    pass

{ .api }
from pipecat.frames.frames import DeprecatedKeypadEntry

# DEPRECATED: Use pipecat.audio.dtmf.types.KeypadEntry instead
class DeprecatedKeypadEntry:
    """Deprecated keypad entry wrapper.

    **DEPRECATED**: This class is deprecated and will be removed in a future version.
    Use `pipecat.audio.dtmf.types.KeypadEntry` instead.

    This class redirects to the new location for backward compatibility.
    """
    pass

{ .api }
# OLD (deprecated)
from pipecat.frames.frames import DeprecatedKeypadEntry

# NEW (recommended)
from pipecat.audio.dtmf.types import KeypadEntry

# Use KeypadEntry enum values
button = KeypadEntry.ONE

{ .api }
from pipecat.frames.frames import STTMuteFrame

class STTMuteFrame(SystemFrame):
    """Mute STT.

    Controls STT muting state.

    Attributes:
        muted (bool): Mute or unmute STT
    """

    def __init__(self, muted: bool = True):
        """Initialize STT mute frame.

        Args:
            muted: True to mute, False to unmute

        Example:
            # Mute STT
            await task.queue_frame(STTMuteFrame(muted=True))

            # Unmute STT
            await task.queue_frame(STTMuteFrame(muted=False))
        """
        pass

{ .api }
from pipecat.frames.frames import ServiceSwitcherFrame

class ServiceSwitcherFrame(ControlFrame):
    """Service switching base frame.

    Base class for service switching control.
    """
    pass

{ .api }
from pipecat.frames.frames import ManuallySwitchServiceFrame

class ManuallySwitchServiceFrame(ServiceSwitcherFrame):
    """Manual service switch.

    Manually switches to a different service by index.

    Attributes:
        service_index (int): Index of service to switch to
    """

    def __init__(self, service_index: int):
        """Initialize manual switch frame.

        Args:
            service_index: Service index to switch to

        Example:
            # Switch to service at index 1
            frame = ManuallySwitchServiceFrame(service_index=1)
        """
        pass

{ .api }
from pipecat.frames.frames import HeartbeatFrame

class HeartbeatFrame(ControlFrame):
    """Heartbeat signal.

    Periodic heartbeat for keep-alive and monitoring.

    Example:
        await self.push_frame(HeartbeatFrame())
    """
    pass

{ .api }
from pipecat.frames.frames import MetricsFrame

class MetricsFrame(SystemFrame):
    """Metrics data.

    Carries performance and usage metrics.

    Attributes:
        data (MetricsData): Metrics data object
    """

    def __init__(self, data: "MetricsData"):
        """Initialize metrics frame.

        Args:
            data: MetricsData object

        Example:
            from pipecat.metrics.metrics import TTFBMetricsData

            frame = MetricsFrame(data=TTFBMetricsData(
                ttfb_ms=145.2,
                processor="llm"
            ))
        """
        pass

{ .api }
async def shutdown_pipeline(task: PipelineTask):
    """Gracefully shut down pipeline."""
    # Queue end frame to flush pending data
    await task.queue_frame(EndFrame())

    # Wait for completion
    await task.run()

{ .api }
async def emergency_stop(task: PipelineTask):
    """Immediately stop pipeline."""
    # Cancel task
    await task.cancel()

    # Or queue cancel frame
    await task.queue_frame(CancelFrame())

{ .api }
class ErrorHandler(FrameProcessor):
    """Handle errors in pipeline."""

    async def process_frame(self, frame, direction):
        try:
            await self._process(frame)
        except RecoverableError as e:
            # Send error frame
            await self.push_frame(ErrorFrame(error=str(e)))
        except FatalError as e:
            # Send fatal error frame
            await self.push_frame(FatalErrorFrame(error=str(e)))

        await self.push_frame(frame, direction)

{ .api }
class DynamicSettingsController(FrameProcessor):
    """Update service settings based on conditions."""

    async def process_frame(self, frame, direction):
        # Adjust TTS voice based on context
        if self._should_change_voice():
            settings_frame = TTSUpdateSettingsFrame(settings={
                "voice": "excited-voice"
            })
            await self.push_frame(settings_frame, direction)

        await self.push_frame(frame, direction)

{ .api }
async def switch_tts_service(task: PipelineTask, service_index: int):
    """Switch to a different TTS service."""
    frame = ManuallySwitchServiceFrame(service_index=service_index)
    await task.queue_frame(frame)

{ .api }
class STTMuteController(FrameProcessor):
    """Control STT muting based on bot speech."""

    async def process_frame(self, frame, direction):
        if isinstance(frame, BotStartedSpeakingFrame):
            # Mute STT when bot speaks
            await self.push_frame(STTMuteFrame(muted=True), direction)

        elif isinstance(frame, BotStoppedSpeakingFrame):
            # Unmute STT when bot stops
            await self.push_frame(STTMuteFrame(muted=False), direction)

        await self.push_frame(frame, direction)