ytm

Documentation

Overview

Package ytm wraps the pure-Go YouTube Music client (raitonoberu/ytmusic), adapting its results to engine.Candidate so search, album art, duration, and "radio" recommendations all flow through the same type used by the TUI.

It is metadata-only: it returns video ids, titles, durations and thumbnail URLs. Turning a video id into a playable audio stream is still yt-dlp's job (see the tui playback layer) — but because we already hold the video id, that step skips the slow YouTube *search* and only does extraction.

Index

• func Charts(country string, limit int) ([]engine.Candidate, error)
• func Lyrics(videoID string) (string, error)
• func Radio(videoID string, limit int) ([]engine.Candidate, error)
• func Resolve(artist, track string) (engine.Candidate, error)
• func Search(query string, limit int) ([]engine.Candidate, error)
• func WatchURL(videoID string) string
• type Album
  • func SearchAlbums(query string, limit int) ([]Album, error)
• type AlbumDetail
  • func BrowseAlbum(a Album, limit int) (*AlbumDetail, error)
• type ArtistHit
  • func SearchArtists(query string, limit int) ([]ArtistHit, error)
• type ArtistPage
  • func BrowseArtist(browseID string) (*ArtistPage, error)

Functions

func Charts

func Charts(country string, limit int) ([]engine.Candidate, error)

Charts returns the *current* YouTube Music top-tracks chart for a country. country is an ISO-3166 alpha-2 code (e.g. "US") or "ZZ"/"" for Global.

YouTube's no-auth charts page doesn't embed a song list directly — it links to per-country chart *playlists* (e.g. "Top 100 Music Videos — United States"). So this does two browse calls: discover the chart playlist, then fetch it. Rows are title + artist; playback resolves the stream at play time (like recs).

func Lyrics

func Lyrics(videoID string) (string, error)

Lyrics returns the plain-text lyrics for a video id ("" if none found).

func Radio

func Radio(videoID string, limit int) ([]engine.Candidate, error)

Radio returns YouTube Music's "watch playlist" for a video id — its native radio/recommendation feed. Useful to augment the local recommender.

func Resolve

func Resolve(artist, track string) (engine.Candidate, error)

Resolve finds the single best YouTube Music match for an artist/track pair. Used to enrich a recommender Candidate (which has no video id) just before playback. Returns the enriched candidate (VideoID/DurationSec/ArtURL filled).

func Search

func Search(query string, limit int) ([]engine.Candidate, error)

Search returns up to limit song results from YouTube Music for the query. Results carry VideoID, DurationSec and ArtURL so playback starts fast and album art / duration need no extra API calls.

func WatchURL

func WatchURL(videoID string) string

WatchURL returns the canonical music.youtube.com URL for a video id, which yt-dlp / mpv resolve to an audio stream.

Types

type Album

type Album struct{ Title, Artist, Year, BrowseID string }

func SearchAlbums

func SearchAlbums(query string, limit int) ([]Album, error)

SearchAlbums returns album entities matching the query.

type AlbumDetail

type AlbumDetail struct {
	Album  Album // input album, with Year filled from the page when missing
	Tracks []engine.Candidate
	ArtURL string // album cover (largest header thumbnail)
}

AlbumDetail is a fully-parsed album page: ordered tracks + header metadata.

func BrowseAlbum

func BrowseAlbum(a Album, limit int) (*AlbumDetail, error)

BrowseAlbum fetches an album page by browse id and parses its tracklist and header metadata.

type ArtistHit

type ArtistHit struct{ Name, BrowseID string }

ArtistHit and Album are lightweight entity results for typed ("bang") searches.

func SearchArtists

func SearchArtists(query string, limit int) ([]ArtistHit, error)

SearchArtists returns artist entities matching the query (most-relevant first).

type ArtistPage

type ArtistPage struct {
	Name        string
	Description string
	TopSongs    []engine.Candidate
	Albums      []Album
	Singles     []Album
}

ArtistPage is a full artist landing: top songs plus the album/single shelves, like the YouTube Music artist page it's parsed from.

func BrowseArtist

func BrowseArtist(browseID string) (*ArtistPage, error)

BrowseArtist fetches and parses an artist page by channel browse id (UC…).