Improve PulseAudio/PipeWire integration and audio device discovery (#240)

## Summary
This PR enhances Sendspin's audio output handling on Linux desktop
environments by properly identifying the application to the sound server
and improving the audio device discovery experience.

## Key Changes
- **PulseAudio/PipeWire metadata**: Added `_set_pulse_client_metadata()`
function that sets libpulse environment variables before client
connection, allowing the audio stream to register as "Sendspin" instead
of a generic "ALSA plug-in [python3]" name. Users can override these
defaults by setting their own environment variables.

- **Audio device recommendations**: Enhanced `list_audio_devices()` to
display recommended desktop audio routing options (`pulse`, `pipewire`,
`default`) when available, making it easier for users to choose
appropriate devices.

- **Improved help text**: Updated help documentation for the
`--audio-device` argument in both player and daemon modes to explicitly
mention that `pulse`, `pipewire`, and `default` are available routing
options on Linux desktops.

- **Automatic initialization**: The metadata setup is called
automatically in `main()` before argument parsing, ensuring proper
identification with the sound server from the start.

## Implementation Details
- The metadata function uses `os.environ.setdefault()` to respect user
overrides
- Recommended devices are filtered to only show those actually available
on the system
- The changes are backward compatible and only affect Linux desktop
environments using PulseAudio or PipeWire

https://claude.ai/code/session_01H1fE1RpT8dQd3FEhveB5qe

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: balloob

sendspin/cli.py

@@ -63,6 +63,25 @@ def arg_str_to_bool(v: str) -> bool:
     raise argparse.ArgumentTypeError("Expected true or false")
 
 
+def _set_pulse_client_metadata() -> None:
+    """Identify the audio stream as Sendspin to the desktop sound server.
+
+    libpulse reads these env vars when it opens the client connection
+    (used by the ALSA ``pulse`` / ``pipewire`` plug devices and by
+    pipewire-pulse). Without them, the stream registers under a generic
+    name like ``ALSA plug-in [python3]``. Only set values that aren't
+    already in the environment so the user can override.
+    """
+    defaults = {
+        "PULSE_PROP_application.name": "Sendspin",
+        "PULSE_PROP_application.id": "org.sendspin.cli",
+        "PULSE_PROP_application.icon_name": "audio-x-generic",
+        "PULSE_PROP_media.role": "music",
+    }
+    for key, value in defaults.items():
+        os.environ.setdefault(key, value)
+
+
 def list_audio_devices() -> None:
     """List all available audio output devices."""
     try:
@@ -106,6 +125,19 @@ def list_audio_devices() -> None:
                 if description:
                     print(f"       {description}")
 
+            alsa_names = {name for name, _ in alsa_devices}
+            recommended = [
+                ("pulse", "Routes through PulseAudio"),
+                ("pipewire", "Routes through PipeWire"),
+                ("default", "System default"),
+            ]
+            recommended = [(n, d) for n, d in recommended if n in alsa_names]
+            if recommended:
+                print("\nRecommended for desktop usage:")
+                print()
+                for name, description in recommended:
+                    print(f"  {name:<12} {description}")
+
 
 def _add_player_runtime_options(target: ArgumentTarget, *, suppress_defaults: bool = False) -> None:
     """Add the interactive player's runtime options."""
@@ -146,7 +178,8 @@ def _add_player_runtime_options(target: ArgumentTarget, *, suppress_defaults: bo
         help=(
             "Audio output device by index (e.g., 0, 1, 2), name prefix (e.g., 'MacBook'), "
             "or raw ALSA device name (e.g., 'dmixer', 'olohuone') for plugin devices like dmix. "
-            "Use 'sendspin audio-devices list' to see enumerated devices."
+            "On Linux desktops, 'pulse', 'pipewire', or 'default' route through the sound "
+            "server. Use 'sendspin audio-devices list' to see enumerated devices."
         ),
     )
     target.add_argument(
@@ -375,8 +408,10 @@ def _build_parser() -> argparse.ArgumentParser:
         type=str,
         default=None,
         help=(
-            "Audio output device by index (e.g., 0, 1, 2) or name prefix (e.g., 'MacBook'). "
-            "Use 'sendspin audio-devices list' to see available devices."
+            "Audio output device by index (e.g., 0, 1, 2), name prefix (e.g., 'MacBook'), "
+            "or raw ALSA device name (e.g., 'dmixer', 'olohuone') for plugin devices like dmix. "
+            "On Linux desktops, 'pulse', 'pipewire', or 'default' route through the sound "
+            "server. Use 'sendspin audio-devices list' to see available devices."
         ),
     )
     daemon_parser.add_argument(
@@ -693,6 +728,8 @@ async def _run_daemon_mode(
 
 def main() -> int:
     """Run the CLI client."""
+    if sys.platform.startswith("linux"):
+        _set_pulse_client_metadata()
     args = parse_args(sys.argv[1:])
 
     # Handle serve subcommand