# Warp Pipe Examples

This page collects common usage patterns for the library and CLI. Snippets assume `#include <warppipe/warppipe.hpp>` and a successful `Client::Create` call.

## Connect with auto-save

```cpp
warppipe::ConnectionOptions opts;
opts.application_name = "my-app";
opts.config_path = "/home/user/.config/warppipe/config.json";

auto result = warppipe::Client::Create(opts);
if (!result.ok()) {
    // handle result.status
}
auto& client = result.value;
```

## Connect to a non-default PipeWire instance

```cpp
warppipe::ConnectionOptions opts;
opts.application_name = "my-app";
opts.remote_name = "pipewire-0"; // or a custom PipeWire instance name

auto result = warppipe::Client::Create(opts);
```

## Per-app routing rule

```cpp
warppipe::RouteRule rule;
rule.match.application_name = "Firefox";
rule.target_node = "warppipe-gaming-sink";

auto add = client->AddRouteRule(rule);
if (!add.ok()) {
    // kInvalidArgument if no match criteria or target is empty
}
```

## Loopback sink to a target node

```cpp
warppipe::VirtualNodeOptions opts;
opts.behavior = warppipe::VirtualBehavior::kLoopback;
opts.target_node = "alsa_output.pci-0000_00_1f.3.analog-stereo";

auto sink = client->CreateVirtualSink("warppipe-loopback", opts);
```

## Policy-only mode (no auto-links)

```cpp
warppipe::ConnectionOptions opts;
opts.policy_only = true;

auto result = warppipe::Client::Create(opts);
auto& client = result.value;

client->SetDefaultSink("warppipe-gaming-sink");
client->SetDefaultSource("warppipe-mic-source");
```

## Volume and mute

```cpp
auto nodes = client->ListNodes();
if (nodes.ok() && !nodes.value.empty()) {
    warppipe::NodeId node = nodes.value.front().id;
    client->SetNodeVolume(node, 0.85f, false);
    auto state = client->GetNodeVolume(node);
}
```

## Audio metering

```cpp
auto nodes = client->ListNodes();
if (nodes.ok() && !nodes.value.empty()) {
    warppipe::NodeId node = nodes.value.front().id;
    client->EnsureNodeMeter(node);
    auto peak = client->NodeMeterPeak(node); // kNotFound if not metered
}

auto master = client->MeterPeak();
```

## Change callback

```cpp
client->SetChangeCallback([] {
    // Fires on registry changes and volume/mute updates.
    // Runs on the PipeWire thread loop; do not call Client methods here.
});
```

## CLI workflow: link by name

```
warppipe_cli list-nodes
warppipe_cli list-ports <node-id>

warppipe_cli link <out-node-name> <out-port-name> <in-node-name> <in-port-name> --linger
warppipe_cli unlink <link-id>
```

## Persisted links and volume state

```
client->SaveConfig("/tmp/warppipe.json");
client->LoadConfig("/tmp/warppipe.json");
```

Saved configs include virtual nodes, routing rules, links (by node/port name), and per-node volume/mute state. Links are recreated when both endpoints appear in the registry.