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.

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 (private)

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

#offsetRational (readonly, private)

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 (private)

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

Overriden to use default parameter.

Returns:

See Also:


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

to_link   :from_track

#albumHallon::Album (private)

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

#artistHallon::Artist? (private)

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

#artistsArtists (private)

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 (private)

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

#availabilitySymbol (private)

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 (private)

Returns true if #availability is available.

Returns:


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

def available?
  availability == :available
end

#discInteger (private)

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

#durationRational (private)

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

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

#indexInteger (private)

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 (private)

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 (private)

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

#nameString (private)

Returns:

  • (String)

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

def name
  Spotify.track_name(pointer)
end

#offline_statusSymbol (private)

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 (private)

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_trackTrack (private)

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

#popularityRational (private)

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 (private)

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 (private)

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

#statusSymbol (private)

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

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

#unwrapTrack, ... (private)

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