Doc updates

Author: alan-george-lk

CMakeLists.txt

@@ -21,7 +21,7 @@ set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 # Make "include(LiveKitSDK)" search in ./cmake
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
-set(LIVEKIT_SDK_VERSION "latest" CACHE STRING "LiveKit C++ SDK version (e.g. 0.2.0 or latest)")
+set(LIVEKIT_SDK_VERSION "latest" CACHE STRING "LiveKit C++ SDK version (e.g. 1.3.0 or latest)")
 set(LIVEKIT_LOCAL_SDK_DIR "" CACHE PATH "Path to a local LiveKit SDK install prefix (skips download)")
 
 if(LIVEKIT_LOCAL_SDK_DIR)

README.md

@@ -1,78 +1,107 @@
 # cpp-example-collection
+
 This repository contains a collection of small, self-contained examples for the
 [LiveKit C++ SDK](https://github.com/livekit/client-sdk-cpp).
 
 The goal of these examples is to demonstrate common usage patterns of the
 LiveKit C++ SDK (connecting to a room, publishing tracks, RPC, data streams,
 etc.) without requiring users to build the SDK from source.
 
-
 ## How the SDK is provided
 
 These examples **automatically download a prebuilt LiveKit C++ SDK release**
 from GitHub at CMake configure time.
 
-This is handled by the cmake helper: [LiveKitSDK.cmake ](https://github.com/livekit-examples/cpp-example-collection/cmake/LiveKitSDK.cmake)
+This is handled by the CMake helper:
+[`LiveKitSDK.cmake`](https://github.com/livekit-examples/cpp-example-collection/blob/main/cmake/LiveKitSDK.cmake).
 
-## Selecting a LiveKit SDK version
+By default, CMake resolves `LIVEKIT_SDK_VERSION=latest` to the newest GitHub
+release and downloads the matching archive for your platform. The extracted SDK
+lands under **build/_deps/livekit-sdk/**.
 
-By default, the examples download the **latest released** LiveKit C++ SDK.
+## Building the examples
 
-You can pin a specific SDK version using the `LIVEKIT_SDK_VERSION` CMake option.
+Run these from the repository root. All examples — including
+[`token_source/`](token_source/) — build together in one pass.
 
-### Examples
+### macOS / Linux
 
-Use the latest release:
 ```bash
 cmake -S . -B build
-# Or use a specific version (recommended for reproducibility):
-cmake -S . -B build -DLIVEKIT_SDK_VERSION=0.2.0
+cmake --build build
 ```
 
-Reconfigure to change versions:
-```bash
-rm -rf build
-cmake -S . -B build -DLIVEKIT_SDK_VERSION=0.3.1
+### Windows (Visual Studio generator)
+
+```powershell
+cmake -S . -B build
+cmake --build build --config Release
 ```
 
-Build against a local SDK:
+The token source examples require LiveKit C++ SDK **v1.3.0** or newer. If
+configure succeeds but those targets fail to compile, pin the SDK version
+explicitly:
+
 ```bash
 rm -rf build
-# install the SDK into $HOME/livekit-sdk-install (or any other directory)
-cmake --install <sdk-build-dir> --prefix $HOME/livekit-sdk-install
-
-# build the examples against the local SDK
-cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=$HOME/livekit-sdk-install
+cmake -S . -B build -DLIVEKIT_SDK_VERSION=1.3.0
+cmake --build build
 ```
 
+### Selecting an SDK version
+
+Pin a specific release with `-DLIVEKIT_SDK_VERSION`:
 
-### Building the examples
-#### macOS / Linux
 ```bash
-cmake -S . -B build # add -DLIVEKIT_SDK_VERSION=0.2.0 if using a specific version
-cmake --build build
+cmake -S . -B build -DLIVEKIT_SDK_VERSION=1.3.0
 ```
 
-#### Windows (Visual Studio generator)
-```powershell
-cmake -S . -B build # add -DLIVEKIT_SDK_VERSION=0.2.0 if using a specific version
-cmake --build build --config Release
+When changing versions, remove the build directory first so CMake re-downloads
+the SDK:
+
+```bash
+rm -rf build
+cmake -S . -B build -DLIVEKIT_SDK_VERSION=1.3.0
 ```
 
-The Livekit Release SDK is downloaded into **build/_deps/livekit-sdk/**
+### Build against a local SDK
 
-### Running the examples
+Use this when validating an unreleased `client-sdk-cpp` commit, or when a
+release tag exists but its prebuilt archives are not yet published:
 
-After building, example binaries are located under:
 ```bash
-build/<example-name>/
+git clone --recurse-submodules https://github.com/livekit/client-sdk-cpp.git
+cd client-sdk-cpp
+./build.sh release --bundle --prefix "$HOME/livekit-sdk-install"
+
+cd /path/to/cpp-example-collection
+rm -rf build
+cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR="$HOME/livekit-sdk-install"
+cmake --build build
 ```
 
+### Troubleshooting configure
+
+- **Start from a clean build directory** after a failed configure or download:
+  `rm -rf build`
+- **GitHub API rate limits** when resolving `latest`: pin
+  `-DLIVEKIT_SDK_VERSION=1.3.0`, or export `GITHUB_TOKEN` and re-run configure.
+- **404 on SDK download**: the release may not have platform archives yet. Pin
+  an older release that does, or use `-DLIVEKIT_LOCAL_SDK_DIR` as above.
+
+## Running the examples
+
+After building, example binaries are located under `build/<example-name>/`.
+
 For example:
+
 ```bash
 ./build/basic_room/basic_room --url <ws-url> --token <token>
 ```
 
+See [`token_source/README.md`](token_source/README.md) for the token-source
+examples.
+
 ### PlatformAudio
 
 The `platform_audio` examples show microphone capture and speaker playout using
@@ -86,8 +115,9 @@ WebRTC's platform Audio Device Module:
 ### Supported platforms
 
 Prebuilt SDKs are downloaded automatically for:
-* Windows: x64
-* macOS: x64, arm64 (Apple Silicon)
-* Linux: x64
+
+- Windows: x64
+- macOS: x64, arm64 (Apple Silicon)
+- Linux: x64
 
 If no matching SDK is available for your platform, CMake configuration will fail with a clear error.

token_source/README.md

@@ -1,4 +1,4 @@
-# Token sources
+# Token Source Examples
 
 These examples show the different ways to obtain the credentials
 (**WebSocket URL** + **participant JWT**) the SDK needs to join a room. Each
@@ -12,28 +12,27 @@ disconnects.
 > not called again unless you connect again. See the SDK's
 > [authentication docs](https://github.com/livekit/client-sdk-cpp/blob/main/docs/authentication.md).
 
-## The types
+## Types
 
-| Example | Type | When to use |
-|---|---|---|
-| `token_source_literal.cpp` | `LiteralTokenSource` | You already have a URL + JWT (minted out of band, e.g. `lk token create`). The SDK consumes them as-is. |
-| `token_source_endpoint.cpp` | `EndpointTokenSource` | Recommended for production. The SDK POSTs request options to your backend token endpoint, which returns the URL + a fresh JWT. API keys stay server-side. |
-| `token_source_sandbox.cpp` | `SandboxTokenSource` | Local development only. Uses LiveKit Cloud's sandbox token server. Not for production. |
-| `token_source_custom.cpp` | `CustomTokenSource` | You have an internal auth/token system. Plug in your own async callback that returns credentials. |
-| `token_source_caching.cpp` | `CachingTokenSource` | A decorator that adds JWT-aware caching around any configurable source (endpoint/sandbox/custom) to cut down on fetch calls. |
+| Type | Example | When to use |
+| --- | --- | --- |
+| `LiteralTokenSource` | `token_source_literal.cpp` | You already have a URL + JWT (minted out of band, e.g. `lk token create`). The SDK consumes them as-is. |
+| `EndpointTokenSource` | `token_source_endpoint.cpp` | Recommended for production. The SDK POSTs request options to your backend token endpoint, which returns the URL + a fresh JWT. API keys stay server-side. |
+| `SandboxTokenSource` | `token_source_sandbox.cpp` | Local development only. Uses LiveKit Cloud's sandbox token server. Not for production. |
+| `CustomTokenSource` | `token_source_custom.cpp` | You have an internal auth/token system. Plug in your own async callback that returns credentials. |
+| `CachingTokenSource` | `token_source_caching.cpp` | A decorator that adds JWT-aware caching around any configurable source (endpoint/sandbox/custom) to cut down on fetch calls. |
 
 `LiteralTokenSource` is *fixed* (no per-call options); the others are
 *configurable* and accept
 [`TokenRequestOptions`](https://github.com/livekit/client-sdk-cpp/blob/main/include/livekit/token_source.h)
 (room name, participant identity, agent dispatch, ...).
 
-## Configuration
+## Configuring the Examples
 
-All inputs come from environment variables, so no secrets or sandbox IDs are
-committed to source.
+All inputs come from environment variables, so no secrets or sandbox IDs are committed to source.
 
 | Variable | Used by | Notes |
-|---|---|---|
+| --- | --- | --- |
 | `LIVEKIT_URL` | literal, custom | WebSocket URL, e.g. `ws://localhost:7880`. |
 | `LIVEKIT_TOKEN` | literal, custom | Participant JWT. |
 | `LIVEKIT_TOKEN_ENDPOINT` | endpoint, caching | Token endpoint URL. Default `http://127.0.0.1:3000/createToken`. |
@@ -43,33 +42,8 @@ committed to source.
 | `LIVEKIT_AGENT_NAME` | sandbox | Optional agent to dispatch into the room. |
 | `LIVEKIT_AGENT_METADATA` | sandbox | Optional metadata for the dispatched agent. |
 
-## Building
-
-The token source API is newer than the latest published SDK release, so build
-these examples against a **local SDK build** of the
-[`feature/token_source_api`](https://github.com/livekit/client-sdk-cpp/tree/feature/token_source_api)
-branch rather than a downloaded release. The commands below pin the branch to
-commit [`bbf6a41`](https://github.com/livekit/client-sdk-cpp/commit/bbf6a41fae42607ee19ff44ccddac786767b34e3)
-so the examples build against a known-good API; drop the `git checkout` of the
-hash to track the branch tip instead.
-
-```bash
-# 1. Build and install the SDK from the feature branch.
-git clone https://github.com/livekit/client-sdk-cpp.git
-cd client-sdk-cpp
-git checkout bbf6a41fae42607ee19ff44ccddac786767b34e3
-git submodule update --init --recursive
-./build.sh release --bundle --prefix "$HOME/livekit-sdk-install"
-
-# 2. Configure the examples against that local install.
-cd /path/to/cpp-example-collection
-cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR="$HOME/livekit-sdk-install"
-cmake --build build
-```
-
-Once the token source API ships in a release, you can drop
-`-DLIVEKIT_LOCAL_SDK_DIR` and use the normal download flow (optionally pinning
-`-DLIVEKIT_SDK_VERSION`).
+These examples require LiveKit C++ SDK **v1.3.0** or newer. Build them with the
+rest of the repo — see the root [README](../README.md#building-the-examples).
 
 ## Running
 

user_timestamped_video/README.md

@@ -23,7 +23,7 @@ Requirements:
   `VideoFrameMetadata` and `setOnVideoFrameEventCallback`, which are not
   available in older SDK releases.
 - To pin the SDK version when configuring the examples, pass
-  `-DLIVEKIT_SDK_VERSION=0.3.4` to CMake.
+  `-DLIVEKIT_SDK_VERSION=1.3.0` to CMake.
 
 Flags: