livekit::Room Class Reference

Represents a LiveKit room session. More...

#include <room.h>

Public Member Functions
void	setDelegate (RoomDelegate *delegate)
	Assign a RoomDelegate that receives room lifecycle callbacks.
bool	connect (const std::string &url, const std::string &token, const RoomOptions &options)
	Connect to a LiveKit room using the given URL and token, applying the supplied connection options.
bool	disconnect (DisconnectReason reason=DisconnectReason::ClientInitiated)
	Disconnect from the room.
RoomInfoData	roomInfo () const
	Retrieve static metadata about the room.
std::weak_ptr< LocalParticipant >	localParticipant () const
	Get the local participant.
std::weak_ptr< RemoteParticipant >	remoteParticipant (const std::string &identity) const
	Look up a remote participant by identity.
std::vector< std::weak_ptr< RemoteParticipant > >	remoteParticipants () const
	Returns a snapshot of all current remote participants.
ConnectionState	connectionState () const
	Returns the current connection state of the room.
std::future< SessionStats >	getStats () const
	Retrieve aggregated WebRTC stats for this room session.
void	registerTextStreamHandler (const std::string &topic, TextStreamHandler handler)
	Register a handler for incoming text streams on a specific topic.
void	unregisterTextStreamHandler (const std::string &topic)
	Unregister the text stream handler for the given topic.
void	registerByteStreamHandler (const std::string &topic, ByteStreamHandler handler)
	Register a handler for incoming byte streams on a specific topic.
void	unregisterByteStreamHandler (const std::string &topic)
	Unregister the byte stream handler for the given topic.
std::weak_ptr< E2EEManager >	e2eeManager () const
	Returns the room's E2EE manager as a weak handle, or an empty handle if E2EE was not enabled at connect time.
void	setOnAudioFrameCallback (const std::string &participant_identity, const std::string &track_name, AudioFrameCallback callback, const AudioStream::Options &opts={})
	Sets the audio frame callback via SubscriptionThreadDispatcher.
void	setOnVideoFrameCallback (const std::string &participant_identity, const std::string &track_name, VideoFrameCallback callback, const VideoStream::Options &opts={})
	Sets the video frame callback via SubscriptionThreadDispatcher.
void	setOnVideoFrameEventCallback (const std::string &participant_identity, const std::string &track_name, VideoFrameEventCallback callback, const VideoStream::Options &opts={})
	Sets the video frame event callback via SubscriptionThreadDispatcher.
void	clearOnAudioFrameCallback (const std::string &participant_identity, const std::string &track_name)
	Clears the audio frame callback via SubscriptionThreadDispatcher.
void	clearOnVideoFrameCallback (const std::string &participant_identity, const std::string &track_name)
	Clears the video frame callback via SubscriptionThreadDispatcher.
DataFrameCallbackId	addOnDataFrameCallback (const std::string &participant_identity, const std::string &track_name, DataFrameCallback callback)
	Adds a data frame callback via SubscriptionThreadDispatcher.
void	removeOnDataFrameCallback (DataFrameCallbackId id)
	Removes the data frame callback via SubscriptionThreadDispatcher.

Friends
class	RoomCallbackTest

Detailed Description

Represents a LiveKit room session.

A Room manages:

• the connection to the LiveKit server
• participant list (local + remote)
• track publications
• server events forwarded to a RoomDelegate

Member Function Documentation

connect()

bool livekit::Room::connect	(	const std::string &	url,
		const std::string &	token,
		const RoomOptions &	options
	)

Connect to a LiveKit room using the given URL and token, applying the supplied connection options.

Parameters

url	WebSocket URL of the LiveKit server.
token	Access token for authentication.
options	Connection options controlling auto-subscribe, dynacast, E2EE, and WebRTC configuration. Behavior: Registers an FFI event listener before sending the connect request. Sends a proto::FfiRequest::Connect with the URL, token, and the provided RoomOptions. Blocks until the FFI connect response arrives. Initializes local participant and remote participants. Emits room/participant/track events to the delegate. IMPORTANT: RoomOptions defaults auto_subscribe = true. Without auto_subscribe enabled, remote tracks will NOT be subscribed automatically, and no remote audio/video will ever arrive.

disconnect()

bool livekit::Room::disconnect

(

DisconnectReason

reason = DisconnectReason::ClientInitiated

)

Disconnect from the room.

This method attempts a best-effort graceful disconnect of the room. If the room was connected prior, after disconnect() is called the room object is considered in a terminal state and should no longer be used. If disconnect() was called before connect(), no operations are performed and the room object is still valid.

Note

~Room() invokes disconnect() automatically if the room is still connected, so explicit calls are optional.

Warning

Safe to call from any thread, but must not be called from inside a RoomDelegate callback — doing so will deadlock the event listener.

Parameters

reason

Reason reported to the server (default: ClientInitiated).

Returns

true if the graceful disconnect succeeds; false if the room was already disconnected (no-op) or the graceful disconnect fails.

e2eeManager()

std::weak_ptr< E2EEManager > livekit::Room::e2eeManager

(

)

const

Returns the room's E2EE manager as a weak handle, or an empty handle if E2EE was not enabled at connect time.

Notes:

• The manager is created after a successful connect().
• If E2EE was not configured in RoomOptions, lock() returns nullptr.
• The handle also becomes empty once the room is torn down or destroyed.

Returns

Weak handle to the E2EE manager.

getStats()

std::future< SessionStats > livekit::Room::getStats

(

)

const

Retrieve aggregated WebRTC stats for this room session.

Dispatches an async request to the server and returns a future that resolves with the stats.

Returns

Future of the room session stats.

Exceptions

std::runtime_error	Synchronously, if the room is not currently connected, or if the FFI request fails to dispatch.
std::runtime_error	On future.get(), if the async request fails.

localParticipant()

std::weak_ptr< LocalParticipant > livekit::Room::localParticipant

(

)

const

Get the local participant.

This object represents the current user, including:

• published tracks (audio/video/screen)
• identity, SID, metadata
• publishing/unpublishing operations

The returned handle is non-owning. Call lock() to obtain a usable weak_ptr; the result is empty (lock() == nullptr) before connect, after room end-of-stream teardown, or once the room is destroyed. This lets callers that cache the handle detect object lifetime instead of holding a dangling pointer.

Returns

Weak handle to the local participant.

registerByteStreamHandler()

void livekit::Room::registerByteStreamHandler	(	const std::string &	topic,
		ByteStreamHandler	handler
	)

Register a handler for incoming byte streams on a specific topic.

When a remote participant opens a byte stream with the given topic, the handler is invoked with:

• a shared_ptr<ByteStreamReader> for consuming the stream
• the identity of the participant who sent the stream

Notes:

• Only one handler may be registered per topic.
• If no handler is registered for a topic, incoming streams with that topic are ignored.
• The ByteStreamReader remains valid as long as the shared_ptr is held, preventing lifetime-related crashes when reading asynchronously.

Exceptions

std::runtime_error

if a handler is already registered for the topic.

registerTextStreamHandler()

void livekit::Room::registerTextStreamHandler	(	const std::string &	topic,
		TextStreamHandler	handler
	)

Register a handler for incoming text streams on a specific topic.

When a remote participant opens a text stream with the given topic, the handler is invoked with:

• a shared_ptr<TextStreamReader> for consuming the stream
• the identity of the participant who sent the stream

Notes:

• Only one handler may be registered per topic.
• If no handler is registered for a topic, incoming streams with that topic are ignored.
• The handler is invoked on the Room event thread. The handler must not block; spawn a background thread if synchronous reading is required.

Exceptions

std::runtime_error

if a handler is already registered for the topic.

remoteParticipant()

std::weak_ptr< RemoteParticipant > livekit::Room::remoteParticipant

(

const std::string &

identity

)

const

Look up a remote participant by identity.

Parameters

identity

The participant’s identity string (not SID).

Returns

Weak handle to the RemoteParticipant if present, otherwise an empty handle (lock() == nullptr). The handle also becomes empty once the participant disconnects, the room is torn down, or the room is destroyed. RemoteParticipant contains:

• identity/name/metadata
• track publications
• callbacks for track subscribed/unsubscribed, muted/unmuted

remoteParticipants()

std::vector< std::weak_ptr< RemoteParticipant > > livekit::Room::remoteParticipants

(

)

const

Returns a snapshot of all current remote participants.

Returns

Vector of weak handles to the current remote participants. Each handle can be promoted with lock(); a handle becomes empty once the corresponding participant disconnects or the room is torn down.

roomInfo()

RoomInfoData livekit::Room::roomInfo

(

)

const

Retrieve static metadata about the room.

This contains fields such as:

• SID
• room name
• metadata
• participant counts
• creation timestamp

setDelegate()

void livekit::Room::setDelegate

(

RoomDelegate *

delegate

)

Assign a RoomDelegate that receives room lifecycle callbacks.

The delegate must remain valid for the lifetime of the Room or until a different delegate is assigned. The Room does not take ownership. Typical usage: class MyDelegate : public RoomDelegate { ... }; MyDelegate del; Room room; room.setDelegate(&del);

unregisterByteStreamHandler()

void livekit::Room::unregisterByteStreamHandler

(

const std::string &

topic

)

Unregister the byte stream handler for the given topic.

If no handler exists for the topic, this function is a no-op.

unregisterTextStreamHandler()

void livekit::Room::unregisterTextStreamHandler

(

const std::string &

topic

)

Unregister the text stream handler for the given topic.

If no handler exists for the topic, this function is a no-op.

---

The documentation for this class was generated from the following file:

• include/livekit/room.h