Documentation
¶
Index ¶
- Constants
- Variables
- func CoverURL(cover, size string) string
- type Album
- type Artist
- type Client
- func (c *Client) AddFavorite(ctx context.Context, trackID int) error
- func (c *Client) AddFavoriteAlbum(ctx context.Context, albumID int) error
- func (c *Client) AddFavoriteArtist(ctx context.Context, artistID int) error
- func (c *Client) AddTracksToPlaylist(ctx context.Context, uuid string, trackIDs []int) error
- func (c *Client) AuthenticateInteractive(ctx context.Context) (*Session, error)
- func (c *Client) CreatePlaylist(ctx context.Context, title, description string) (string, error)
- func (c *Client) GetAlbumTracks(ctx context.Context, albumID string) ([]Track, error)
- func (c *Client) GetArtistAlbums(ctx context.Context, artistID int) ([]Album, error)
- func (c *Client) GetArtistAllTracks(ctx context.Context, artistID int) ([]Track, error)
- func (c *Client) GetArtistTopTracks(ctx context.Context, artistID, limit int) ([]Track, error)
- func (c *Client) GetAuthClient(ctx context.Context) *http.Client
- func (c *Client) GetFavoriteAlbums(ctx context.Context, limit int) ([]Album, error)
- func (c *Client) GetFavoriteArtists(ctx context.Context, limit int) ([]Artist, error)
- func (c *Client) GetFavorites(ctx context.Context, limit int) ([]Track, error)
- func (c *Client) GetMixTracks(ctx context.Context, mixID string) ([]Track, error)
- func (c *Client) GetMixes(ctx context.Context) ([]Mix, error)
- func (c *Client) GetPlaylistTracks(ctx context.Context, uuid string) ([]Track, error)
- func (c *Client) GetStreamURL(ctx context.Context, trackID int, lowData bool) (StreamInfo, error)
- func (c *Client) GetTrack(ctx context.Context, trackID string) (*Track, error)
- func (c *Client) GetTrackRadio(ctx context.Context, trackID int) ([]Track, error)
- func (c *Client) GetUser(ctx context.Context) (*UserResponse, error)
- func (c *Client) GetUserPlaylists(ctx context.Context) ([]Playlist, error)
- func (c *Client) RemoveFavorite(ctx context.Context, trackID int) error
- func (c *Client) RemoveFavoriteAlbum(ctx context.Context, albumID int) error
- func (c *Client) RemoveFavoriteArtist(ctx context.Context, artistID int) error
- func (c *Client) RevokeToken(ctx context.Context, token string) error
- func (c *Client) Search(ctx context.Context, query string) ([]Track, error)
- func (c *Client) SearchAll(ctx context.Context, query string) (*SearchResults, error)
- func (c *Client) TokenSource(ctx context.Context) oauth2.TokenSource
- type FavoritesResponse
- type Mix
- type Playlist
- type Quality
- type SearchResponse
- type SearchResults
- type Session
- type StreamInfo
- type StreamResponse
- type Track
- type UserResponse
Constants ¶
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 ¶
var ErrInvalidID = errors.New("invalid Tidal resource ID")
ErrInvalidID is returned when a resource ID is not in the shape Tidal uses.
var ErrNotFound = errors.New("not found")
ErrNotFound is returned by GetTrack when the API responds with 404.
Functions ¶
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 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 (*Client) AddFavoriteAlbum ¶
AddFavoriteAlbum adds an album to the user's favorites.
func (*Client) AddFavoriteArtist ¶
AddFavoriteArtist adds an artist to the user's favorites.
func (*Client) AddTracksToPlaylist ¶
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 ¶
AuthenticateInteractive runs the flow in the terminal before TUI launch
func (*Client) CreatePlaylist ¶
CreatePlaylist creates a new playlist and returns its UUID.
func (*Client) GetAlbumTracks ¶
func (*Client) GetArtistAlbums ¶
GetArtistAlbums returns the artist's full discography, paginating through the v1 /artists/{id}/albums endpoint until exhausted.
func (*Client) GetArtistAllTracks ¶
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 ¶
GetArtistTopTracks returns the artist's most popular tracks (up to limit).
func (*Client) GetFavoriteAlbums ¶
GetFavoriteAlbums returns the user's favorited albums.
func (*Client) GetFavoriteArtists ¶
GetFavoriteArtists returns the user's favorited artists.
func (*Client) GetFavorites ¶
func (*Client) GetMixTracks ¶
func (*Client) GetPlaylistTracks ¶
GetPlaylistTracks returns the tracks of a playlist by its UUID.
func (*Client) GetStreamURL ¶
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) GetTrackRadio ¶
func (*Client) GetUserPlaylists ¶
GetUserPlaylists returns the playlists the user has created or saved.
func (*Client) RemoveFavorite ¶
func (*Client) RemoveFavoriteAlbum ¶
RemoveFavoriteAlbum removes an album from the user's favorites.
func (*Client) RemoveFavoriteArtist ¶
RemoveFavoriteArtist removes an artist from the user's favorites.
func (*Client) RevokeToken ¶
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 ¶
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 ¶
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 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.
type SearchResponse ¶
type SearchResponse struct {
Tracks struct {
Items []Track `json:"items"`
} `json:"tracks"`
}
type SearchResults ¶
SearchResults holds the multi-category results of a search query.
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"`
}