jyapayne/warp-pipe
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs

Browse source
This commit is contained in:
Joey Yakimowich-Payne 2026-01-31 11:21:28 -07:00
commit 9d57ba5d25
9 changed files with 235 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

33
README.md
View file

@ -1,6 +1,6 @@
# warppipe
A C++17 static library wrapping libpipewire for virtual audio node management, link routing, and per-app routing policy.
Warp Pipe is a C++20 static library wrapping libpipewire for virtual audio node management, link routing, and per-app routing policy.
## Features
@ -8,6 +8,8 @@ A C++17 static library wrapping libpipewire for virtual audio node management, l
- **Link management** — connect and disconnect ports by node+port name or ID, with passive and linger options
- **Per-app routing rules** — match applications by name, process binary, or media role and auto-route to target sinks
- **Persistence** — JSON config with atomic writes, auto-save on change, auto-load on startup
- **Volume control** — set per-node volume and mute state
- **Audio metering** — per-node and master peak meters
- **Metadata integration** — read and set default audio sink/source via PipeWire metadata
- **Policy-only mode** — observe and set metadata without creating links (avoids fighting WirePlumber)
- **Thread-safe** — dedicated PipeWire thread loop; all public methods callable from any thread
@ -18,20 +20,24 @@ Requirements:
- CMake 3.20+
- pkg-config
- libpipewire-0.3 development files
- C++17 compiler
- C++20 compiler
- Qt6 6.2+ (for the GUI target; disable with `-DWARPPIPE_BUILD_GUI=OFF`)
- Catch2 v3 (for tests; required when `-DWARPPIPE_BUILD_TESTS=ON`)
```sh
cmake -S . -B build
cmake --build build
```
Targets: `warppipe` (library), `warppipe_example`, `warppipe_cli`, `warppipe_tests`, `warppipe_perf`
Targets: `warppipe` (library), `warppipe_example`, `warppipe_cli`, `warppipe_tests`, `warppipe_perf`, `warppipe-gui`, `warppipe-gui-tests`
### Dependencies
- [libpipewire-0.3](https://pipewire.org/) — system package
- [nlohmann/json](https://github.com/nlohmann/json) — fetched automatically via CMake FetchContent
- [Catch2 v3](https://github.com/catchorg/Catch2) — fetched automatically via CMake FetchContent
- [nlohmann/json](https://github.com/nlohmann/json) — fetched automatically if not installed
- [Catch2 v3](https://github.com/catchorg/Catch2) — required for tests (via `find_package`)
- [Qt6](https://www.qt.io/) — required for `warppipe-gui` (default on)
- [QtNodes](https://github.com/paceholder/nodeeditor) — fetched automatically when GUI is enabled
## Quick Start
@ -77,11 +83,13 @@ warppipe_cli load-config <path>
warppipe_cli defaults
```
`link` uses node and port names (not IDs). `--passive` sets `PW_KEY_LINK_PASSIVE`, and `--linger` sets `PW_KEY_OBJECT_LINGER` so links persist after the client exits. `defaults` prints the current and configured default sink/source names.
`create-sink` and `create-source` block until interrupted with Ctrl-C.
## Configuration
Config is JSON. Set `ConnectionOptions::config_path` to enable auto-save/load, or use `SaveConfig`/`LoadConfig` manually.
Config is JSON. Set `ConnectionOptions::config_path` to enable auto-save/load, or use `SaveConfig`/`LoadConfig` manually. The config persists virtual nodes, routing rules, saved links, and per-node volume/mute state.
```json
{
@ -93,7 +101,9 @@ Config is JSON. Set `ConnectionOptions::config_path` to enable auto-save/load, o
"rate": 48000,
"channels": 2,
"loopback": false,
"target_node": ""
"target_node": "",
"volume": 1.0,
"mute": false
}
],
"route_rules": [
@ -105,6 +115,14 @@ Config is JSON. Set `ConnectionOptions::config_path` to enable auto-save/load, o
},
"target_node": "warppipe-gaming-sink"
}
],
"links": [
{
"out_node": "Firefox",
"out_port": "output_FL",
"in_node": "warppipe-gaming-sink",
"in_port": "input_FL"
}
]
}
```
@ -126,6 +144,7 @@ In this mode the policy engine still evaluates rules but does not create links.
- [API Reference](docs/api.md) — full API, threading model, error model, performance notes
- [Config Schema](docs/config-schema.md) — JSON configuration format and persistence behavior
- [GUI Usage](docs/gui-usage.md) — how to run the Qt GUI and capture screenshots
## Tests