​
Frame

The base class for all frames in Pipecat. Provides core functionality for frame identification and timing.

​
Properties

id
integer

Unique identifier for the frame. Auto-generated during frame initialization.

name
string

Frame class name with unique counter (e.g., “Frame#1”, “AudioFrame#2”)

pts
Optional[int]

Presentation timestamp in nanoseconds. Used for frame timing and synchronization.

​
Methods

def __post_init__(self):
    """
    Initializes frame properties. Called automatically after frame creation.
    Sets id, name, and initializes pts to None.
    """

def __str__(self):
    """Returns the frame's name"""

​
DataFrame

Base class for all frames carrying data through the pipeline (audio, text, images, etc.).

@dataclass
class DataFrame(Frame):
    pass

​
SystemFrame

Base class for frames that carry system-level signals and can bypass normal processing rules.

@dataclass
class SystemFrame(Frame):
    pass

​
ControlFrame

Base class for frames that manage pipeline flow and processing control.

@dataclass
class ControlFrame(Frame):
    pass

​
AppFrame

Base class for application-specific custom frames.

@dataclass
class AppFrame(Frame):
    pass

​
Usage Example

from pipecat.frames import DataFrame

# Creating a custom data frame
@dataclass
class CustomDataFrame(DataFrame):
    data: bytes
    metadata: dict

    def __str__(self):
        return f"{self.name}(size: {len(self.data)})"

# Using the frame
frame = CustomDataFrame(data=b"example", metadata={"type": "test"})
print(frame.id)    # Unique ID
print(frame.name)  # e.g., "CustomDataFrame#1"
SoundfileMixerAudio Frames