Class: LastFM::Track

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Struct

from_xml, inherited, #initialize, package, #to_json

Constructor Details

This class inherits a constructor from LastFM::Struct

Instance Attribute Details

#album ⇒ LastFM::Album

Returns the current value of album.

Returns:



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def album
  @album
end

#artist ⇒ LastFM::Artist, String

Returns the current value of artist.

Returns:



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def artist
  @artist
end

#duration ⇒ Fixnum

Returns the current value of duration.

Returns:

  • (Fixnum) —

    the current value of duration



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def duration
  @duration
end

#id ⇒ Fixnum

Returns the current value of id.

Returns:

  • (Fixnum) —

    the current value of id



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def id
  @id
end

#images ⇒ Hash

Returns the current value of images.

Returns:

  • (Hash) —

    the current value of images



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def images
  @images
end

#listeners ⇒ Fixnum

Returns the current value of listeners.

Returns:

  • (Fixnum) —

    the current value of listeners



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def listeners
  @listeners
end

#mbid ⇒ String

Returns the current value of mbid.

Returns:

  • (String) —

    the current value of mbid



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def mbid
  @mbid
end

#name ⇒ String

Returns the current value of name.

Returns:

  • (String) —

    the current value of name



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def name
  @name
end

#playcount ⇒ Fixnum

Returns the current value of playcount.

Returns:

  • (Fixnum) —

    the current value of playcount



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def playcount
  @playcount
end

#position ⇒ Fixnum

Returns the current value of position.

Returns:

  • (Fixnum) —

    the current value of position



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def position
  @position
end

#streamable ⇒ Boolean

Returns the current value of streamable.

Returns:

  • (Boolean) —

    the current value of streamable



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def streamable
  @streamable
end

#streamable_fulltrack ⇒ Boolean

Returns the current value of streamable_fulltrack.

Returns:

  • (Boolean) —

    the current value of streamable_fulltrack



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def streamable_fulltrack
  @streamable_fulltrack
end

#tags ⇒ Array

Returns the current value of tags.

Returns:

  • (Array) —

    the current value of tags



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def tags
  @tags
end

#url ⇒ String

Returns the current value of url.

Returns:

  • (String) —

    the current value of url



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def url
  @url
end

#wiki ⇒ LastFM::Wii

Returns the current value of wiki.

Returns:

  • (LastFM::Wii) —

    the current value of wiki



18
19
20
 
# File 'lib/lastfm/track.rb', line 18

def wiki
  @wiki
end

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:



65
66
67
68
 
# File 'lib/lastfm/track.rb', line 65

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:



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

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:



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

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:



103
104
105
 
# File 'lib/lastfm/track.rb', line 103

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:



115
116
117
 
# File 'lib/lastfm/track.rb', line 115

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:



128
129
130
131
 
# File 'lib/lastfm/track.rb', line 128

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:



143
144
145
146
147
148
 
# File 'lib/lastfm/track.rb', line 143

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:



159
160
161
162
163
164
 
# File 'lib/lastfm/track.rb', line 159

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:



174
175
176
177
178
 
# File 'lib/lastfm/track.rb', line 174

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:



187
188
189
 
# File 'lib/lastfm/track.rb', line 187

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:



199
200
201
202
203
204
 
# File 'lib/lastfm/track.rb', line 199

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:



211
212
213
214
 
# File 'lib/lastfm/track.rb', line 211

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:



222
223
224
225
 
# File 'lib/lastfm/track.rb', line 222

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:



245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/lastfm/track.rb', line 245

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:



266
267
268
269
270
271
 
# File 'lib/lastfm/track.rb', line 266

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:



281
282
283
284
 
# File 'lib/lastfm/track.rb', line 281

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:



291
292
293
294
 
# File 'lib/lastfm/track.rb', line 291

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:



301
302
303
304
 
# File 'lib/lastfm/track.rb', line 301

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:



317
318
319
320
 
# File 'lib/lastfm/track.rb', line 317

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

Instance Method Details

#update_from_node(node) ⇒ Object 



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/lastfm/track.rb', line 20

def update_from_node(node)
  case node.name.to_sym
    when :name
      self.name = node.content
    when :id
      self.id = node.content.to_i
    when :duration
      self.duration = node.content.to_i
    when :mbid
      self.mbid = node.content
    when :url
      self.url = node.content
    when :listeners
      self.listeners = node.content.to_i
    when :playcount
      self.playcount = node.content.to_i
    when :streamable
      self.streamable = (node.content == '1')
      self.streamable_fulltrack = (node['fulltrack'] == '1')
    when :image
      self.images ||= {}
      self.images.merge!({node['size'].to_sym => node.content})
    when :artist
      self.artist = (node.find('*').count == 0) ? node.content : LastFM::Artist.from_xml(node)
    when :album
      self.position = node['position'].to_i
      self.album = LastFM::Album.from_xml(node)
    when :toptags
      self.tags = node.find('tag').map do |tag|
        LastFM::Tag.from_xml(tag)
      end
    when :wiki
      self.wiki = LastFM::Wiki.from_xml(node)
  end
end