bhetherman/spotify-voice-assistant
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Update documentation for v1.0.0 release

Browse Source 
Major documentation updates:
- Streamline README by removing redundant sections
- Link to example files instead of duplicating configuration
- Fix typos and update model recommendations
- Add GPU acceleration documentation link
- Remove outdated "Prompt Optimization" section

Test suite improvements:
- Add comprehensive queue management tests (5 new tests)
- Add shuffle control tests (3 new tests)
- Fix combined query references to match current system prompt
- Update total test count to 53
- Renumber all test sections for consistency
- TODO refresh
This commit is contained in:
Chad Auld committed 2025-11-20 18:14:06 -07:00
1 parent db0303d8a9
commit 4d477fa218
8 files changed
+506 -589
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

TODO.md
+149 -119
View File
@@ -1,76 +1,88 @@
# TODO
Development roadmap and enhancement proposals for Spotify Voice Assistant.
Development roadmap and future enhancements for Spotify Voice Assistant.
## Future Enhancements
**Current Version:** v1.0.0
### 1. Artist Filter Parameter
Add optional artist filter parameter to improve multi-part query accuracy.
## Completed in v1.0.0
**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
- Exact match search for all content types (artists, albums, tracks, playlists)
- Smart playlist search (user playlists first, then public)
- Queue functionality (play vs queue modes)
- Shuffle controls
- Performance caching (Spotify client + user playlists)
- Clear cache service
- Comprehensive test 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.~~
## Future Enhancements
**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
### 1. Podcast Support
**Also implemented:**
- Playlist exact matching with same logic
- User playlist search with exact and partial matching
- Caching for user playlists to improve performance
Add support for searching and playing podcasts and podcast episodes.
**Current limitation:**
- Integration only supports music content (artists, albums, tracks, playlists)
**Proposed:**
- Add `type="podcast"` for searching podcasts (shows)
- Add `type="episode"` for searching specific podcast episodes
- Support "Play the latest episode of [podcast name]"
- Support "Play [episode name] from [podcast name]"
**Implementation:**
- 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 to TEST_CASES.md
**API endpoints:**
- `client.search(query, ["show"])` for podcast search
- `client.search(query, ["episode"])` for episode search
- `client.get_show_episodes(show_id)` for getting episodes
---
### 2. Saved Content Quick Access
Extend saved/favorite content search beyond playlists.
**Currently supported:**
- User playlists via `type="playlist"` (searches user first, then public)
**Proposed additions:**
- `type="saved_tracks"` for liked songs
- `type="saved_albums"` for saved albums
- `type="followed_artists"` for followed artists
**Benefits:**
- "Play from my liked songs"
- "Play from my saved albums"
- Faster access to frequently played content
**Implementation:**
- Use Spotify API: `get_saved_tracks()`, `get_saved_albums()`, `get_followed_artists()`
- Handle pagination for large libraries
- Apply similar caching strategy as user playlists
- Add search/filter capabilities within saved content
---
### 3. Configuration Options
Allow users to configure integration behavior via Home Assistant UI or YAML.
**Proposed configurable options:**
Allow users to configure integration behavior via YAML or UI.
**Proposed options:**
- Number of results to check for exact match (currently hardcoded to 10)
- Cache duration/invalidation behavior
- Default search type when ambiguous
- Logging verbosity level
- 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:**
**Implementation:**
- Add config flow for UI-based configuration
- Support YAML configuration in `configuration.yaml`
- Ensure sensible defaults
@@ -78,86 +90,104 @@ Allow users to configure integration behavior via Home Assistant UI or YAML.
---
### 4. Integration with HA Assist
Make the integration work with Home Assistant's built-in voice pipeline (Assist) without requiring Extended OpenAI Conversation.
### 4. Artist Filter Parameter
**Current behavior:**
- Requires Extended OpenAI Conversation (or similar) to provide function calling interface
Add optional artist parameter for more precise filtering.
**Proposed enhancement:**
- Register as a native Home Assistant intent/sentence pattern
- Allow Assist to use it directly via standard voice pipeline
**Current approach:**
- LLM strips artist from query per system prompt
- Relies on Spotify's search ranking
**Proposed:**
- Add optional `artist` parameter to `search_spotify` service
- Example: `search_spotify(query="Yellow", type="track", artist="Coldplay")`
**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
- More precise matching for common track names (e.g., "Hurt" by NIN vs Johnny Cash)
- Explicit filtering vs relying on search ranking
**Trade-offs:**
- Would likely still require intent patterns like "Play [artist] on [device]"
- Requires LLM to extract both query and artist separately
- May reduce natural language flexibility
- Current approach works well for most cases
**Implementation:**
- Update `services.yaml` to add optional `artist` parameter
- Apply artist filtering in `__init__.py`
- Update Extended OpenAI function definition
- Maintain backward compatibility
---
### 5. HA Assist Integration
Make integration work with Home Assistant's built-in voice pipeline without requiring Extended OpenAI Conversation.
**Current limitation:**
- Requires Extended OpenAI Conversation (or similar) for function calling
**Proposed:**
- Register as native Home Assistant intent/sentence pattern
- Work directly with Assist voice pipeline
**Trade-offs:**
- Would likely require rigid intent patterns ("Play [artist] on [device]")
- Less flexible than LLM-based approach
- May lose natural language advantage
- Music Assistant already provides this via their voice support
**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)
**Consider:**
- Whether this adds value given Music Assistant's HA Assist integration
- Could maintain 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).
### 6. Multi-room/Group Playback
**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.
Add support for playing on speaker groups or multiple devices simultaneously.
**Current behavior:**
- Integration only supports music content (artists, albums, tracks, playlists)
- Podcasts are not searchable or playable
- Plays on single device specified in command
**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]"
**Proposed:**
- Support speaker groups defined in Home Assistant
- "Play Coldplay on all speakers"
- "Play Coldplay in the downstairs"
**Benefits:**
- Complete Spotify content coverage
- Voice control for podcast listening
- Consistent experience across all Spotify content types
**Implementation:**
- Detect speaker groups from media_player entities
- Update LLM prompt to understand group concepts
- Test with various Spotify Connect group configurations
**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
### 7. Playback Context Awareness
Add awareness of what's currently playing for smarter commands.
**Examples:**
- "Play more like this" - queue similar artists/tracks
- "Who is this?" - return current track/artist info
- "Add this to my workout playlist" - save current track
**Implementation:**
- Query current playback state from Spotify integration
- Add new service calls for context-aware operations
- Update LLM functions with current playback info
---
## Non-Goals
Things we explicitly won't implement:
1. **Advanced Spotify API features** - Use SpotifyPlus for this
2. **Multi-provider music aggregation** - Use Music Assistant for this
3. **Rich UI/queue management** - Use Music Assistant for this
4. **Cookie-based authentication** - Sticking with OAuth via HA's Spotify integration
---
## Contributing
Have ideas for enhancements? Open an issue or submit a PR on GitHub.