mpd v0.1.0 Mpd.Handler View Source

The Mpd.Handle is the module responsible for executing commands with the mpd server. It wraps protocol's TCP command to prevent unsupported calls to the server.

Configuration

By default, the Handler uses the following configuration:

  • hostname: binary(): "localhost"; refers to server hostname
  • port: integer(): 6600; refers to server port

You can override those by calling doing the following:

iex> Application.put_env(:mpd, :hostname, "http://someserver.com")

Or using Config

config :mpd, :hostname, "http://someserver.com"

Usage

There are 3 main ways to call commands using the Handler.

  • call/1: Executes the command and return the outputs. It returns nil for side-effect calls such at :play
  • cast/1: Executes the command in an asynchronous Task.
  • call_idle/1: Executes the idle command and sends events to a given process.

Idles

While most commands mutates the player states or returns information, idles are use to listen on the mpd server.

For instance, the :player idle will listen on player event. Running cast_idle(:player, self()) would send any player event to the current process.

Link to this section Summary

Functions

Calls a command through TCP to the MPD server using gen_tcp. Most commands doesn't return anywthing and therefore will return {:ok, nil}.

Calls idle commmand and connect the socket port to a process where it'll sends incoming events.

Calls idle like call_idle/1 but only for given idles. See MPD's protocol definition for idles list and detail.

Calls a command inside an asynchronous task

Link to this section Types

Specs

command() ::
  :currentsong
  | :listall
  | :next
  | :pause
  | :play
  | :previous
  | :stats
  | :status
  | :toggle
  | {:add
     | :consume
     | :crossfade
     | :listallinfo
     | :random
     | :repeat
     | :replay_gain_mode
     | :setvol, any()}

Specs

command_result() :: {:ok, any()} | {:error, any()}

Specs

idles() ::
  :database
  | :message
  | :mixer
  | :options
  | :output
  | :partition
  | :player
  | :playlist
  | :sticker
  | :stored_playlist
  | :subscription
  | :update

Specs

replay_modes() :: :off | :track | :album | :auto

Link to this section Functions

Specs

call(command()) :: command_result()

Calls a command through TCP to the MPD server using gen_tcp. Most commands doesn't return anywthing and therefore will return {:ok, nil}.

Commands that has output returns structs reprenting the output, like :currentsong.

Available commands

Here is a complete list of supported commands and there expected output.

Commands name should represent protocol's commands, see https://www.musicpd.org/doc/html/protocol.html

  • :next: Returns nil, plays the next song in queue
  • :pause: Returns nil, put the player on pause
  • :play: Returns nil, put the player on play
  • :previous: Returns nil, plays the previous song in queue
  • :toggle: Returns nil, plays the player if paused, otherwise pauses it.
  • {:add, uri}: Returns nil, adds song with uri to the queue. URI's refers to song's file attribute.
  • {:consume, boolean()}: Returns nil, sets consume to either true or false.
  • {:crossfade, integer()}: Returns nil, sets crossfade to given integer value as seconds.
  • {:random, boolean()}: Returns nil, sets random mode to either true or false.
  • {:repeat, boolean()}: Returns nil, sets repeat mode to either true or false.
  • {:setvol, integer()}: Returns nil, sets volume to give integer value.
  • {:replay_gain_mode, replay_modes()}: Returns nil, sets given replay mode.
  • :currentsong: Returns Mpd.Song.t() with the tags and filename of the current playing song.
  • :listall: Returns map(binary() => Mpd.Song.t()), key is the filename and value is a song struct with tags.
  • :stats: Returns Mpd.Stats.t() representing server stats
  • :status: Returns Mpd.Status.t() representing the actual player state
  • {:listallinfo, uri}: Returns Mpd.Song.t() with given song's uri information.

Calls idle commmand and connect the socket port to a process where it'll sends incoming events.

For more information about idle commands see MPD's protocol definition

Examples

iex> Mpd.Handler.call_idle(self())
#Port<0.563>

iex> flush()
{:tcp, #Port<0.563>, 'OK MPD 0.20.0
'}
{:tcp, #Port<0.563>, 'changed: player
OK
'} # when the player is paused, for instance
:ok

Specs

call_idle(idles() | [idles()], pid()) :: port()

Calls idle like call_idle/1 but only for given idles. See MPD's protocol definition for idles list and detail.

Examples

iex> Mpd.Handler.call_idle(:options, self())
#Port<0.563>

iex> flush()
{:tcp, #Port<0.563>, 'OK MPD 0.20.0
'}
:ok

Previous call would not receive events when the player gets updated as it only listens for options idle.

Specs

cast(command()) :: Task.t()

Calls a command inside an asynchronous task

See call/1 for more details

Examples

iex> Mpd.Handler.cast(:play)
%Task{}