client

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Jan 3, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// BaseURL is the Spotify Web API base URL.
	BaseURL = "https://api.spotify.com/v1"
)

Variables

This section is empty.

Functions

func BuildURL

func BuildURL(path string, params map[string]string) string

BuildURL builds a URL with query parameters.

func IsAlreadyPlayingError

func IsAlreadyPlayingError(err error) bool

IsAlreadyPlayingError checks if an error is a 403 "restriction violated" error, which occurs when trying to resume playback that is already active.

func IsNoActiveDeviceError

func IsNoActiveDeviceError(err error) bool

IsNoActiveDeviceError checks if an error is a "no active device" error.

Types

type APIError

type APIError struct {
	ErrorInfo struct {
		Status  int    `json:"status"`
		Message string `json:"message"`
	} `json:"error"`
}

APIError represents a Spotify API error response.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) IsNoActiveDevice

func (e *APIError) IsNoActiveDevice() bool

IsNoActiveDevice returns true if the error indicates no active device.

type Album

type Album struct {
	ID           string       `json:"id"`
	Name         string       `json:"name"`
	URI          string       `json:"uri"`
	Href         string       `json:"href"`
	AlbumType    string       `json:"album_type"`
	TotalTracks  int          `json:"total_tracks"`
	ReleaseDate  string       `json:"release_date"`
	Images       []Image      `json:"images"`
	Artists      []Artist     `json:"artists"`
	ExternalURLs ExternalURLs `json:"external_urls"`
}

Album represents a Spotify album.

type Artist

type Artist struct {
	ID           string       `json:"id"`
	Name         string       `json:"name"`
	URI          string       `json:"uri"`
	Href         string       `json:"href"`
	Type         string       `json:"type"`
	ExternalURLs ExternalURLs `json:"external_urls"`
}

Artist represents a Spotify artist.

type Client

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

Client is a Spotify API client.

func New

func New(clientID string, storage *auth.TokenStorage) *Client

New creates a new Spotify client.

func (*Client) AddToQueue

func (c *Client) AddToQueue(ctx context.Context, uri string, deviceID string) error

AddToQueue adds a track to the playback queue.

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, path string) error

Delete performs a DELETE request to the Spotify API.

func (*Client) Get

func (c *Client) Get(ctx context.Context, path string, result interface{}) error

Get performs a GET request to the Spotify API.

func (*Client) GetCurrentUser

func (c *Client) GetCurrentUser(ctx context.Context) (*User, error)

GetCurrentUser returns the current user's profile.

func (*Client) GetDevices

func (c *Client) GetDevices(ctx context.Context) ([]Device, error)

GetDevices returns the user's available playback devices.

func (*Client) GetPlaybackState

func (c *Client) GetPlaybackState(ctx context.Context) (*PlaybackState, error)

GetPlaybackState returns the current playback state.

func (*Client) GetQueue

func (c *Client) GetQueue(ctx context.Context) (*Queue, error)

GetQueue returns the user's playback queue.

func (*Client) GetRecentlyPlayed added in v0.2.0

func (c *Client) GetRecentlyPlayed(ctx context.Context, limit int) (*RecentlyPlayedResponse, error)

GetRecentlyPlayed returns the user's recently played tracks.

func (*Client) HasToken

func (c *Client) HasToken() bool

HasToken returns true if there's any token (even if expired).

func (*Client) IsAuthenticated

func (c *Client) IsAuthenticated() bool

IsAuthenticated returns true if there's a valid (non-expired) token.

func (*Client) LoadToken

func (c *Client) LoadToken() error

LoadToken loads the token from storage.

func (*Client) Next

func (c *Client) Next(ctx context.Context, deviceID string) error

Next skips to the next track.

func (*Client) Pause

func (c *Client) Pause(ctx context.Context, deviceID string) error

Pause pauses playback.

func (*Client) Play

func (c *Client) Play(ctx context.Context, deviceID string, opts *PlayOptions) error

Play starts or resumes playback. If opts is nil, resumes current playback. If deviceID is empty, uses the currently active device.

func (*Client) Post

func (c *Client) Post(ctx context.Context, path string, body interface{}, result interface{}) error

Post performs a POST request to the Spotify API.

func (*Client) Previous

func (c *Client) Previous(ctx context.Context, deviceID string) error

Previous skips to the previous track.

func (*Client) Put

func (c *Client) Put(ctx context.Context, path string, body interface{}, result interface{}) error

Put performs a PUT request to the Spotify API.

func (*Client) RefreshToken

func (c *Client) RefreshToken(ctx context.Context) error

RefreshToken refreshes the access token if needed.

func (*Client) Search

func (c *Client) Search(ctx context.Context, opts SearchOptions) (*SearchResponse, error)

Search performs a search query.

func (*Client) Seek

func (c *Client) Seek(ctx context.Context, positionMs int, deviceID string) error

Seek seeks to a position in the current track.

func (*Client) SetRepeat

func (c *Client) SetRepeat(ctx context.Context, state string, deviceID string) error

SetRepeat sets the repeat mode (off, track, context).

func (*Client) SetShuffle

func (c *Client) SetShuffle(ctx context.Context, state bool, deviceID string) error

SetShuffle sets the shuffle mode.

func (*Client) SetToken

func (c *Client) SetToken(token *auth.Token) error

SetToken sets the current token.

func (*Client) SetVerbose

func (c *Client) SetVerbose(verbose bool, logFunc func(format string, args ...interface{}))

SetVerbose enables verbose logging.

func (*Client) SetVolume

func (c *Client) SetVolume(ctx context.Context, percent int, deviceID string) error

SetVolume sets the playback volume (0-100).

func (*Client) TransferPlayback

func (c *Client) TransferPlayback(ctx context.Context, deviceID string, play bool) error

TransferPlayback transfers playback to a different device.

type Context

type Context struct {
	Type         string       `json:"type"`
	URI          string       `json:"uri"`
	Href         string       `json:"href"`
	ExternalURLs ExternalURLs `json:"external_urls"`
}

Context represents a playback context (album, artist, playlist).

type Device

type Device struct {
	ID               string `json:"id"`
	Name             string `json:"name"`
	Type             string `json:"type"`
	IsActive         bool   `json:"is_active"`
	IsRestricted     bool   `json:"is_restricted"`
	IsPrivateSession bool   `json:"is_private_session"`
	VolumePercent    *int   `json:"volume_percent"` // Nullable
	SupportsVolume   bool   `json:"supports_volume"`
}

Device represents a Spotify playback device.

type DevicesResponse

type DevicesResponse struct {
	Devices []Device `json:"devices"`
}

DevicesResponse is the response from the devices endpoint.

type ExternalIDs

type ExternalIDs struct {
	ISRC string `json:"isrc"`
	EAN  string `json:"ean"`
	UPC  string `json:"upc"`
}

ExternalIDs contains external identifiers.

type ExternalURLs

type ExternalURLs struct {
	Spotify string `json:"spotify"`
}

ExternalURLs contains external URLs for a resource.

type Followers

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

Followers represents follower information.

type Image

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

Image represents an image resource.

type PlayHistory added in v0.2.0

type PlayHistory struct {
	Track    Track    `json:"track"`
	PlayedAt string   `json:"played_at"`
	Context  *Context `json:"context"`
}

PlayHistory represents a recently played track entry.

type PlayOffset

type PlayOffset struct {
	Position int    `json:"position,omitempty"` // Track index
	URI      string `json:"uri,omitempty"`      // Track URI
}

PlayOffset specifies where to start playback in a context.

type PlayOptions

type PlayOptions struct {
	ContextURI string      `json:"context_uri,omitempty"`
	URIs       []string    `json:"uris,omitempty"`
	Offset     *PlayOffset `json:"offset,omitempty"`
	PositionMS int         `json:"position_ms,omitempty"`
}

PlayOptions configures a play request.

type PlaybackState

type PlaybackState struct {
	Device               Device   `json:"device"`
	ShuffleState         bool     `json:"shuffle_state"`
	RepeatState          string   `json:"repeat_state"` // off, track, context
	Timestamp            int64    `json:"timestamp"`
	ProgressMS           int      `json:"progress_ms"`
	IsPlaying            bool     `json:"is_playing"`
	Item                 *Track   `json:"item"`
	CurrentlyPlayingType string   `json:"currently_playing_type"` // track, episode, ad, unknown
	Context              *Context `json:"context"`
}

PlaybackState represents the current playback state.

type Playlist

type Playlist struct {
	ID            string       `json:"id"`
	Name          string       `json:"name"`
	URI           string       `json:"uri"`
	Href          string       `json:"href"`
	Description   string       `json:"description"`
	Public        bool         `json:"public"`
	Collaborative bool         `json:"collaborative"`
	Images        []Image      `json:"images"`
	Owner         User         `json:"owner"`
	ExternalURLs  ExternalURLs `json:"external_urls"`
	Tracks        struct {
		Total int    `json:"total"`
		Href  string `json:"href"`
	} `json:"tracks"`
}

Playlist represents a Spotify playlist.

type Queue

type Queue struct {
	CurrentlyPlaying *Track  `json:"currently_playing"`
	Queue            []Track `json:"queue"`
}

Queue represents the user's playback queue.

type RecentlyPlayedResponse added in v0.2.0

type RecentlyPlayedResponse struct {
	Items   []PlayHistory `json:"items"`
	Next    string        `json:"next"`
	Cursors struct {
		After  string `json:"after"`
		Before string `json:"before"`
	} `json:"cursors"`
	Limit int `json:"limit"`
}

RecentlyPlayedResponse represents the response from the recently played endpoint.

type SearchAlbums

type SearchAlbums struct {
	Items  []Album `json:"items"`
	Total  int     `json:"total"`
	Limit  int     `json:"limit"`
	Offset int     `json:"offset"`
	Href   string  `json:"href"`
	Next   string  `json:"next"`
}

SearchAlbums contains album search results.

type SearchArtists

type SearchArtists struct {
	Items  []Artist `json:"items"`
	Total  int      `json:"total"`
	Limit  int      `json:"limit"`
	Offset int      `json:"offset"`
	Href   string   `json:"href"`
	Next   string   `json:"next"`
}

SearchArtists contains artist search results.

type SearchOptions

type SearchOptions struct {
	Query  string
	Types  []SearchType
	Limit  int
	Offset int
	Market string
}

SearchOptions configures a search query.

type SearchPlaylists

type SearchPlaylists struct {
	Items  []Playlist `json:"items"`
	Total  int        `json:"total"`
	Limit  int        `json:"limit"`
	Offset int        `json:"offset"`
	Href   string     `json:"href"`
	Next   string     `json:"next"`
}

SearchPlaylists contains playlist search results.

type SearchResponse

type SearchResponse struct {
	Tracks    *SearchTracks    `json:"tracks"`
	Artists   *SearchArtists   `json:"artists"`
	Albums    *SearchAlbums    `json:"albums"`
	Playlists *SearchPlaylists `json:"playlists"`
}

SearchResponse represents the response from a search query.

type SearchTracks

type SearchTracks struct {
	Items  []Track `json:"items"`
	Total  int     `json:"total"`
	Limit  int     `json:"limit"`
	Offset int     `json:"offset"`
	Href   string  `json:"href"`
	Next   string  `json:"next"`
}

SearchTracks contains track search results.

type SearchType

type SearchType string

SearchType represents a type of Spotify content to search.

const (
	SearchTypeTrack    SearchType = "track"
	SearchTypeArtist   SearchType = "artist"
	SearchTypeAlbum    SearchType = "album"
	SearchTypePlaylist SearchType = "playlist"
)

type Track

type Track struct {
	ID           string       `json:"id"`
	Name         string       `json:"name"`
	URI          string       `json:"uri"`
	Href         string       `json:"href"`
	DurationMS   int          `json:"duration_ms"`
	Explicit     bool         `json:"explicit"`
	IsPlayable   bool         `json:"is_playable"`
	TrackNumber  int          `json:"track_number"`
	DiscNumber   int          `json:"disc_number"`
	Popularity   int          `json:"popularity"`
	Artists      []Artist     `json:"artists"`
	Album        Album        `json:"album"`
	ExternalURLs ExternalURLs `json:"external_urls"`
	ExternalIDs  ExternalIDs  `json:"external_ids"`
}

Track represents a Spotify track.

type User

type User struct {
	ID           string       `json:"id"`
	DisplayName  string       `json:"display_name"`
	Email        string       `json:"email"`
	Country      string       `json:"country"`
	Product      string       `json:"product"`
	Type         string       `json:"type"`
	URI          string       `json:"uri"`
	Href         string       `json:"href"`
	Images       []Image      `json:"images"`
	Followers    Followers    `json:"followers"`
	ExternalURLs ExternalURLs `json:"external_urls"`
}

User represents a Spotify user profile.

Jump to

Keyboard shortcuts

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