|
LiveKit C++ Client SDK v1.13.1
Real-time audio/video/data SDK for C++
|
This document covers everything you need to build the LiveKit C++ SDK from source: prerequisites, cloning the repository, the build scripts, and advanced CMake/vcpkg flows.
| Platform | Compiler | Package manager |
|---|---|---|
| Linux | Clang 21+ with libclang (See here for rationale) | apt |
| macOS | Xcode 12+ Apple Clang (macOS 12.3+ for ScreenCaptureKit) | Homebrew |
| Windows | Visual Studio 2019+ (MSBuild or Ninja) | vcpkg (see below) |
These dependencies are linked by the SDK, used directly by its production C++ sources, or support optional repository targets.
| Dependency | Platform | Version | Source | How it is used |
|---|---|---|---|---|
client-sdk-rust / livekit_ffi | All | livekit_ffi pinned commit | Git submodule | Owns WebRTC, networking, media, and most business logic. The C++ SDK calls its C ABI and exchanges Protobuf FFI requests, responses, and events. Its shared library ships beside liblivekit. |
| Protobuf | All | 25.3 vendored; 5.29.5+ on Windows | Vendored / vcpkg | Generates and implements the FFI message types used throughout the C++ wrapper for rooms, tracks, streams, frames, statistics, RPC, encryption, and capture. |
| Abseil | All | 20240116.2 vendored; vcpkg-managed on Windows | Vendored / vcpkg | Supports the Protobuf build. Production C++ sources do not call Abseil APIs directly. |
| spdlog | All | 1.15.1 vendored; vcpkg-managed on Windows | Vendored / vcpkg | Implements the internal LK_LOG_* macros, default stderr logger, log-level filtering, and the public log callback adapter. |
| nlohmann/json | All | 3.12.0 vendored; vcpkg-managed on Windows | Vendored / vcpkg | Parses token-endpoint JSON responses and JWT payload claims. |
| Chromium trace-event code | All | Pinned source snapshot | Vendored source | Implements trace-event macros used by the production tracing API. Benchmark utilities consume the resulting Chromium-format traces, but Chromium is not a benchmark library dependency. |
| libcurl | Mac, Linux | System-provided | System library | Implements HTTP requests made by TokenSource. |
| OpenSSL | Linux | System-provided | System library | Linked into liblivekit. Current production C++ sources do not call OpenSSL APIs directly. |
| Apple system frameworks | Mac | OS-provided | System frameworks | Supplies the audio, video, graphics, security, UI, and ScreenCaptureKit frameworks required by the media stack. |
| WinHTTP | Windows | OS-provided | System library | Implements HTTP requests made by TokenSource. |
| Dependency | Platform | Version | Source | How it is used |
|---|---|---|---|---|
| GStreamer | All | Platform-provided | System library | Used by the Rust capture-gstreamer backend. The C++ capture API reaches it through the FFI; GStreamer headers are not exposed publicly. |
| Dependency | Platform | Version | Source | How it is used |
|---|---|---|---|---|
| GoogleTest | All | 1.14.0 | Vendored | Implements unit, integration, and stress test executables. It is not linked into SDK bundles. |
This section outlines the recommended dependency/environmental setup for each supported platform.
If you plan to build the example collection (SDL-based renderer + camera/mic capture), also install:
CMake's vcpkg manifest mode (below) reads vcpkg.json and installs the rest automatically the first time you configure.
The SDK uses recursive submodules for the Rust core, shared C++ tooling, and the C++ example collection.
The repo ships with build.sh (Linux/macOS) and build.cmd (Windows) that wrap the right CMake preset for your platform and pick sensible defaults.
Linux/macOS:
Windows:
GStreamer is required only when the selected sources include gstreamer. This includes --capture / --capture=all and release -capture bundles, which enable all three sources. Standard SDK builds and builds selecting only pattern, clock, or both do not require GStreamer.
For builds that include gstreamer, install GStreamer development libraries at build time and GStreamer libraries at runtime. The SDK does not redistribute these libraries or plugins. Install the runtime plugins required by your pipeline too. Pattern and clock sources need a compatible GPU adapter at runtime.
macOS: Install both the official universal runtime and development packages from the GStreamer downloads page. These packages support both x86_64 and arm64. Configure the framework paths:
Use one GStreamer installation method per machine to keep libraries and plugins consistent.
Ubuntu / Debian: Install the development packages and runtime plugins:
Windows: Install the MSVC x86_64 runtime and development components from the GStreamer downloads page. Add the installation's bin directory to PATH and its lib/pkgconfig directory to PKG_CONFIG_PATH.
For GStreamer builds, development files must be discoverable through pkg-config. You can verify that they are available with:
To create an installable SDK bundle with public headers, runtime libraries, and CMake package files, add --bundle --prefix <install-dir> to a build command:
Linux/macOS:
Windows:
The build scripts pass an explicit job count to cmake --build --parallel. Set CMAKE_BUILD_PARALLEL_LEVEL to override the auto-detected logical CPU count. Run ./build.sh help for additional packaging and configuration options, including --archive, --archive-name, --version, and -G.
For more control, drive CMake directly via the presets in CMakePresets.json:
Windows requires VCPKG_ROOT to be set:
vcpkg will automatically install all dependencies listed in vcpkg.json the first time you configure with its toolchain file. This dependency path is supported only on Windows. Linux and macOS use the vendored dependency paths described above.
| Option | Default | Description |
|---|---|---|
LIVEKIT_BUILD_EXAMPLES | OFF | Build example applications |
LIVEKIT_BUILD_TESTS | OFF | Build test executables |
LIVEKIT_USE_SYSTEM_PROTOBUF | OFF on Linux/macOS; ON on Windows | Select the platform dependency path; CMake forces the value |
LIVEKIT_LOG_LEVEL | TRACE | Compile-time log threshold (see logging.md) |
LIVEKIT_VERSION | 0.0.0 | SDK version string baked into the binary; set with --version or CMake |
LIVEKIT_CAPTURE | empty (none) | Capture sources for the Rust FFI (all, none, or a comma-separated list; see Capture sources) |
After a successful build:
Release archives use the same layout: include/, lib/, and (on Windows) bin/. The repository root also receives a compile_commands.json symlink. Example builds use local-install/ while configuring the example collection. The exact build-tree layout can vary with the CMake generator.
The easiest way to consume the SDK without building from source is via the cpp-example-collection helper, which downloads a release tarball at CMake configure time:
See the example collection's LiveKitSDK.cmake for the full pattern.
Prefer the CMake package above. It provides the correct include directory and the LiveKit::livekit shared-library target. If you link a release archive manually, add its include/ directory and link only the main SDK library:
| Platform | Link-time file | Runtime files to deploy |
|---|---|---|
| Windows | lib/livekit.lib | bin/livekit.dll and bin/livekit_ffi.dll beside the application executable |
| Linux | lib/liblivekit.so | liblivekit.so and liblivekit_ffi.so in the same runtime-library directory |
| macOS | lib/liblivekit.dylib | liblivekit.dylib and liblivekit_ffi.dylib in the same runtime-library directory |
Do not link the Rust FFI library directly: livekit already records it as a shared-library dependency. On Linux, liblivekit.so uses a $ORIGIN runpath to locate liblivekit_ffi.so next to it. On macOS, it uses @loader_path for the same purpose. Your application must still be configured to find liblivekit at runtime (for example, by using an appropriate executable RPATH or platform packaging mechanism).
Official release archives bundle the two SDK libraries above. They do not bundle, or dynamically depend on, Protobuf, Abseil, or OpenSSL. As of v1.7.0:
liblivekit.so additionally depends on the system C++ runtime, glibc, and libcurl.so.4; liblivekit_ffi.so depends on the system C++ runtime and glibc. Install the matching runtime packages for your target distribution.libcurl; no Homebrew Protobuf, Abseil, or OpenSSL runtime is required.These are release-artifact requirements, not source-build prerequisites. For an updated audit of a specific release, inspect its binaries with ldd (Linux), otool -L (macOS), or dumpbin /dependents (Windows).
Initialize submodules:
Some WebRTC sources use deprecated declarations. If ./build.sh release errors with -Werror=deprecated-declarations, relax it for the build:
On Linux, install clang-21 as shown above. Rust bindgen uses libclang to generate the libyuv bindings; this is separate from the Clang 21 compiler requirement imposed by libwebrtc's hermetic libc++. build.sh accepts both versioned libraries such as libclang-21.so.1 and an unversioned libclang.so. For a custom installation, set LLVM_ROOT or point LIBCLANG_PATH at its library directory. On macOS, install the Xcode Command Line Tools; build.sh selects Xcode Apple Clang with xcrun.
This was a historical issue; Rust only recompiles now when Rust source files change or the Rust library is missing.
On Linux and macOS, Protobuf, Abseil, spdlog, and nlohmann/json are fetched while CMake configures the project. Check network access and verify that all recursive submodules are initialized:
On Windows, make sure VCPKG_ROOT is set and pass the vcpkg toolchain file as shown above.
Not currently supported via our scripts — the Visual Studio (MSBuild) CMake generator doesn't produce compile_commands.json. The Ninja generator does; see tools.md.
Or clean one configured build tree with its CMake targets:
Replace build-release with build-debug for a Debug configuration.
The SDK places Rust FFI outputs in client-sdk-rust/target/cpp-<feature-hash>/. Deep checkout paths can make WebRTC header paths exceed the Windows path limit. Set CARGO_TARGET_DIR to a short absolute path before building, for example set CARGO_TARGET_DIR=C:\lk-rust in Command Prompt. The SDK appends the feature directory so different source selections have separate outputs. Windows CI uses this setting for builds, tests, and release bundles. clean-all removes the default Rust target directory; remove a custom root separately when it is no longer needed.
Capture is disabled by default. Select sources with -DLIVEKIT_CAPTURE=<value> or --capture[=list] / --no-capture.
Available sources (comma-separated; each maps to capture-* on livekit-ffi):
| Source | Description |
|---|---|
gstreamer | GStreamer pipelines (needs GStreamer at build and runtime) |
pattern | GPU test pattern |
clock | GPU wall clock |
Special values: none or empty (disabled), all (every source). LIVEKIT_CAPTURE_ENABLED is 1 when any source is selected; installed share/livekit/build-info.json also records cargo_features.
On Windows, use build.cmd release --capture --bundle --prefix sdk-out\livekit-sdk-capture. Windows also accepts source lists, for example build.cmd release --capture=pattern,clock. Custom CMake configurations use LIVEKIT_CAPTURE=all or a source list such as LIVEKIT_CAPTURE=pattern,clock.
The build scripts set LIVEKIT_CAPTURE. The generated numeric LIVEKIT_CAPTURE_ENABLED macro (0 or 1) supports #if checks in consumers. It indicates whether any source was compiled in; it does not identify which sources are available. Check cargo_features in share/livekit/build-info.json for the selected backends. Creating a source omitted from the SDK build fails through the returned future with std::runtime_error. Capture-enabled bundles install the public API under include/livekit/capture/; standard bundles omit that directory. Use <livekit/capture/capture_source.h> for direct inclusion. The source-tree header also rejects use in a standard build. share/livekit/build-info.json in an installed bundle describes the same build features; neither value tests whether a GPU or a requested GStreamer plugin is available at runtime.
Release downloads with -capture in their names include these features, for example livekit-sdk-macos-arm64-capture-<version>.tar.gz. Standard release bundles have capture disabled.
See Additional capture dependencies before building or running a capture-enabled SDK.
Rust artifacts are stored under client-sdk-rust/target/cpp-<feature-hash>/, with separate directories for each normalized source selection. Generated build.h files live in each CMake build directory, so feature metadata follows the installed SDK instead of another configuration's most recent build.
See Capture sources for dependencies and usage.
The SDK compiler requirement moved from GCC to Clang 21 when the core Rust SDK upgraded to WebRTC M150. LiveKit's M150 artifact is built with Chromium's hermetic libc++ and ships those same headers for the Rust webrtc-sys C++ bridge. Chromium built that artifact with Clang 23, while the shipped libc++ headers declare Clang 21 as their minimum supported compiler. Older Clang versions fail on newer builtins used by those headers. GCC is also unsuitable for this artifact because it does not preserve the required libc++ trivial_abi calling conventions.
The SDK also heavily used Clang tooling for formatting and tidy code quality checks before this WebRTC update, so a Clang dependency was not avoided before the migration off GCC.
Stable Linux distributions generally freeze a compiler major version for the life of a release. For example, Ubuntu 22.04 provides Clang 14, Ubuntu 24.04 provides Clang 18, Debian 12 provides Clang 14, and Debian 13 provides Clang
build.sh sources scripts/setup-linux-toolchain.sh, which locates the right Clang environment paths and exports CC, CXX, and LIBCLANG_PATH for CMake and Cargo. Within build.sh, those settings apply only to the build and its child processes. Direct CMake users can source the same setup script and those environment settings remain in the current shell. Neither usage modifies the system-wide compiler configuration.
To use a custom LLVM installation instead, set LLVM_ROOT to its prefix (for example, /opt/llvm-21.1.8).