Voice-controlled Spotify playback using natural language. Just say "Play Coldplay on the kitchen speaker" and your music starts playing - no complex YAML patterns, no cookie authentication, just works.

The Problem

Want to control Spotify with your voice in Home Assistant? You'll quickly hit these issues:

Spotcast requires cookie authentication (sp_dc, sp_key) which breaks frequently with "serverTime" errors
Music Assistant requires running a separate music server - heavyweight for just Spotify
SpotifyPlus is feature-rich but complex to set up for simple voice commands
Custom Sentences require rigid YAML patterns - "Play {artist} on {speaker}" instead of natural language
Built-in Spotify integration has no search service for voice assistants to use
Other integrations return wrong artists - Standard Spotify search returns personalized recommendations instead of exact matches

The Solution

A lightweight integration designed specifically for voice assistants that:

✅ Natural language from day one - "Play Coldplay" not "play artist equals Coldplay" ✅ Zero additional authentication - Reuses your existing Home Assistant Spotify OAuth ✅ Exact match artist search - Finds Coldplay when you ask for Coldplay, not recommendations ✅ Works with any Spotify Connect device - WiiM, Sonos, Google Cast, Echo, whatever you have ✅ Under 120 lines of code - Simple, maintainable, easy to understand ✅ Voice assistant ready - Complete Extended OpenAI Conversation examples included

Quick Start

Say goodbye to complex configurations. Get voice-controlled music in 3 steps:

1. Install Prerequisites

Spotify Premium account (required for Spotify Connect)
Official Spotify integration configured in Home Assistant
Extended OpenAI Conversation (or another LLM conversation agent)
At least one Spotify Connect device (see Compatible Speakers)

2. Install This Integration

Via HACS (Recommended):

HACS > Integrations > ⋮ (menu) > Custom repositories
Add: https://github.com/cauld/spotify-voice-assistant
Category: Integration
Install "Spotify Voice Assistant"
Restart Home Assistant

Manual Installation:

Download this repository
Copy custom_components/spotify_search to your HA custom_components folder
Restart Home Assistant

Add to configuration.yaml:

spotify_search:

3. Configure Extended OpenAI Conversation

Copy these functions to Extended OpenAI Conversation settings:

Click to expand function configuration

- spec:
    name: search_spotify
    description: Search Spotify for an artist, album, or track and return the Spotify URI. Use this before playing music to get the URI.
    parameters:
      type: object
      properties:
        query:
          type: string
          description: Artist, album, or track name to search for (e.g., "Coldplay", "Parachutes", "Yellow")
        type:
          type: string
          enum: [artist, album, track]
          description: Type of content to search for
      required:
        - query
        - type
  function:
    type: script
    sequence:
      - service: spotify_search.search
        response_variable: _function_result
        data:
          query: "{{ query }}"
          type: "{{ type }}"

- spec:
    name: play_music
    description: Play music on a Spotify Connect device using a Spotify URI. You must first call search_spotify to get the URI.
    parameters:
      type: object
      properties:
        spotify_uri:
          type: string
          description: Spotify URI from search_spotify (e.g., "spotify:artist:4gzpq5DPGxSnKTe4SA8HAU")
        media_player:
          type: string
          description: Entity ID of Spotify Connect media player (e.g., "media_player.kitchen_speaker")
      required:
        - spotify_uri
        - media_player
  function:
    type: script
    sequence:
      - service: media_player.play_media
        target:
          entity_id: "{{ media_player }}"
        data:
          media_content_id: "{{ spotify_uri }}"
          media_content_type: "music"

- spec:
    name: control_playback
    description: Control music playback (pause, resume, stop, next track, previous track, set volume)
    parameters:
      type: object
      properties:
        action:
          type: string
          enum: [pause, play, stop, next_track, previous_track, volume_set]
          description: Playback control action
        media_player:
          type: string
          description: Entity ID of media player
        volume_level:
          type: number
          description: Volume level (0-100) for volume_set action only
      required:
        - action
        - media_player
  function:
    type: script
    sequence:
      - choose:
          - conditions:
              - condition: template
                value_template: "{{ action == 'pause' }}"
            sequence:
              - service: media_player.media_pause
                target:
                  entity_id: "{{ media_player }}"
          - conditions:
              - condition: template
                value_template: "{{ action == 'play' }}"
            sequence:
              - service: media_player.media_play
                target:
                  entity_id: "{{ media_player }}"
          - conditions:
              - condition: template
                value_template: "{{ action == 'stop' }}"
            sequence:
              - service: media_player.media_stop
                target:
                  entity_id: "{{ media_player }}"
          - conditions:
              - condition: template
                value_template: "{{ action == 'next_track' }}"
            sequence:
              - service: media_player.media_next_track
                target:
                  entity_id: "{{ media_player }}"
          - conditions:
              - condition: template
                value_template: "{{ action == 'previous_track' }}"
            sequence:
              - service: media_player.media_previous_track
                target:
                  entity_id: "{{ media_player }}"
          - conditions:
              - condition: template
                value_template: "{{ action == 'volume_set' }}"
            sequence:
              - service: media_player.volume_set
                target:
                  entity_id: "{{ media_player }}"
                data:
                  volume_level: "{{ volume_level / 100 }}"

Add this to your Extended OpenAI Conversation system prompt:

Music Playback:
- When asked to play music, follow this two-step process: 1) Call search_spotify to get the Spotify URI, 2) Call play_music with the URI and media player entity
- Available media players: [list your Spotify Connect devices here, e.g., "media_player.kitchen_speaker, media_player.living_room_sonos"]
- Parse commands like "Play {Artist/Album/Track}" and determine the media type automatically
- For playback control (pause, skip, volume), use the control_playback function

Done! Try It

"Play Coldplay on the kitchen speaker"
"Play the album Parachutes"
"Play Yellow by Coldplay"
"Pause the music"
"Skip to the next track"
"Set volume to 50%"

Compatible Speakers

This integration works with any Spotify Connect-compatible device:

Tested & Verified

WiiM Audio Pro (and all WiiM speakers)
Sonos speakers (all models with Spotify)
Google Nest/Home speakers
Amazon Echo with Spotify

Should Work (Spotify Connect Compatible)

Smart Speakers:
- Apple HomePod (with Spotify app)
- Bose Home Speaker series
- JBL Link series
- Harman Kardon Citation series
- Bang & Olufsen Beosound series
Streaming Devices:
- Chromecast Audio
- Roku with Spotify channel
- Fire TV with Spotify
- Apple TV with Spotify app
AV Receivers:
- Denon HEOS-enabled receivers
- Yamaha MusicCast receivers
- Marantz NR/SR series
- Pioneer VSX series with Spotify
DIY Solutions:
- Raspberry Pi with Raspotify
- Raspberry Pi with Spotifyd
- Any Linux/Mac/Windows computer running Spotify
Mobile Devices:
- Phones/tablets running Spotify app (for testing)

Requirements

Spotify Premium account (Spotify Connect requires Premium)
Device must show up in Home Assistant as a media_player entity
Device must support Spotify Connect (check manufacturer specs)

Note: If your device runs Spotify and shows up in Home Assistant's integrations, it will work with this integration.

How It Works

The Two-Step Process

1. Search Spotify

You: "Play Coldplay"
LLM: Calls search_spotify(query="Coldplay", type="artist")
Response: {"uri": "spotify:artist:4gzpq5DPGxSnKTe4SA8HAU", "name": "Coldplay"}

2. Play on Device

LLM: Calls play_music(uri="spotify:artist:...", media_player="media_player.kitchen_speaker")
Result: Music starts playing

Exact Match Artist Search

When searching for artists, this integration uses smart matching to avoid Spotify's personalization issues:

Queries Spotify for top 10 artist results
Checks each result for exact name match (case-insensitive)
Returns exact match if found, otherwise returns first result
Logs match type (exact/first) for debugging

Why this matters: Standard Spotify search prioritizes personalized recommendations. If you search "Coldplay," you might get Taylor Swift if you listen to her frequently. Our exact matching ensures you get Coldplay when you ask for Coldplay.

No Additional Authentication

The integration leverages Home Assistant's official Spotify integration:

Uses existing OAuth tokens
No cookies to manage (sp_dc, sp_key)
No tokens to refresh
Works as long as your Spotify integration works

Performance Optimization

The integration includes smart caching for optimal performance:

First search: ~1.6-5.6ms (finds and caches Spotify client) Subsequent searches: ~0.1ms (uses cached client) Performance gain: 15-50x faster on repeated searches

Cache Features:

Automatically validates cached client on every call
Self-invalidates when Spotify integration is reloaded or removed
Manual cache clearing available via spotify_search.clear_cache service

The cache is module-level and process-scoped, so it clears automatically on Home Assistant restart.

Advanced Usage

Developer Tools Testing

Test the search service directly:

service: spotify_search.search
data:
  query: "Coldplay"
  type: "artist"

Response:

{
  "uri": "spotify:artist:4gzpq5DPGxSnKTe4SA8HAU",
  "name": "Coldplay",
  "type": "artist"
}

Use in Automations

automation:
  - alias: "Morning Music"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: spotify_search.search
        response_variable: artist_result
        data:
          query: "Chillhop Music"
          type: "artist"
      - service: media_player.play_media
        target:
          entity_id: media_player.kitchen_speaker
        data:
          media_content_id: "{{ artist_result.uri }}"
          media_content_type: "music"

Clear Cache Service

If you experience issues after removing or re-adding the Spotify integration, you can manually clear the cached client:

service: spotify_search.clear_cache

The cache automatically invalidates when the Spotify integration is reloaded, so manual clearing is rarely needed.

Debug Logging

Enable detailed logging in configuration.yaml:

logger:
  default: info
  logs:
    custom_components.spotify_search: debug

This shows search queries, match types (exact vs. first result), and any errors.

Troubleshooting

"No Spotify media player entity found"

Cause: Official Spotify integration not configured.

Solution:

Settings > Integrations > Add Integration
Search for "Spotify"
Complete OAuth authentication
Verify media_player.spotify_* entity appears
Restart Home Assistant

"Spotify entity does not have a coordinator"

Cause: Spotify integration hasn't fully initialized.

Solution: Wait 30 seconds after HA starts, or restart Home Assistant.

Voice commands not working

Cause: Extended OpenAI Conversation functions not configured.

Solution:

Verify functions are added to Extended OpenAI settings
Check system prompt includes music playback instructions
Test search service manually in Developer Tools
Check Home Assistant logs for errors

Wrong artist/song playing

Cause: Exact match not found in top 10 results.

Solution:

Use more specific query: "Coldplay band" instead of just "Coldplay"
Check search result in Developer Tools first
Try searching by track or album if artist search fails

Music won't play on speaker

Cause: Device not Spotify Connect compatible or not in HA.

Solution:

Verify device supports Spotify Connect (check manufacturer site)
Check device shows in Settings > Integrations
Test playing Spotify directly to device from Spotify app
Verify Spotify Premium account is active

Comparison with Alternatives

Feature	Spotify Voice Assistant	Spotcast	Music Assistant	SpotifyPlus
Primary Focus	Voice control	Casting	Full music server	Spotify API wrapper
Lines of Code	<120	1000+	10,000+	5000+
Authentication	Reuses HA OAuth	Cookies (breaks often)	Own server auth	Own OAuth flow
Setup Complexity	1 YAML line	Cookies + config	Full server install	Complex config
Exact Artist Match	✅ Yes	❌ No	✅ Yes	✅ Yes
Voice Assistant Ready	✅ Yes (built-in)	⚠️ Partial	✅ Yes	⚠️ Partial
Natural Language	✅ LLM-based	❌ Rigid patterns	✅ LLM-based	❌ Manual calls
External Dependencies	None	None	Separate server	None
Hardware Support	Any Spotify Connect	Chromecast focused	Universal	Any Spotify Connect

Features

✅ Voice-first design - Built for natural language from day one
✅ Hardware agnostic - Works with any Spotify Connect device
✅ Search by type - Artists, albums, tracks, playlists
✅ Exact match preference - Finds what you ask for, not recommendations
✅ Complete examples - Extended OpenAI Conversation config included
✅ Playback control - Pause, play, skip, volume - all via voice
✅ Zero config authentication - Leverages existing Spotify integration
✅ Detailed logging - Debug mode shows exactly what's happening
✅ Service response support - Returns data to automations/scripts

Roadmap

Playlist search support
Configuration options (search limits, match behavior)
Search result caching for faster responses
Support for multiple search result types
Album/track exact name matching
Integration with HA Assist (native conversation)
Favorite/saved content quick access
Multi-room playback examples

Contributing

Contributions welcome! Please submit a Pull Request.

Support

Issues: GitHub Issues
Discussions: Home Assistant Community

License

MIT License - See LICENSE file for details

Acknowledgments

Built on Home Assistant Spotify integration
Designed for Extended OpenAI Conversation
Inspired by the HA community's need for simple voice-controlled music