Skip to content

Add Music Library Hub - Unified Search, Browse, and Queue Management#7

Merged
YoeriVD merged 9 commits intodevfrom
copilot/add-music-library-command
Feb 25, 2026
Merged

Add Music Library Hub - Unified Search, Browse, and Queue Management#7
YoeriVD merged 9 commits intodevfrom
copilot/add-music-library-command

Conversation

Copy link

Copilot AI commented Feb 24, 2026 •
edited by YoeriVD
Loading

Description

Adds a comprehensive Music Library Hub command providing unified access to Music Assistant's library through a tab-based interface.

Four Main Tabs:

  • Search - Full-text search across library (artists, albums, tracks, playlists) with 50-item limit, 500ms debounce, and "add to queue" actions
  • Browse - Drill-down navigation through Artists → Albums → Tracks with 20-item pagination and breadcrumb back navigation
  • Recently Played - Quick access to 30 most recent items with auto-detected media type icons
  • Queue Manager - View/reorder/remove queue items, toggle shuffle, cycle repeat modes, clear queue with confirmation

API Methods Added (15 total):

// Library access with pagination
await client.search("Beatles", 50);
await client.getLibraryArtists(searchQuery, limit, offset);
await client.getLibraryAlbums(searchQuery, limit, offset);
await client.getLibraryPlaylists(searchQuery, limit, offset);

// Drill-down navigation
await client.getArtistAlbums(artistId, "library");
await client.getAlbumTracks(albumId, "library");
await client.getPlaylistTracks(playlistId, "library");

// Queue operations
await client.playMedia(track, queueId, QueueOption.NEXT);
await client.queueCommandMoveItem(queueId, itemId, -1); // move up
await client.queueCommandDelete(queueId, itemId);
await client.queueCommandClear(queueId);
await client.queueCommandShuffle(queueId, true);
await client.queueCommandRepeat(queueId, RepeatMode.ALL);

Implementation Details:

  • 996 lines of tab-based UI in music-library-hub.tsx
  • 275 lines of new methods in music-assistant-client.ts
  • 465 lines of comprehensive unit tests (27 new tests, 99.34% coverage)
  • Color-coded icons for media types, toast feedback for all operations
  • State management via useCachedPromise and useCachedState
  • Proper async handling of active player selection using getSelectedQueueID()
  • Controlled search bar component (always uses defined values, never undefined)

Bug Fixes:

  • Fixed incorrect function reference: replaced non-existent getStoredQueueID() with proper async getSelectedQueueID()
  • Fixed React controlled/uncontrolled component warning: search bar now always controlled by using empty string instead of undefined for non-search tabs

Screencast

Checklist

Original prompt

This section details on the original issue you should resolve

<issue_title>Music Library Hub - Unified Search, Browse, and Queue Management</issue_title>
<issue_description>## Description
Add a comprehensive "Music Library" command providing unified access to Music Assistant's library with four main features:

  1. Search: Full-text search across entire library with 50-item limit
  2. Browse: Drill-down navigation through Artists, Albums, and Playlists
  3. Recently Played: Quick access to recently played items
  4. Queue Manager: Reorder, remove, or clear items from the active queue

This is a complex view command with multiple tabs for power users who want deeper library exploration from the launcher.

Priority

P1 - Tier 2

Story Points

13

Effort Estimate

6-8 hours

Acceptance Criteria

General

  • Tab-based navigation between Search, Browse, Recently Played, and Queue Manager
  • Responsive UI that handles large result sets gracefully
  • All operations refresh data after execution
  • Comprehensive error handling with user-friendly messages
  • Support for all player types and queue scenarios

Search Tab

  • Text input for search query
  • Search across entire library (tracks, artists, albums, playlists)
  • Display first 50 results with pagination indicator
  • Show result metadata (artist, album, duration for tracks)
  • Select result to add to active queue (immediately after currently playing track)
  • Visual feedback (toast) on successful add or error
  • Loading state during search

Browse Tab

  • Sub-tabs or dropdown for Artists, Albums, Playlists
  • Artists list with 20-item virtual pagination
  • Click artist to see their albums (drill-down view)
  • Albums list with 20-item virtual pagination
  • Click album to see tracks (drill-down view)
  • Playlists list with 20-item virtual pagination
  • Click playlist to see tracks
  • Jump "back" or "up" navigation in drill-down views
  • "Add to Queue" button for each track/album/playlist

Recently Played Tab

  • List of recently played items (30-50 items)
  • Show metadata (artist, album, play count, last played date)
  • Virtual pagination (20 items per page)
  • "Add to Queue" quick action for each item

Queue Manager Tab

  • Display current queue items with track number and metadata
  • Drag-to-reorder functionality for queue items
  • Remove button for individual items
  • "Clear Queue" button with confirmation
  • Show queue state (shuffle, repeat) at top
  • Refresh to sync with server state
  • Error handling for concurrent queue modifications

Implementation Notes

  • Type: View Command (complex UI with tabs)
  • Base Pattern: Similar to src/manage-player-groups.tsx for tab structure
  • Key APIs:
    • search() - Search library (text query)
    • getLibraryArtists() - List library artists with pagination
    • getLibraryAlbums() - List library albums with pagination
    • getLibraryPlaylists() - List library playlists with pagination
    • getLibraryPlaylistTracks() - Get tracks in specific playlist
    • getLibraryArtistAlbums() - Get albums by artist
    • getLibraryAlbumTracks() - Get tracks in album
    • getRecentlyPlayedItems() - Get recently played items
    • getPlayerQueueItems() - Get current queue items
    • queueCommandDelete() - Remove item from queue
    • queueCommandMoveItem() - Reorder queue items
    • queueCommandClear() - Clear entire queue
  • Files to Create/Modify:
    • Create src/music-library-hub.tsx (new file)
    • Update package.json to add command entry for music-library or library

Architecture Notes

  • Use React hooks for tab state management
  • Implement virtual pagination for all list views (performance)
  • Consider caching search results (no refresh unless user searches again)
  • Queue state should refresh on every operation
  • Consider debouncing search input (search after 500ms of no typing)

Performance Considerations

  • Virtual pagination for large result sets (artists, albums, playlists)
  • Lazy-load drill-down data (only fetch when user clicks drill)
  • Search limit of 50 results (configurable in future)
  • Clear cached search results when leaving tab

Testing

  • Test search with various queries (empty, partial, no results)
  • Test browse navigation (artist drill, album drill, back navigation)
  • Test pagination for lists with 20+ items
  • Test add to queue from all tabs
  • Test queue reordering (different positions)
  • Test queue item removal
  • Test queue clear with confirmation
  • Test with different player types
  • Test error scenarios (API failures, no queue)
  • Test UI state persistence within command execution
  • Test with large result sets (100+ items)

Stretch Goals (Future Enhancements)

  • Save favorite searches
  • Playlist creation from search results
  • Favorite playlist indicators
  • Playback queue visualization...

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot AI and others added 3 commits February 24, 2026 18:38
@YoeriVD
Add Music Library Hub command with search, browse, recently played, a…
3f70103 
…nd queue management

Co-authored-by: YoeriVD <2865793+YoeriVD@users.noreply.github.com>
@YoeriVD
Add comprehensive tests for library and queue management methods
5d372f9 
Co-authored-by: YoeriVD <2865793+YoeriVD@users.noreply.github.com>
@YoeriVD
Fix code review issues: remove undefined onTabChange and correct sear…
25b6728 
…ch limit message

Co-authored-by: YoeriVD <2865793+YoeriVD@users.noreply.github.com>
Copilot AI changed the title [WIP] Add unified search and queue management for music library Add Music Library Hub - Unified Search, Browse, and Queue Management Feb 24, 2026
YoeriVD
YoeriVD reviewed Feb 24, 2026
View reviewed changes
YoeriVD
YoeriVD reviewed Feb 24, 2026
View reviewed changes
@YoeriVD
Merge Music Library Hub changelog into existing PR entry
4cfad34 
Co-authored-by: YoeriVD <2865793+YoeriVD@users.noreply.github.com>
@YoeriVD
Fix undefined getStoredQueueID import - use getSelectedQueueID properly
f0499b6 
Co-authored-by: YoeriVD <2865793+YoeriVD@users.noreply.github.com>
YoeriVD
YoeriVD reviewed Feb 24, 2026
View reviewed changes
Copy link
Owner

@YoeriVD YoeriVD left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot 19:44:28 The List view is changing an uncontrolled search bar to be controlled. This is likely caused by the searchText changing from undefined to a defined value, which should not happen. Decide between using a controlled or uncontrolled search bar element for the lifetime of the component. More info: https://reactjs.org/link/controlled-components

YoeriVD
YoeriVD reviewed Feb 24, 2026
View reviewed changes
Copy link
Owner

@YoeriVD YoeriVD left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot Error: API error: 500 Internal Server Error - Internal server error

MusicAssistantApi.sendCommand:music-assistant-api.ts:116:14

113:
114: if (!response.ok) {
115: const errorText = await response.text();
116: throw new Error(API error: ${response.status} ${response.statusText} - ${errorText});
117: }
118:
119: const data = await response.json();

@YoeriVD
Fix uncontrolled to controlled search bar warning
2cc321d 
Co-authored-by: YoeriVD <2865793+YoeriVD@users.noreply.github.com>
Copy link
Author

Copilot AI commented Feb 24, 2026

@copilot 19:44:28 The List view is changing an uncontrolled search bar to be controlled. This is likely caused by the searchText changing from undefined to a defined value, which should not happen...

Fixed! Changed searchText from undefined to "" (empty string) and onSearchTextChange from undefined to () => {} (no-op function) for non-search tabs. The search bar is now always controlled, preventing the React warning. (commit 2cc321d)

Copy link
Author

Copilot AI commented Feb 24, 2026

@copilot Error: API error: 500 Internal Server Error - Internal server error

MusicAssistantApi.sendCommand:music-assistant-api.ts:116:14...

This is a 500 Internal Server Error from the Music Assistant server, not a client-side code issue. To help diagnose this, could you provide more context:

  1. Which tab were you on when this occurred (Search, Browse, Recently Played, or Queue Manager)?
  2. What specific action triggered the error?
  3. Does this happen consistently or only sometimes?

The error suggests the Music Assistant server is having trouble processing the request. It could be:

  • An unsupported Music Assistant version
  • A specific API endpoint that's not available on your server
  • Server-side issues with your Music Assistant instance

If you can share which action triggers it, I can check if there's a code workaround or better error handling needed.

@YoeriVD YoeriVD marked this pull request as ready for review February 25, 2026 09:08
@YoeriVD YoeriVD self-requested a review February 25, 2026 09:08
@YoeriVD YoeriVD changed the base branch from dev to main February 25, 2026 09:17
@YoeriVD YoeriVD changed the base branch from main to dev February 25, 2026 09:17
@YoeriVD YoeriVD merged commit 14d7d7e into dev Feb 25, 2026
@YoeriVD YoeriVD deleted the copilot/add-music-library-command branch February 25, 2026 09:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@YoeriVD YoeriVD YoeriVD approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@YoeriVD YoeriVD

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Music Library Hub - Unified Search, Browse, and Queue Management

2 participants

@YoeriVD