[kahrendt]

Lets a player withdraw the server's volume and mute commands at runtime, for outputs whose level is set elsewhere (e.g. line out to an amplifier). The current spec carries supported_commands in client/state and lets a player change it mid-session (roles/player/v1.md "client/state player object"), so no reconnect is needed.

Closes #82.

Change

• New PlayerRole::set_volume_adjustable(bool) and set_mute_adjustable(bool), main loop only, both enabled by default, mirroring set_output_delay_adjustable(). The flags are not persisted.
• While one is disabled: its command leaves supported_commands, its volume/muted value is omitted from client/state, and a server command for it is ignored. The stored value is kept and reported again when re-enabled.
• ClientPlayerStateObject::volume/muted become std::optional; the formatter writes them only when set.
• Examples: basic_client and tui_client gain -F (the server cannot set the volume, which starts at 100) and -M (the server cannot set mute). Local volume and mute controls still work.
• docs/integration-guide.md documents the setters.

Notes

• Omitting the value is one compliant choice; the spec also allows reporting it read-only without the command. Read-only reporting is left for when a consumer needs it.

Tests

• Table test over the knobs: supported_commands, presence of volume/muted, the defaults, and a disable/re-enable row.
• Table test that an unadvertised volume or mute command reaches neither the listener nor the stored value.
• Formatter test that unset keys are omitted while 0/false are still written.
• Loopback test that withdrawing and restoring both knobs republishes client/state while connected; dropping either setter's publish hangs it.

[Copilot]

🟡 Changes recommended

The central runtime publication behavior lacks effective coverage, and a new test unnecessarily bypasses the public API.

2 open findings

• Add started-client test for runtime state withdraw and restore · New
• Use public setters and getters instead of private flags · New

What changed in this PR

Adds runtime controls for withdrawing server volume and mute commands without reconnecting.

Changes:

• Adds volume/mute adjustability APIs and conditional state serialization.
• Ignores withdrawn commands while preserving local values.
• Updates tests, documentation, and example CLI flags.

File	Description
include/​sendspin/​player_role.h	Declares and documents new setters.
src/​player_role.cpp	Implements flags, state reporting, and command guards.
src/​player_role_impl.h	Stores adjustability flags.
src/​protocol_messages.h	Makes volume and mute optional.
src/​protocol.cpp	Omits unset fields during serialization.
tests/​test_player_role.cpp	Tests capabilities and ignored commands.
tests/​test_protocol.cpp	Tests optional-field serialization.
docs/​integration-guide.md	Documents runtime controls.
examples/​basic_client/​main.cpp	Adds -F and -M options.
examples/​basic_client/​README.md	Documents new options.
examples/​tui_client/​main.cpp	Adds -F and -M options.
examples/​tui_client/​README.md	Documents new options.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The implementation, API documentation, examples, and observable-behavior tests consistently cover the requested runtime withdrawal behavior.

0 open findings

2 resolved since last review

• Add started-client test for runtime state withdraw and restore
• Use public setters and getters instead of private flags

🧠 Review effort: Balanced