Paracusia

Paracusia is an MPD client library for Elixir.

Installation

Add paracusia to your list of dependencies in mix.exs:

def deps do
  [{:paracusia, "~> 0.2.11"}]
end

If MPD runs on localhost and the standard port 6600 without password authorization, no further configuration is required. Otherwise, the environment variables MPD_HOST and MPD_PORT can be set. Just like with the command line application mpc, a password may be provided by setting MPD_HOST to "password@host". Alternatively, users may set the application variables hostname, password and port in the configuration file:

config :paracusia,
  hostname: "192.168.1.5",
  password: "topsecret",
  port: 6696,
  retry_after: 100,
  max_retry_attempts: 3

The hostname may refer to an IPv4 address, an IPv6 address, a domain, or a file in case MPD is accessible by a Unix domain socket. Omit the password if no password authorization is required. Application variables take precedence over environment variables, i.e., environment variables are used as fallback in case no application variables are specified. If at least one application variable is defined, no environment variables will be used. Once the MPD credentials are configured, you may continue to start your application and control MPD.

Usage

To play the first song in the current playlist:

:ok = Paracusia.MpdClient.Playback.play_pos(0)

To obtain all files and directories in MPD's root directory:

{:ok, uris} = Paracusia.MpdClient.Database.lsinfo("")

Note that all functions of all submodules of Paracusia.MpdClient always return :ok or {:ok, result} if everything went well, or {:error, {errorcode, description}} otherwise. For instance, if we choose a number that is larger than our current playlist and try to play it, MPD refuses to do so and instead warns us that the song index is invalid:

Paracusia.MpdClient.Playback.play_pos(999)
{:error, {"2@0", "error 2@0 while executing command play: Bad song index"}}

Paracusia maintains a list of subscribers which receive a message whenever the current state of MPD changes. Use the Paracusia.PlayerState.subscribe/1 function to become a subscriber, for instance:

iex(1)> Paracusia.PlayerState.subscribe(self())
:ok
iex(2)> Paracusia.MpdClient.Playback.pause(true) # to receive some messages
iex(3)> flush()
{:paracusia,
 {:mixer_changed,
  %Paracusia.PlayerState{…}
 }
}

Check out Paracusia.DefaultEventHandler to get an overview of what messages are sent for what reasons. In general, Paracusia sends a message whenever one of MPD's subsystems has changed. See the idle command for more details on which changes are associated with which subsystems.

API

See the documentation for more details.

Bugs and General Feedback

Please open an issue in case you find any bugs, have any questions or want to suggest improvements.