feat: Add device selection and management for multi-room audio control

[jmward09]

Overview

This PR adds device selection and management capabilities to enable multi-room audio control through Spotify Connect. This feature enables voice assistants and automation systems to route playback to specific devices (e.g., "play this in the kitchen" or "transfer to the living room speaker").

Implementation

This PR implements a hybrid approach that addresses the concerns raised in #11:

Approach 1: Separate Devices Tool (For Simplicity)

• New Devices tool with list and transfer actions
• Clear separation of concerns for device management
• Easier for small LLMs to understand and use

Approach 2: Enhanced Playback Tool (For Convenience)

• Added optional device_id parameter to Playback tool's start action
• Allows inline device specification: "start this track on device X"
• Maintains backward compatibility (parameter is optional)

This hybrid approach provides:

• Simplicity: Dedicated Devices tool for discovery and transfer
• Convenience: Inline device control when starting playback
• Flexibility: Users can choose the approach that fits their use case
• Backward Compatibility: All existing functionality preserved

Changes

1. Enhanced Playback Tool

class Playback(ToolModel):
    # ... existing fields ...
    device_id: Optional[str] = Field(
        default=None, 
        description="Optional device ID to start playback on. Use Devices tool to get available device IDs."
    )

When device_id is provided, the handler uses direct spotipy calls for device control:

• Supports both track URIs (uris parameter) and context URIs (context_uri parameter)
• Falls back to existing behavior when device_id is omitted

2. New Devices Tool

class Devices(ToolModel):
    """Manage Spotify playback devices.
    - list: Get all available Spotify Connect devices.
    - transfer: Transfer playback to a specific device.
    """
    action: str = Field(description="Action to perform: 'list' or 'transfer'.")
    device_id: Optional[str] = Field(default=None, description="Device ID to transfer playback to (required for transfer action).")
    play: Optional[bool] = Field(default=True, description="Whether to start playing after transfer (default: true).")

Actions:

• list: Returns all available Spotify Connect devices with id, name, type, volume, is_active
• transfer: Transfers playback to specified device with optional auto-play

Testing

Tested with 13 Spotify Connect devices including:

• WiiM Pro Plus (dedicated audio system)
• iMac (Loki)
• Amazon Echo devices (Kitchen, Living Room, Bedroom, etc.)
• Echo groups (Everywhere, Downstairs)

Test Cases:

• ✅ List all devices (13 devices returned)
• ✅ Transfer playback between devices (WiiM ↔ Loki)
• ✅ Start playback on specific device with track URI
• ✅ Start playback on specific device with context URI
• ✅ Backward compatibility: Playback without device_id works as before
• ✅ Resume playback on specific device (no URI, just device_id)

Use Cases

1. Voice Assistants: "Play this song in the kitchen"
2. Multi-Room Audio: Move playback as you move between rooms
3. Device-Specific Automations: High-quality audio on dedicated systems, announcements on smart speakers
4. Context-Aware Playback: Different devices for different scenarios (work playlist on desktop, party music on speakers)

Relation to #11

This PR addresses the design discussion in #11 where:

• @varunneal preferred adding device_id to existing tools
• @Shringe proposed a dedicated device management tool

Our hybrid approach implements both suggestions, providing the simplicity of a dedicated tool while also offering the convenience of inline device control. This gives users maximum flexibility while maintaining clean separation of concerns.

Backward Compatibility

All existing functionality is preserved:

• Playback tool works exactly as before when device_id is omitted
• No breaking changes to existing integrations
• Optional parameters only

Documentation

Comprehensive documentation included in production deployment:

• Device selection examples
• Multi-room audio use cases
• Integration patterns with Home Assistant
• Troubleshooting guide

Would be happy to add documentation to the repo if desired.

---

Related PRs:

• feat: Add SPOTIPY_CACHE_PATH environment variable support #45: SPOTIPY_CACHE_PATH environment variable support