Class: MPD

Inherits:
Object
  • Object
show all
Includes:
Parser, Plugins::Channels, Plugins::Controls, Plugins::Database, Plugins::Information, Plugins::Outputs, Plugins::PlaybackOptions, Plugins::Playlists, Plugins::Queue, Plugins::Reflection, Plugins::Stickers
Defined in:
lib/ruby-mpd.rb,
lib/ruby-mpd/song.rb,
lib/ruby-mpd/parser.rb,
lib/ruby-mpd/version.rb,
lib/ruby-mpd/playlist.rb,
lib/ruby-mpd/exceptions.rb,
lib/ruby-mpd/plugins/queue.rb,
lib/ruby-mpd/plugins/outputs.rb,
lib/ruby-mpd/plugins/channels.rb,
lib/ruby-mpd/plugins/controls.rb,
lib/ruby-mpd/plugins/database.rb,
lib/ruby-mpd/plugins/stickers.rb,
lib/ruby-mpd/plugins/playlists.rb,
lib/ruby-mpd/plugins/reflection.rb,
lib/ruby-mpd/plugins/information.rb,
lib/ruby-mpd/plugins/playback_options.rb

Overview

The main class/namespace of the MPD client.

Defined Under Namespace

Modules: Parser, Plugins Classes: AlreadyExists, AlreadyUpdating, ConnectionError, Error, IncorrectPassword, NotFound, NotListError, NotPlaying, PermissionError, Playlist, PlaylistLoadError, PlaylistMaxError, ServerArgumentError, ServerError, Song, SystemError

Constant Summary collapse

VERSION = 
'0.3.0'

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Plugins::Channels

#channels, #readmessages, #sendmessage, #subscribe, #unsubscribe

Methods included from Plugins::Reflection

#commands, #config, #decoders, #notcommands, #tags, #url_handlers

Methods included from Plugins::Outputs

#disableoutput, #enableoutput, #outputs

Methods included from Plugins::Stickers

#delete_sticker, #find_sticker, #get_sticker, #list_stickers, #set_sticker

Methods included from Plugins::Database

#albums, #artists, #count, #directories, #files, #list, #rescan, #search, #songs, #songs_by_artist, #update

Methods included from Plugins::Playlists

#playlists

Methods included from Plugins::Queue

#add, #addid, #clear, #delete, #move, #queue, #queue_changes, #queue_search, #save, #shuffle, #song_priority, #song_with_id, #swap, #swapid

Methods included from Plugins::Controls

#next, #pause=, #play, #previous, #seek, #stop

Methods included from Plugins::PlaybackOptions

#consume=, #crossfade=, #mixrampdb=, #mixrampdelay=, #random=, #repeat=, #replay_gain_mode=, #replay_gain_status, #single=, #volume=

Methods included from Plugins::Information

#clearerror, #consume?, #crossfade, #current_song, #paused?, #playing?, #playlist_version, #random?, #repeat?, #single?, #stats, #status, #stopped?, #volume

Constructor Details

#initialize(hostname = 'localhost', port = 6600, opts = {}) ⇒ MPD

Initialize an MPD object with the specified hostname and port. When called without arguments, ‘localhost’ and 6600 are used.

When called with callbacks: true as an optional argument, callbacks will be enabled by starting a separate polling thread.

Parameters:

  • hostname (String) (defaults to: 'localhost') —

    Hostname of the daemon

  • port (Integer) (defaults to: 6600) —

    Port of the daemon

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

    Optional parameters. Currently accepts callbacks



54
55
56
57
58
59
60
61
62
 
# File 'lib/ruby-mpd.rb', line 54

def initialize(hostname = 'localhost', port = 6600, opts = {})
  @hostname = hostname
  @port = port
  @options = {callbacks: false}.merge(opts)
  reset_vars

  @mutex = Mutex.new
  @callbacks = {}
end

Instance Attribute Details

#version ⇒ Object (readonly)

The version of the MPD protocol the server is using.



43
44
45
 
# File 'lib/ruby-mpd.rb', line 43

def version
  @version
end

Instance Method Details

#connect(callbacks = nil) ⇒ true

Connect to the daemon.

When called without any arguments, this will just connect to the server and wait for your commands.

Returns:

  • (true) —

    Successfully connected.

Raises:

  • (MPDError) —

    If connect is called on an already connected instance.



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/ruby-mpd.rb', line 147

def connect(callbacks = nil)
  raise ConnectionError, 'Already connected!' if self.connected?

  @socket = File.exists?(@hostname) ? UNIXSocket.new(@hostname) : TCPSocket.new(@hostname, @port)

  # by protocol, we need to get a 'OK MPD <version>' reply
  # should we fail to do so, the connection was unsuccessful
  if response = @socket.gets
    @version = response.chomp.gsub('OK MPD ', '') # Read the version
  else
    reset_vars
    raise ConnectionError, 'Unable to connect (possibly too many connections open)'
  end

  if callbacks
    warn "Using 'true' or 'false' as an argument to MPD#connect has been deprecated, and will be removed in the future!"
    @options.merge!(callbacks: callbacks)
  end

  callback_thread if @options[:callbacks]
  return true
end

#connected? ⇒ Boolean

Check if the client is connected.

Returns:

  • (Boolean) —

    True only if the server responds otherwise false.



173
174
175
176
177
178
 
# File 'lib/ruby-mpd.rb', line 173

def connected?
  return false if !@socket

  ret = send_command(:ping) rescue false
  return ret
end

#disconnect ⇒ Boolean

Disconnect from the MPD daemon. This has no effect if the client is not connected. Reconnect using the #connect method. This will also stop the callback thread, thus disabling callbacks.

Returns:

  • (Boolean) —

    True if successfully disconnected, false otherwise.



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/ruby-mpd.rb', line 184

def disconnect
  @cb_thread[:stop] = true if @cb_thread

  return false if !@socket

  begin
    @socket.puts 'close'
    @socket.close
  rescue Errno::EPIPE
    # socket was forcefully closed
  end

  reset_vars
  return true
end

#emit(event, *args) ⇒ void

This method returns an undefined value.

Triggers an event, running it’s callbacks.

Parameters:

  • event (Symbol) —

    The event that happened.



96
97
98
99
100
101
 
# File 'lib/ruby-mpd.rb', line 96

def emit(event, *args)
  return unless @callbacks[event]
  @callbacks[event].each do |handle|
    handle.call *args
  end
end

#kill ⇒ Boolean

Kills the MPD process.

Returns:

  • (Boolean) —

    returns true if successful.

Raises:

  • (MPDError) —

    if the command failed.



209
210
211
 
# File 'lib/ruby-mpd.rb', line 209

def kill
  send_command :kill
end

#on(event, &block) ⇒ void

This method returns an undefined value.

This will register a block callback that will trigger whenever that specific event happens.

mpd.on :volume do |volume|
  puts "Volume was set to #{volume}!"
end

One can also define separate methods or Procs and whatnot, just pass them in as a parameter.

method = Proc.new {|volume| puts "Volume was set to #{volume}!" }
mpd.on :volume, &method

Parameters:

  • event (Symbol) —

    The event we wish to listen for.

  • block (Proc, Method) —

    The actual callback.



88
89
90
91
 
# File 'lib/ruby-mpd.rb', line 88

def on(event, &block)
  @callbacks[event] ||= []
  @callbacks[event].push block
end

#password(pass) ⇒ Boolean

Used for authentication with the server.

Parameters:

  • pass (String) —

    Plaintext password

Returns:

  • (Boolean) —

    returns true if successful.

Raises:

  • (MPDError) —

    if the command failed.



216
217
218
 
# File 'lib/ruby-mpd.rb', line 216

def password(pass)
  send_command :password, pass
end

#ping ⇒ Boolean

Ping the server.

Returns:

  • (Boolean) —

    returns true if successful.

Raises:

  • (MPDError) —

    if the command failed.



222
223
224
 
# File 'lib/ruby-mpd.rb', line 222

def ping
  send_command :ping
end

#reconnect ⇒ Boolean

Attempts to reconnect to the MPD daemon.

Returns:

  • (Boolean) —

    True if successfully reconnected, false otherwise.



202
203
204
205
 
# File 'lib/ruby-mpd.rb', line 202

def reconnect
  disconnect
  connect
end

#send_command(command, *args) ⇒ true, ...

Used to send a command to the server, and to recieve the reply. Reply gets parsed. Synchronized on a mutex to be thread safe.

Can be used to get low level direct access to MPD daemon. Not recommended, should be just left for internal use by other methods.

Returns:

  • (true) —

    If “OK” is returned.

  • (Array<Hash>, Array<String>, String, Integer) —

    Parsed response.

Raises:

  • (MPDError) —

    if the command failed.



235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/ruby-mpd.rb', line 235

def send_command(command, *args)
  raise ConnectionError, "Not connected to the server!" if !@socket

  @mutex.synchronize do
    begin
      @socket.puts convert_command(command, *args)
      response = handle_server_response
      return parse_response(command, response)
    rescue Errno::EPIPE
      reconnect
      retry
    end
  end
end