Data tracks: core by ladvoc · Pull Request #990 · livekit/server-sdk-go

ladvoc · 2026-09-03T17:56:05Z

Adds core types (e.g., info, frame, schema, etc.) and packetizer/depacketizer.

Closes BOT-541

cnderrauber · 2026-09-11T03:08:56Z

+func (d *depacketizer) frameFromSingle(packet dtp.Packet, options depacketizerPushOptions) depacketizerPushResult {
+	var result depacketizerPushResult
+	if len(d.partials) >= options.maxPartialFrames {
+		result.drop = d.evictOldest(packet.FrameNumber)


The single frame has not been appended to the partials, do we still need to evict one?

A Single arriving while the partials map is at capacity is treated as a signal that the oldest in-flight partial is stale: the publisher has moved on to a later frame, and on an unordered channel with no retransmits its missing packets aren't coming. It doesn't change what gets dropped (the next Start would evict it anyway), only that the drop is reported promptly and attributed to the frame that actually superseded it. This matches the Rust implementation.

cnderrauber

LGTM!

boks1971

Left a bunch of small comment. Good stuff @ladvoc !

Would be good to act on the extension ID collision ASAP. I will look into moving the internal one to 255 and accept both on read side for a deploy and then we can replace ID at 1 with e2ee extension id.

boks1971 · 2026-09-29T06:42:06Z

+		nanos = 0
+	}
+	seconds, remainder := uint64(nanos)/1_000_000_000, uint64(nanos)%1_000_000_000
+	return uint32(seconds*clockRate + (remainder*clockRate+500_000_000)/1_000_000_000)


Can potentially make this simpler.

d.Seconds()

returns float64. So, you can just multiply that by clockRate and cast back to uint32 I think. Something like

return uint32(float64(clockRate) * d.Seconds())

May need bounds check though of < 0 or > something which will actually overflow uint32. I don't think there is great handling for greater than uint32 other than just let it wrap. So, maybe something like

return uint32(max(0, float64(clockRate) * d.Seconds()))

Went back and forth on this with an agent, and it pointed me to this:

In all non-constant conversions involving floating-point or complex values, if the result type cannot represent the value the conversion succeeds but the result value is implementation-dependent.

Which I think means the cast to uint32 may wrap on some arches and saturate on others if we use float64. For reference, this is the same calculation in the Rust implementation; the main difference there is Duration is guaranteed to not be negative.

boks1971 · 2026-09-29T06:53:24Z

+		return 0, errHandlesExhausted
+	}
+	a.value++
+	return trackHandle(a.value), nil


guessing this might be locked from outside. If not, should protect this.

Yes, handle allocator is owned by LocalManager (defined in #991) which locks this.

boks1971 · 2026-09-29T06:54:58Z

+var ErrInvalidSID = errors.New("invalid data track SID")
+
+// SID is the server-assigned identifier of a data track.
+type SID string


If you want a type, can we use livekit.TrackID? I think that is what server uses for all TrackID (both media and data)

Addressed in 5bf5e11.

boks1971 · 2026-09-29T08:44:47Z

+type depacketizerDropReason int
+
+const (
+	dropReasonInterrupted depacketizerDropReason = iota


I usually do the enum prefix fully depacketizerDropReason... so that collisions are avoided just in case and also makes me think less :-)

Addressed in d75e577.

boks1971 · 2026-09-29T08:47:05Z

+}
+
+func (d *depacketizer) push(packet dtp.Packet, options depacketizerPushOptions) depacketizerPushResult {
+	switch markerOf(&packet.Header) {


can this method be pushed to protocol? Yeah, server does not need that, but it may at some point if it has to do sub-sampling. Also feels cleaner to have all packet utilities there.

When server needs to depacketize, this whole thing could move to protocol too, but that is later. Would be good to have all packet utilities in protocol for now.

I agree, this is something that will likely be shared in the future. I'm assuming you're talking about the markerOf helper in particular?

Yeah, meant markerOf. Basically, anything to do with packet. Can be unit tested there.

boks1971 · 2026-09-29T09:43:19Z

+	"github.com/stretchr/testify/require"
+)
+
+var defaultPushOptions = depacketizerPushOptions{maxPartialFrames: 1}


Recommend renaming this to something like testDefaultPushOptions. defaultPushOptions seems like it is in the implementation.

Addressed in 9f576d9.

boks1971 · 2026-09-29T09:46:15Z

+	supportedVersion = 0
+
+	extensionIDE2EE          uint8 = 1
+	extensionIDUserTimestamp uint8 = 2


We have to fix this for the relay stuff. Maybe, we allocate 3 (or maybe the highest number for relay and in one version, the read side has to check for both)

And let us move these to proto definitions.

I moved most of this to livekit/protocol in livekit/protocol#1834 (except client specific parts) and integrated in 0e0a11b. I didn't add the extension IDs to the Protobuf enum over there yet since that would require re-naming DTEI_PARTICIPANT_SID_LOW—although maybe it is time to do that now. Let me know your thoughts.

Thank you @ladvoc . Let's wait on adding the extension IDs to the proto definition for a little bit more.

This is now defined in protocol - livekit/protocol#1861

boks1971 · 2026-09-29T10:07:53Z

+		return nil, errMTUTooShort
+	}
+	header.FrameNumber = p.frameNumber
+	p.frameNumber++


guessing there is locking outside

Correct, in #991, each local track owns a packetizer which it locks.

boks1971 · 2026-09-29T10:12:41Z

+		msg.FrameEncoding = frameEncodingToProto(info.FrameEncoding)
+	}
+	return msg
+}


Till this point, I think it can go into protocol. Also, feels like there may be some protobuf library to do some of this. I am not sure though.

For consistency with other client SDKs.

ladvoc force-pushed the ladvoc/data-track-core branch from f15a229 to b7b6532 Compare September 4, 2026 16:04

ladvoc marked this pull request as ready for review September 4, 2026 16:07

ladvoc requested a review from a team as a code owner September 4, 2026 16:07

ladvoc requested a review from boks1971 September 4, 2026 16:07

github-actions Bot added the slack-ts:cs-devs:1788538066.959249 label Sep 4, 2026

This comment was marked as resolved.

Sign in to view

ladvoc force-pushed the ladvoc/data-track-core branch from b7b6532 to 1c85018 Compare September 4, 2026 22:58

This comment was marked as resolved.

Sign in to view

ladvoc force-pushed the ladvoc/data-track-core branch from 5572d61 to dc69ba0 Compare September 8, 2026 21:55

cnderrauber reviewed Sep 11, 2026

View reviewed changes

ladvoc force-pushed the ladvoc/data-track-core branch 2 times, most recently from c9fa55a to ae3dc6f Compare September 14, 2026 21:28

ladvoc force-pushed the ladvoc/data-track-core branch from c2ca3f6 to 5692ffc Compare September 14, 2026 21:40

ladvoc requested a review from cnderrauber September 14, 2026 21:40

cnderrauber approved these changes Sep 15, 2026

View reviewed changes

ladvoc force-pushed the ladvoc/data-track-core branch from 5692ffc to 5810844 Compare September 22, 2026 16:46

ladvoc changed the title ~~Data tracks core~~ Data tracks: core Sep 22, 2026

boks1971 approved these changes Sep 29, 2026

View reviewed changes

ladvoc force-pushed the ladvoc/data-track-core branch from 5810844 to 0caac7c Compare October 5, 2026 22:15

ladvoc force-pushed the ladvoc/data-track-core branch from 0e0a11b to 3436ef7 Compare October 19, 2026 19:13

ladvoc added 3 commits October 19, 2026 12:31

Add datatrack package with schema types

ec52261

Add data track handle type and allocator

6616150

Add data track frame and info types

b7b76dc

ladvoc added 15 commits October 19, 2026 12:31

Add data track packet helpers and clock

0ad5272

Add data track packetizer

3bd7f06

Add data track depacketizer

c1a7dde

Add data track proto conversions

c4c54c2

Model schema and frame encodings as sealed interfaces

2f78e9c

Replace partial frames in place on repeated start

0be0ec1

For consistency with other client SDKs.

Rename timestampRate to clockRate

91fe703

Return explicit error when handles are exhausted

4a43c3e

Document why a single-packet frame evicts at capacity

b5f46dd

Return early from finalize when packet count does not match

036167c

Break timestamp comparison tie at half range

56ebf30

Use existing TrackID alias from livekit/protocol

ea9ca4d

Prefix all enum cases

4ded19f

Prefix name to avoid collision

737bf63

Use upstream support for client extensions

9283287

ladvoc force-pushed the ladvoc/data-track-core branch from 3436ef7 to 9283287 Compare October 19, 2026 20:05

ladvoc merged commit cd9f9aa into main Oct 21, 2026
9 checks passed

ladvoc deleted the ladvoc/data-track-core branch October 21, 2026 00:55

Conversation

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

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

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!

cnderrauber left a comment

Choose a reason for hiding this comment

Uh oh!

boks1971 left a comment

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 Oct 5, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ladvoc Oct 8, 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 Oct 6, 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!

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!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

ladvoc commented Sep 3, 2026 •

edited

Loading

ladvoc Oct 5, 2026 •

edited

Loading

ladvoc Oct 8, 2026 •

edited

Loading

ladvoc Oct 6, 2026 •

edited

Loading