gotidal

package module
v0.5.0-alpha Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2025 License: Apache-2.0 Imports: 13 Imported by: 0

README

gotidal

An unofficial Go library for interacting with the TIDAL API.

Go Reference GitHub License GitHub Tag GitHub Actions Workflow Status GitHub Actions Workflow Status GitHub go.mod Go version Codecov 0 dependencies!

Guidelines

As the public TIDAL API is still in beta and subject to change, we cannot guarantee this package will always work and therefore should not be used in production systems. We endeavor to patch and release fixes as soon as possible.

Hopefully, in the future, we will be able to match parity and provide backward compatibility with TIDAL.

Official Documentation

Developer documentation and API keys: https://developer.tidal.com/

Discussion and feature requests: https://github.com/orgs/tidal-music/discussions

Roadmap

Please see the issues tab for work left to be completed.

Installation

go get -u github.com/tomjowitt/gotidal

Usage

There are working examples for each TIDAL endpoint in the /examples folder.

package main

import (
 ...

 "github.com/tomjowitt/gotidal"
)

const maxSearchResults = 5

func main() {
    ctx := context.Background()

    clientID := os.Getenv("TIDAL_CLIENT_ID")
    clientSecret := os.Getenv("TIDAL_CLIENT_SECRET")

    client, err := gotidal.NewClient(clientID, clientSecret, "AU")
    if err != nil {
        log.Fatal(err)
    }

    params := gotidal.SearchParams{
        Query:       "Peso Pluma",
        Limit:       maxSearchResults,
        Popularity:  gotidal.SearchPopularityCountry,
    }

    results, err := client.Search(ctx, params)
    if err != nil {
        log.Fatal(err)
    }

    for _, album := range results.Albums {
        log.Printf("%s - %s", album.Title, album.Artists[0].Name)
    }

Credits

Logo created with Gopher Konstructor https://github.com/quasilyte/gopherkon based on original artwork by Renee French.

Documentation

Overview

Package gotidal provides an unofficial Go SDK for interacting with the TIDAL API.

https://developer.tidal.com/

Index

Constants

View Source
const (
	SearchTypeAlbums          = "ALBUMS"
	SearchTypeArtists         = "ARTISTS"
	SearchTypeTracks          = "TRACKS"
	SearchTypeVideos          = "VIDEOS"
	SearchPopularityWorldwide = "WORLDWIDE"
	SearchPopularityCountry   = "COUNTRY"
)

Variables

View Source
var ErrMissingRequiredParameters = errors.New("both the Query and the CountryCode parameters are required")
View Source
var ErrUnexpectedResponseCode = errors.New("returned an unexpected status code")

Functions

This section is empty.

Types

type Album

type Album struct {
	AlbumResource `json:"resource"`
}

Album represents an individual release.

type AlbumProperties

type AlbumProperties struct {
	Content []string `json:"content"`
}

AlbumProperties represents the properties of an album.

type AlbumResource

type AlbumResource struct {
	ID              string           `json:"id"`
	BarcodeID       string           `json:"barcodeID"`
	Title           string           `json:"title"`
	Artists         []artistResource `json:"artists"`
	Duration        int              `json:"duration"`
	ReleaseDate     string           `json:"releaseDate"`
	ImageCover      []Image          `json:"imageCover"`
	VideoCover      []Image          `json:"videoCover"`
	NumberOfVolumes int              `json:"numberOfVolumes"`
	NumberOfTracks  int              `json:"numberOfTracks"`
	NumberOfVideos  int              `json:"numberOfVideos"`
	Type            string           `json:"type"`
	Copyright       string           `json:"copyright"`
	MediaMetaData   MediaMetaData    `json:"mediaMetadata"`
	Properties      AlbumProperties  `json:"properties"`
	TidalURL        string           `json:"tidalUrl"`
	ProviderInfo    ProviderInfo     `json:"providerInfo"`
}

type Artist

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

Artist represents an individual artist.

type Client

type Client struct {
	HTTPClient  HTTPClient
	ContentType string
	Environment string
	Token       string
	CountryCode string
}

Client defines the parameters needed to create a TIDAL API client.

func NewClient

func NewClient(clientID string, clientSecret string, countryCode string) (*Client, error)

NewClient returns an API client based on a users credentials and location.

func (*Client) GetAlbumByBarcodeID

func (c *Client) GetAlbumByBarcodeID(ctx context.Context, barcodeID string) ([]Album, error)

GetAlbumByBarcodeID returns a list of albums that match a barcode ID.

func (*Client) GetAlbumTracks

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

GetAlbumTracks returns a list of album tracks.

The items endpoint is paginated so we set a fairly high limit (100 items) in the hope to catch most cases in one round-trip. If the metadata reports a higher total then we make susequent API calls until all the tracks are returned.

This endpoint also supports videos but it was hard to find any examples of this, so for the moment this is tracks only.

func (*Client) GetAlbumsByArtist

func (c *Client) GetAlbumsByArtist(ctx context.Context, id string, params PaginationParams) ([]Album, error)

GetAlbumsByArtist returns a paginated list of albums for an artist.

func (*Client) GetMultipleAlbums

func (c *Client) GetMultipleAlbums(ctx context.Context, ids []string) ([]Album, error)

GetMultipleAlbums returns a list of albums filtered by their IDs.

func (*Client) GetMultipleArtists

func (c *Client) GetMultipleArtists(ctx context.Context, ids []string) ([]Artist, error)

GetMultipleArtists returns a list of artists filtered by their IDs.

func (*Client) GetMultipleTracks

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

GetMultipleTracks returns a list of tracks filtered by their IDs.

func (*Client) GetSimilarAlbums

func (c *Client) GetSimilarAlbums(ctx context.Context, id string, params PaginationParams) ([]string, error)

GetSimilarAlbums returns a slice of album IDs that can be used as a parameter in the GetMultipleAlbums function.

func (*Client) GetSimilarArtists

func (c *Client) GetSimilarArtists(ctx context.Context, id string, params PaginationParams) ([]string, error)

GetSimilarArtists returns a slice of artist IDs that can be used as a parameter in the GetMultipleArtists function.

func (*Client) GetSingleAlbum

func (c *Client) GetSingleAlbum(ctx context.Context, id string) (*Album, error)

GetSingleAlbum returns an album that matches an ID.

func (*Client) GetSingleArtist

func (c *Client) GetSingleArtist(ctx context.Context, id string) (*Artist, error)

GetSingleArtist returns an artist that matches an ID.

func (*Client) GetSingleTrack

func (c *Client) GetSingleTrack(ctx context.Context, id string) (*Track, error)

GetAlbumsByArtist returns a list of albums that match an artist ID.

func (*Client) GetTracksByISRC

func (c *Client) GetTracksByISRC(ctx context.Context, isrc string, params PaginationParams) ([]Track, error)

GetTracksByISRC returns a list of tracks that match an ISRC.

ISRC lookup can be found here. This is a useful tool for finding ISRCs for testing purposes: https://isrcsearch.ifpi.org/

func (*Client) Search

func (c *Client) Search(ctx context.Context, params SearchParams) (*SearchResults, error)

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient provides an interface to make HTTP requests.

type Image

type Image struct {
	URL    string `json:"url"`
	Width  int    `json:"width"`
	Height int    `json:"height"`
}

Image represents an individual image.

type ItemMetaData

type ItemMetaData struct {
	Total int `json:"total"`
}

type MediaMetaData

type MediaMetaData struct {
	Tags []string `json:"tags"`
}

MediaMetaData represents the metadata of an album.

type PaginationParams

type PaginationParams struct {
	Limit  int
	Offset int
}

PaginationParams defines the limit and offset for pagination functions.

type ProviderInfo

type ProviderInfo struct {
	ID   string `json:"providerId"`
	Name string `json:"providerName"`
}

ProviderInfo represents the provider of an album.

type SearchParams

type SearchParams struct {
	// Search query in plain text.
	// Example: Beyoncé
	Query string `json:"query"`

	// Target search type. Optional. Searches for all types if not specified.
	// Example: ARTISTS, ALBUMS, TRACKS, VIDEOS
	Type string `json:"type"`

	// Pagination offset (in number of items). Required if 'query' is provided.
	// Example: 0
	Offset int `json:"offset"`

	// Page size. Required if 'query' is provided.
	// Example: 10
	Limit int `json:"limit"`

	// Specify which popularity type to apply for query result: either worldwide or country popularity.
	// Worldwide popularity is used by default if nothing is specified.
	// Example: WORLDWIDE, COUNTRY
	Popularity string `json:"popularity"`
}

SearchParams defines the request parameters used by the TIDAL search API endpoint. See: https://developer.tidal.com/apiref?spec=search&ref=search

type SearchResults

type SearchResults struct {
	Albums  []Album
	Artists []Artist
	Tracks  []Track
	Videos  []Video
}

type Track

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

Track represents an individual track on an album.

type Video

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

Video represents an individula video.

type VideoProperties

type VideoProperties struct {
	Content   []string `json:"content"`
	VideoType string   `json:"video-type"`
}

Directories

Path Synopsis
examples
album command
artist command
search command
token command
track command

Jump to

Keyboard shortcuts

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