Class: Hallon::Track

Inherits:
Base
  • Object
show all
Includes:
Linkable, Loadable
Defined in:
lib/hallon/track.rb

Overview

Tracks are an essential part to the Spotify service. They are browsable entities that can also be played by streaming.

See Also:

Direct Known Subclasses

Playlist::Track

Defined Under Namespace

Classes: Artists

Instance Attribute Summary collapse

Attributes inherited from Base

#pointer

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Loadable

#load

Methods included from Linkable

#===, included, #to_str

Methods inherited from Base

#==, from, from_link, #is_linkable?, #session, to_link, #to_pointer, #to_s

Constructor Details

#initialize(link) ⇒ Track

Construct a new Track instance.

Parameters:



44
45
46
47
48
49
 
# File 'lib/hallon/track.rb', line 44

def initialize(link)
  FFI::MemoryPointer.new(:int) do |ptr|
    @pointer = to_pointer(link, Spotify::Track, ptr)
    @offset  = Rational(ptr.read_int, 1000)
  end
end

Instance Attribute Details

#offset ⇒ Rational (readonly)

Offset into track in seconds this track was created with.

Returns:

  • (Rational) 


39
40
41
 
# File 'lib/hallon/track.rb', line 39

def offset
  @offset
end

Class Method Details

.local(title, artist, album = nil, length = nil) ⇒ Track

Note:

I’ve been unable to get local tracks to get matched up in libspotify v11, it’s possible this function does not work properly in libspotify v11.

Create a new local track.

Local tracks in Spotify allows you to specify title, artist, and optionally also album and length. This will create a local track (meaning #local? returns true) that libspotify will try to match up with an actual track in the Spotify database.

If the track is successfully matched, once loaded, #available? will return true and you’ll be able to inspect the track’s #artist and #album, as well as the information in the track itself. If the track is playable you’ll also be able to play it!

Examples:

creating a local track

track = Hallon::Track.local "Californication", "Red Hot Chili Peppers"
puts track.artist.name # => "Red Hot Chili Peppers"
puts track.album.name # => "Californication"
p track.local? # => true

Parameters:

  • title (String)
  • artist (String)
  • album (String) (defaults to: nil)
  • length (Integer) (defaults to: nil)

Returns:



76
77
78
79
 
# File 'lib/hallon/track.rb', line 76

def self.local(title, artist, album = nil, length = nil)
  track = Spotify.localtrack_create(artist, title, album || "", length || -1)
  new(track)
end

Instance Method Details

#_to_link ⇒ Hallon::Link

Overriden to use default parameter.

Returns:

See Also:



26
 
# File 'lib/hallon/track.rb', line 26

to_link   :from_track

#album ⇒ Hallon::Album

Returns album this track belongs to.

Returns:



159
160
161
162
 
# File 'lib/hallon/track.rb', line 159

def album
  album = Spotify.track_album(pointer)
  Album.from(album)
end

#artist ⇒ Hallon::Artist?

Note:

There may be more than one artist, see #artists for retrieving them all!

Returns artist who performed this track.

Returns:

See Also:



167
168
169
 
# File 'lib/hallon/track.rb', line 167

def artist
  artists.first
end

#artists ⇒ Artists

Returns all Artists who performed this Track.

Returns:



172
173
174
 
# File 'lib/hallon/track.rb', line 172

def artists
  Artists.new(self)
end

#autolinked? ⇒ Boolean

Returns true if the track is autolinked.

Returns:

  • (Boolean) —

    true if the track is autolinked.



201
202
203
 
# File 'lib/hallon/track.rb', line 201

def autolinked?
  Spotify.track_is_autolinked(session.pointer, pointer)
end

#availability ⇒ Symbol

Track availability.

Returns:

  • (Symbol) —

    :unavailable, :available, :not_streamable, :banned_by_artist



184
185
186
 
# File 'lib/hallon/track.rb', line 184

def availability
  Spotify.track_get_availability(session.pointer, pointer)
end

#available? ⇒ Boolean

Returns true if #availability is available.

Returns:



177
178
179
 
# File 'lib/hallon/track.rb', line 177

def available?
  availability == :available
end

#disc ⇒ Integer

Note:

This function is a bit special. See libspotify docs for details.

Disc number this track appears in.

Returns:

  • (Integer) —

    disc index from album this track appears in.



104
105
106
 
# File 'lib/hallon/track.rb', line 104

def disc
  Spotify.track_disc(pointer)
end

#duration ⇒ Rational

Duration of the track in seconds.

Returns:

  • (Rational) 


89
90
91
 
# File 'lib/hallon/track.rb', line 89

def duration
  Rational(Spotify.track_duration(pointer), 1000)
end

#from_link ⇒ Spotify::Link (private)

Returns pointer representation of given link.

Parameters:

Returns:

  • (Spotify::Link) —

    pointer representation of given link.



21
 
# File 'lib/hallon/track.rb', line 21

from_link :as_track_and_offset

#index ⇒ Integer

Note:

This function is a bit special. See libspotify docs for details.

Returns position of track on its’ disc.

Returns:

  • (Integer) —

    position of track on its’ disc.



110
111
112
 
# File 'lib/hallon/track.rb', line 110

def index
  Spotify.track_index(pointer)
end

#loaded? ⇒ Boolean

Returns true if track is loaded.

Returns:

  • (Boolean) —

    true if track is loaded.



121
122
123
 
# File 'lib/hallon/track.rb', line 121

def loaded?
  Spotify.track_is_loaded(pointer)
end

#local? ⇒ Boolean

Returns true if the track is a local track.

Returns:

  • (Boolean) —

    true if the track is a local track.



196
197
198
 
# File 'lib/hallon/track.rb', line 196

def local?
  Spotify.track_is_local(session.pointer, pointer)
end

#name ⇒ String

Returns:

  • (String) 


82
83
84
 
# File 'lib/hallon/track.rb', line 82

def name
  Spotify.track_name(pointer)
end

#offline_status ⇒ Symbol

Returns track offline status.

Returns:

  • (Symbol) —

    track offline status.



154
155
156
 
# File 'lib/hallon/track.rb', line 154

def offline_status
  Spotify.track_offline_get_status(pointer)
end

#placeholder? ⇒ Boolean

Note:

Track does not have to be loaded for this to return a useful value.

Note:

Placeholder tracks are not really tracks, but merely containers

for other objects to allow storing them in playlists such as the inbox.

Returns:

  • (Boolean) —

    true if the track is a placeholder.

See Also:



132
133
134
 
# File 'lib/hallon/track.rb', line 132

def placeholder?
  Spotify.track_is_placeholder(pointer)
end

#playable_track ⇒ Track

Returns the track this track is autolinked to for audio playback.

Returns:

  • (Track) —

    the track this track is autolinked to for audio playback.

See Also:



190
191
192
193
 
# File 'lib/hallon/track.rb', line 190

def playable_track
  track = Spotify.track_get_playable(session.pointer, pointer)
  Track.from(track)
end

#popularity ⇒ Rational

Track popularity, between 0 and 100.

Returns:

  • (Rational) 


96
97
98
 
# File 'lib/hallon/track.rb', line 96

def popularity
  Spotify.track_popularity(pointer)
end

#starred=(starred) ⇒ Object

Note:

this method might raise a Spotify::Error, however when this might occur is not documented in libspotify (and I have yet to find any way to trigger it myself). it’s entirely possible that this method never returns an error, but we can’t know for sure.

Set #starred? status of current track.

Parameters:

  • starred (Boolean)

Raises:

  • (Spotify:Error) —

    if libspotify reports an error (when this happens is unknown and undocumented)



216
217
218
 
# File 'lib/hallon/track.rb', line 216

def starred=(starred)
  starred ? session.star(self) : session.unstar(self)
end

#starred? ⇒ Boolean

Note:

This’ll always return false unless the track is loaded.

Returns true if the track is starred.

Returns:

  • (Boolean) —

    true if the track is starred.



207
208
209
 
# File 'lib/hallon/track.rb', line 207

def starred?
  Spotify.track_is_starred(session.pointer, pointer)
end

#status ⇒ Symbol

Returns track error status.

Returns:

  • (Symbol) —

    track error status.

See Also:

  • Error.explain


116
117
118
 
# File 'lib/hallon/track.rb', line 116

def status
  Spotify.track_error(pointer)
end

#to_link(offset = offset) ⇒ Hallon::Link

Create a Link to the current track and offset in seconds.

Parameters:

  • offset (Float) (defaults to: offset) —

    offset into track in seconds

Returns:



32
 
# File 'lib/hallon/track.rb', line 32

to_link   :from_track

#unwrap ⇒ Track, ...

Unwraps a #placeholder? Track into its’ real object.

Returns:

See Also:



140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/hallon/track.rb', line 140

def unwrap
  return self unless placeholder?

  case (link = to_link).type
  when :playlist
    Playlist.new(link)
  when :album
    Album.new(link)
  when :artist
    Artist.new(link)
  end
end