sendspin/sendspin-cpp

Readme

# sendspin-cpp

[![CI](https://github.com/Sendspin/sendspin-cpp/actions/workflows/ci.yml/badge.svg)](https://github.com/Sendspin/sendspin-cpp/actions/workflows/ci.yml)
[![Component Registry](https://components.espressif.com/components/sendspin/sendspin-cpp/badge.svg)](https://components.espressif.com/components/sendspin/sendspin-cpp)

Standalone C++ library implementing the [Sendspin synchronized audio streaming protocol](https://www.sendspin-audio.com/). Builds on both ESP-IDF (ESP32) and host platforms (macOS/Linux). Designed to be consumed by ESPHome but has no ESPHome dependencies.

[![A project from the Open Home Foundation](https://www.openhomefoundation.org/badges/ohf-project.png)](https://www.openhomefoundation.org/)

## Features

- Modular Sendspin role composition: artwork, color, controller, metadata, player, source, and visualizer
- WebSocket client and server support
- Mandatory Noise KKpsk2 encryption on every connection, with Pairing PSK token and pairing code pairing
- Decodes FLAC and PCM and streams captured PCM, plus Opus decode and encode when built with `SENDSPIN_ENABLE_OPUS` (the default)
- Cross-platform: ESP-IDF (ESP32) and host (macOS/Linux)

## Documentation

- **[Integration Guide](docs/integration-guide.md)** -- How to integrate sendspin-cpp into your application, including required callbacks, role composition, and platform setup
- **[Internals](docs/internals.md)** -- Internal architecture, threading model, and inter-class communication
- **[Playback Sync](docs/playback-sync.md)** -- Clock synchronization and how decoded audio is aligned to server timestamps

## Build

### Host (macOS/Linux)

```bash
cmake -B build
cmake --build build
```

Dependencies (fetched automatically via CMake FetchContent): ArduinoJson, noise-c, IXWebSocket, micro-flac for the player role, and micro-opus for the player or source role when `SENDSPIN_ENABLE_OPUS` is on.

### ESP-IDF

Available on the [ESP-IDF Component Registry](https://components.espressif.com/components/sendspin/sendspin-cpp). Add to your project's `idf_component.yml`:

```yaml
dependencies:
  sendspin/sendspin-cpp: ">=0.1.2"
```

Requires ESP-IDF v5.5.2 or later, the first release whose ring buffer reclaims space correctly when items are returned out of order.

## Examples

- **`examples/basic_client/`** -- Standalone host example with PortAudio audio output
- **`examples/tui_client/`** -- Terminal UI host example with PortAudio audio output
- **`examples/source_client/`** -- Host example streaming the default PortAudio input to the server (source role)

## License

Apache 2.0