Class: LastFM::Api::Track

Inherits:
Object
  • Object
show all
Defined in:
lib/lastfm/api/track.rb

Class Method Summary collapse

Class Method Details

.add_tags(params) ⇒ Object

Add a list of user supplied tags to a track.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required) —

    the artist name

  • :track (String, required) —

    the track name

  • :tags (Array, required) —

    array of tags to apply to this track. accepts a maximum of 10.

See Also:



12
13
14
15
 
# File 'lib/lastfm/api/track.rb', line 12

def add_tags( params )
  LastFM.requires_authentication
  LastFM.post( "track.addTags", params )
end

.ban(params) ⇒ Object

Ban a track for the current user.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required) —

    the artist name

  • :track (String, required) —

    the track name

See Also:



22
23
24
25
 
# File 'lib/lastfm/api/track.rb', line 22

def ban( params )
  LastFM.requires_authentication
  LastFM.post( "track.ban", params )
end

.get_buylinks(params) ⇒ Array<LastFM::Buylink>

Get a list of buy Links for a track.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    the artist name

  • :track (String, required unless :mbid) —

    the track name

  • :country (String, required) —

    a country name, as defined by ISO 3166-1

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :autocorrect (Boolean, optional) —

    correct misspelled artist and track names to be returned in the response

Returns:

  • (Array<LastFM::Buylink>) —

    collection of links where this track can be bought or downloaded

See Also:



36
37
38
39
40
41
42
43
 
# File 'lib/lastfm/api/track.rb', line 36

def get_buylinks( params )
  xml = LastFM.get( "track.getBuylinks", params )
  [:physical, :download].each_with_object([]) do |type, buylinks|
    xml.find("affiliations/#{type}s/affiliation").each do |buylink|
      buylinks << LastFM::Buylink.from_xml( buylink, :type => type )
    end
  end
end

.get_correction(params) ⇒ Object

Use the last.fm corrections data to check whether the supplied track has a correction to a canonical track

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required) —

    the artist name to correct

  • :track (String, required) —

    the track name to correct

See Also:



50
51
52
 
# File 'lib/lastfm/api/track.rb', line 50

def get_correction( params )
  LastFM.get( "track.getCorrection", params )
end

.get_fingerprint_metadata(params) ⇒ Object

Retrieve track metadata associated with a fingerprint id generated by the Last.fm Fingerprinter. Returns track elements, along with a ‘rank’ value between 0 and 1 reflecting the confidence for each match.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :fingerprint_id (String, required) —

    the fingerprint id to look up

See Also:



62
63
64
 
# File 'lib/lastfm/api/track.rb', line 62

def get_fingerprint_metadata( params )
  LastFM.get( "track.getFingerPrintMetadata", params )
end

.get_info(params) ⇒ LastFM::Track

Get the metadata for a track.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    the artist name

  • :track (String, required unless :mbid) —

    the track name

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :autocorrect (Boolean, optional) —

    correct misspelled artist and track names to be returned in the response

  • :username (String, optional) —

    username whose playcount for, and whether they’ve loved, this track is to be returned in the reponse

Returns:

  • (LastFM::Track) —

    track constructed from the metadata contained in the response

See Also:



75
76
77
78
 
# File 'lib/lastfm/api/track.rb', line 75

def get_info( params )
  xml = LastFM.get( "track.getInfo", params )
  LastFM::Track.from_xml( xml )
end

.get_shouts(params) ⇒ Array<LastFM::Shout>

Get shouts for a track.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    the artist name

  • :track (String, required unless :mbid) —

    the track name

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :autocorrect (Boolean, optional) —

    correct misspelled artist and track names to be returned in the response

  • :page (Fixnum, optional) —

    the page number to fetch. defaults to first page

  • :limit (Fixnum, optional) —

    the number of results to fetch per page. defaults to 50

Returns:

See Also:



90
91
92
93
94
95
 
# File 'lib/lastfm/api/track.rb', line 90

def get_shouts( params )
  xml = LastFM.get( "track.getShouts", params )
  xml.find('shouts/shout').map do |shout|
    LastFM::Shout.from_xml( shout )
  end
end

.get_similar(params) ⇒ Array<LastFM::Track>

Get similar tracks for a track on Last.fm, based on listening data.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    the artist name

  • :track (String, required unless :mbid) —

    the track name

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :autocorrect (Boolean, optional) —

    correct misspelled artist and track names to be returned in the response

  • :limit (Fixnum, optional) —

    the number of results to fetch. defaults to 50

Returns:

  • (Array<LastFM::Track>) —

    similar tracks, ordered by similarity

See Also:



106
107
108
109
110
111
 
# File 'lib/lastfm/api/track.rb', line 106

def get_similar( params )
  xml = LastFM.get( "track.getSimilar", params )
  xml.find('similartracks/track').map do |track|
    LastFM::Track.from_xml( track )
  end
end

.get_tags(params) ⇒ Object

Get the tags on a track.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    the artist name

  • :track (String, required unless :mbid) —

    the track name

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :autocorrect (Boolean, optional) —

    correct misspelled artist and track names to be returned in the response

  • :user (String, optional) —

    if called in non-authenticated mode you must specify the user to look up

See Also:



121
122
123
124
125
 
# File 'lib/lastfm/api/track.rb', line 121

def get_tags( params )
  secure = !params.include?(:user)
  LastFM.requires_authentication if secure
  LastFM.post( "track.getTags", params, secure )
end

.get_top_fans(params) ⇒ Object

Get the top fans for a track, based on listening data.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    the artist name

  • :track (String, required unless :mbid) —

    the track name

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :autocorrect (Boolean, optional) —

    correct misspelled artist and track names to be returned in the response

See Also:



134
135
136
 
# File 'lib/lastfm/api/track.rb', line 134

def get_top_fans( params )
  LastFM.get( "track.getTopFans", params )
end

.get_top_tags(params) ⇒ Array<LastFM::Tag>

Get the top fans for a track, ordered by tag count.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    the artist name

  • :track (String, required unless :mbid) —

    the track name

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :autocorrect (Boolean, optional) —

    correct misspelled artist and track names to be returned in the response

Returns:

  • (Array<LastFM::Tag>) —

    list of tags ordered by popularity

See Also:



146
147
148
149
150
151
 
# File 'lib/lastfm/api/track.rb', line 146

def get_top_tags( params )
  xml = LastFM.get( "track.getTopTags", params )
  xml.find('toptags/tag').map do |tag|
    LastFM::Tag.from_xml( tag )
  end
end

.love(params) ⇒ Object

Love a track for the current user.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required) —

    the artist name

  • :track (String, required) —

    the track name

See Also:



158
159
160
161
 
# File 'lib/lastfm/api/track.rb', line 158

def love( params )
  LastFM.requires_authentication
  LastFM.post( "track.love", params )
end

.remove_tag(params) ⇒ Object

Remove a user’s tag from a track.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required) —

    the artist name

  • :track (String, required) —

    the track name

  • :tag (String, required) —

    a single user tag to remove from this track

See Also:



169
170
171
172
 
# File 'lib/lastfm/api/track.rb', line 169

def remove_tag( params )
  LastFM.requires_authentication
  LastFM.post( "track.removeTag", params )
end

.scrobble(params) ⇒ Object

Used to add a track-play to a user’s profile. Scrobble a track, or a batch of tracks. Single tracks may be passed using the Object types listed, batches of tracks must be passed in as Arrays of each Object type. Allows up to a maximum of 50 scrobbles per batch. For batch scrobbles, Array indices of optional parameters must line up with the indicies of their corresponding tracks.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    artist name

  • :track (String, required unless :mbid) —

    track name

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :timestamp (Time, optional) —

    time the track started playing

  • :album (String, optional) —

    album name

  • :album_artist (String, optional) —

    album artist, if this differend from the track artist

  • :track_number (Fixnum, optional) —

    track number of the track on the album

  • :duration (Fixnum, optional) —

    track length, in seconds

  • :stream_id (String, optional) —

    track stream id, received from the radio.getPlaylist service

  • :chosen_by_user (Boolean, optional) —

    whether or not the user chose the track

  • :context (String, optional) —

    sub-client version (not public, only enabled for certain api keys)

See Also:



192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/lastfm/api/track.rb', line 192

def scrobble( params )
  LastFM.requires_authentication
  # Tracks are passed to the service using array notation for each of the above params
  array_params = {}
  params.each do |hkey, hval|
    hval = hval.to_i if hval.is_a?(Time)
    Array(hval).each_with_index do |aval, index|
      array_params["#{hkey}[#{index}]"] = aval
    end
  end
  LastFM.post( "track.scrobble", array_params )
end

.search(params) ⇒ Array<LastFM::Track>

Search for a track by track name. Returns track matches sorted by relevance.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :track (String, required) —

    the track name

  • :artist (String, optional) —

    narrow results based on an artist

  • :page (Fixnum, optional) —

    the page number to fetch. defaults to first page

  • :limit (Fixnum, optional) —

    the number of results to fetch per page. defaults to 50

Returns:

See Also:



213
214
215
216
217
218
 
# File 'lib/lastfm/api/track.rb', line 213

def search( params )
  xml = LastFM.get( "track.search", params )
  xml.find('results/trackmatches/track').map do |track|
    LastFM::Track.from_xml( track )
  end
end

.share(params) ⇒ Object

Share a track twith one or more Last.fm users or other friends.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required) —

    the artist name

  • :track (String, required) —

    the track name

  • :recipient (Array, required) —

    a list of email addresses or Last.fm usernames. maximum is 10

  • :message (String, optional) —

    an optional message to send. if not supplied a default message will be used

  • :public (Boolean, optional) —

    optionally show in the sharing users activity feed. defaults to false

See Also:



228
229
230
231
 
# File 'lib/lastfm/api/track.rb', line 228

def share( params )
  LastFM.requires_authentication
  LastFM.post( "track.share", params )
end

.unban(params) ⇒ Object

Unban a track for the current user.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required) —

    the artist name

  • :track (String, required) —

    the track name

See Also:



238
239
240
241
 
# File 'lib/lastfm/api/track.rb', line 238

def unban( params )
  LastFM.requires_authentication
  LastFM.post( "track.unban", params )
end

.unlove(params) ⇒ Object

Unlove a track for the current user.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required) —

    the artist name

  • :track (String, required) —

    the track name

See Also:



248
249
250
251
 
# File 'lib/lastfm/api/track.rb', line 248

def unlove( params )
  LastFM.requires_authentication
  LastFM.post( "track.unlove", params )
end

.update_now_playing(params) ⇒ Object

Used to notify Last.fm that a user has started listening to a track.

Parameters:

  • params (Hash) —

    a customizable set of options

Options Hash (params):

  • :artist (String, required unless :mbid) —

    artist name

  • :track (String, required unless :mbid) —

    track name

  • :mbid (String, optional) —

    the musicbrainz id for the track

  • :album (String, optional) —

    album name

  • :album_artist (String, optional) —

    album artist, if this differend from the track artist

  • :track_number (Fixnum, optional) —

    track number of the track on the album

  • :duration (Fixnum, optional) —

    track length, in seconds

  • :context (String, optional) —

    sub-client version (not public, only enabled for certain api keys)

See Also:



264
265
266
267
 
# File 'lib/lastfm/api/track.rb', line 264

def update_now_playing( params )
  LastFM.requires_authentication
  LastFM.post( "track.updateNowPlaying", params )
end