Class: Turntabler::Song

Inherits:
Resource show all
Defined in:
lib/turntabler/song.rb

Overview

Represents a song that can be played on Turntable

Instance Attribute Summary collapse

Attributes inherited from Resource

#id

Instance Method Summary collapse

Methods inherited from Resource

#==, attribute, #attributes=, #hash, #loaded?, #pretty_print, #pretty_print_instance_variables

Methods included from Assertions

#assert_valid_keys, #assert_valid_values

Methods included from DigestHelpers

#digest

Constructor Details

#initialize(client) ⇒ Song

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Song.



97
98
99
100
101
102
103
104
 
# File 'lib/turntabler/song.rb', line 97

def initialize(client, *)
  @up_votes_count = 0
  @down_votes_count = 0
  @votes = []
  @score = 0
  super
  @playlist = client.user.playlists.build(:_id => 'default') if played_by != client.user
end

Instance Attribute Details

#album ⇒ String (readonly)

The name of the album this song is on

Returns:

  • (String) 


22
 
# File 'lib/turntabler/song.rb', line 22

attribute :album

#artist ⇒ String (readonly)

The name of the artist

Returns:

  • (String) 


18
 
# File 'lib/turntabler/song.rb', line 18

attribute :artist

#cover_art_url ⇒ String (readonly)

The URL for the cover art image

Returns:

  • (String) 


34
 
# File 'lib/turntabler/song.rb', line 34

attribute :cover_art_url, :coverart

#down_votes_count ⇒ Fixnum (readonly)

Note:

This is only available for the current song playing in a room

The number of down votes this song has received.

Returns:

  • (Fixnum) 


70
 
# File 'lib/turntabler/song.rb', line 70

attribute :down_votes_count, :downvotes, :load => false

#genre ⇒ String (readonly)

The type of music

Returns:

  • (String) 


26
 
# File 'lib/turntabler/song.rb', line 26

attribute :genre

#isrc ⇒ String (readonly)

The standard code id for this song

Returns:

  • (String) 


14
 
# File 'lib/turntabler/song.rb', line 14

attribute :isrc

#label ⇒ String (readonly)

The label that produced the music

Returns:

  • (String) 


30
 
# File 'lib/turntabler/song.rb', line 30

attribute :label

#length ⇒ Fixnum (readonly)

Number of seconds the song lasts

Returns:

  • (Fixnum) 


38
 
# File 'lib/turntabler/song.rb', line 38

attribute :length

#played_by ⇒ Turntabler::User (readonly)

Note:

This is only available for the current song playing in a room

The DJ that played this song

Returns:



92
93
94
 
# File 'lib/turntabler/song.rb', line 92

attribute :played_by, :djid, :load => false do |value|
  room? ? room.build_user(:_id => value) : User.new(client, :_id => value)
end

#playlist ⇒ Turntabler::Playlist (readonly)

The playlist this song is referenced from

Returns:



54
55
56
 
# File 'lib/turntabler/song.rb', line 54

attribute :playlist, :load => false do |id|
  client.user.playlists.build(:_id => id)
end

#score ⇒ Float (readonly)

Note:

This is only available for the current song playing in a room

The percentage score for this song based on the number of votes

Returns:

  • (Float) 


87
 
# File 'lib/turntabler/song.rb', line 87

attribute :score, :load => false

#snaggable ⇒ Boolean (readonly)

Whether this song can be snagged

Returns:

  • (Boolean) 


42
 
# File 'lib/turntabler/song.rb', line 42

attribute :snaggable

#source ⇒ String (readonly)

The source from which the song was uploaded

Returns:

  • (String) 


46
 
# File 'lib/turntabler/song.rb', line 46

attribute :source

#source_id ⇒ String (readonly)

The id of the song on the original source service

Returns:

  • (String) 


50
 
# File 'lib/turntabler/song.rb', line 50

attribute :source_id, :sourceid

#started_at ⇒ Time (readonly)

The time at which the song was started

Returns:

  • (Time) 


60
 
# File 'lib/turntabler/song.rb', line 60

attribute :started_at, :starttime, :load => false

#title ⇒ String (readonly)

The title of the song

Returns:

  • (String) 


10
 
# File 'lib/turntabler/song.rb', line 10

attribute :title, :song

#up_votes_count ⇒ Fixnum (readonly)

Note:

This is only available for the current song playing in a room

The number of up votes this song has received.

Returns:

  • (Fixnum) 


65
 
# File 'lib/turntabler/song.rb', line 65

attribute :up_votes_count, :upvotes, :load => false

#votes ⇒ Array<Vote> (readonly)

Note:

This is only available for the current song playing in a room

The log of votes this song has received. This will only include up votes or down votes that were previously up votes.

Returns:



76
77
78
79
80
81
82
 
# File 'lib/turntabler/song.rb', line 76

attribute :votes, :votelog, :load => false do |votes|
  votes.each do |(user_id, direction)|
    self.votes.delete_if {|vote| vote.user.id == user_id}
    self.votes << Vote.new(client, :userid => user_id, :direction => direction) if user_id && !user_id.empty?
  end
  self.votes
end

Instance Method Details

#add(options = {}) ⇒ true

Adds the song to one of the user’s playlists.

Examples:

song.add(:index => 1)   # => true

Parameters:

  • options (Hash) (defaults to: {}) —

    The options for where to add the song

Options Hash (options):

  • :playlist (String) — default: "default" —

    The playlist to add the song in

  • :index (Fixnum) — default: 0 —

    The location in the playlist to insert the song

Returns:

  • (true)

Raises:

  • (ArgumentError) —

    if an invalid option is specified

  • (Turntabler::Error) —

    if the command fails



211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/turntabler/song.rb', line 211

def add(options = {})
  assert_valid_keys(options, :playlist, :index)
  options = {:playlist => playlist.id, :index => 0}.merge(options)

  # Create a copy of the song so that the playlist can get set properly
  song = dup
  song.attributes = {:playlist => options[:playlist]}
  playlist, index = song.playlist, options[:index]

  api('playlist.add', :playlist_name => playlist.id, :song_dict => {:fileid => id}, :index => index)
  playlist.songs.insert(index, song) if playlist.loaded?
  true
end

#ends_at ⇒ Time

The time at which this song will end playing.

Examples:

song.ends_at  # => 2013-01-05 12:14:25 -0500

Returns:

  • (Time) 


111
112
113
 
# File 'lib/turntabler/song.rb', line 111

def ends_at
  started_at + client.clock_delta + length if started_at
end

#load ⇒ true

Loads the attributes for this song. Attributes will automatically load when accessed, but this allows data to be forcefully loaded upfront.

Examples:

song.load     # => true
song.title    # => "..."

Returns:

  • (true)

Raises:



132
133
134
135
136
 
# File 'lib/turntabler/song.rb', line 132

def load
  data = api('playlist.get_metadata', :playlist_name => playlist.id, :files => [id])
  self.attributes = data['files'][id]
  super
end

#move(to_index) ⇒ true

Move a song from one location in the playlist to another.

Parameters:

  • to_index (Fixnum) —

    The index to move the song to

Returns:

  • (true)

Raises:

  • (ArgumentError) —

    if an invalid option is specified

  • (Turntabler::Error) —

    if the command fails song.move(5) # => true



245
246
247
248
249
 
# File 'lib/turntabler/song.rb', line 245

def move(to_index)
  api('playlist.reorder', :playlist_name => playlist.id, :index_from => index, :index_to => to_index)
  playlist.songs.insert(to_index, playlist.songs.delete(self))
  true
end

#remove ⇒ true

Removes the song from the playlist at the given index.

Examples:

song.remove   # => true

Returns:

  • (true)

Raises:

  • (ArgumentError) —

    if an invalid option is specified

  • (Turntabler::Error) —

    if the command fails



232
233
234
235
236
 
# File 'lib/turntabler/song.rb', line 232

def remove
  api('playlist.remove', :playlist_name => playlist.id, :index => index)
  playlist.songs.delete(self)
  true
end

#rotate_out ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Moves this song to the back of the playlist it’s associated with. If there are other songs in front of it, those will be moved to the back as well.



255
256
257
258
 
# File 'lib/turntabler/song.rb', line 255

def rotate_out
  playlist.songs.rotate!(index + 1)
  true
end

#seconds_remaining ⇒ Fixnum

The number of seconds remaining to play in the song

Examples:

song.seconds_remaining  # => 12

Returns:

  • (Fixnum) 


120
121
122
 
# File 'lib/turntabler/song.rb', line 120

def seconds_remaining
  ends_at ? (ends_at - started_at).round : 0
end

#skip ⇒ true

Skips the song.

Examples:

song.skip   # => true

Returns:

  • (true)

Raises:



145
146
147
148
149
 
# File 'lib/turntabler/song.rb', line 145

def skip
  assert_current_song
  api('room.stop_song', :roomid => room.id, :section => room.section)
  true
end

#snag ⇒ true

Note:

This will not add the song to the user’s playlist

Triggers the heart animation for the song.

Examples:

song.snag   # => true

Returns:

  • (true)

Raises:



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/turntabler/song.rb', line 182

def snag
  assert_current_song
  sh = digest(rand)
  api('snag.add',
    :djid => room.current_dj.id,
    :songid => id,
    :roomid => room.id,
    :section => room.section,
    :site => 'queue',
    :location => 'board',
    :in_queue => 'false',
    :blocked => 'false',
    :vh => digest([client.user.id, room.current_dj.id, id, room.id, 'queue', 'board', 'false', 'false', sh] * '/'),
    :sh => sh,
    :fh => digest(rand)
  )
  true
end

#vote(direction = :up) ⇒ true

Vote for the song.

Examples:

song.vote         # => true
song.vote(:down)  # => true

Parameters:

  • direction (Symbol) (defaults to: :up) —

    The direction to vote the song (:up or :down)

Returns:

  • (true)

Raises:



160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/turntabler/song.rb', line 160

def vote(direction = :up)
  assert_current_song
  api('room.vote',
    :roomid => room.id,
    :section => room.section,
    :val => direction,
    :songid => id,
    :vh => digest("#{room.id}#{direction}#{id}"),
    :th => digest(rand),
    :ph => digest(rand)
  )
  true
end