Portability	Haskell 98
Stability	alpha
Maintainer	bsinclai@turing.une.edu.au

Network.MPD

Contents

Basic data types
Connections
Command related data types
Admin commands
Database commands
Playlist commands
Playback commands
Miscellaneous commands
Extensions/shortcuts

Description

An MPD client library. MPD is a daemon for playing music that is controlled over a network socket. Its site is at http://www.musicpd.org/.

To avoid name clashes with the standard Prelude functions, do:

 import qualified Network.MPD as MPD

Synopsis

Basic data types

data MPD a Source

The MPD monad is basically a reader and error monad combined.

To use the error throwing/catching capabilities:

 import Control.Monad.Error

To run IO actions within the MPD monad:

 import Control.Monad.Trans

Instances

Monad MPD
Functor MPD
MonadIO MPD
MonadError MPDError MPD

data MPDError Source

The MPDError type is used to signal errors, both from the MPD and otherwise.

Constructors

NoMPD	MPD not responding
TimedOut	The connection timed out
Unexpected String	MPD returned an unexpected response. This is a bug, either in the library or in MPD itself.
Custom String	Used for misc. errors
ACK ACKType String	ACK type and a message from the server

Instances

Eq MPDError
Show MPDError
Error MPDError
MonadError MPDError MPD

data ACKType Source

Represents various MPD errors (aka. ACKs).

Constructors

InvalidArgument	Invalid argument passed (ACK 2)
InvalidPassword	Invalid password supplied (ACK 3)
Auth	Authentication required (ACK 4)
UnknownCommand	Unknown command (ACK 5)
FileNotFound	File or directory not found ACK 50)
PlaylistMax	Playlist at maximum size (ACK 51)
System	A system error (ACK 52)
PlaylistLoad	Playlist loading failed (ACK 53)
Busy	Update already running (ACK 54)
NotPlaying	An operation requiring playback got interrupted (ACK 55)
FileExists	File already exists (ACK 56)
UnknownACK	An unknown ACK (aka. bug)

Instances

Eq ACKType

type Response a = Either MPDError aSource

A response is either an MPDError or some result.

Connections

withMPD :: MPD a -> IO (Response a)Source

A wrapper for withMPDEx that uses localhost:6600 as the default host:port, or whatever is found in the environment variables MPD_HOST and MPD_PORT. If MPD_HOST is of the form "password@host" the password will be supplied as well.

Examples:

 withMPD $ play Nothing
 withMPD $ add_ "" "tool" >> play Nothing >> currentSong

withMPDEx Source

Arguments

:: String	Host name.
-> Integer	Port number.
-> IO (Maybe String)	An action that supplies passwords.
-> MPD a	The action to run.
-> IO (Response a)

Run an MPD action against a server.

Command related data types

type Artist = String Source

type Album = String Source

type Title = String Source

type PlaylistName = String Source

Used for commands which require a playlist name. If empty, the current playlist is used.

type Path = String Source

Used for commands which require a path within the database. If empty, the root path is used.

data Meta Source

Available metadata types/scope modifiers, used for searching the database for entries with certain metadata values.

Constructors

Artist
Album
Title
Track
Name
Genre
Date
Composer
Performer
Disc
Any
Filename

Instances

Show Meta
MPDArg Meta

data Match Source

When searching for specific items in a collection of songs, we need a reliable way to build predicates. Match is one way of achieving this. Each Match is a clause, and by putting matches together in lists, we can compose queries.

For example, to match any song where the value of artist is "Foo", we use:

 Match Artist "Foo"

In composite matches (queries), all clauses must be satisfied, which means that each additional clause narrows the search. For example, to match any song where the value of artist is "Foo" AND the value of album is "Bar", we use:

 [Match Artist "Foo", Match Album "Bar"]

By adding additional clauses we can narrow the search even more, but this is usually not necessary.

Constructors

Match Meta String

Instances

Show Match

type Query = [Match]Source

A query comprises a list of Match predicates

type Seconds = Integer Source

data PLIndex Source

Represents a song's playlist index.

Constructors

Pos Integer	A playlist position index (starting from 0)
ID Integer	A playlist ID number that more robustly identifies a song.

Instances

Eq PLIndex
Show PLIndex

data State Source

Represents the different playback states.

Constructors

Playing
Stopped
Paused

Instances

Eq State
Show State

data Count Source

Represents the result of running count.

Constructors

Count
Fields cSongs :: Integer Number of songs matching the query cPlaytime :: Seconds Total play time of matching songs

Instances

Eq Count
Show Count

data Device Source

Represents an output device.

Constructors

Device
Fields dOutputID :: Int Output's ID number dOutputName :: String Output's name as defined in the MPD configuration file dOutputEnabled :: Bool

Instances

Eq Device
Show Device

data Stats Source

Container for database statistics.

Constructors

Stats
Fields stsArtists :: Integer Number of artists. stsAlbums :: Integer Number of albums. stsSongs :: Integer Number of songs. stsUptime :: Seconds Daemon uptime in seconds. stsPlaytime :: Seconds Total playing time. stsDbPlaytime :: Seconds Total play time of all the songs in the database. stsDbUpdate :: Integer Last database update in UNIX time.

Instances

Eq Stats
Show Stats

data Song Source

Represents a single song item.

Constructors

Song
Fields sgArtist :: String sgAlbum :: String sgTitle :: String sgFilePath :: String sgGenre :: String sgName :: String sgComposer :: String sgPerformer :: String sgLength :: Seconds Length in seconds sgDate :: Int Year sgTrack :: (Int, Int) Track number/total tracks sgDisc :: (Int, Int) Position in set/total in set sgIndex :: Maybe PLIndex

Instances

Eq Song
Show Song

data Status Source

Container for MPD status.

Constructors

Status

Fields

stState :: State
stVolume :: Int: A percentage (0-100)
stRepeat :: Bool
stRandom :: Bool
stPlaylistVersion :: Integer: A value that is incremented by the server every time the playlist changes.
stPlaylistLength :: Integer: The number of items in the current playlist.
stSongPos :: Maybe PLIndex: Current song's position in the playlist.
stSongID :: Maybe PLIndex: Current song's playlist ID.
stTime :: (Seconds, Seconds): Time elapsed/total time.
stBitrate :: Int: Bitrate (in kilobytes per second) of playing song (if any).
stXFadeWidth :: Seconds: Crossfade time.
stAudio :: (Int, Int, Int): Samplerate/bits/channels for the chosen output device (see mpd.conf).
stUpdatingDb :: Integer: Job ID of currently running update (if any).
stError :: String: Last error message (if any).

Instances

Eq Status
Show Status

Admin commands

disableOutput :: Int -> MPD ()Source

Turn off an output device.

enableOutput :: Int -> MPD ()Source

Turn on an output device.

kill :: MPD ()Source

Kill the server. Obviously, the connection is then invalid.

outputs :: MPD [Device]Source

Retrieve information for all output devices.

update :: [Path] -> MPD ()Source

Update the server's database. If no paths are given, all paths will be scanned. Unreadable or non-existent paths are silently ignored.

Database commands

find :: Query -> MPD [Song]Source

Search the database for entries exactly matching a query.

list Source

Arguments

:: Meta	Metadata to list
-> Query
-> MPD [String]

List all metadata of metadata (sic).

listAll :: Path -> MPD [Path]Source

List the songs (without metadata) in a database directory recursively.

listAllInfo :: Path -> MPD [Either Path Song]Source

Recursive lsInfo.

lsInfo :: Path -> MPD [Either Path Song]Source

Non-recursively list the contents of a database directory.

search :: Query -> MPD [Song]Source

Search the database using case insensitive matching.

count :: Query -> MPD Count Source

Count the number of entries matching a query.

Playlist commands

Unless otherwise noted all playlist commands operate on the current playlist.

add :: PlaylistName -> Path -> MPD [Path]Source

Like add_ but returns a list of the files added.

add_ :: PlaylistName -> Path -> MPD ()Source

Add a song (or a whole directory) to a playlist. Adds to current if no playlist is specified. Will create a new playlist if the one specified does not already exist.

addId :: Path -> MPD Integer Source

Like add, but returns a playlist id.

clear :: PlaylistName -> MPD ()Source

Clear a playlist. Clears current playlist if no playlist is specified. If the specified playlist does not exist, it will be created.

currentSong :: MPD (Maybe Song)Source

Get the currently playing song.

delete :: PlaylistName -> PLIndex -> MPD ()Source

Remove a song from a playlist. If no playlist is specified, current playlist is used. Note that a playlist position (Pos) is required when operating on playlists other than the current.

load :: PlaylistName -> MPD ()Source

Load an existing playlist.

move :: PlaylistName -> PLIndex -> Integer -> MPD ()Source

Move a song to a given position. Note that a playlist position (Pos) is required when operating on playlists other than the current.

playlistInfo :: Maybe PLIndex -> MPD [Song]Source

Retrieve metadata for songs in the current playlist.

listPlaylist :: PlaylistName -> MPD [Path]Source

Retrieve a list of files in a given playlist.

listPlaylistInfo :: PlaylistName -> MPD [Song]Source

Retrieve metadata for files in a given playlist.

playlist :: MPD [(PLIndex, Path)]Source

Retrieve file paths and positions of songs in the current playlist. Note that this command is only included for completeness sake; it's deprecated and likely to disappear at any time, please use playlistInfo instead.

plChanges :: Integer -> MPD [Song]Source

Retrieve a list of changed songs currently in the playlist since a given playlist version.

plChangesPosId :: Integer -> MPD [(PLIndex, PLIndex)]Source

Like plChanges but only returns positions and ids.

playlistFind :: Query -> MPD [Song]Source

Search for songs in the current playlist with strict matching.

playlistSearch :: Query -> MPD [Song]Source

Search case-insensitively with partial matches for songs in the current playlist.

rm :: PlaylistName -> MPD ()Source

Delete existing playlist.

rename Source

Arguments

:: PlaylistName	Original playlist
-> PlaylistName	New playlist name
-> MPD ()

Rename an existing playlist.

save :: PlaylistName -> MPD ()Source

Save the current playlist.

shuffle :: MPD ()Source

Shuffle the playlist.

swap :: PLIndex -> PLIndex -> MPD ()Source

Swap the positions of two songs. Note that the positions must be of the same type, i.e. mixing Pos and ID will result in a no-op.

Playback commands

crossfade :: Seconds -> MPD ()Source

Set crossfading between songs.

next :: MPD ()Source

Play the next song.

pause :: Bool -> MPD ()Source

Pause playing.

play :: Maybe PLIndex -> MPD ()Source

Begin/continue playing.

previous :: MPD ()Source

Play the previous song.

random :: Bool -> MPD ()Source

Set random playing.

repeat :: Bool -> MPD ()Source

Set repeating.

seek :: Maybe PLIndex -> Seconds -> MPD ()Source

Seek to some point in a song. Seeks in current song if no position is given.

setVolume :: Int -> MPD ()Source

Set the volume (0-100 percent).

volume :: Int -> MPD ()Source

Increase or decrease volume by a given percent, e.g. 'volume 10' will increase the volume by 10 percent, while 'volume (-10)' will decrease it by the same amount. Note that this command is only included for completeness sake ; it's deprecated and may disappear at any time, please use setVolume instead.

stop :: MPD ()Source

Stop playing.

Miscellaneous commands

clearError :: MPD ()Source

Clear the current error message in status.

close :: MPD ()Source

Close an MPD connection.

commands :: MPD [String]Source

Retrieve a list of available commands.

notCommands :: MPD [String]Source

Retrieve a list of unavailable (due to access restrictions) commands.

password :: String -> MPD ()Source

Send password to server to authenticate session. Password is sent as plain text.

ping :: MPD ()Source

Check that the server is still responding.

reconnect :: MPD ()Source

Refresh a connection.

stats :: MPD Stats Source

Get server statistics.

status :: MPD Status Source

Get the server's status.

tagTypes :: MPD [String]Source

Retrieve a list of available song metadata.

urlHandlers :: MPD [String]Source

Retrieve a list of supported urlhandlers.

Extensions/shortcuts

addMany :: PlaylistName -> [Path] -> MPD ()Source

Add a list of songs/folders to a playlist. Should be more efficient than running add many times.

deleteMany :: PlaylistName -> [PLIndex] -> MPD ()Source

Delete a list of songs from a playlist. If there is a duplicate then no further songs will be deleted, so take care to avoid them (see prune for this).

complete :: String -> MPD [Either Path Song]Source

Returns all songs and directories that match the given partial path name.

crop :: Maybe PLIndex -> Maybe PLIndex -> MPD ()Source

Crop playlist. The bounds are inclusive. If Nothing or ID is passed the cropping will leave your playlist alone on that side.

prune :: MPD ()Source

Remove duplicate playlist entries.

lsDirs :: Path -> MPD [Path]Source

List directories non-recursively.

lsFiles :: Path -> MPD [Path]Source

List files non-recursively.

lsPlaylists :: MPD [PlaylistName]Source

List all playlists.