playlist

package
v1.60.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package playlist manages an ordered track list with shuffle and repeat support.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNeedsAuth = errors.New("sign-in required")

ErrNeedsAuth is returned by providers that require interactive sign-in before they can be used.

Functions

func IsFeed 

func IsFeed(path string) bool

IsFeed reports whether the URL points to a podcast RSS/XML feed.

func IsLocalM3U 

func IsLocalM3U(path string) bool

IsLocalM3U reports whether the path is a local (non-URL) M3U file.

func IsLocalPLS 

func IsLocalPLS(path string) bool

IsLocalPLS reports whether the path is a local (non-URL) PLS file.

func IsM3U 

func IsM3U(path string) bool

IsM3U reports whether the path points to an M3U playlist file (URL or local).

func IsPLS 

func IsPLS(path string) bool

IsPLS reports whether the path points to a PLS playlist file (URL or local).

func IsURL 

func IsURL(path string) bool

IsURL reports whether path is an HTTP or HTTPS URL, or a yt-dlp search protocol string.

func IsXiaoyuzhouEpisode 

func IsXiaoyuzhouEpisode(path string) bool

IsXiaoyuzhouEpisode reports whether the URL points to a Xiaoyuzhou episode page.

func IsYTDL 

func IsYTDL(path string) bool

IsYTDL reports whether the URL points to a site supported by yt-dlp (YouTube, SoundCloud, Bandcamp, ytsearch: protocol, etc.).

func IsYTSearch 

func IsYTSearch(path string) bool

IsYTSearch reports whether path is a yt-dlp search expression (ytsearch:, ytsearchN:, scsearch:, scsearchN:).

func IsYouTubeMusicURL 

func IsYouTubeMusicURL(path string) bool

IsYouTubeMusicURL reports whether the URL points to YouTube Music (music.youtube.com). These URLs require yt-dlp rather than the native YouTube API client.

func IsYouTubeURL 

func IsYouTubeURL(path string) bool

IsYouTubeURL reports whether the URL points to YouTube (youtube.com or youtu.be). YouTube Music (music.youtube.com) is excluded — use IsYouTubeMusicURL for that.

func TotalDurationSecs 

func TotalDurationSecs(tracks []Track) int

TotalDurationSecs sums DurationSecs across a slice of tracks, skipping entries with unknown duration (zero).

Types

type Authenticator 

type Authenticator interface {
	Authenticate() error
}

Authenticator is optionally implemented by providers that require sign-in.

type Playlist 

type Playlist struct {
	// contains filtered or unexported fields
}

Playlist manages an ordered list of tracks with shuffle and repeat support. All exported methods are safe for concurrent use: the Bubbletea UI loop mutates the playlist while Lua plugin goroutines read state through it.

func New 

func New() *Playlist

New creates an empty Playlist.

func (*Playlist) ActivateSelected 

func (p *Playlist) ActivateSelected() (SelectionActivation, bool)

ActivateSelected promotes the selected row to the active playable track. Queue state is ignored for candidate selection and left unchanged. If no playable track can be activated, playlist state is unchanged.

func (*Playlist) Add 

func (p *Playlist) Add(tracks ...Track)

Add appends tracks to the playlist.

func (*Playlist) BookmarkCount 

func (p *Playlist) BookmarkCount() int

BookmarkCount returns the number of bookmarked tracks.

func (*Playlist) ClearQueue 

func (p *Playlist) ClearQueue()

ClearQueue removes all entries from the play-next queue.

func (*Playlist) Current 

func (p *Playlist) Current() (Track, int)

Current returns the currently selected track and its index.

func (*Playlist) CurrentIsQueued 

func (p *Playlist) CurrentIsQueued() bool

func (*Playlist) CycleRepeat 

func (p *Playlist) CycleRepeat()

CycleRepeat cycles through Off -> All -> One.

func (*Playlist) Dequeue 

func (p *Playlist) Dequeue(trackIdx int) bool

Dequeue removes a track from the queue. Returns true if it was found.

func (*Playlist) Index 

func (p *Playlist) Index() int

Index returns the track index of the current position.

func (*Playlist) Len 

func (p *Playlist) Len() int

Len returns the number of tracks.

func (*Playlist) Move 

func (p *Playlist) Move(from, to int) bool

Move swaps the track at position from with the track at position to, updating order, queue, and position references so playback is unaffected. When shuffle is off, the visual order becomes the new playback order.

func (*Playlist) MoveQueue 

func (p *Playlist) MoveQueue(from, to int) bool

MoveQueue swaps the two entries at the given positions in the play-next queue.

func (*Playlist) Next 

func (p *Playlist) Next() (Track, bool)

Next advances to the next track according to queue, repeat, and shuffle. Unplayable queued entries are pruned as playback advances. RepeatOne still limits playback to the current track.

func (*Playlist) PeekNext 

func (p *Playlist) PeekNext() (Track, bool)

PeekNext returns the next track without advancing the playlist position. Returns false when the next track can't be predicted (e.g., shuffle wrap).

func (*Playlist) Prev 

func (p *Playlist) Prev() (Track, bool)

Prev moves to the previous track, skipping unavailable tracks. Wraps around with RepeatAll.

func (*Playlist) Queue 

func (p *Playlist) Queue(trackIdx int)

Queue adds a track to the play-next queue by its index.

func (*Playlist) QueueLen 

func (p *Playlist) QueueLen() int

QueueLen returns the number of tracks in the queue.

func (*Playlist) QueuePosition 

func (p *Playlist) QueuePosition(trackIdx int) int

QueuePosition returns the 1-based position of a track in the queue, or 0 if the track is not queued.

func (*Playlist) QueueTracks 

func (p *Playlist) QueueTracks() []Track

QueueTracks returns copies of the tracks in queue order.

func (*Playlist) Remove 

func (p *Playlist) Remove(idx int) bool

Remove deletes the track at index idx, updating order, queue, and position references so playback state is preserved when possible. Returns true if a track was removed. If the removed track was the active one, the position stays at the same order slot so playback advances naturally on next.

func (*Playlist) RemoveQueueAt 

func (p *Playlist) RemoveQueueAt(pos int)

RemoveQueueAt removes the entry at the given 0-based queue position.

func (*Playlist) Repeat 

func (p *Playlist) Repeat() RepeatMode

Repeat returns the current repeat mode.

func (*Playlist) Replace 

func (p *Playlist) Replace(tracks []Track)

Replace clears the playlist and loads the given tracks, resetting position, queue, and shuffle order.

func (*Playlist) SetIndex 

func (p *Playlist) SetIndex(i int)

SetIndex sets the current position to the given track index.

func (*Playlist) SetRepeat 

func (p *Playlist) SetRepeat(mode RepeatMode)

SetRepeat sets the repeat mode directly.

func (*Playlist) SetTrack 

func (p *Playlist) SetTrack(i int, t Track)

SetTrack replaces the track at index i.

func (*Playlist) Shuffled 

func (p *Playlist) Shuffled() bool

Shuffled returns whether shuffle is enabled.

func (*Playlist) ToggleBookmark 

func (p *Playlist) ToggleBookmark(idx int)

ToggleBookmark flips the Bookmark flag on the track at the given index.

func (*Playlist) ToggleShuffle 

func (p *Playlist) ToggleShuffle()

ToggleShuffle enables or disables shuffle mode. Uses Fisher-Yates shuffle, preserving the current track at position 0.

func (*Playlist) Tracks 

func (p *Playlist) Tracks() []Track

Tracks returns all tracks in the playlist.

type PlaylistInfo 

type PlaylistInfo struct {
	ID           string
	Name         string
	TrackCount   int
	DurationSecs int
	Section      string
}

PlaylistInfo describes a playlist with its name and track count.

DurationSecs is optional: providers that can compute it cheaply should populate it so the UI can render a total runtime. A zero value means "unknown" and the UI will hide the duration column.

Section is optional: providers may set it to group their playlists in the UI. Adjacent rows that share a Section are rendered under one header; a change of Section emits a "── header ──" divider. The radio provider uses SectionedList.IDPrefix instead and leaves Section empty.

type Provider 

type Provider interface {
	// Name returns the display name of this provider.
	Name() string

	// Playlists returns the available playlists from this provider.
	Playlists() ([]PlaylistInfo, error)

	// Tracks returns the tracks in the given playlist.
	Tracks(playlistID string) ([]Track, error)
}

Provider is the interface for playlist sources (radio, Navidrome, Spotify, etc.).

type Refresher 

type Refresher interface {
	Refresh()
}

Refresher is optionally implemented by providers that cache playlist or track data and support invalidating that cache so the next Playlists() / Tracks() call re-fetches from the source.

type RepeatMode 

type RepeatMode int

RepeatMode controls playlist repeat behavior. 

const (
	RepeatOff RepeatMode = iota
	RepeatAll
	RepeatOne
)

func (RepeatMode) String 

func (r RepeatMode) String() string

type SelectionActivation 

type SelectionActivation struct {
	Track   Track
	Index   int
	Skipped bool
}

SelectionActivation describes the playable track activated from the selected row.

type Track 

type Track struct {
	Path         string
	Title        string
	Artist       string
	Album        string
	Genre        string
	Year         int
	TrackNumber  int
	Stream       bool // true for HTTP/HTTPS URLs
	Realtime     bool // true for real-time/live streams (e.g. radio)
	Feed         bool // true for RSS/podcast feed URLs (resolved before playback)
	DurationSecs int  // known duration in seconds (0 = unknown)
	Bookmark     bool // user-bookmarked track

	Unplayable bool // true when the track is known not playable in the current playback context

	EmbeddedLyrics string // embedded lyrics from local file tags, when present
	AlbumArtURL    string // file:// URL for cached embedded album art, when present

	// ProviderMeta holds provider-specific key-value pairs.
	// Keys are namespaced by provider, e.g. "navidrome.id", "jellyfin.id".
	ProviderMeta map[string]string
}

Track represents a single audio file or HTTP stream.

func RefreshEmbeddedMetadata 

func RefreshEmbeddedMetadata(track Track) Track

RefreshEmbeddedMetadata returns track with embedded local-file lyrics and album art populated from its current Path. Existing non-embedded fields are preserved so saved playlist metadata and provider fields remain stable.

func TrackFromFilename 

func TrackFromFilename(path string) Track

TrackFromFilename creates a Track by parsing "Artist - Title" from the filename, or using the bare filename as the title.

func TrackFromPath 

func TrackFromPath(path string) Track

TrackFromPath creates a Track by parsing the filename or URL. For local files, embedded tags (ID3v2, Vorbis, MP4) are tried first, falling back to "Artist - Title" filename parsing.

func (Track) DisplayName 

func (t Track) DisplayName() string

DisplayName returns a formatted display string for the track.

func (Track) IsLive 

func (t Track) IsLive() bool

IsLive reports whether the track is a live stream (e.g. Icecast radio)

func (Track) Meta 

func (t Track) Meta(key string) string

Meta returns the value for a provider-specific metadata key, or "" if unset.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.