Build & Installation Guide

This page covers how to build and install the LiveKit C++ Client SDK for real-time audio/video communication.

📦 Requirements

CMake ≥ 3.20
Rust / Cargo (latest stable toolchain)
Git LFS (required for examples) Some example data files (e.g., audio assets) are stored using Git LFS. You must install Git LFS before cloning or pulling the repo if you want to run the examples.

Platform-Specific Requirements:

For Building the SDK:

Windows: Visual Studio 2019+, vcpkg
Linux: sudo apt install libprotobuf-dev libssl-dev (protobuf 3.x)
macOS: brew install protobuf (protobuf 3.x)

For Using the Pre-built SDK:

Windows: ✅ All dependencies included (DLLs bundled) - ready to use
Linux: ⚠️ Requires libprotobuf and libssl-dev; deploy liblivekit_ffi.so with your executable
macOS: ⚠️ Requires protobuf; deploy liblivekit_ffi.dylib with your executable

Note: If the SDK was built with Protobuf 6.0+, you also need libabsl-dev (Linux) or abseil (macOS).

🧩 Clone the Repository

Make sure to initialize the Rust submodule (client-sdk-rust):

# Option 1: Clone with submodules in one step
git clone --recurse-submodules https://github.com/livekit/client-sdk-cpp.git

# Option 2: Clone first, then initialize submodules
git clone https://github.com/livekit/client-sdk-cpp.git
cd client-sdk-cpp
git submodule update --init --recursive

⚙️ BUILD

Quick Build (Using Build Scripts)

Linux/macOS:

./build.sh clean          # Clean CMake build artifacts
./build.sh clean-all      # Deep clean (C++ + Rust + generated files)
./build.sh debug          # Build Debug version
./build.sh release        # Build Release version
./build.sh debug-tests    # Build Debug with tests
./build.sh release-tests  # Build Release with tests

Windows

cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$PWD/vcpkg/scripts/buildsystems/vcpkg.cmake"  # Generate Makefiles in build folder
# Build (Release or Debug)
cmake --build build --config Release
# or:
cmake --build build --config Debug
# Clean CMake build artifacts
Remove-Item -Recurse -Force build

Note (Windows), This assumes vcpkg is checked out in the repo root at .\vcpkg. You must install protobuf via vcpkg (so CMake can find ProtobufConfig.cmake and protoc), for example:

.\vcpkg\vcpkg install protobuf:x64-windows

Windows:

.\build.cmd clean          # Clean CMake build artifacts
.\build.cmd clean-all      # Deep clean (C++ + Rust + generated files)
.\build.cmd debug          # Build Debug version
.\build.cmd release        # Build Release version
.\build.cmd debug-tests    # Build Debug with tests
.\build.cmd release-tests  # Build Release with tests

Advanced Build (Using CMake Presets)

For more control and platform-specific builds, see the detailed instructions in README_BUILD.md.

Prerequisites (Windows only):

Set VCPKG_ROOT environment variable pointing to your vcpkg installation

# Windows PowerShell
$env:VCPKG_ROOT = "C:\path\to\vcpkg"

Prerequisites (Linux/macOS):

Install system dependencies (see above)

Quick start:

# Windows
cmake --preset windows-release
cmake --build --preset windows-release

# Linux
cmake --preset linux-release
cmake --build --preset linux-release

# macOS
cmake --preset macos-release
cmake --build --preset macos-release

📖 For complete build instructions, troubleshooting, and platform-specific notes, see README_BUILD.md

🧪 Run Example

Generate Tokens

Before running any participant, create JWT tokens with the proper identity and room name, example

lk token create -r test -i your_own_identity  --join --valid-for 99999h --dev --room=your_own_room

SimpleRoom

./build/examples/SimpleRoom --url $URL --token <jwt-token>

You can also provide the URL and token via environment variables:

export LIVEKIT_URL=ws://localhost:7880
export LIVEKIT_TOKEN=<jwt-token>
./build/examples/SimpleRoom

End-to-End Encryption (E2EE) You can enable E2E encryption for the streams via --enable_e2ee and --e2ee_key flags, by running the following cmds in two terminals or computers. Note, jwt_token needs to be different identity

./build/examples/SimpleRoom --url $URL --token <jwt-token> --enable_e2ee --e2ee_key="your_key"

Note, all participants must use the exact same E2EE configuration and shared key. If the E2EE keys do not match between participants:

Media cannot be decrypted
Video tracks will appear as a black screen
Audio will be silent
No explicit error may be shown at the UI level

Press Ctrl-C to exit the example.

SimpleRpc

The SimpleRpc example demonstrates how to:

Connect multiple participants to the same LiveKit room
Register RPC handlers (e.g., arrival, square-root, divide, long-calculation)
Send RPC requests from one participant to another
Handle success, application errors, unsupported methods, and timeouts
Observe round-trip times (RTT) for each RPC call

🔑 Generate Tokens

Before running any participant, create JWT tokens with caller, greeter and math-genius identities and room name.

lk token create -r test -i caller --join --valid-for 99999h --dev --room=your_own_room
lk token create -r test -i greeter --join --valid-for 99999h --dev --room=your_own_room
lk token create -r test -i math-genius --join --valid-for 99999h --dev --room=your_own_room

▶ Start Participants

Every participant is run as a separate terminal process, note --role needs to match the token identity.

./build/examples/SimpleRpc --url $URL --token <jwt-token> --role=math-genius

The caller will automatically:

Wait for the greeter and math-genius to join
Perform RPC calls
Print round-trip times
Annotate expected successes or expected failures

SimpleDataStream

The SimpleDataStream example demonstrates how to:
Connect multiple participants to the same LiveKit room
Register text stream and byte stream handlers by topic (e.g. "chat", "files")
Send a text stream (chat message) from one participant to another
Send a byte stream (file/image) from one participant to another
Attach custom stream metadata (e.g. sent_ms) via stream attributes
Measure and print one-way latency on the receiver using sender timestamps
Receive streamed chunks and reconstruct the full payload on the receiver

🔑 Generate Tokens

Before running any participant, create JWT tokens with caller and greeter identities and your room name.

lk token create -r test -i caller  --join --valid-for 99999h --dev --room=your_own_room
lk token create -r test -i greeter --join --valid-for 99999h --dev --room=your_own_room

▶ Start Participants

Start the receiver first (so it registers stream handlers before messages arrive):

./build/examples/SimpleDataStream --url $URL --token <jwt-token>

On another terminal or computer, start the sender

./build/examples/SimpleDataStream --url $URL --token <jwt-token>

Sender (e.g. greeter)

Waits for the peer, then sends a text stream ("chat") and a file stream ("files") with timestamps and metadata, logging stream IDs and send times.

Receiver (e.g. caller)

Registers handlers for text and file streams, logs stream events, computes one-way latency, and saves the received file locally.

🧪 Integration & Stress Tests

The SDK includes integration and stress tests using Google Test (gtest).

Build Tests

Linux/macOS:

./build.sh debug-tests      # Build Debug with tests
./build.sh release-tests    # Build Release with tests

Windows:

.\build.cmd debug-tests
.\build.cmd release-tests

Run Tests

After building, run tests using ctest or directly:

# Run all tests via ctest
cd build-debug
ctest --output-on-failure

# Or run test executables directly
./build-debug/bin/livekit_integration_tests
./build-debug/bin/livekit_stress_tests

# Run specific test suites
./build-debug/bin/livekit_integration_tests --gtest_filter="*Rpc*"
./build-debug/bin/livekit_stress_tests --gtest_filter="*MaxPayloadStress*"

Test Types

Executable	Description
`livekit_integration_tests`	Quick tests (~1-2 minutes) for SDK functionality
`livekit_stress_tests`	Long-running tests (configurable, default 1 hour)

RPC Test Environment Variables

RPC integration and stress tests require a LiveKit server and two participant tokens:

# Required
export LIVEKIT_URL="wss://your-server.livekit.cloud"
export LIVEKIT_CALLER_TOKEN="<token with caller identity>"
export LIVEKIT_RECEIVER_TOKEN="<token with receiver identity>"

# Optional (for stress tests)
export RPC_STRESS_DURATION_SECONDS=3600   # Test duration (default: 1 hour)
export RPC_STRESS_CALLER_THREADS=4        # Concurrent caller threads (default: 4)

Generate tokens for RPC tests:

lk token create -r test -i rpc-caller --join --valid-for 99999h --dev --room=rpc-test-room
lk token create -r test -i rpc-receiver --join --valid-for 99999h --dev --room=rpc-test-room

Test Coverage

SDK Initialization: Initialize/shutdown lifecycle
Room: Room creation, options, connection
Audio Frame: Frame creation, manipulation, edge cases
RPC: Round-trip calls, max payload (15KB), timeouts, errors, concurrent calls
Stress Tests: High throughput, bidirectional RPC, memory pressure

🧰 Recommended Setup

macOS

brew install cmake protobuf rust

Ubuntu / Debian

sudo apt update
sudo apt install -y cmake protobuf-compiler build-essential
curl https://sh.rustup.rs -sSf | sh

🛠️ Development Tips

Update Rust version

cd client-sdk-cpp
git fetch origin
git switch -c try-rust-main origin/main

# Sync submodule URLs and check out what origin/main pins (recursively):
git submodule sync --recursive
git submodule update --init --recursive --checkout

# Now, in case the nested submodule under yuv-sys didn’t materialize, force it explicitly:
cd ..
git -C client-sdk-rust/yuv-sys submodule sync --recursive
git -C client-sdk-rust/yuv-sys submodule update --init --recursive --checkout

# Sanity check:
git submodule status --recursive

If yuv-sys fails to build

cargo clean -p yuv-sys
cargo build -p yuv-sys -vv

Full clean (Rust + C++ build folders)

In some cases, you may need to perform a full clean that deletes all build artifacts from both the Rust and C++ folders:

./build.sh clean-all

Clang format

CPP SDK is using clang C++ format

brew install clang-format

GeezerVison

Latest commit

History

Folders and files

Repository files navigation

Build & Installation Guide

📦 Requirements

For Building the SDK:

For Using the Pre-built SDK:

🧩 Clone the Repository

⚙️ BUILD

Quick Build (Using Build Scripts)

Advanced Build (Using CMake Presets)

🧪 Run Example

Generate Tokens

SimpleRoom

SimpleRpc

🔑 Generate Tokens

▶ Start Participants

SimpleDataStream

🔑 Generate Tokens

▶ Start Participants

🧪 Integration & Stress Tests

Build Tests

Run Tests

Test Types

RPC Test Environment Variables

Test Coverage

🧰 Recommended Setup

macOS

Ubuntu / Debian

🛠️ Development Tips

Update Rust version

If yuv-sys fails to build

Full clean (Rust + C++ build folders)

Clang format

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages