#include <subscription_thread_dispatcher.h>

Public Member Functions
	SubscriptionThreadDispatcher ()
	Constructs an empty dispatcher with no registered callbacks or readers.

	~SubscriptionThreadDispatcher ()
	Stops all active readers and clears all registered callbacks.

void	setOnAudioFrameCallback (const std::string &participant_identity, TrackSource source, AudioFrameCallback callback, AudioStream::Options opts={})

void	setOnAudioFrameCallback (const std::string &participant_identity, const std::string &track_name, AudioFrameCallback callback, AudioStream::Options opts={})

void	setOnVideoFrameCallback (const std::string &participant_identity, TrackSource source, VideoFrameCallback callback, VideoStream::Options opts={})

void	setOnVideoFrameCallback (const std::string &participant_identity, const std::string &track_name, VideoFrameCallback callback, VideoStream::Options opts={})

void	clearOnAudioFrameCallback (const std::string &participant_identity, TrackSource source)

void	clearOnAudioFrameCallback (const std::string &participant_identity, const std::string &track_name)

void	clearOnVideoFrameCallback (const std::string &participant_identity, TrackSource source)

void	clearOnVideoFrameCallback (const std::string &participant_identity, const std::string &track_name)

void	handleTrackSubscribed (const std::string &participant_identity, TrackSource source, const std::string &track_name, const std::shared_ptr< Track > &track)

void	handleTrackUnsubscribed (const std::string &participant_identity, TrackSource source, const std::string &track_name)

DataFrameCallbackId	addOnDataFrameCallback (const std::string &participant_identity, const std::string &track_name, DataFrameCallback callback)

void	removeOnDataFrameCallback (DataFrameCallbackId id)

void	handleDataTrackPublished (const std::shared_ptr< RemoteDataTrack > &track)

void	handleDataTrackUnpublished (const std::string &sid)

void	stopAll ()

Friends
class	SubscriptionThreadDispatcherTest

Detailed Description

Owns subscription callback registration and per-subscription reader threads.

SubscriptionThreadDispatcher is the low-level companion to Room's remote track subscription flow. Room forwards user-facing callback registration requests here, and then calls handleTrackSubscribed and handleTrackUnsubscribed as room events arrive.

For each registered (participant identity, TrackSource) pair, this class may create a dedicated AudioStream or VideoStream and a matching reader thread. That thread blocks on stream reads and invokes the registered callback with decoded frames.

This type is intentionally independent from RoomDelegate. High-level room events such as RoomDelegate::onTrackSubscribed() remain in Room, while this dispatcher focuses only on callback registration, stream ownership, and reader-thread lifecycle.

The design keeps track-type-specific startup isolated so additional track kinds can be added later without pushing more thread state back into Room.

Member Function Documentation

◆ addOnDataFrameCallback()

DataFrameCallbackId livekit::SubscriptionThreadDispatcher::addOnDataFrameCallback	(	const std::string &	participant_identity,
		const std::string &	track_name,
		DataFrameCallback	callback
	)

Add a callback for data frames from a specific remote participant's data track.

Multiple callbacks may be registered for the same (participant, track_name) pair; each one creates an independent FFI subscription.

The callback fires on a dedicated background thread. If the remote data track has not yet been published, the callback is stored and auto-wired when the track appears (via handleDataTrackPublished).

Parameters

participant_identity	Identity of the remote participant.
track_name	Name of the remote data track.
callback	Function to invoke per data frame.

Returns: An opaque ID that can later be passed to removeOnDataFrameCallback() to tear down this subscription.

◆ clearOnAudioFrameCallback() [1/2]

void livekit::SubscriptionThreadDispatcher::clearOnAudioFrameCallback	(	const std::string &	participant_identity,
		const std::string &	track_name
	)

Remove an audio callback registration and stop any active reader.

If an audio reader thread is active for the given key, its stream is closed and the thread is joined before this call returns.

Parameters

participant_identity	Identity of the remote participant.
track_name	Track name to clear.

◆ clearOnAudioFrameCallback() [2/2]

void livekit::SubscriptionThreadDispatcher::clearOnAudioFrameCallback	(	const std::string &	participant_identity,
		TrackSource	source
	)

Remove an audio callback registration and stop any active reader.

If an audio reader thread is active for the given key, its stream is closed and the thread is joined before this call returns.

Parameters

participant_identity	Identity of the remote participant.
source	Track source to clear.

◆ clearOnVideoFrameCallback() [1/2]

void livekit::SubscriptionThreadDispatcher::clearOnVideoFrameCallback	(	const std::string &	participant_identity,
		const std::string &	track_name
	)

Remove a video callback registration and stop any active reader.

If a video reader thread is active for the given key, its stream is closed and the thread is joined before this call returns.

Parameters

participant_identity	Identity of the remote participant.
track_name	Track name to clear.

◆ clearOnVideoFrameCallback() [2/2]

void livekit::SubscriptionThreadDispatcher::clearOnVideoFrameCallback	(	const std::string &	participant_identity,
		TrackSource	source
	)

Remove a video callback registration and stop any active reader.

If a video reader thread is active for the given key, its stream is closed and the thread is joined before this call returns.

Parameters

participant_identity	Identity of the remote participant.
source	Track source to clear.

◆ handleDataTrackPublished()

void livekit::SubscriptionThreadDispatcher::handleDataTrackPublished ( const std::shared_ptr< RemoteDataTrack > & track )

Notify the dispatcher that a remote data track has been published.

Room calls this when it receives a kDataTrackPublished event. For every registered callback whose (participant, track_name) matches, a reader thread is launched.

Parameters

track The newly published remote data track.

◆ handleDataTrackUnpublished()

void livekit::SubscriptionThreadDispatcher::handleDataTrackUnpublished ( const std::string & sid )

Notify the dispatcher that a remote data track has been unpublished.

Room calls this when it receives a kDataTrackUnpublished event. Any active data reader threads for this track SID are closed and joined.

Parameters

sid	The SID of the unpublished data track.

◆ handleTrackSubscribed()

void livekit::SubscriptionThreadDispatcher::handleTrackSubscribed	(	const std::string &	participant_identity,
		TrackSource	source,
		const std::string &	track_name,
		const std::shared_ptr< Track > &	track
	)

Start or restart reader dispatch for a newly subscribed remote track.

Room calls this after it has processed a track-subscription event and updated its publication state. If a matching callback registration exists, the dispatcher creates the appropriate stream type and launches a reader thread for the (participant, source) key.

If no matching callback is registered, this is a no-op.

Parameters

participant_identity	Identity of the remote participant.
source	Track source associated with the subscription.
track	Subscribed remote track to read from.

◆ handleTrackUnsubscribed()

void livekit::SubscriptionThreadDispatcher::handleTrackUnsubscribed	(	const std::string &	participant_identity,
		TrackSource	source,
		const std::string &	track_name
	)

Stop reader dispatch for an unsubscribed remote track.

Room calls this when a remote track is unsubscribed. Any active reader stream for the given (participant, source) key is closed and its thread is joined. Callback registration is preserved so future re-subscription can start dispatch again automatically.

Parameters

participant_identity	Identity of the remote participant.
source	Track source associated with the subscription.
track_name	Track name associated with the subscription.

◆ removeOnDataFrameCallback()

void livekit::SubscriptionThreadDispatcher::removeOnDataFrameCallback ( DataFrameCallbackId id )

Remove a data frame callback previously registered via addOnDataFrameCallback(). Stops and joins the active reader thread for this subscription. No-op if the ID is not (or no longer) registered.

Parameters

id	The identifier returned by addOnDataFrameCallback().

◆ setOnAudioFrameCallback() [1/2]

void livekit::SubscriptionThreadDispatcher::setOnAudioFrameCallback	(	const std::string &	participant_identity,
		const std::string &	track_name,
		AudioFrameCallback	callback,
		AudioStream::Options	opts = `{}`
	)

Register or replace an audio frame callback for a remote subscription.

The callback is keyed by remote participant identity plus track_name. If the matching remote audio track is already subscribed, Room may immediately call handleTrackSubscribed to start a reader.

Parameters

participant_identity	Identity of the remote participant.
track_name	Track name to match.
callback	Function invoked for each decoded audio frame.
opts	Options used when creating the backing AudioStream.

◆ setOnAudioFrameCallback() [2/2]

void livekit::SubscriptionThreadDispatcher::setOnAudioFrameCallback	(	const std::string &	participant_identity,
		TrackSource	source,
		AudioFrameCallback	callback,
		AudioStream::Options	opts = `{}`
	)

Register or replace an audio frame callback for a remote subscription.

The callback is keyed by remote participant identity plus source. If the matching remote audio track is already subscribed, Room may immediately call handleTrackSubscribed to start a reader.

Parameters

participant_identity	Identity of the remote participant.
source	Track source to match.
callback	Function invoked for each decoded audio frame.
opts	Options used when creating the backing AudioStream.

◆ setOnVideoFrameCallback() [1/2]

void livekit::SubscriptionThreadDispatcher::setOnVideoFrameCallback	(	const std::string &	participant_identity,
		const std::string &	track_name,
		VideoFrameCallback	callback,
		VideoStream::Options	opts = `{}`
	)

Register or replace a video frame callback for a remote subscription.

The callback is keyed by remote participant identity plus track_name. If the matching remote video track is already subscribed, Room may immediately call handleTrackSubscribed to start a reader.

Parameters

participant_identity	Identity of the remote participant.
track_name	Track name to match.
callback	Function invoked for each decoded video frame.
opts	Options used when creating the backing VideoStream.

◆ setOnVideoFrameCallback() [2/2]

void livekit::SubscriptionThreadDispatcher::setOnVideoFrameCallback	(	const std::string &	participant_identity,
		TrackSource	source,
		VideoFrameCallback	callback,
		VideoStream::Options	opts = `{}`
	)

Register or replace a video frame callback for a remote subscription.

The callback is keyed by remote participant identity plus source. If the matching remote video track is already subscribed, Room may immediately call handleTrackSubscribed to start a reader.

Parameters

participant_identity	Identity of the remote participant.
source	Track source to match.
callback	Function invoked for each decoded video frame.
opts	Options used when creating the backing VideoStream.

◆ stopAll()

void livekit::SubscriptionThreadDispatcher::stopAll ( )

Stop all readers and clear all callback registrations.

This is used during room teardown or EOS handling to ensure no reader thread survives beyond the lifetime of the owning Room.

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

include/livekit/subscription_thread_dispatcher.h

Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ addOnDataFrameCallback()

◆ clearOnAudioFrameCallback() [1/2]

◆ clearOnAudioFrameCallback() [2/2]

◆ clearOnVideoFrameCallback() [1/2]

◆ clearOnVideoFrameCallback() [2/2]

◆ handleDataTrackPublished()

◆ handleDataTrackUnpublished()

◆ handleTrackSubscribed()

◆ handleTrackUnsubscribed()

◆ removeOnDataFrameCallback()

◆ setOnAudioFrameCallback() [1/2]

◆ setOnAudioFrameCallback() [2/2]

◆ setOnVideoFrameCallback() [1/2]

◆ setOnVideoFrameCallback() [2/2]

◆ stopAll()