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



104
105
106
107
108
109
110
111
# File 'lib/turntabler/song.rb', line 104

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

#albumString (readonly)

The name of the album this song is on

Returns:

  • (String)


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

attribute :album

#artistString (readonly)

The name of the artist

Returns:

  • (String)


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

attribute :artist

#cover_art_urlString (readonly)

The URL for the cover art image

Returns:

  • (String)


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

attribute :cover_art_url, :coverart

#down_votes_countFixnum (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)


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

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

#genreString (readonly)

The type of music

Returns:

  • (String)


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

attribute :genre

#isrcString (readonly)

The standard code id for this song

Returns:

  • (String)


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

attribute :isrc

#labelString (readonly)

The label that produced the music

Returns:

  • (String)


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

attribute :label

#lengthFixnum (readonly)

Number of seconds the song lasts

Returns:

  • (Fixnum)


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

attribute :length

#played_byTurntabler::User (readonly)

Note:

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

The DJ that played this song

Returns:



99
100
101
# File 'lib/turntabler/song.rb', line 99

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

#playlistTurntabler::Playlist (readonly)

The playlist this song is referenced from



61
62
63
# File 'lib/turntabler/song.rb', line 61

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

#released_onDate (readonly)

The date the song / album was released on

Returns:

  • (Date)


35
36
37
# File 'lib/turntabler/song.rb', line 35

attribute :released_on, :releasedate do |value|
  Date.parse(value)
end

#scoreFloat (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)


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

attribute :score, :load => false

#snaggableBoolean (readonly)

Whether this song can be snagged

Returns:

  • (Boolean)


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

attribute :snaggable

#sourceString (readonly)

The source from which the song was uploaded

Returns:

  • (String)


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

attribute :source

#source_idString (readonly)

The id of the song on the original source service

Returns:

  • (String)


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

attribute :source_id, :sourceid

#started_atTime (readonly)

The time at which the song was started

Returns:

  • (Time)


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

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

#titleString (readonly)

The title of the song

Returns:

  • (String)


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

attribute :title, :song

#up_votes_countFixnum (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)


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

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

#votesArray<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:



83
84
85
86
87
88
89
# File 'lib/turntabler/song.rb', line 83

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



218
219
220
221
222
223
224
225
226
227
228
229
230
# File 'lib/turntabler/song.rb', line 218

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_atTime

The time at which this song will end playing.

Examples:

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

Returns:

  • (Time)


118
119
120
# File 'lib/turntabler/song.rb', line 118

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

#loadtrue

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:



139
140
141
142
143
# File 'lib/turntabler/song.rb', line 139

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



252
253
254
255
256
# File 'lib/turntabler/song.rb', line 252

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

#removetrue

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



239
240
241
242
243
# File 'lib/turntabler/song.rb', line 239

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

#rotate_outObject

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.



262
263
264
265
# File 'lib/turntabler/song.rb', line 262

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

#seconds_remainingFixnum

The number of seconds remaining to play in the song

Examples:

song.seconds_remaining  # => 12

Returns:

  • (Fixnum)


127
128
129
# File 'lib/turntabler/song.rb', line 127

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

#skiptrue

Skips the song.

Examples:

song.skip   # => true

Returns:

  • (true)

Raises:



152
153
154
155
156
# File 'lib/turntabler/song.rb', line 152

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

#snagtrue

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:



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
# File 'lib/turntabler/song.rb', line 189

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:



167
168
169
170
171
172
173
174
175
176
177
178
179
# File 'lib/turntabler/song.rb', line 167

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