> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# C++ SDK Overview

> The Pipecat C++ SDK: PipecatClient for native voice AI apps on Linux, macOS and Windows, with Daily and WebSocket transports.

The Pipecat C++ SDK builds native client applications, such as robots, kiosks, smart devices or games, that talk to a Pipecat bot. Like the other client SDKs, it speaks the [RTVI protocol](https://docs.pipecat.ai/api-reference/standards/rtvi-standard.md), and it:

* Starts bots through an endpoint, like Pipecat Cloud or your own server, and connects to them
* Sends the user's audio to the bot and receives the bot's, as 16-bit PCM
* Reports what happens in the conversation through typed callbacks: transcriptions, bot output, function calls, metrics and more
* Sends text and app-defined messages to the bot, and waits for its answers

It supports Linux (`x86_64` and `aarch64`), macOS (`aarch64`) and Windows (`x86_64`), and needs a C++17 compiler.

## Transports

The client connects to your bot with a transport:

> [card] [Daily](https://docs.pipecat.ai/api-reference/client/cpp/transports/daily.md)
>
> Connects to the bot's Daily room, using WebRTC

> [card] [WebSocket](https://docs.pipecat.ai/api-reference/client/cpp/transports/websocket.md)
>
> Connects to the bot's WebSocket

You can also write your own by implementing `pipecat::Transport`.

## Installation

You need CMake 3.16 or newer and a C++17 compiler (GCC 9 or newer, Clang, Apple Clang or MSVC). The client uses [libcurl](https://curl.se/libcurl/) to make HTTP requests, and [nlohmann/json](https://github.com/nlohmann/json) 3.7 or newer, which CMake downloads if it's not installed.

### Adding it to your CMake project

The simplest way is to let CMake download a release, with `FetchContent`. Turn on the transports you need before making it available:

```cmake theme={null}
include(FetchContent)

set(PIPECAT_BUILD_WEBSOCKET ON)
FetchContent_Declare(
  pipecat
  URL https://github.com/pipecat-ai/pipecat-client-cxx/releases/download/v1.0.0/pipecat-client-cxx-1.0.0.tar.gz
  URL_HASH SHA256=329deb59b7868be9447d6211c83b276df8f4d3488666c02166dcbf7ec5d27775
)
FetchContent_MakeAvailable(pipecat)

target_link_libraries(my_app PRIVATE pipecat::websocket)
```

Each transport's target also links the client. If you only use the client, e.g. with your own transport, link `pipecat::pipecat`.

The client's dependencies still need to be installed (see below), and so do the transport's, which its page explains.

### Building and installing

You can also build the SDK yourself and install it:

> [tab] Linux
>
> ```bash theme={null}
> sudo apt-get install cmake ninja-build libcurl4-openssl-dev nlohmann-json3-dev
> git clone https://github.com/pipecat-ai/pipecat-client-cxx
> cd pipecat-client-cxx
> cmake . -G Ninja -Bbuild -DCMAKE_BUILD_TYPE=Release
> ninja -C build
> cmake --install build --prefix /path/to/pipecat
> ```

> [tab] macOS
>
> macOS already includes libcurl:
>
> ```bash theme={null}
> brew install cmake ninja nlohmann-json
> git clone https://github.com/pipecat-ai/pipecat-client-cxx
> cd pipecat-client-cxx
> cmake . -G Ninja -Bbuild -DCMAKE_BUILD_TYPE=Release
> ninja -C build
> cmake --install build --prefix /path/to/pipecat
> ```

> [tab] Windows
>
> The dependencies come from [vcpkg](https://vcpkg.io/en/), which downloads them when you configure. Set it up following one of its [tutorials](https://learn.microsoft.com/en-us/vcpkg/get_started/get-started), so that `VCPKG_ROOT` points to it. Then:
>
> ```bash theme={null}
> git clone https://github.com/pipecat-ai/pipecat-client-cxx
> cd pipecat-client-cxx
> cmake --preset vcpkg
> cmake --build build --config Release
> cmake --install build --config Release --prefix C:/path/to/pipecat
> ```

Add `-DPIPECAT_BUILD_DAILY=ON` or `-DPIPECAT_BUILD_WEBSOCKET=ON` when configuring to build the transports too. To cross-compile for Linux `aarch64`, see the repository's [README](https://github.com/pipecat-ai/pipecat-client-cxx#cross-compiling-linux-aarch64).

Then, in your CMake project, point `CMAKE_PREFIX_PATH` to the install directory, and ask for the transports you use as components:

```cmake theme={null}
find_package(pipecat 1.0 REQUIRED COMPONENTS websocket)
target_link_libraries(my_app PRIVATE pipecat::websocket)
```

A `pipecat.pc` file is also installed, for Meson and other build systems that use pkg-config.

## Usage

Create a `pipecat::PipecatClient` with a transport and your callbacks, then start the bot and connect to it:

```cpp theme={null}
#include <pipecat/daily/transport.h>
#include <pipecat/pipecat.h>

#include <iostream>

class App : public pipecat::PipecatClientCallbacks {
   public:
    void on_bot_ready(const pipecat::rtvi::BotReadyData& data) override {
        std::cout << "Bot ready" << std::endl;
    }

    void on_user_transcript(const pipecat::rtvi::TranscriptData& data) override {
        if (data.final) {
            std::cout << "User: " << data.text << std::endl;
        }
    }

    void on_bot_output(const pipecat::rtvi::BotOutputData& data) override {
        std::cout << "Bot: " << data.text << std::endl;
    }

    // Handle an LLM function call. `respond` can also be called later, from
    // any thread, e.g. when a slow operation finishes.
    void on_llm_function_call_in_progress(
            const pipecat::rtvi::LLMFunctionCallInProgressData& data,
            pipecat::FunctionCallResultCallback respond
    ) override {
        if (data.function_name == "get_weather") {
            respond({{"conditions", "sunny"}, {"temperature", 22}});
        }
    }
};

int main() {
    App app;

    pipecat::PipecatClientOptions options;
    options.transport = std::make_unique<pipecat::DailyTransport>();
    options.callbacks = &app;
    pipecat::PipecatClient client(std::move(options));

    // Start the bot (e.g. on Pipecat Cloud or your own server) and wait
    // until it's ready.
    pipecat::APIRequest request;
    request.endpoint = "https://example.com/start";
    client.start_bot_and_connect(request);

    client.send_text("Hello!");

    // Meanwhile, your audio threads send user audio and play bot audio (16-bit
    // PCM) with client.send_user_audio() and client.read_bot_audio().

    client.disconnect();
}
```

The client can also send app-defined messages to your bot and wait for its answer, with a callback or a `std::future`:

```cpp theme={null}
auto weather = client.send_client_request("get-weather", {{"city", "SF"}}).get();
```

### Threading

* `start_bot()`, `connect()` and `disconnect()` block the calling thread. Everything else returns right away. All methods are thread-safe.
* Callbacks and `send_client_request()` callbacks run on the client's own event thread, one at a time and in order. You can call any client method from them, including `disconnect()` or waiting on a `send_client_request()` future.
* Events wait while a callback runs, so keep callbacks short. Function calls can be answered later instead of blocking.
* Callbacks must not throw, and must not destroy the client.
* Call `send_user_audio()` and `read_bot_audio()` from your own audio threads.

## Examples

The repository has two examples, which work with a bot on your machine or on Pipecat Cloud, using either transport:

> [card] [Text](https://github.com/pipecat-ai/pipecat-client-cxx/tree/main/examples/text)
>
> Chat with a bot in the terminal

> [card] [Voice](https://github.com/pipecat-ai/pipecat-client-cxx/tree/main/examples/voice)
>
> Talk with a bot using your microphone and speakers

## Migrating from 0.x

Version 1.0 is a rewrite that brings the SDK up to RTVI protocol 2.1, and isn't compatible with 0.x: `rtvi::RTVIClient` is now `pipecat::PipecatClient`, and the Daily transport moved into the same repository. See [Migrating from 0.x](https://github.com/pipecat-ai/pipecat-client-cxx#-migrating-from-0x) for where 0.x's API went.

## Documentation

> [card] [API Reference](https://docs.pipecat.ai/api-reference/client/cpp/api-reference.md)
>
> The client and transports' API reference

> [card] [Transports](https://docs.pipecat.ai/api-reference/client/cpp/transports/daily.md)
>
> Daily and WebSocket transports

> [card] [Source](https://github.com/pipecat-ai/pipecat-client-cxx)
>
> Pipecat Client C++ on GitHub

> [card] [Changelog](https://github.com/pipecat-ai/pipecat-client-cxx/blob/main/CHANGELOG.md)
>
> What changed in each release


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.