# TODO

Development roadmap and enhancement proposals for Spotify Voice Assistant.

## Future Enhancements

### 1. Artist Filter Parameter
Add optional artist filter parameter to improve multi-part query accuracy.

**Current approach (v1.0.0):**
- Combine artist and song into query string: "Yellow Coldplay"
- Relies on Spotify's search ranking algorithm
- Works well via LLM prompt enhancement

**Proposed enhancement:**
- Add `artist` parameter to `search_spotify` service
- Apply artist filtering to search results
- Example: `search_spotify(query="Yellow", type="track", artist="Coldplay")`

**Benefits:**
- More precise matching when multiple artists have songs with same name (e.g., "Hurt" by Nine Inch Nails vs Johnny Cash)
- Explicit artist filtering vs relying on search ranking
- Better handling of edge cases

**Implementation notes:**
- Update `services.yaml` to add `artist` parameter (optional)
- Update `search_spotify` function in `__init__.py` to apply artist filtering
- Update function definition in Extended OpenAI Conversation
- Consider backward compatibility - make parameter optional
- Update documentation and examples

**Trade-offs:**
- Requires more specific parameter extraction from LLM
- May reduce flexibility of natural language queries
- Current combined query approach already works well for most cases

---

### 2. ~~Extend Exact Name Matching to Albums and Tracks~~ ✅ COMPLETED (v1.0.0)
~~Apply the same "exact match" logic currently used for artists to albums and tracks.~~

**Status:** Implemented in v1.0.0
- All search types (artist, album, track, playlist) now use exact name matching
- Searches use limit=10 and check for exact matches before falling back to first result
- Consistent behavior across all content types
- Logs indicate match type (exact/first/partial) for debugging

**Also implemented:**
- Playlist exact matching with same logic
- User playlist search with exact and partial matching
- Caching for user playlists to improve performance

---

### 3. Configuration Options
Allow users to configure integration behavior via Home Assistant UI or YAML.

**Proposed configurable options:**
- Number of results to check for exact match (currently hardcoded to 10)
- Whether to require exact match or allow fuzzy matching
- Default search type (artist/album/track) when not specified
- Cache duration/behavior
- Logging verbosity

**Current behavior:**
- All behavior is hardcoded in the integration

**Benefits:**
- Users can tune behavior for their specific needs without modifying code
- Easier troubleshooting with configurable logging
- Flexibility for different use cases

**Implementation notes:**
- Add config flow for UI-based configuration
- Support YAML configuration in `configuration.yaml`
- Ensure sensible defaults
- Document all options in README

---

### 4. Integration with HA Assist
Make the integration work with Home Assistant's built-in voice pipeline (Assist) without requiring Extended OpenAI Conversation.

**Current behavior:**
- Requires Extended OpenAI Conversation (or similar) to provide function calling interface

**Proposed enhancement:**
- Register as a native Home Assistant intent/sentence pattern
- Allow Assist to use it directly via standard voice pipeline

**Benefits:**
- Users who want to use HA's default voice pipeline (Whisper → built-in LLM → actions) could use this integration
- Lower barrier to entry for non-technical users

**Trade-offs:**
- Would likely still require intent patterns like "Play [artist] on [device]"
- Less flexible than LLM-based approach
- May lose natural language advantage

**Implementation notes:**
- Register intent handlers via Home Assistant's conversation integration
- Define sentence patterns for common use cases
- Consider maintaining both approaches (function calling + intent patterns)

---

### 5. Saved/Favorite Content Quick Access
Add ability to search/play from user's Spotify saved content (liked songs, saved albums, followed artists).

**Status:** Partially implemented in v1.0.0
- ✅ User playlists: `type="user_playlist"` searches only saved playlists
- ✅ Caching implemented for user playlist data
- ⏳ Future: Saved tracks, albums, and followed artists

**Implemented in v1.0.0:**
- Voice commands like "Play my workout playlist" now work
- Searches only user's saved playlists (not all of Spotify)
- Exact and partial matching for user playlists
- Performance-optimized with caching

**Still to implement:**
- `type="saved_tracks"` for liked songs
- `type="saved_albums"` for saved albums
- `type="followed_artists"` for followed artists

**Implementation notes:**
- Use Spotify API endpoints: `get_saved_tracks()`, `get_saved_albums()`
- Handle pagination for large libraries
- Apply similar caching strategy as user playlists

---

### 6. Podcast Support
Add support for searching and playing podcasts and podcast episodes.

**Current behavior:**
- Integration only supports music content (artists, albums, tracks, playlists)
- Podcasts are not searchable or playable

**Proposed enhancement:**
- Add `type="podcast"` for searching podcasts (shows)
- Add `type="episode"` for searching specific podcast episodes
- Support playing latest episode: "Play the latest episode of [podcast name]"
- Support playing specific episodes: "Play [episode name] from [podcast name]"

**Benefits:**
- Complete Spotify content coverage
- Voice control for podcast listening
- Consistent experience across all Spotify content types

**Implementation notes:**
- Use Spotify API search types: `show` and `episode`
- Consider caching user's saved/followed podcasts
- Handle episode-specific logic (latest vs specific episode)
- Update Extended OpenAI function definitions
- Update system prompts with podcast examples
- Add podcast test cases

**API endpoints needed:**
- `client.search(query, ["show"])` for podcast search
- `client.search(query, ["episode"])` for episode search
- `client.get_show_episodes(show_id)` for getting episodes
- Potentially: saved/followed shows endpoint