Repository navigation
Conversation
…sendFile Incoming data streams were rebuilt from the low-level stream_header/chunk/ trailer events. Since livekit-ffi 0.15.0 always advertises data streams v2, modern senders send C++ participants single-packet and deflate-compressed streams, which that path can't read: inline streams hang readAll() forever and compressed chunks arrive as raw deflate bytes. The FFI also handed C++ an owned reader handle for every incoming stream, which C++ ignored, so every stream's content stayed buffered in the FFI for the life of the process. Receive: - Room consumes text/byte_stream_opened: unhandled topics drop the reader handle; handled topics start read_incremental and route the resulting *_stream_reader_events (keyed by reader handle) to the reader. The low-level stream_*_received events are now ignored. - Readers surface abnormal ends (sender close reason, size limit, disconnect) as DataStreamError after draining buffered chunks, merge end-of-stream attributes into info() on the reading thread, gain close(), and ByteStreamReader gains readAll(). Room shutdown wakes blocked readers. - RoomOptions::data_stream.max_payload_byte_length sets the receive limit. Send: - LocalParticipant::sendText / sendBytes / sendFile use the FFI one-shot sends (compression and single-packet delivery when recipients support them). They throw DataStreamError on failure and refuse to reach the FFI once the room has disconnected, since the FFI panics there. TextStreamOpenedEvent / ByteStreamOpenedEvent::reader_handle stays 0 and is documented as deprecated. Existing writers are unchanged (v1 framing is still accepted by FFI readers). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1egoman
commented
Nov 20, 2026
| /// | ||
| /// Derives from std::runtime_error, so existing | ||
| /// `catch (const std::runtime_error&)` handlers keep working. | ||
| class LIVEKIT_API DataStreamError : public std::runtime_error { |
Author
There was a problem hiding this comment.
Open question: the new data stream calls throw DataStreamError. Readers now also throw when a stream ends with an error (see readNext below), where they used to return truncated data silently. That keeps the existing data stream API's throw style, but AGENTS.md prefers Result<T, E> for typed errors, and the reader change is a behaviour change for existing callers. Is throwing the right call, or should these return Result / expose an error() accessor instead?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First of two PRs that move C++ data streams onto the livekit-ffi data streams API, the same port Python did in python-sdks#769. This one fixes receiving. The writer port is stacked on top of it in the follow-up PR.
Why
Since #318 (livekit-ffi 0.15.0), the FFI always advertises data streams v2 for every client. JS, Swift, Android, Python, Node, Rust and Unity senders therefore send C++ participants single-packet ("inline") and deflate-compressed streams. C++ rebuilt streams from the low-level
stream_header/chunk/trailer_receivedevents, which can't represent v2 traffic:readAll()hangs forever.text/byte_stream_opened. C++ ignored it, so the FFI kept each stream's full content buffered for the life of the process.C++-to-C++ still worked only because C++ sends v1 framing.
What changes
Receive
Roomconsumestext/byte_stream_opened:*_read_incrementaland routes the resulting*_stream_reader_events (keyed by reader handle) to the reader.stream_*_receivedevents are now ignored.TextStreamReader/ByteStreamReader:DataStreamError, after any buffered chunks have been returned.close()stops reading early and wakes blocked reads.ByteStreamReader::readAll()."Disconnected while receiving".RoomOptions::data_stream.max_payload_byte_lengthsets the receive size limit.Send
LocalParticipant::sendText/sendBytes/sendFile(one-shot sends, compressed and single-packet when recipients support it). They block likeperformRpcand throwDataStreamErroron failure.StreamTextOptions/StreamByteOptions, withcompressdefaulting to true.unwrap()s the session there, and C++ turns an FFI panic intoSIGTERM.API compatibility: source compatible. Everything is additive except the behaviour change below.
TextStreamOpenedEvent/ByteStreamOpenedEvent::reader_handlestays 0 and is now documented@deprecated. Existing writers are untouched here; FFI readers accept their v1 framing.Behaviour change: readers now throw when a stream ends abnormally. Before, they silently returned truncated data.
Notes for reviewers
Room, not per-readerFfiClientlisteners. The plan suggested one listener per reader. Routing through the room's existing listener avoids N listeners (each FFI event fans out to every listener) and any remove-listener-from-own-callback issues. It also keeps reader lifetime simple: the room holds the reader until EOS or shutdown.info()data race.info()returned a reference that the FFI thread mutated at end of stream. End-of-stream attributes are now merged on the reading thread, whenreadNext()/readAll()reaches the end. Theconst&signature is unchanged, andinfo()is documented as not safe to call concurrently withreadNext().readNext()logs a warning if it would block on the FFI callback thread. That thread also delivers chunks, so blocking there is a real deadlock risk; this is now documented on the handler APIs.FfiClient::shutdown()is safe in C++ (pitfall 6 / python-sdks#857). The FFI library stays loaded, anddrop_handleafter dispose is a map removal.Testing
All runs were local on macOS arm64, against
livekit-server --devwith tokens fromscripts/set-test-tokens.sh.close()waking a blocked read, attribute merge)RoomOptions.data_stream→ protoDataStreamE2ETest: 17/17 pass (3 existing, 14 new):sendTextsmall, 50 KB compressed, uncompressed, and multi-byte Unicode across chunk boundariessendBytessendFile, plus a missing fileclose()waking a pending readStreamHandlesAreReleasedsends 20 streams on an unhandled topic plus one handled stream, then checks that every reader handle is gone from the FFI. With the unhandled-topic drop removed, the test fails ("reader handle N was leaked").LIVEKIT_CREATE_TOKEN_URLlocally). 5 fail, and all 5 also fail onmainon this machine:DataTrackE2ETest.{DefineAndGetSchema, DefineAndGetCustomSchemaEncoding, DefineDuplicateSchemaFails}RoomTest.ServerDeletedRoomDisconnectsAndTearsDownLocallyPlatformAudioIntegrationTest.PlatformAudioFramesReachRemote(local audio device)livekit1.3.0) calledsend_textwith a short message and a 50 KB message to a C++ receiver:main, the C++ side received 0 of 2 streams; both hung../scripts/generate-docs.shpasses with no warnings.check_no_private_symbols.pypasses on a release build.cpp-tools/clang-format.shwrapper fails to parse under macOS's bash 3.2.uint64_t/size_tconversions and thesendFilebasename handling on Windows.Not in this PR
cpp-example-collection/simple_data_streamupdate is deferred and will be a follow-up.sendBytes, compression, limits) and changelog notes should follow once a release ships.🤖 Generated with Claude Code