Skip to content

AGENTS.md

Latest commit

 

History

History
285 lines (213 loc) · 15.7 KB

AGENTS.md

File metadata and controls

285 lines (213 loc) · 15.7 KB

AGENTS.md — LiveKit C++ Client SDK

Project Overview

This is client-sdk-cpp, the official LiveKit C++ client SDK. It wraps a Rust core (client-sdk-rust/) via a protobuf-based FFI bridge. All WebRTC, networking, and media logic lives in Rust; the C++ layer provides an ergonomic API for C++ consumers.

Architecture

Core Principle

Rust owns as much of the business logic as possible. The C++ layer should be a thin wrapper around the Rust core. If a feature may be used by another SDK it should be implemented in Rust. Since this is an SDK, ensure backwards compatibility is maintained when possible.

Platform Support

The SDK must be supported on the following platforms:

  • windows x64
  • linux x86_64
  • linux arm64
  • macOS x86_64
  • macOS arm64

FFI Patterns

SDK features follow one of two FFI patterns:

Synchronous calls:

  1. Serialize a protobuf FfiRequest message.
  2. Send it to Rust via FfiClient::instance().sendRequest(req).
  3. Receive a FfiResponse with the result.
  4. Expose the result through the C++ API.

Asynchronous calls:

  1. Set up an async handler that listens for an event keyed by a request_async_id.
  2. Serialize a protobuf FfiRequest message containing the request_async_id.
  3. Send it to Rust via FfiClient::instance().sendRequest(req).
  4. Receive a synchronous FfiResponse (acknowledgement) and, later, an asynchronous FfiEvent callback with the actual result.
  5. Expose the result through the C++ API.

When making larger scale changes, check with the developer before committing to architecture changes involving changes to the client-sdk-rust/ submodule.

Threading Model

The SDK has three categories of threads:

FFI callback thread — The Rust FFI layer calls LivekitFfiCallback from a Rust-managed thread (typically a Tokio runtime thread). This single entry point deserializes the FfiEvent and calls FfiClient::PushEvent, which:

  1. Completes any pending async std::promise matched by async_id.
  2. Invokes all registered FfiClient listeners (including Room::OnEvent).

All RoomDelegate callbacks and stream handler callbacks (e.g., registerTextStreamHandler) are invoked on this FFI callback thread. Handlers must not block; spawn a background thread if synchronous work is needed.

Per-subscription reader threads — SubscriptionThreadDispatcher creates a dedicated std::thread for each active audio, video, or data track subscription. These threads block on AudioStream::read(), VideoStream::read(), or DataTrackStream::read() and invoke the registered AudioFrameCallback, VideoFrameCallback, or DataFrameCallback on that reader thread — not on the FFI callback thread. A hard limit of 20 concurrent reader threads is enforced.

Application threads — The calling thread for public API methods such as Room::Connect, LocalParticipant::publishTrack, AudioSource::captureFrame, etc. These may block while waiting for FFI responses or future completion.

Thread-safety guarantees

Component Thread-safe? Notes
FfiClient::sendRequest Yes (C++ side) No C++ mutex; relies on the Rust FFI being safe for concurrent calls. Multiple threads may call concurrently.
FfiClient listener/async registration Yes Protected by internal std::mutex.
Room Yes Internal std::mutex protects all mutable state. RoomDelegate is called outside the lock.
SubscriptionThreadDispatcher Yes Internal std::mutex protects registrations and active readers. Thread joins happen outside the lock.
AudioStream / VideoStream / DataTrackStream Yes Internal std::mutex + condition_variable coordinate the FFI producer thread and the consumer reader thread.
AudioSource::captureFrame No Not safe to call concurrently from multiple threads.
VideoSource::captureFrame No Not safe to call concurrently from multiple threads.
LocalAudioTrack / LocalVideoTrack No Thin sendRequest wrappers with no internal synchronization.
LocalDataTrack::tryPush No Thin sendRequest wrapper with no internal synchronization.
TextStreamWriter / ByteStreamWriter Serialized write() is serialized by an internal write_mutex_.

Directory Layout

Be sure to update the directory layout in this file if the directory layout changes.

Path Description
include/livekit/ Public API headers (what SDK consumers include)
src/ Implementation files and internal-only headers (ffi_client.h, lk_log.h, etc.)
src/tests/ Google Test integration and stress tests
examples/ In-tree example applications
bridge/ Deprecated C-style bridge layer — do not add new functionality
client-sdk-rust/ Git submodule holding the Rust core of the SDK
client-sdk-rust/livekit-ffi/protocol/*.proto FFI contract (protobuf definitions, read-only reference)
cmake/ Build helpers (protobuf.cmake, spdlog.cmake, LiveKitConfig.cmake.in)
docker/ Dockerfile for CI and SDK distribution images
scripts/ Developer / CI helper scripts (e.g. clang-tidy.sh)
.github/workflows/ GitHub Actions CI workflows

Key Types

  • FfiClient — Singleton that sends FFI requests to Rust and dispatches event callbacks. Defined in src/ffi_client.h (internal).
  • FfiHandle — RAII wrapper for Rust-owned resource handles; drop releases the FFI resource.
  • Room — Central object for connecting to a LiveKit server room.
  • RoomDelegate — Virtual callback interface for room lifecycle events.
  • SubscriptionThreadDispatcher — Owns callback registrations and per-subscription reader threads for audio, video, and data tracks. Room delegates callback management here.
  • LocalParticipant / RemoteParticipant — Participant objects for publishing and receiving tracks.

Build

for building, use the build.sh script for Linux and macOS, and the build.cmd script for Windows. Do not invoke CMake directly to build the SDK. Updates to ./build.sh and ./build.cmd should be accompanied by updates to this file and the README.md file.

./build.sh debug              # Debug build
./build.sh debug-tests        # Debug build with tests
./build.sh debug-examples     # Debug build with examples
./build.sh release            # Release build
./build.sh release-tests      # Release build with tests
./build.sh release-examples   # Release build with examples
./build.sh build-all          # All of the above
./build.sh clean              # Clean build artifacts + local-install
./build.sh clean-all          # Full clean (C++ + local-install + Rust targets)

The build scripts pass an explicit job count to cmake --build --parallel. Set CMAKE_BUILD_PARALLEL_LEVEL to override the default detected logical CPU count.

Requirements: CMake 3.20+, C++17, Rust toolchain (cargo), protoc. On macOS: brew install cmake ninja protobuf abseil. On Linux: see the CI workflow for apt packages. spdlog is vendored automatically via FetchContent (or vcpkg on Windows) to avoid system conflicts.

SDK Packaging

./build.sh release --bundle --prefix /path/to/install

This installs headers, libraries, and CMake config files so downstream projects can use find_package(LiveKit CONFIG).

Coding Conventions

Copyright Header

All source files must have the LiveKit Apache 2.0 copyright header. Use the current year for new files. Do not copyright externally pulled/cloned files.

Logging

  • Use LK_LOG_* macros from src/lk_log.h (internal header, not public API).
  • LK_LOG_ERROR — when something is broken.
  • LK_LOG_WARN — when something is unexpected but recoverable.
  • LK_LOG_INFO — initialization, critical state changes.
  • LK_LOG_DEBUG — potentially useful diagnostic info.
  • Do not spam logs. Keep it concise.
  • In production/internal SDK code, do not use std::cout, std::cerr, printf, or raw spdlog calls; use the logging APIs instead. Tests may use standard streams sparingly for ad hoc diagnostics when appropriate.
  • The public logging API is include/livekit/logging.h (setLogLevel, setLogCallback). spdlog is a private dependency — it must never leak into public headers.

Public API Surface

  • Keep public APIs small. Minimize what goes into include/livekit/.
  • Use #pragma once to guard headers.
  • All publicly visible symbols must use LIVEKIT_API macro (via include/livekit/visibility.h).
  • Never introduce backwards compatibility breaking changes to the public API.
  • lk_log.h lives under src/ (internal). The public-facing logging API is include/livekit/logging.h.
  • spdlog must not appear in any public header or installed header.

Include Conventions

  • Public headers (include/livekit/*.h) must include other public headers with the livekit/ prefix: #include "livekit/track.h", never the bare #include "track.h" form. The prefixed spelling matches what consumers see (#include <livekit/track.h>), resolves through the standard -I include/ search path rather than the implementation-defined "current directory first" rule of #include "...", and avoids accidental name collisions with third-party headers that happen to share short names like track.h.
  • Use double quotes for project headers (#include "livekit/foo.h") and angle brackets for system / third-party headers (#include <vector>, #include <gtest/gtest.h>).
  • Implementation files in src/ may include internal headers without a prefix (#include "ffi_client.h"); they are not part of the public surface and live alongside their consumers.
  • Test code (in-tree or external-style canaries) must consume public headers via <livekit/foo.h> to mirror real consumer usage

Symbol Visibility / Exported ABI

The livekit shared library is built with hidden symbol visibility on all platforms. Only symbols explicitly tagged with LIVEKIT_API (declared in include/livekit/visibility.h) are part of the public ABI. Vendored static dependencies are also compiled with hidden visibility so their symbols cannot leak into liblivekit.{so,dylib,dll}.

Rules for new code:

  • Mark any new public class, free function, or out-of-line static method with LIVEKIT_API. POD/aggregate structs and pure-inline classes do not need annotation because they emit no out-of-line symbols.
  • For internal symbols that must remain visible to in-tree tests (the tests link the same shared library), use LIVEKIT_INTERNAL_API. External consumers must not rely on these.
  • Do not add __declspec(dllexport) or __attribute__((visibility("default"))) by hand; always go through LIVEKIT_API / LIVEKIT_INTERNAL_API.
  • On Windows, WINDOWS_EXPORT_ALL_SYMBOLS is deliberately disabled for the livekit target. Use LIVEKIT_API to export.

The exported ABI is enforced by .github/scripts/check_no_private_symbols.py, run from the make-release.yml "Symbol leak check" CI step so a leak blocks the release build itself (it does not run on regular pushes/PRs). The script fails if nm/dumpbin reports any exported symbol matching a forbidden substring (currently spdlog::, fmt::v, google::protobuf, absl::). To run it locally, point it at the built shared library:

python3 .github/scripts/check_no_private_symbols.py \
    build-release/lib/liblivekit.dylib   # or .so / livekit.dll

When adding a new third-party library or vendored dependency to the SDK, update .github/scripts/check_no_private_symbols.py to add a forbidden substring pattern for the new dependency's namespace/symbol prefix. The denylist is intentionally explicit — a new dep that leaks symbols will otherwise silently pollute liblivekit.{so,dylib,dll} and clash at runtime with the same library loaded elsewhere in the host process.

Error Handling

  • Use LK_LOG_WARN for non-fatal unexpected conditions.
  • Use Result<T, E> for operations that can fail with typed errors (e.g., data track publish/subscribe).

Integer Types

  • Prefer fixed-width integer types from <cstdint> (std::int32_t, std::uint64_t, etc.) over raw primitive integer types when size or signedness matters.
  • This applies in public APIs, FFI/protobuf-facing code, serialized payloads, handles, timestamps, IDs, and any cross-platform boundary where integer width must be explicit.
  • Use raw primitive integer types only when the value is intentionally platform-sized or when preserving an existing public API is necessary for backwards compatibility.
  • Do not change an existing public API from a raw primitive integer type to a fixed-width type for style consistency alone unless the compatibility impact has been reviewed.

Git Practices

  • Use git mv when moving or renaming files.

CMake

  • spdlog is linked PRIVATE to the livekit target. It must not appear in exported/installed dependencies.
  • protobuf is vendored via FetchContent on non-Windows platforms; Windows uses vcpkg.
  • The CMake install produces a find_package(LiveKit CONFIG)-compatible package with LiveKitConfig.cmake, LiveKitTargets.cmake, and LiveKitConfigVersion.cmake.

Readability and Performance

Code should be easy to read and understand. If a sacrifice is made for performance or readability, it should be documented.

Adhere to clang-format checks configured in .clang-format. Run ./scripts/clang-format.sh if needed to confirm code styling, and ./scripts/clang-format.sh --fix to auto-format generated code created.

Static Analysis

Adhere to clang-tidy checks configured in .clang-tidy. Run ./scripts/clang-tidy.sh if needed to confirm code quality.

Dependencies

Dependency Scope Notes
protobuf Private (built-in) Vendored via FetchContent (Unix) or vcpkg (Windows)
spdlog Private FetchContent or system package; must NOT leak into public API
client-sdk-rust Build-time Git submodule, built via cargo during CMake build
Google Test Test only FetchContent in src/tests/CMakeLists.txt

When adding a new private/vendored dependency to this table, also add a forbidden symbol pattern for it to .github/scripts/check_no_private_symbols.py so the "Symbol leak check" CI step will fail loudly if its symbols escape the public ABI of liblivekit.

Testing

Tests are under src/tests/ using Google Test:

./build.sh debug-tests
cd build-debug && ctest

Integration tests (src/tests/integration/) cover: room connections, callbacks, data tracks, RPC, logging, audio processing, and the subscription thread dispatcher.

When adding new client facing functionality, add a new test case to the existing test suite. When adding new client facing functionality, add benchmarking to understand the limitations of the new functionality.

General C++ Development

  • Do not use dynamic memory allocation after initialization
  • Keep each function short (roughly ≤ 60 lines)
  • Declare all data objects at the smallest possible level of scope
  • Each calling function must check the return value of nonvoid functions, and each called function must check the validity of all parameters provided by the caller

Deprecated / Out of Scope

  • bridge/ (livekit_bridge) is deprecated. Do not add new functionality to it.

Common Pitfalls

  • A Room with auto_subscribe = false will never receive remote audio/video frames — this is almost never what you want.
  • A single participant cannot subscribe to its own tracks as "remote." Testing sender/receiver requires two separate room connections with distinct identities.
  • macOS dylibs require install_name_tool fixups for @rpath — the CMakeLists.txt handles this automatically. Do not manually adjust RPATH unless you understand the implications.
  • When consuming the installed SDK, use -DLIVEKIT_LOCAL_SDK_DIR=/path/to/sdk to point cmake at a local install instead of downloading a release tarball.