lastfm

Documentation

Overview

Implements a simple http://last.fm API client library.

The library currently doesn't support authentication, so it only implements a few queries that are useful without authentication.

Index

• Constants
• type Album
• type AlbumInfo
• type Artist
• type LastFM
  • func New(apiKey string) LastFM
  • func (lfm *LastFM) CompareTaste(user1 string, user2 string) (taste *Tasteometer, err error)
  • func (lfm *LastFM) GetArtistTopTags(artist Artist, autocorrect bool) (toptags *TopTags, err error)
  • func (lfm *LastFM) GetRecentTracks(user string, count int) (tracks *RecentTracks, err error)
  • func (lfm *LastFM) GetTrackInfo(track Track, user string, autocorrect bool) (info *TrackInfo, err error)
  • func (lfm *LastFM) GetTrackTopTags(track Track, autocorrect bool) (toptags *TopTags, err error)
  • func (lfm *LastFM) GetUserNeighbours(user string, limit int) (neighbours Neighbours, err error)
  • func (lfm *LastFM) GetUserTopArtists(user string, period Period, limit int) (top *TopArtists, err error)
  • func (lfm *LastFM) LoadCache(r io.Reader) error
  • func (lfm *LastFM) SaveCache(w io.Writer) error
• type LastFMError
  • func (e *LastFMError) Error() string
• type Neighbour
• type Neighbours
• type Period
  • func (p Period) String() string
• type RecentTracks
• type Tag
• type Tasteometer
• type TopArtists
• type TopTags
• type Track
• type TrackInfo
• type Wiki

Constants

const (
	DefaultDuration        = 5 * time.Minute
	DefaultCleanupInterval = 1 * time.Minute
)

Types

type Album

type Album struct {
	Name string `xml:",chardata"`
	MBID string `xml:"mbid,attr"`
}

Less detailed struct returned in GetRecentTracks.

type AlbumInfo

type AlbumInfo struct {
	TrackNo int    `xml:"position,attr"`
	Name    string `xml:"title"`
	Artist  string `xml:"artist"`
	MBID    string `xml:"mbid"`
	URL     string `xml:"url"`
}

More detailed struct returned in GetTrackInfo.

type Artist

type Artist struct {
	Name      string `xml:"name"`
	PlayCount int    `xml:"playcount"` // Currently is always 0, except when part of the result of GetUserTopArtists.
	MBID      string `xml:"mbid"`
	URL       string `xml:"url"`
}

type LastFM

type LastFM struct {
	Cache struct {
		*sync.RWMutex
		*cache.Cache
	}
	// contains filtered or unexported fields
}

Struct used to access the API servers.

func New

func New(apiKey string) LastFM

Create a new LastFM struct. The apiKey parameter must be an API key registered with Last.fm.

func (*LastFM) CompareTaste

func (lfm *LastFM) CompareTaste(user1 string, user2 string) (taste *Tasteometer, err error)

Compares the taste of 2 users.

See http://www.last.fm/api/show/tasteometer.compare.

func (*LastFM) GetArtistTopTags

func (lfm *LastFM) GetArtistTopTags(artist Artist, autocorrect bool) (toptags *TopTags, err error)

Gets the top tags for an Artist. The second argument tells last.fm whether it is to apply autocorrections to the artist name.

The Artist struct must specify either the MBID or the Name. Example literals that can be given as the first argument:

lastfm.Artist{MBID: "mbid"}
lastfm.Artist{Name: "Artist"}

See http://www.last.fm/api/show/artist.getTopTags.

func (*LastFM) GetRecentTracks

func (lfm *LastFM) GetRecentTracks(user string, count int) (tracks *RecentTracks, err error)

Gets a list of recent tracks from the user. The .Tracks field includes the currently playing track, if any, and up to the count most recent scrobbles. The .NowPlaying field points to any currently playing track.

See http://www.last.fm/api/show/user.getRecentTracks.

func (*LastFM) GetTrackInfo

func (lfm *LastFM) GetTrackInfo(track Track, user string, autocorrect bool) (info *TrackInfo, err error)

Gets information for a Track. The user argument can either be empty ("") or specify a last.fm username, in which case .UserPlaycount and .UserLoved will be valid in the returned struct. The autocorrect parameter controls whether last.fm's autocorrection algorithms should be run on the artist or track names.

The Track struct must specify either the MBID or both Artist.Name and Name. Example literals that can be given as the first argument:

lastfm.Track{MBID: "mbid"}
lastfm.Track{Artist: lastfm.Artist{Name: "Artist"}, Name: "Track"}

See http://www.last.fm/api/show/track.getInfo.

func (*LastFM) GetTrackTopTags

func (lfm *LastFM) GetTrackTopTags(track Track, autocorrect bool) (toptags *TopTags, err error)

Gets the top tags for a Track. The second argument tells last.fm whether it is to apply autocorrections to the name/artist.

The Track struct must specify either the MBID or both Artist.Name and Name. Example literals that can be given as the first argument:

lastfm.Track{MBID: "mbid"}
lastfm.Track{Artist: lastfm.Artist{Name: "Artist"}, Name: "Track"}

See http://www.last.fm/api/show/track.getTopTags.

func (*LastFM) GetUserNeighbours

func (lfm *LastFM) GetUserNeighbours(user string, limit int) (neighbours Neighbours, err error)

Gets a list of up to limit closest neighbours of a user. A neighbour is another user that has high tasteometer comparison scores.

See http://www.last.fm/api/show/user.getNeighbours

func (*LastFM) GetUserTopArtists

func (lfm *LastFM) GetUserTopArtists(user string, period Period, limit int) (top *TopArtists, err error)

Gets a list of the (up to limit) most played artists of a user within a Period.

See http://www.last.fm/api/show/user.getTopArtists.

func (*LastFM) LoadCache

func (lfm *LastFM) LoadCache(r io.Reader) error

Reads a gob-encoded representation of the Cache from the given io.Reader. Does not change the current Cache if there is a read or decoding error.

The Cache will have its parameters set to this package's DefaultDuration and DefaultCleanupInterval. To change the cache's duration/interval, a new cache is needed like so:

lfm.Cache = cache.NewFrom(duration, interval, lfm.Cache.Items())

This method is not safe for concurrent access, use before starting any requests.

func (*LastFM) SaveCache

func (lfm *LastFM) SaveCache(w io.Writer) error

Writes a gob-encoded representation of the Cache to the given io.Writer.

type LastFMError

type LastFMError struct {
	Code    int    `xml:"code,attr"`
	Message string `xml:",chardata"`
	// contains filtered or unexported fields
}

func (*LastFMError) Error

func (e *LastFMError) Error() string

type Neighbour

type Neighbour struct {
	Name  string  `xml:"name"`
	Match float32 `xml:"match"`
}

type Neighbours

type Neighbours []Neighbour

type Period

type Period int

const (
	Overall Period = 1 + iota
	OneWeek
	OneMonth
	ThreeMonths
	SixMonths
	OneYear
)

func (Period) String

func (p Period) String() string

type RecentTracks

type RecentTracks struct {
	User       string  `xml:"user,attr"`
	Total      int     `xml:"total,attr"`
	Tracks     []Track `xml:"track"`
	NowPlaying *Track  `xml:"-"` // Points to the currently playing track, if any
}

type Tag

type Tag struct {
	Name  string `xml:"name"`
	Count int    `xml:"count"`
	URL   string `xml:"url"`
}

type Tasteometer

type Tasteometer struct {
	Users   []string `xml:"input>user>name"`            // The compared users
	Score   float32  `xml:"result>score"`               // Varies from 0.0 to 1.0
	Artists []string `xml:"result>artists>artist>name"` // Short list of up to 5 common artists with the most affinity
}

type TopArtists

type TopArtists struct {
	User   string `xml:"user,attr"`
	Period Period `xml:"-"`
	Total  int    `xml:"total,attr"`

	Artists []Artist `xml:"artist"`

	// For internal use
	RawPeriod string `xml:"type,attr"`
}

type TopTags

type TopTags struct {
	Artist string `xml:"artist,attr"`
	Track  string `xml:"track,attr"`
	Tags   []Tag  `xml:"tag"`
}

type Track

type Track struct {
	NowPlaying bool      `xml:"nowplaying,attr"`
	Artist     Artist    `xml:"artist"`
	Album      Album     `xml:"album"`
	Loved      bool      `xml:"loved"`
	Name       string    `xml:"name"`
	MBID       string    `xml:"mbid"`
	URL        string    `xml:"url"`
	Date       time.Time `xml:"-"`

	// For internal use
	RawDate lfmDate `xml:"date"`
}

type TrackInfo

type TrackInfo struct {
	ID             int           `xml:"id"`
	Name           string        `xml:"name"`
	MBID           string        `xml:"mbid"`
	URL            string        `xml:"url"`
	Duration       time.Duration `xml:"-"`
	Listeners      int           `xml:"listeners"`
	TotalPlaycount int           `xml:"playcount"`
	Artist         Artist        `xml:"artist"`

	// Sometimes not present
	Album   *AlbumInfo `xml:"album"`
	TopTags []string   `xml:"toptags>tag>name"`
	Wiki    *Wiki      `xml:"wiki"`

	// Only present if the user parameter isn't empty ("")
	UserPlaycount int  `xml:"userplaycount"`
	UserLoved     bool `xml:"userloved"`

	// For internal use
	RawDuration string `xml:"duration"`
}

type Wiki

type Wiki struct {
	Published time.Time `xml:"-"`
	Summary   string    `xml:"summary"`
	Content   string    `xml:"content"`

	// For internal use
	RawPublished string `xml:"published"`
}