tidal

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ClientID = "fX2JxdmntZWK0ixT"
	// ClientSecret is the public client secret baked into the official Tidal
	// app; it is not a user credential. Distributing it is required for the
	// device-flow login to work, so the gosec hardcoded-credentials check is
	// suppressed here.
	ClientSecret = "1Nn9AfDAjxrgJFJbKNWLeAyKGVGmINuXPPLHVXAvxAg=" //nolint:gosec // G101: public OAuth client secret, not a user credential
	AuthURL      = "https://auth.tidal.com/v1/oauth2"
	BaseURL      = "https://api.tidal.com/v1"
	BaseURLV2    = "https://openapi.tidal.com/v2"
)

Variables

View Source
var ErrInvalidID = errors.New("invalid Tidal resource ID")

ErrInvalidID is returned when a resource ID is not in the shape Tidal uses.

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound is returned by GetTrack when the API responds with 404.

Functions

func CoverURL

func CoverURL(cover, size string) string

CoverURL returns the HTTPS URL for the album cover image at the given size. cover is the UUID string returned in Track.Album.Cover. Typical sizes: "80x80", "160x160", "320x320", "640x640", "1280x1280". Returns "" when cover is empty.

Types

type Album

type Album struct {
	ID             int    `json:"id"`
	Title          string `json:"title"`
	Cover          string `json:"cover"` // UUID, same format as Track.Album.Cover
	ReleaseDate    string `json:"releaseDate"`
	NumberOfTracks int    `json:"numberOfTracks"`
}

Album is a standalone album as returned by the artist albums endpoint. (Track has its own inline album struct; this is the richer top-level shape.)

type Artist

type Artist struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

type Client

type Client struct {
	Session   *Session
	Oauth     *oauth2.Config
	Transport http.RoundTripper // optional; overrides the base transport (used in tests)

	// OnTokenRefresh, when set, is called with the updated session every time
	// oauth2 mints a new access token, so the caller can write it back to the
	// secrets store. Without it a refresh lives only in memory: the stored
	// refresh token is never replaced, and `gotidal logout` ends up revoking a
	// credential that is no longer the live one. Set by cmd/gotidal, which
	// owns the store; this package deliberately does not import it.
	OnTokenRefresh func(Session)
	// contains filtered or unexported fields
}

func NewClient

func NewClient() *Client

func (*Client) AddFavorite

func (c *Client) AddFavorite(ctx context.Context, trackID int) error

func (*Client) AddFavoriteAlbum

func (c *Client) AddFavoriteAlbum(ctx context.Context, albumID int) error

AddFavoriteAlbum adds an album to the user's favorites.

func (*Client) AddFavoriteArtist

func (c *Client) AddFavoriteArtist(ctx context.Context, artistID int) error

AddFavoriteArtist adds an artist to the user's favorites.

func (*Client) AddTracksToPlaylist

func (c *Client) AddTracksToPlaylist(ctx context.Context, uuid string, trackIDs []int) error

AddTracksToPlaylist appends tracks to a playlist. Tidal's v1 playlist mutation requires the playlist's current ETag in an If-None-Match header, so this first fetches the ETag, then POSTs the comma-separated track IDs.

func (*Client) AuthenticateInteractive

func (c *Client) AuthenticateInteractive(ctx context.Context) (*Session, error)

AuthenticateInteractive runs the flow in the terminal before TUI launch

func (*Client) CreatePlaylist

func (c *Client) CreatePlaylist(ctx context.Context, title, description string) (string, error)

CreatePlaylist creates a new playlist and returns its UUID.

func (*Client) GetAlbumTracks

func (c *Client) GetAlbumTracks(ctx context.Context, albumID string) ([]Track, error)

func (*Client) GetArtistAlbums

func (c *Client) GetArtistAlbums(ctx context.Context, artistID int) ([]Album, error)

GetArtistAlbums returns the artist's full discography, paginating through the v1 /artists/{id}/albums endpoint until exhausted.

func (*Client) GetArtistAllTracks

func (c *Client) GetArtistAllTracks(ctx context.Context, artistID int) ([]Track, error)

GetArtistAllTracks collects every track across all of the artist's albums. Albums are fetched concurrently (bounded by artistAllTracksConcurrency); an album that fails to load (e.g. region-locked) is skipped rather than aborting the whole list. The result is flattened in album order and deduped by track ID so songs that appear on both an album and a single/compilation are not repeated.

func (*Client) GetArtistTopTracks

func (c *Client) GetArtistTopTracks(ctx context.Context, artistID, limit int) ([]Track, error)

GetArtistTopTracks returns the artist's most popular tracks (up to limit).

func (*Client) GetAuthClient

func (c *Client) GetAuthClient(ctx context.Context) *http.Client

func (*Client) GetFavoriteAlbums

func (c *Client) GetFavoriteAlbums(ctx context.Context, limit int) ([]Album, error)

GetFavoriteAlbums returns the user's favorited albums.

func (*Client) GetFavoriteArtists

func (c *Client) GetFavoriteArtists(ctx context.Context, limit int) ([]Artist, error)

GetFavoriteArtists returns the user's favorited artists.

func (*Client) GetFavorites

func (c *Client) GetFavorites(ctx context.Context, limit int) ([]Track, error)

func (*Client) GetMixTracks

func (c *Client) GetMixTracks(ctx context.Context, mixID string) ([]Track, error)

func (*Client) GetMixes

func (c *Client) GetMixes(ctx context.Context) ([]Mix, error)

func (*Client) GetPlaylistTracks

func (c *Client) GetPlaylistTracks(ctx context.Context, uuid string) ([]Track, error)

GetPlaylistTracks returns the tracks of a playlist by its UUID.

func (*Client) GetStreamURL

func (c *Client) GetStreamURL(ctx context.Context, trackID int, lowData bool) (StreamInfo, error)

GetStreamURL resolves the stream URL for trackID, walking qualityLadder (HI_RES_LOSSLESS down to LOW) top to bottom and returning the first tier Tidal grants. lowData selects lowDataQualityLadder instead — HIGH then LOW only, skipping both lossless FLAC tiers — for a metered-connection toggle where bandwidth matters more than bit-perfectness.

func (*Client) GetTrack

func (c *Client) GetTrack(ctx context.Context, trackID string) (*Track, error)

func (*Client) GetTrackRadio

func (c *Client) GetTrackRadio(ctx context.Context, trackID int) ([]Track, error)

func (*Client) GetUser

func (c *Client) GetUser(ctx context.Context) (*UserResponse, error)

func (*Client) GetUserPlaylists

func (c *Client) GetUserPlaylists(ctx context.Context) ([]Playlist, error)

GetUserPlaylists returns the playlists the user has created or saved.

func (*Client) RemoveFavorite

func (c *Client) RemoveFavorite(ctx context.Context, trackID int) error

func (*Client) RemoveFavoriteAlbum

func (c *Client) RemoveFavoriteAlbum(ctx context.Context, albumID int) error

RemoveFavoriteAlbum removes an album from the user's favorites.

func (*Client) RemoveFavoriteArtist

func (c *Client) RemoveFavoriteArtist(ctx context.Context, artistID int) error

RemoveFavoriteArtist removes an artist from the user's favorites.

func (*Client) RevokeToken

func (c *Client) RevokeToken(ctx context.Context, token string) error

RevokeToken revokes the given token via the Tidal OAuth2 revocation endpoint. Errors are logged but not fatal — the caller should still delete the local session regardless.

func (*Client) Search

func (c *Client) Search(ctx context.Context, query string) ([]Track, error)

Search returns only the track results for a query. It is retained for callers that just need tracks (e.g. the tidal:// URL resolver); the grouped multi-category results are available via SearchAll.

func (*Client) SearchAll

func (c *Client) SearchAll(ctx context.Context, query string) (*SearchResults, error)

SearchAll queries every category (tracks, artists, albums, playlists) and returns the grouped results. Track artists are normalized so Track.Artist is always populated.

func (*Client) TokenSource

func (c *Client) TokenSource(ctx context.Context) oauth2.TokenSource

type FavoritesResponse

type FavoritesResponse struct {
	Items []struct {
		Item Track `json:"item"`
	} `json:"items"`
}

type Mix

type Mix struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	SubTitle    string `json:"subTitle"`
	Description string `json:"description"`
}

type Playlist

type Playlist struct {
	UUID           string `json:"uuid"`
	Title          string `json:"title"`
	Description    string `json:"description"`
	NumberOfTracks int    `json:"numberOfTracks"`
	Duration       int    `json:"duration"`
}

Playlist is a user-created or saved Tidal playlist. UUID is the v1 playlist identifier used for track and mutation endpoints.

type Quality

type Quality string

Quality is a Tidal audio-quality tier, as accepted by the "audioquality" stream parameter. This package owns the canonical ladder: callers should use these constants and Label rather than re-listing the tier strings.

const (
	QualityHiRes    Quality = "HI_RES_LOSSLESS"
	QualityLossless Quality = "LOSSLESS"
	QualityHigh     Quality = "HIGH"
	QualityLow      Quality = "LOW"
)

func (Quality) Label

func (q Quality) Label() string

Label returns a short human-readable label for the tier, suitable for a compact UI badge. Unknown tiers fall back to the lower-cased raw value so a tier added to the ladder still renders something rather than vanishing.

type SearchResponse

type SearchResponse struct {
	Tracks struct {
		Items []Track `json:"items"`
	} `json:"tracks"`
}

type SearchResults

type SearchResults struct {
	Tracks    []Track
	Artists   []Artist
	Albums    []Album
	Playlists []Playlist
}

SearchResults holds the multi-category results of a search query.

type Session

type Session struct {
	AccessToken  string    `json:"access_token"`
	RefreshToken string    `json:"refresh_token"`
	TokenType    string    `json:"token_type"`
	Expiry       time.Time `json:"expiry"`
	UserID       int       `json:"user_id"`
	CountryCode  string    `json:"country_code"`
}

type StreamInfo

type StreamInfo struct {
	URL     string
	Ext     string  // e.g. "flac", "mp4", "m4a"
	Quality Quality // the tier that was actually granted
}

StreamInfo carries the resolved stream URL and its detected format extension.

type StreamResponse

type StreamResponse struct {
	URLs []string `json:"urls"`
}

type Track

type Track struct {
	ID     int    `json:"id"`
	Title  string `json:"title"`
	Artist Artist `json:"artist"`
	// Artists is the plural form returned by some endpoints (notably /search),
	// where the singular "artist" field is absent. normalizeArtist backfills
	// Artist from Artists[0] so callers can always rely on Track.Artist.
	Artists []Artist `json:"artists"`
	Album   struct {
		ID    int    `json:"id"`
		Title string `json:"title"`
		Cover string `json:"cover"` // UUID, e.g. "a3f1d2e4-1234-5678-abcd-ef0123456789"
	} `json:"album"`
	Duration int    `json:"duration"`
	URL      string `json:"url"`
}

type UserResponse

type UserResponse struct {
	ID           int    `json:"id"`
	CountryCode  string `json:"countryCode"`
	Email        string `json:"email"`
	FullName     string `json:"fullName"`
	ProfileImage string `json:"picture"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址