Data track integration by 1egoman · Pull Request #1820 · livekit/client-sdk-js

1egoman · 2026-02-20T20:36:27Z

Integrates the data track managers (both incoming and outgoing) into the existing sdk Room and RemoteParticipant interfaces. Once this is merged, data tracks is fully implemented!

Interface - Publishing

const localDataTrack = await room.publishDataTrack({name: "data track name"});
await localDataTrack.tryPush(new Uint8Array(/* ... */));

// Once you are done with the local data track, it can be unpublished:
await localDataTrack.unpublish();

Interface - Subscribing

// There are two ways to get a remote data track, either a room event:
room.on(RoomEvent.RemoteDataTrackPublished, async (remoteDataTrack) => {
  // ...
});

// Or a new field on `RemoteParticipant`:
const remoteDataTrack = remoteParticipant.dataTracks.get("track name"); // Get a data track which has been published
const remoteDataTrack = await remoteParticipant.dataTracks.getDeferred("track name"); // Get a data track which _will_ be published shortly

// Either way, once you have a remoteDataTrack, you can subscribe:
const stream = await remoteDataTrack.subscribe(/* optional abort signal */);
for await (const frame of stream) {
  console.log(`Received bytes from ${remoteDataTrack.info.name}:`, frame.payload);
}

Todo:

Decide on how to show the example app chart vs hexdump - show both? Just one? commit introducing chart.
Add changeset

changeset-bot · 2026-02-20T20:36:34Z

⚠️ No Changeset found

Latest commit: e5dc9ae

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

examples/demo/demo.ts

github-actions · 2026-02-24T21:53:43Z

size-limit report 📦

Path	Size
dist/livekit-client.esm.mjs	94.71 KB (+9.17% 🔺)
dist/livekit-client.umd.js	103.49 KB (+6.34% 🔺)

src/utils/waitable-map.ts

src/room/data-track/LocalDataTrack.ts

src/room/participant/RemoteParticipant.ts

lukasIO · 2026-03-16T16:34:52Z

src/room/events.ts

+  /**
+   * Emits when a new data track has been published by a downstream participant.
+   */
+  RemoteDataTrackPublished = 'remoteDataTrackPublished',


Suggested change

RemoteDataTrackPublished = 'remoteDataTrackPublished',

DataTrackPublished = 'dataTrackPublished',

conforms with existing TrackPublished and TrackUnpublished APIs which are remote if not explicitly prefixed with Local

usually we would also proxy the events as a ParticipantEvent and emit it directly on the participant.
If we want it to feel a bit closer to how existing APIs work, that might be a good idea here, too

conforms with existing TrackPublished and TrackUnpublished APIs which are remote if not explicitly prefixed with Local

Ah, good point - updated.

usually we would also proxy the events as a ParticipantEvent and emit it directly on the participant.
If we want it to feel a bit closer to how existing APIs work, that might be a good idea here, too

Looking at the current participant events, it looks like they are segmented by locality rather than type. ie:

trackPublished: (publication: RemoteTrackPublication) => void; // ... trackUnpublished: (publication: RemoteTrackPublication) => void; // ... localTrackPublished: (publication: LocalTrackPublication) => void; localTrackUnpublished: (publication: LocalTrackPublication) => void;

Because of this, I'm sort of of the opinion to hold off on proxying these events to the participant until the larger track changes get rolled out across everything, and then at that point we can get these all going through the same interfaces rather than tacking on some additional data track specific events to this list. Any concerns with that approach?

src/room/events.ts

src/utils/waitable-map.ts

src/room/data-track/LocalDataTrack.ts

lukasIO · 2026-03-16T16:49:53Z

src/room/data-track/LocalDataTrack.ts

+
+  /** Publish the track to the SFU. This must be done before calling {@link tryPush} for the first time. */
+  async publish(signal?: AbortSignal) {
+    try {


I guess this should error early (or warn and return) if isPublished is true?

There is already an error that gets thrown within publishRequest if the track is already published, but I could probably make the error message a little nicer (right now it is one of those "panic" bare errors).

IMO in this case, I think an explicit throw makes sense because you really should not be publishing / unpublishing data tracks without some care. But looking at the existing tracks it looks like it just warns and that's it. So maybe it makes sense to convert this throw into a warning, not sure.

EDIT: more thoughts on this here!

lukasIO · 2026-03-16T16:51:23Z

src/room/data-track/LocalDataTrack.ts

+   * */
+  async unpublish() {
+    if (!this.handle) {
+      throw DataTrackPushFrameError.trackUnpublished();


suggestion: might be enough to log a warning here and return early?

Yea I am not sure - see my previous comment about the throw vs warning here. I like the hard error in that it is something that can be caught and explicitly handled though since this is checking an invariant. The existing track publication logic for audio / video tracks logs a warning so maybe it makes sense to update it to be consistent.

I guess one downside to the hard error is it opens this code up to a TOC-TOU issue where something like the below could happen:

if (track.isPublished) { // Imagine here the track is unpublished at the SFU level for some unrelated reason ... await track.unpublish(); // ... so this would then throw an error }

I am definitely curious what others think here!

src/room/data-track/LocalDataTrack.ts

Lukas has some reservations: #1820 (comment)

…as rust

After doing this I was able to get it to work end to end!

Example of where this can be triggered is specifying an empty name when creating a new data track.

Temporarily replace the hexdump with a chart for a demo. I think this probably should be reverted though, the hexdump is more useful longer term.

…ks data channel Adds a "sendLossyBytes" method which hooks into the existing data channel logging / buffer status / etc infrastructure.

…urn DataTrackSubscriptionReader instead of ReadableStream" This reverts commit ee2d5ed.

The api now looks like: const readableStream = track.subscribe({ signal }); for await (const frame of readableStream) { // Do something with `frame` } Manual cancellation can be done with `signal` OR `readableStream` - they should act identically.

…sts can determine sfu subscription completion

…ion api

This is a pretty rare case but could occur in theory

This was updated at the SFU level.

examples/demo/demo.ts

ladvoc · 2026-03-18T19:01:21Z

src/room/participant/LocalParticipant.ts

+            error = DataTrackPublishError.limitReached(response.message);
+            break;
+          default:
+            this.log.error(


question: If later new error reasons are added for data track operations, would we want to log an error on older client or introduce an unknown case?

Good point, I hadn't considered this. It looks like the rust implementation is raising an error in this case currently - a PublishError::Internal.

I will do something similar here (2d58fee) but in regards to the name: What do you think about ::Unknown for this case in both js / rust, or maybe something else that is specific for this exact case? Internal is being used as a catch all in a few other places so it isn't unique.

src/room/participant/LocalParticipant.ts

ladvoc · 2026-03-18T19:03:20Z

src/room/events.ts

+  /**
+   * Emits when a new data track has been published by a downstream participant.
+   */
+  DataTrackPublished = 'dataTrackPublished',


comment: In Rust, this event is called RemoteDataTrackPublished.

This was a change lukas requested, more info here: #1820 (comment)

ladvoc · 2026-03-18T19:05:45Z

src/room/Room.ts

+      .on('sfuUpdateSubscription', (event) => {
+        this.engine.client.sendUpdateDataSubscription(event.sid, event.subscribe);
+      })
+      .on('trackAvailable', (event) => {


question: Would it make sense to rename the manager level events for consistency with the room level ones (e.g., published instead of available)? Will do this in Rust too if you end up changing it.

Good point, renamed here: e5dc9ae

ladvoc

LGTM ✅

src/room/data-track/RemoteDataTrack.ts

… are active The message from the SFU doesn't contain all participant identities, only the ones which change.

examples/data-tracks/data-tracks-demo.ts

This allows multiple different versions of the app to run and all join the same room

examples/demo/demo.ts

…eOptions

…ackUnpublished

github-advanced-security bot found potential problems Feb 20, 2026

View reviewed changes

1egoman mentioned this pull request Feb 25, 2026

Data tracks - incoming manager #1819

Merged

1egoman force-pushed the data-track-integration branch 2 times, most recently from 2f31fbc to 6a5960d Compare February 25, 2026 21:48

1egoman force-pushed the data-track-integration branch from 6a5960d to 2e6f8cf Compare March 5, 2026 20:51

1egoman changed the title ~~(WIP) Data track integration~~ Data track integration Mar 5, 2026

ladvoc self-requested a review March 6, 2026 22:09

lukasIO reviewed Mar 10, 2026

View reviewed changes

src/utils/waitable-map.ts Outdated Show resolved Hide resolved

lukasIO reviewed Mar 10, 2026

View reviewed changes

src/utils/waitable-map.ts Outdated Show resolved Hide resolved

pblazej reviewed Mar 16, 2026

View reviewed changes

src/room/data-track/LocalDataTrack.ts Show resolved Hide resolved

pblazej reviewed Mar 16, 2026

View reviewed changes

src/room/participant/RemoteParticipant.ts Outdated Show resolved Hide resolved

lukasIO reviewed Mar 16, 2026

View reviewed changes

1egoman force-pushed the data-track-integration branch from 2619816 to 8e7a138 Compare March 16, 2026 17:40

1egoman added a commit that referenced this pull request Mar 16, 2026

fix: make LocalDataTrack.publish internal for now

d88e3b5

Lukas has some reservations: #1820 (comment)

1egoman marked this pull request as ready for review March 16, 2026 18:38

1egoman added 13 commits March 17, 2026 13:42

feat: initial pass at integrating data tracks via similar interfaces …

df8e4c8

…as rust

feat: wire up local data track publishing

6db9301

feat: add remote data tracks to example

3c2b632

feat: add remote data track unpublished event

e49c460

fix: clear remote data track list on disconnect

6769472

feat: add seperate data track data channel per rust implementation

d7ba7b4

After doing this I was able to get it to work end to end!

feat: clean up example and fix a lot of minor bugs

ff6d6d1

feat: add invalid name error

9ce387a

Example of where this can be triggered is specifying an empty name when creating a new data track.

feat: remove disabling input with published / unpublished state

a9c4b22

refactor: move videos / screenshare into main column

0e28bd2

feat: replace hexdump with chart (REVERT THIS)

ec372eb

Temporarily replace the hexdump with a chart for a demo. I think this probably should be reverted though, the hexdump is more useful longer term.

feat: refactor RTCEngine to add first class support for the data trac…

bfd279a

…ks data channel Adds a "sendLossyBytes" method which hooks into the existing data channel logging / buffer status / etc infrastructure.

fix: run npm run format

9e2bdb9

1egoman added 12 commits March 18, 2026 09:20

Revert "feat: make some changes to the data track subscription to ret…

9dc05e5

…urn DataTrackSubscriptionReader instead of ReadableStream" This reverts commit ee2d5ed.

fix: run npm run format

051106e

fix: add missing awaits to test assertions

89c9ab8

fix: ensure that readable stream is complete after cancellation

cb870af

feat: return sfu subscription promise from createReadableStream so te…

3359552

…sts can determine sfu subscription completion

feat: update tests to take into account new synchronous sfu subscript…

506bdba

…ion api

refactor: rename createReadableStream -> openSubscriptionStream

31f0106

feat: update main demo to use sync data track subscription api

0dc2c07

fix: run npm run format

eabe0cc

feat; add missing sfuSubscriptionComplete reject in onAbort

ceecf68

This is a pretty rare case but could occur in theory

fix: make data track extension lengths no longer rtp oriented

17e1cf5

This was updated at the SFU level.

github-advanced-security bot found potential problems Mar 18, 2026

View reviewed changes

examples/demo/demo.ts Fixed Show fixed Hide fixed

examples/demo/demo.ts Dismissed Show dismissed Hide dismissed

examples/demo/demo.ts Dismissed Show dismissed Hide dismissed

examples/demo/demo.ts Fixed Show fixed Hide fixed

ladvoc reviewed Mar 18, 2026

View reviewed changes

src/room/participant/LocalParticipant.ts Show resolved Hide resolved

ladvoc reviewed Mar 18, 2026

View reviewed changes

feat: add standalone data tracks example

d40d70c

ladvoc approved these changes Mar 18, 2026

View reviewed changes

ladvoc reviewed Mar 18, 2026

View reviewed changes

src/room/data-track/RemoteDataTrack.ts Show resolved Hide resolved

fix: address bug in data track subscription when multiple subscribers…

1009b4d

… are active The message from the SFU doesn't contain all participant identities, only the ones which change.

github-advanced-security bot found potential problems Mar 18, 2026

View reviewed changes

1egoman added 3 commits March 18, 2026 15:24

fix: rename highWaterMark to bufferSize at jacob's suggestion

562c606

fix: set a static room name in the example

f67ae2b

This allows multiple different versions of the app to run and all join the same room

feat: port inbuilt demo example back to use hexdump

0a4a335

github-advanced-security bot found potential problems Mar 18, 2026

View reviewed changes

examples/demo/demo.ts Dismissed Show dismissed Hide dismissed

examples/demo/demo.ts Dismissed Show dismissed Hide dismissed

1egoman added 4 commits March 19, 2026 09:18

refactor: rename RemoteDataTrackSubscribeOptions -> DataTrackSubscrib…

2806c6a

…eOptions

feat: ensure DataTrackSubscribeOptions is exported from the package

30d8fc7

feat: add explicit "unknown" case for data track publishing

2d58fee

feat: rename trackAvailable -> trackPublished, trackUnavailable -> tr…

e5dc9ae

…ackUnpublished

	RemoteDataTrackPublished = 'remoteDataTrackPublished',
	DataTrackPublished = 'dataTrackPublished',

Conversation

1egoman commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Interface - Publishing

Interface - Subscribing

Uh oh!

changeset-bot bot commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

lukasIO Mar 16, 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!

1egoman Mar 16, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1egoman Mar 19, 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!

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 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

1egoman commented Feb 20, 2026 •

edited

Loading

changeset-bot bot commented Feb 20, 2026 •

edited

Loading

github-actions bot commented Feb 24, 2026 •

edited

Loading

lukasIO Mar 16, 2026 •

edited

Loading

1egoman Mar 16, 2026 •

edited

Loading

1egoman Mar 19, 2026 •

edited

Loading