LiveKit Protocol Stubs

1.1.5 · active · verified Fri Apr 10

livekit-protocol provides Python protocol stubs for LiveKit, a powerful open-source platform for real-time video, audio, and data communication. It contains the protobuf message definitions used internally by other LiveKit Python SDK components like livekit-client and livekit-rtc. The library is actively maintained as part of the LiveKit Python SDKs monorepo, with frequent updates that often align with new features across the LiveKit ecosystem. The current version is 1.1.5.

Warnings

gotcha The `livekit-protocol` library is a low-level dependency. Most application developers should interact with LiveKit using higher-level libraries like `livekit-client` (for web/mobile client-like functionality) or `livekit-rtc` (for server-side room control) which abstract away the direct manipulation of these protocol messages.
Fix: Unless you specifically need to handle raw LiveKit protocol messages (e.g., implementing a custom signalling server or proxy), prefer using `livekit-client` or `livekit-rtc`.
breaking Protocol definitions can change between minor versions of `livekit-protocol`, especially when new features or data structures (e.g., new event types, added fields to existing messages) are introduced. Mismatched versions with other `livekit-*` libraries in your project can lead to serialization/deserialization errors or unexpected behavior.
Fix: Always ensure that `livekit-protocol` is kept in sync with the major and minor versions of other `livekit-client` or `livekit-rtc` libraries you are using. Refer to the LiveKit Python SDK changelogs for specific details on protocol changes before upgrading.
gotcha This library contains generated code from `.proto` files. While the imports typically follow `from livekit.protocol import livekit_models`, the module names correspond directly to the original `.proto` file names (e.g., `livekit_models.proto` becomes `livekit_models.py`). Be mindful of this convention when importing specific message types.
Fix: When looking for a specific message, consult the `livekit/protocol` directory in the source code to identify which `livekit_*.py` module it resides in, and import accordingly (e.g., `from livekit.protocol import livekit_models as models`).

Install

pip install livekit-protocol Install stable version

Imports

ParticipantInfo

from livekit.protocol import livekit_models as models
# then use models.ParticipantInfo(...)

JoinResponse

from livekit.protocol import livekit_rtc as rtc
# then use rtc.JoinResponse(...)

Quickstart

This quickstart demonstrates how to import and instantiate a basic protobuf message, `ParticipantInfo`, from the `livekit-protocol` library. This library is primarily for defining the structure of messages used in LiveKit's real-time communication, and direct interaction is typically for advanced use cases or internal SDK development.

from livekit.protocol import livekit_models as models

# Create a ParticipantInfo message
participant_info = models.ParticipantInfo(
    sid="PA_12345",
    identity="test-user",
    name="Test User",
    state=models.ParticipantInfo.State.JOINED,
    metadata="{}"
)

print(f"Participant SID: {participant_info.sid}")
print(f"Participant Identity: {participant_info.identity}")
print(f"Participant State: {participant_info.state}")

# You can also serialize/deserialize these messages
serialized_data = participant_info.SerializeToString()

# To deserialize (e.g., from a network stream)
new_participant_info = models.ParticipantInfo()
new_participant_info.ParseFromString(serialized_data)

print(f"Deserialized Participant Identity: {new_participant_info.identity}")

view raw JSON →