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

Requirements

Before using this integration, you need:

Home Assistant - Obviously!
Spotify Premium account - Required for Spotify Connect API
Spotify integration - Home Assistant's official Spotify integration (provides OAuth authentication)
Extended OpenAI Conversation - Or another LLM-based conversation agent (Ollama, Google Generative AI, etc.)
At least one Spotify Connect device - Any speaker/device that appears in Spotify (see Compatible Speakers for examples)

Note: This integration is specifically designed for custom voice assistants (Extended OpenAI Conversation, etc.). If you're using Home Assistant's built-in voice pipeline without a custom LLM, Music Assistant's native voice support may be sufficient.

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 is excellent for UI-based music control, but voice commands require specific sentence patterns that break when using custom voice assistants (Extended OpenAI Conversation, etc.)
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
Standard Spotify search returns wrong artists - Personalized recommendations instead of exact matches (ask for Coldplay, get Taylor Swift)

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

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

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"]
- Default speaker: If no speaker is specified, use media_player.kitchen_speaker (change this to your preferred default)
- Parse commands like "Play {Artist/Album/Track}" and determine the media type automatically
- For playback control (pause, skip, volume), use the control_playback function

Customize the default speaker: Replace media_player.kitchen_speaker with your preferred media player entity ID. The LLM will use this when you say "Play Coldplay" without specifying a location.

Done! Try It

Standard Patterns (like intent-based systems):

"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%"

Natural Language (LLM advantage):

"I'm in the mood for some Coldplay"
"Put on that song Yellow"
"Start playing Coldplay" (uses default speaker from prompt)
"Can you play the Parachutes album?"
"Play me something by Coldplay"
"I want to hear some chill music from Coldplay"
"Play Coldplay but shuffle it"
"Put on some music from that British band with Chris Martin"

Conversational Playback Control:

"Make it louder" (instead of "Set volume to 70")
"Turn it down a bit" (instead of "Set volume to 30")
"Next song please" (instead of "Skip to next track")
"Stop the music" (instead of "Pause playback")

Note: When no speaker is specified, the LLM will use the default media player defined in your Extended OpenAI Conversation prompt. Add instructions like "If no speaker specified, use media_player.kitchen_speaker" to your system prompt.

Why Natural Language Matters

Traditional voice assistants require specific sentence patterns:

Intent Pattern: "Play [artist] on [speaker]"
✅ Works: "Play Coldplay on kitchen speaker"
❌ Fails: "I want to listen to Coldplay"
❌ Fails: "Put on some Coldplay"
❌ Fails: "Start playing Coldplay in the kitchen"

This integration uses LLM-based function calling to understand conversational requests:

LLM Understanding: Extracts intent from natural speech
✅ Works: "Play Coldplay on kitchen speaker"
✅ Works: "I want to listen to Coldplay"
✅ Works: "Put on some Coldplay"
✅ Works: "Start playing Coldplay in the kitchen"
✅ Works: "Play me that British band with Chris Martin"

The LLM understands what you mean, not just what you say.

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.

Use With Music Assistant

You can (and should!) use both Music Assistant and this integration together. They complement each other perfectly:

Music Assistant

Best for: Rich UI-based music control in dashboards and automations
Strengths: Multi-room audio, queue management, playlist management, beautiful UI
Voice support: Built-in voice commands work with Home Assistant's default voice pipeline
Limitation: Voice commands require specific sentence patterns and don't work with custom voice assistants (Extended OpenAI Conversation, custom LLMs, etc.)

This Integration (Spotify Voice Assistant)

Best for: Natural language voice control with custom voice assistants
Strengths: Works with Extended OpenAI Conversation, fully natural language, exact artist matching
Use case: "Play some Coldplay in the kitchen" → LLM interprets naturally and plays music
Limitation: Not a full music server, just search + playback control

Why Use Both?

Many users (including the author) run both together:

Music Assistant provides the UI for manual control, queue management, and automations
This integration handles natural language voice commands via custom LLM assistants
They work together seamlessly: Music started via voice appears in Music Assistant's UI and remains fully controllable there

Example workflow: Say "Play Coldplay on office speaker" → music starts → open Music Assistant UI → see what's playing, adjust volume, skip tracks, manage queue - all through MA's interface.

They don't conflict because they access the same underlying Spotify Connect devices. This integration just provides the search service that custom voice assistants need to find music.

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

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