Data tracks support by ladvoc · Pull Request #586 · livekit/python-sdks

ladvoc · 2026-03-05T23:19:47Z

No description provided.

pblazej · 2026-03-16T10:46:53Z

Some things from talking to claude (maybe you find it useful):

SubscribeDataTrackError / PublishDataTrackError not exported
existing streams use aclose() (async), while DataTrackSubscription uses close() (sync); all of them can probably leverage https://www.geeksforgeeks.org/python/aenter-in-python/
no remote_data_track_unpublished event - just mirroring rust comment here
try_push should probably be push in python
remote_data_track_published should be data_track_published as other tracks
DataTrackFrame(payload=...) may validate the input type (what happens if you pass a string etc.)

livekit-rtc/livekit/rtc/data_track.py

1egoman · 2026-03-19T16:02:02Z

livekit-rtc/livekit/rtc/data_track.py

+    async def __anext__(self) -> DataTrackFrame:
+        if self._closed:
+            raise StopAsyncIteration
+
+        event: proto_ffi.FfiEvent = await self._queue.get()


question: Should the python implementation of data tracks be updated to have the synchronous track.subscribe() behavior which was implemented in javascript, with any subscription errors cascading down into the first iterator __anext__ call?

Discussed on slack with @ladvoc, we decided this behavior makes sense to do here as well!

livekit-rtc/livekit/rtc/data_track.py

livekit-rtc/livekit/rtc/participant.py

1egoman · 2026-03-20T13:49:23Z

livekit-rtc/livekit/rtc/data_track.py

        """Subscribes to the data track to receive frames.

+        Args:
+            buffer_size: Maximum number of received frames to buffer internally.


thought: I realize this could get out of date quickly if the default starts changing a bunch, but it might be nice to actually include the default value here (I think it is 16?).

Or maybe another alternative to sidestep that duplication concern could be to link to the future docs page (probably will be https://docs.livekit.io/transport/data/data-tracks/#buffer-size) where this is mentioned.

Yeah, I left that out here to avoid stale documentation in the future. Will make sure that is clear on the docs page.

Is there a significant downside to including the docs page in the docstring?

You mean a link to the docs? I'm on board with that once it's published! Ideally, links would be included for other APIs as well.

theomonnom · 2026-03-26T18:02:12Z

examples/data_tracks/subscriber.py

+        track.info.name,
+        track.publisher_identity,
+    )
+    subscription = await track.subscribe()


Should we have the same API as AudioTrack/VideoTrack for subscription?

data_track_subscribed event and set_subscribed

We opted to diverge from media tracks in a few places to make the API more convenient to use for its target use cases. A few reasons for this in particular:

Auto-subscribe is not supported for data tracks.

Unlike media tracks, there are options when subscribing. For now the only option is buffer size, but v2 will introduce options for which there aren't necessarily reasonable defaults (e.g., requested FPS).

Data tracks support fan-out: a user can call track.subscribe() more than once on the same track to handle frames in multiple places in their application (e.g., displaying in a UI and writing to an MCAP file).

theomonnom · 2026-03-26T18:02:59Z

livekit-rtc/livekit/rtc/data_track.py

+
+
+@dataclass
+class DataTrackOptions:


Let's use TypedDict

Addressed in c1e9bfb.

theomonnom · 2026-03-26T18:03:44Z

livekit-rtc/livekit/rtc/data_track.py

+
+
+@dataclass
+class DataTrackFrame:


For consistency should we use dataclass as well on other frames?

python-sdks/livekit-rtc/livekit/rtc/video_frame.py

Line 26 in 791bb46

class VideoFrame:

I'm not too familiar with the tradeoffs, but it seems like semantically DataTrackFrame is more of a simple value type compared to VideoFrame which has an initializer and methods? Happy to make the change here or in a follow-up PR if you think dataclass is a better fit though.

theomonnom · 2026-03-26T18:04:34Z

livekit-rtc/livekit/rtc/data_track.py

+    async def __anext__(self) -> DataTrackFrame:
+        if self._closed:
+            raise StopAsyncIteration
+
+        self._send_read_request()
+        event: proto_ffi.FfiEvent = await self._queue.get()
+        sub_event = event.data_track_subscription_event
+        detail = sub_event.WhichOneof("detail")
+
+        if detail == "frame_received":
+            proto_frame = sub_event.frame_received.frame
+            user_ts: Optional[int] = None
+            if proto_frame.HasField("user_timestamp"):
+                user_ts = proto_frame.user_timestamp
+            return DataTrackFrame(
+                payload=proto_frame.payload,
+                user_timestamp=user_ts,
+            )
+        elif detail == "eos":
+            self._close()
+            raise StopAsyncIteration
+        else:
+            self._close()
+            raise StopAsyncIteration


I don't think the user should be responsible for pulling here, can we have a main loop like VideoStream/AudioStream?

The risk is that it becomes easier for users to OOM their program

On the Rust side, each subscription uses a fixed-size receive buffer (configurable at subscribe time), and frames are dropped if the consumer can't keep up—so there's no risk of unbounded memory growth. The pull model here is intentional: the read request (L278) applies backpressure on the underlying Rust buffer, so frame events are only delivered as fast as they're processed in Python. This is different from VideoStream's approach, but the bounded buffer on the native side serves the same purpose as VideoStream's RingQueue. Please let me know if this addresses your concern.

theomonnom · 2026-03-26T18:05:29Z

livekit-rtc/livekit/rtc/participant.py


+    async def publish_data_track(
+        self,
+        options: Union[str, DataTrackOptions],


The Union is unnecessary complexity? OK if DataTrackOptions is a TypedDict?

Addressed in cad3c25. At the call site, this now looks like:

track = await room.local_participant.publish_data_track({"name": "my_sensor_data"})

Do you think keyword args would be cleaner here?

theomonnom · 2026-03-26T18:06:28Z

livekit-rtc/livekit/rtc/data_track.py

+        self._close()
+        self._ffi_handle.dispose()
+
+    def __del__(self) -> None:


No need for a destructor if we follow the main task pattern:

python-sdks/livekit-rtc/livekit/rtc/video_stream.py

Line 139 in 791bb46

async def _run(self) -> None:

theomonnom · 2026-03-26T18:06:34Z

livekit-rtc/livekit/rtc/data_track.py

+            self._closed = True
+            FfiClient.instance.queue.unsubscribe(self._queue)
+
+    def close(self) -> None:


close becomes async

ladvoc and others added 18 commits March 5, 2026 11:43

Pin submodule

c4e12dd

Update proto

61f4815

Add initial examples

159a198

Initial FFI implementation

1c603d5

Hide proto type

00c00ca

Improve error reporting

0d4c5d2

More generic type signature for try_push

671777d

Data class for frame

7bea8cb

Data class for track info

10e6561

Frame convenience methods

629d405

Doc strings

fb073be

generated protobuf

3a0a171

Refine example

7707e40

Format

869dcbb

Pin RTC

50a9a95

End-to-end test for data tracks

19a592a

Patch proto generation script

96ed624

generated protobuf

b98deb3

1egoman reviewed Mar 19, 2026

View reviewed changes

ladvoc added 3 commits March 19, 2026 16:21

Pin submodule

dcc4639

Generate proto

17008fa

Expose buffer size option

f2adba9

1egoman reviewed Mar 20, 2026

View reviewed changes

ladvoc added 6 commits March 24, 2026 14:13

Rename event

9e6784e

Expose unpublished event

b54ac64

Pin submodule

38a5ebb

Generate proto

b75cb34

Add explicit request to receive next frame for subscription

509fe32

Format

8d9c838

theomonnom reviewed Mar 26, 2026

View reviewed changes

ladvoc marked this pull request as ready for review March 26, 2026 18:42

This comment was marked as resolved.

Sign in to view

ladvoc added 5 commits March 27, 2026 11:56

Pin submodule

9a7378d

Generate proto

d794d98

Make subscribe method sync

8fe8de5

Use typed dict for options

c1e9bfb

Reduce type complexity

cad3c25

Conversation

ladvoc commented Mar 5, 2026

Uh oh!

pblazej commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ladvoc Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ladvoc Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ladvoc Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pblazej commented Mar 16, 2026 •

edited

Loading

ladvoc Mar 27, 2026 •

edited

Loading

ladvoc Mar 27, 2026 •

edited

Loading

ladvoc Mar 27, 2026 •

edited

Loading