Let --audio-format take an ordered list of preferred formats

[chrisuthe]

--audio-format only ever moved one entry to the front of the advertised supported_formats list, but the README and ROADMAP described it as holding the player to that one format. This makes it a list and describes it as what it is: a preference, not a restriction.

• --audio-format / audio-format takes one or more comma-separated specs in priority order, e.g. flac:48000:24:2,pcm:48000:24:2. A single spec behaves exactly as before. A repeated flag or key replaces the list, like every other option.
• The listed formats go first, in order, followed by every other advertised entry in its ranked order. Nothing is removed, so a server can still fall back to a later entry.
• Parse time refuses empty entries, duplicates and invalid specs, and names the bad entry.
• Startup refuses to run if any listed format is not advertised, naming every missing one. On success it logs the pinned formats in order.
• README, --help, the packaged config example, the wiki (Advanced Usage, Configuration), header and main.cpp comments, and ROADMAP Publish the draft the release job created, not the tag #24 now all describe the option the same way.

Tests cover list parsing, rejection cases, merge order with no lost or duplicated entries, and multiple missing entries, plus the flag and config-file paths. Two existing control-socket tests fail under ctest only when the build directory's path is long enough to push the absolutized socket path past the 107-byte sun_path limit; they pass from a shorter working directory.

[Copilot]

🟢 Approval recommended

The implementation, validation, ordering behavior, tests, and documentation are consistent with the stated requirements.

Pull request overview

Extends --audio-format from one preferred format to an ordered preference list while preserving fallback formats.

Changes:

• Parses and validates comma-separated format lists.
• Reorders advertised formats and reports all unavailable preferences.
• Updates tests, help text, configuration examples, and documentation.

File summaries

File	Description
src/supported_formats.cpp	Implements list parsing, formatting, and ordering.
src/supported_formats.h	Declares and documents the new APIs.
src/cli.cpp	Connects list parsing to CLI/config handling.
src/cli.h	Stores ordered format preferences.
src/main.cpp	Applies preferences and reports missing formats.
tests/supported_formats_test.cpp	Tests parsing and advertisement ordering.
tests/cli_test.cpp	Tests CLI list handling and validation.
tests/config_file_test.cpp	Tests configuration precedence.
README.md	Updates user-facing option documentation.
packaging/sendspin-cli.conf.example	Updates the packaged configuration example.
docs/wiki/Configuration.md	Documents configuration syntax and semantics.
docs/wiki/Advanced-Usage.md	Expands usage guidance.
docs/ROADMAP.md	Updates the shipped feature description.

Review details

• Files reviewed: 13/13 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.