Add play/append/queue actions to Spotify and YouTube search results

Search results overlays now support Enter (play now), a (append), and
q (queue next) on the selected track, instead of only routing to a
Spotify cloud-playlist add. The cloud-playlist add moves to p.

YouTube/SoundCloud net search gains a results picker (ytsearch10 /
scsearch10) using the same keymap, replacing the previous one-shot
ytsearch1 auto-queue. Adds shared playTrackImmediate / appendTrack /
queueTrackNext helpers and closeNetSearch / closeSpotSearch helpers
that drop cached result slices on close.

playlist.IsYTSearch generalises the ytsearch:/ytsearchN:/scsearch:/
scsearchN: prefix check used by IsURL, IsYouTubeURL, and IsYTDL.

Author: bjarneo

docs/keybindings.md

@@ -71,6 +71,19 @@ Press `Ctrl+K` in the player to see all keybindings.
 | `r` | Cycle repeat (Off / All / One) |
 | `z` | Toggle shuffle |
 
+## Search results overlays
+
+When `Ctrl+F` opens the Spotify search or YouTube/SoundCloud net search and you're viewing the results list:
+
+| Key | Action |
+|---|---|
+| `↑` `↓` / `j` `k` | Move cursor |
+| `Enter` | Play the selected track now |
+| `a` | Append the selected track to the playlist |
+| `q` | Queue the selected track to play next |
+| `p` | (Spotify only) Save the selected track to a Spotify playlist |
+| `Esc` `Backspace` | Back to the search input |
+
 ## General
 
 | Key | Action |

playlist/playlist.go

@@ -62,8 +62,30 @@ func (t Track) Meta(key string) string {
 // IsURL reports whether path is an HTTP or HTTPS URL, or a yt-dlp search protocol string.
 func IsURL(path string) bool {
 	return strings.HasPrefix(path, "http://") || strings.HasPrefix(path, "https://") ||
-		strings.HasPrefix(path, "ytsearch:") || strings.HasPrefix(path, "ytsearch1:") ||
-		strings.HasPrefix(path, "scsearch:") || strings.HasPrefix(path, "scsearch1:")
+		IsYTSearch(path)
+}
+
+// IsYTSearch reports whether path is a yt-dlp search expression
+// (ytsearch:, ytsearchN:, scsearch:, scsearchN:).
+func IsYTSearch(path string) bool {
+	return matchSearchPrefix(path, "ytsearch") || matchSearchPrefix(path, "scsearch")
+}
+
+func matchSearchPrefix(path, name string) bool {
+	if !strings.HasPrefix(path, name) {
+		return false
+	}
+	rest := path[len(name):]
+	colon := strings.IndexByte(rest, ':')
+	if colon < 0 {
+		return false
+	}
+	for _, c := range rest[:colon] {
+		if c < '0' || c > '9' {
+			return false
+		}
+	}
+	return true
 }
 
 // IsM3U reports whether the path points to an M3U playlist file (URL or local).
@@ -109,7 +131,7 @@ func IsYouTubeURL(path string) bool {
 		return false
 	}
 	// ytsearch: protocols are handled by yt-dlp, not the native YouTube client.
-	if strings.HasPrefix(path, "ytsearch:") || strings.HasPrefix(path, "ytsearch1:") {
+	if IsYTSearch(path) {
 		return false
 	}
 	u, err := url.Parse(path)
@@ -152,8 +174,7 @@ func IsYTDL(path string) bool {
 	if IsYouTubeURL(path) || IsYouTubeMusicURL(path) {
 		return true
 	}
-	if strings.HasPrefix(path, "ytsearch:") || strings.HasPrefix(path, "ytsearch1:") ||
-		strings.HasPrefix(path, "scsearch:") || strings.HasPrefix(path, "scsearch1:") {
+	if IsYTSearch(path) {
 		return true
 	}
 	u, err := url.Parse(path)

playlist/url_test.go

@@ -11,8 +11,11 @@ func TestIsURL(t *testing.T) {
 		{"https://example.com/stream.mp3", true},
 		{"ytsearch:lofi hip hop", true},
 		{"ytsearch1:some song", true},
+		{"ytsearch10:multi result query", true},
 		{"scsearch:artist name", true},
 		{"scsearch1:track name", true},
+		{"scsearch10:multi result query", true},
+		{"ytsearchabc:bad", false},
 		{"/home/user/music/song.mp3", false},
 		{"relative/path.flac", false},
 		{"", false},
@@ -122,6 +125,7 @@ func TestIsYouTubeURL(t *testing.T) {
 		// ytsearch protocols should NOT match
 		{"ytsearch:lofi hip hop", false},
 		{"ytsearch1:some song", false},
+		{"ytsearch10:multi result query", false},
 		// Non-YouTube
 		{"https://soundcloud.com/artist/track", false},
 		{"/local/file.mp3", false},
@@ -170,8 +174,10 @@ func TestIsYTDL(t *testing.T) {
 		// Search protocols
 		{"ytsearch:lofi hip hop", true},
 		{"ytsearch1:some song", true},
+		{"ytsearch10:multi result query", true},
 		{"scsearch:artist name", true},
 		{"scsearch1:track name", true},
+		{"scsearch5:multi result query", true},
 		// SoundCloud
 		{"https://soundcloud.com/artist/track", true},
 		// Bandcamp

site/index.html

@@ -1478,7 +1478,7 @@ <h3>Run the setup wizard</h3>
       <div class="source" style="--src-color:#ff0000">
         <div class="source-badge">yt-dlp</div>
         <div class="source-name">YouTube</div>
-        <div class="source-desc">Search and queue videos. Press <kbd>f</kbd> to search in-player.</div>
+        <div class="source-desc">Search videos with <kbd>Ctrl+F</kbd>, then play, append, or queue from a results list.</div>
       </div>
       <div class="source" style="--src-color:#ff0000">
         <div class="source-badge">OAuth · cached</div>
@@ -1910,6 +1910,17 @@ <h3>Run the setup wizard</h3>
         </div>
       </div>
 
+      <div class="keys-group">
+        <div class="keys-group-title">Search Results</div>
+        <div class="keys-group-body">
+          <div class="key-row"><kbd>Enter</kbd><span>Play selected track now</span></div>
+          <div class="key-row"><kbd>a</kbd><span>Append selected to playlist</span></div>
+          <div class="key-row"><kbd>q</kbd><span>Queue selected to play next</span></div>
+          <div class="key-row"><kbd>p</kbd><span>Save to Spotify playlist (Spotify only)</span></div>
+          <div class="key-row"><kbd>Esc</kbd><span>Back to search input</span></div>
+        </div>
+      </div>
+
       <div class="keys-group">
         <div class="keys-group-title">Providers &amp; UI</div>
         <div class="keys-group-body">

ui/model/commands.go

@@ -64,8 +64,12 @@ type lyricsLoadedMsg struct {
 	err   error
 }
 
-// netSearchLoadedMsg carries tracks dynamically searched from the internet.
-type netSearchLoadedMsg []playlist.Track
+// netSearchResultsMsg carries the result set of a yt-dlp/sc-dlp search query
+// so the UI can present a picker rather than auto-queuing.
+type netSearchResultsMsg struct {
+	tracks []playlist.Track
+	err    error
+}
 
 // streamPlayedMsg signals that async stream Play() completed.
 type streamPlayedMsg struct{ err error }
@@ -189,10 +193,7 @@ func fetchLyricsCmd(artist, title string) tea.Cmd {
 func fetchNetSearchCmd(query string) tea.Cmd {
 	return func() tea.Msg {
 		tracks, err := resolve.Remote([]string{query})
-		if err != nil {
-			return err
-		}
-		return netSearchLoadedMsg(tracks)
+		return netSearchResultsMsg{tracks: tracks, err: err}
 	}
 }
 

ui/model/keys.go

@@ -652,9 +652,10 @@ func (m *Model) handleKey(msg tea.KeyPressMsg) tea.Cmd {
 				screen:  spotSearchInput,
 			}
 		} else {
-			m.netSearch.active = true
-			m.netSearch.query = ""
-			m.netSearch.soundcloud = false
+			m.netSearch = netSearchState{
+				active: true,
+				screen: netSearchInput,
+			}
 			m.prevFocus = m.focus
 			m.focus = focusNetSearch
 		}
@@ -1027,7 +1028,9 @@ func (m *Model) handlePaste(content string) tea.Cmd {
 	}
 
 	if m.netSearch.active {
-		m.netSearch.query += content
+		if m.netSearch.screen == netSearchInput {
+			m.netSearch.query += content
+		}
 		return nil
 	}
 
@@ -1118,32 +1121,37 @@ func (m *Model) handleSearchKey(msg tea.KeyPressMsg) tea.Cmd {
 	return nil
 }
 
-// handleNetSearchKey processes key presses while in net search mode.
+// handleNetSearchKey dispatches key presses to the active net search screen.
 func (m *Model) handleNetSearchKey(msg tea.KeyPressMsg) tea.Cmd {
-	switch msg.String() {
-	case "ctrl+k":
+	if msg.String() == "ctrl+k" {
 		m.openKeymap()
 		return nil
 	}
+	switch m.netSearch.screen {
+	case netSearchInput:
+		return m.handleNetSearchInputKey(msg)
+	case netSearchResults:
+		return m.handleNetSearchResultsKey(msg)
+	}
+	return nil
+}
 
+// handleNetSearchInputKey handles text entry on the net search overlay.
+func (m *Model) handleNetSearchInputKey(msg tea.KeyPressMsg) tea.Cmd {
 	switch msg.Code {
 	case tea.KeyEscape:
-		m.netSearch.active = false
-		m.focus = m.prevFocus
+		m.closeNetSearch()
 
 	case tea.KeyEnter:
-		var cmd tea.Cmd
-		m.netSearch.active = false
-		m.focus = m.prevFocus
-		if strings.TrimSpace(m.netSearch.query) != "" {
-			prefix := "ytsearch1:"
+		if strings.TrimSpace(m.netSearch.query) != "" && !m.netSearch.loading {
+			prefix := "ytsearch10:"
 			if m.netSearch.soundcloud {
-				prefix = "scsearch1:"
+				prefix = "scsearch10:"
 			}
-			m.status.Show("Queuing search...", statusTTLShort)
-			cmd = fetchNetSearchCmd(prefix + strings.TrimSpace(m.netSearch.query))
+			m.netSearch.loading = true
+			m.netSearch.err = ""
+			return fetchNetSearchCmd(prefix + strings.TrimSpace(m.netSearch.query))
 		}
-		return cmd
 
 	case tea.KeyBackspace:
 		m.netSearch.query = removeLastRune(m.netSearch.query)
@@ -1156,7 +1164,50 @@ func (m *Model) handleNetSearchKey(msg tea.KeyPressMsg) tea.Cmd {
 			m.netSearch.query += msg.Text
 		}
 	}
+	return nil
+}
+
+// handleNetSearchResultsKey handles navigation through net search results.
+func (m *Model) handleNetSearchResultsKey(msg tea.KeyPressMsg) tea.Cmd {
+	count := len(m.netSearch.results)
 
+	switch msg.String() {
+	case "up", "k":
+		if m.netSearch.cursor > 0 {
+			m.netSearch.cursor--
+		} else if count > 0 {
+			m.netSearch.cursor = count - 1
+		}
+	case "down", "j":
+		if m.netSearch.cursor < count-1 {
+			m.netSearch.cursor++
+		} else if count > 0 {
+			m.netSearch.cursor = 0
+		}
+	case "enter":
+		if count > 0 && !m.netSearch.loading {
+			track := m.netSearch.results[m.netSearch.cursor]
+			m.closeNetSearch()
+			return m.playTrackImmediate(track)
+		}
+	case "a":
+		if count > 0 && !m.netSearch.loading {
+			track := m.netSearch.results[m.netSearch.cursor]
+			m.closeNetSearch()
+			return m.appendTrack(track)
+		}
+	case "q":
+		if count > 0 && !m.netSearch.loading {
+			track := m.netSearch.results[m.netSearch.cursor]
+			m.closeNetSearch()
+			return m.queueTrackNext(track)
+		}
+	case "esc", "backspace":
+		m.netSearch.screen = netSearchInput
+		m.netSearch.results = nil
+		m.netSearch.cursor = 0
+		m.netSearch.err = ""
+	}
 	return nil
 }
 

ui/model/keys_spotify_search.go

@@ -10,7 +10,7 @@ import (
 func (m *Model) handleSpotSearchKey(msg tea.KeyPressMsg) tea.Cmd {
 	switch msg.String() {
 	case "ctrl+c":
-		m.spotSearch.visible = false
+		m.closeSpotSearch()
 		return m.quit()
 	}
 
@@ -31,7 +31,7 @@ func (m *Model) handleSpotSearchKey(msg tea.KeyPressMsg) tea.Cmd {
 func (m *Model) handleSpotSearchInputKey(msg tea.KeyPressMsg) tea.Cmd {
 	switch msg.Code {
 	case tea.KeyEscape:
-		m.spotSearch.visible = false
+		m.closeSpotSearch()
 	case tea.KeyEnter:
 		if m.spotSearch.query != "" && !m.spotSearch.loading {
 			s, ok := m.spotSearch.prov.(provider.Searcher)
@@ -74,6 +74,24 @@ func (m *Model) handleSpotSearchResultsKey(msg tea.KeyPressMsg) tea.Cmd {
 			m.spotSearch.cursor = 0
 		}
 	case "enter":
+		if count > 0 && !m.spotSearch.loading {
+			track := m.spotSearch.results[m.spotSearch.cursor]
+			m.closeSpotSearch()
+			return m.playTrackImmediate(track)
+		}
+	case "a":
+		if count > 0 && !m.spotSearch.loading {
+			track := m.spotSearch.results[m.spotSearch.cursor]
+			m.closeSpotSearch()
+			return m.appendTrack(track)
+		}
+	case "q":
+		if count > 0 && !m.spotSearch.loading {
+			track := m.spotSearch.results[m.spotSearch.cursor]
+			m.closeSpotSearch()
+			return m.queueTrackNext(track)
+		}
+	case "p":
 		if count > 0 && !m.spotSearch.loading {
 			m.spotSearch.selTrack = m.spotSearch.results[m.spotSearch.cursor]
 			m.spotSearch.loading = true

ui/model/playback.go

@@ -79,6 +79,66 @@ func (m *Model) playCurrentTrack() tea.Cmd {
 	return m.playTrack(activation.Track)
 }
 
+// playTrackImmediate appends a track to the playlist and starts playing it now,
+// stopping any current playback. Used by search-result "Play now" actions.
+func (m *Model) playTrackImmediate(track playlist.Track) tea.Cmd {
+	m.player.Stop()
+	m.player.ClearPreload()
+	m.playlist.Add(track)
+	idx := m.playlist.Len() - 1
+	m.playlist.SetIndex(idx)
+	m.plCursor = idx
+	m.adjustScroll()
+	m.status.Showf(statusTTLMedium, "Playing: %s", track.DisplayName())
+	cmd := m.playCurrentTrack()
+	m.notifyPlayback()
+	return cmd
+}
+
+// appendTrack appends a track to the playlist; auto-plays if nothing is playing.
+func (m *Model) appendTrack(track playlist.Track) tea.Cmd {
+	wasEmpty := m.playlist.Len() == 0
+	m.playlist.Add(track)
+	idx := m.playlist.Len() - 1
+	m.status.Showf(statusTTLMedium, "Added: %s", track.DisplayName())
+	if wasEmpty || !m.player.IsPlaying() {
+		m.playlist.SetIndex(idx)
+		m.plCursor = idx
+		m.adjustScroll()
+		cmd := m.playCurrentTrack()
+		m.notifyPlayback()
+		return cmd
+	}
+	return nil
+}
+
+// closeNetSearch fully resets the net search overlay and restores focus,
+// dropping any cached results so they don't linger between sessions.
+func (m *Model) closeNetSearch() {
+	m.netSearch = netSearchState{}
+	m.focus = m.prevFocus
+}
+
+// closeSpotSearch fully resets the Spotify search overlay, dropping cached
+// results, playlists, and the selected track.
+func (m *Model) closeSpotSearch() {
+	m.spotSearch = spotSearchState{}
+}
+
+// queueTrackNext adds a track to the playlist and queues it to play next.
+func (m *Model) queueTrackNext(track playlist.Track) tea.Cmd {
+	m.playlist.Add(track)
+	idx := m.playlist.Len() - 1
+	m.playlist.Queue(idx)
+	m.status.Showf(statusTTLMedium, "Queued: %s", track.DisplayName())
+	if !m.player.IsPlaying() {
+		cmd := m.nextTrack()
+		m.notifyPlayback()
+		return cmd
+	}
+	return nil
+}
+
 // playTrack plays a track, using async HTTP for streams and sync I/O for local files.
 // yt-dlp URLs are streamed via a piped yt-dlp | ffmpeg chain for instant playback.
 func (m *Model) playTrack(track playlist.Track) tea.Cmd {