libmpd-0.5.0: An MPD client library.

Stabilityalpha
MaintainerJoachim Fasting <joachim.fasting@gmail.com>

Network.MPD

Contents

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

class (Monad m, MonadError MPDError m) => MonadMPD m where

A typeclass to allow for multiple implementations of a connection to an MPD server.

Methods

close :: m ()

Close the connection.

Instances

data MPD a

The main implementation of an MPD client. It actually connects to a server and interacts with it.

To use the error throwing/catching capabilities:

 import Control.Monad.Error (throwError, catchError)

To run IO actions within the MPD monad:

 import Control.Monad.Trans (liftIO)

Instances

Monad MPD 
Functor MPD 
Applicative MPD 
MonadIO MPD 
MonadMPD MPD 
MonadError MPDError MPD 

data MPDError

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

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 = Either MPDError

A response is either an MPDError or some result.

type Host = String

type Port = Integer

type Password = String

Connections

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

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 :: Host -> Port -> Password -> MPD a -> IO (Response a)

The most configurable API for running an MPD action.

Command related data types

type Artist = String

type Album = String

type Title = String

type PlaylistName = String

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

type Path = String

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

data Metadata

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

Instances

Eq Metadata 
Ord Metadata 
Show Metadata 
MPDArg Metadata 

data ObjectType

Object types.

Constructors

SongObj 

Instances

Eq ObjectType 
Show ObjectType 
MPDArg ObjectType 

type Seconds = Integer

data State

Represents the different playback states.

Constructors

Playing 
Stopped 
Paused 

Instances

Eq State 
Show State 

data Subsystem

Represents the various MPD subsystems.

Constructors

DatabaseS

The song database

UpdateS

Database updates

StoredPlaylistS

Stored playlists

PlaylistS

The current playlist

PlayerS

The player

MixerS

The volume mixer

OutputS

Audio outputs

OptionsS

Playback options

Instances

Eq Subsystem 
Show Subsystem 
MPDArg Subsystem 

data ReplayGainMode

Constructors

Off

Disable replay gain

TrackMode

Per track mode

AlbumMode

Per album mode

Instances

data Count

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 Output

Represents an output device.

Constructors

Output 

Fields

outID :: Int

Output's ID number

outName :: String

Output's name as defined in the MPD configuration file

outEnabled :: Bool
 

Instances

Eq Output 
Show Output 

data Song

Represents a single song item.

Constructors

Song 

Fields

sgFilePath :: String
 
sgTags :: Map Metadata [String]

Map of available tags (multiple occurences of one tag type allowed)

sgLastModified :: Maybe UTCTime

Last modification date

sgLength :: Seconds

Length of the song in seconds

sgIndex :: Maybe (Int, Int)

Position/ID in playlist

Instances

Eq Song 
Show Song 

sgGet :: Metadata -> Song -> Maybe [String]

Get list of specific tag type

data Playlist

Represents a single playlist item.

Constructors

Playlist 

Fields

plName :: String
 
plLastModified :: Maybe UTCTime
 

Instances

Eq Playlist 
Show Playlist 

data Entry

Represents a single item in database.

Constructors

SongE Song 
PlaylistE Playlist 
DirectoryE String 

Instances

Eq Entry 
Show Entry 

data Stats

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 Status

Container for MPD status.

Constructors

Status 

Fields

stState :: State
 
stVolume :: Int

A percentage (0-100)

stRepeat :: Bool
 
stRandom :: Bool
 
stPlaylistID :: 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 Int

Current song's position in the playlist.

stSongID :: Maybe Int

Current song's playlist ID.

stNextSongPos :: Maybe Int

Next song's position in the playlist.

stNextSongID :: Maybe Int

Next song's playlist ID.

stTime :: (Double, Seconds)

Time elapsed/total time.

stBitrate :: Int

Bitrate (in kilobytes per second) of playing song (if any).

stXFadeWidth :: Seconds

Crossfade time.

stMixRampdB :: Double

MixRamp threshold in dB

stMixRampDelay :: Double

MixRamp extra delay in seconds

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).

stSingle :: Bool

If True, MPD will play only one song and stop after finishing it.

stConsume :: Bool

If True, a song will be removed after it has been played.

stError :: Maybe String

Last error message (if any).

Instances

Eq Status 
Show Status 

Query interface

data Query

An interface for creating MPD queries.

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

 Artist =? "Foo"

We can also compose queries, thus narrowing the search. For example, to match any song where the value of artist is "Foo" and the value of album is "Bar", we use:

 Artist =? "Foo" <&> Album =? "Bar"

Instances

Show Query 
Monoid Query 
MPDArg Query 

(=?) :: Metadata -> String -> Query

Create a query.

(<&>) :: Query -> Query -> Query

Combine queries.

anything :: Query

An empty query. Matches anything.

Querying MPD's status

clearError :: MonadMPD m => m ()

Clear the current error message in status.

currentSong :: MonadMPD m => m (Maybe Song)

Get the current song.

idle :: MonadMPD m => [Subsystem] -> m ()

Make MPD server notify the client if there is a noteworthy change in one or more of its subsystems. Note that after running this command you can either monitor handle for incoming notifications or cancel this by noidle. Any command other than noidle sent to MPD server while idle is active will be ignored.

getIdle :: MonadMPD m => m [Subsystem]

Get idle notifications. If there is no notifications ready at the moment, this function will block until they show up.

noidle :: MonadMPD m => m ()

Cancel idle.

status :: MonadMPD m => m Status

Get the server's status.

stats :: MonadMPD m => m Stats

Get server statistics.

Playback options

consume :: MonadMPD m => Bool -> m ()

Set consume mode

crossfade :: MonadMPD m => Seconds -> m ()

Set crossfading between songs.

random :: MonadMPD m => Bool -> m ()

Set random playing.

repeat :: MonadMPD m => Bool -> m ()

Set repeating.

setVolume :: MonadMPD m => Int -> m ()

Set the volume (0-100 percent).

single :: MonadMPD m => Bool -> m ()

Set single mode

replayGainMode :: MonadMPD m => ReplayGainMode -> m ()

Set the replay gain mode.

replayGainStatus :: MonadMPD m => m [String]

Get the replay gain options.

Controlling playback

next :: MonadMPD m => m ()

Play the next song.

pause :: MonadMPD m => Bool -> m ()

Pause playing.

play :: MonadMPD m => Maybe Int -> m ()

Begin/continue playing.

playId :: MonadMPD m => Int -> m ()

Play a file with given id.

previous :: MonadMPD m => m ()

Play the previous song.

seek :: MonadMPD m => Int -> Seconds -> m ()

Seek to some point in a song.

seekId :: MonadMPD m => Int -> Seconds -> m ()

Seek to some point in a song (id version)

stop :: MonadMPD m => m ()

Stop playing.

The current playlist

add :: MonadMPD m => Path -> m [Path]

Like add_ but returns a list of the files added.

add_ :: MonadMPD m => Path -> m ()

Add a song (or a whole directory) to the current playlist.

addId

Arguments

:: MonadMPD m 
=> Path 
-> Maybe Integer

Optional playlist position

-> m Int 

Like add, but returns a playlist id.

clear :: MonadMPD m => m ()

Clear the current playlist.

delete :: MonadMPD m => Int -> m ()

Remove a song from the current playlist.

deleteId :: MonadMPD m => Int -> m ()

Remove a song from the current playlist.

move :: MonadMPD m => Int -> Int -> m ()

Move a song to a given position in the current playlist.

moveId :: MonadMPD m => Int -> Int -> m ()

Move a song from (songid) to (playlist index) in the playlist. If to is negative, it is relative to the current song in the playlist (if there is one).

playlist :: MonadMPD m => m [(Int, Path)]

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.

playlistId :: MonadMPD m => Maybe Int -> m [Song]

Displays a list of songs in the playlist. If id is specified, only its info is returned.

playlistFind :: MonadMPD m => Query -> m [Song]

Search for songs in the current playlist with strict matching.

playlistInfo :: MonadMPD m => Maybe (Int, Int) -> m [Song]

Retrieve metadata for songs in the current playlist.

playlistSearch :: MonadMPD m => Query -> m [Song]

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

plChanges :: MonadMPD m => Integer -> m [Song]

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

plChangesPosId :: MonadMPD m => Integer -> m [(Int, Int)]

Like plChanges but only returns positions and ids.

shuffle

Arguments

:: MonadMPD m 
=> Maybe (Int, Int)

Optional range (start, end)

-> m () 

Shuffle the playlist.

swap :: MonadMPD m => Int -> Int -> m ()

Swap the positions of two songs.

swapId :: MonadMPD m => Int -> Int -> m ()

Swap the positions of two songs (Id version

Stored playlist

listPlaylist :: MonadMPD m => PlaylistName -> m [Path]

Retrieve a list of files in a given playlist.

listPlaylistInfo :: MonadMPD m => PlaylistName -> m [Song]

Retrieve metadata for files in a given playlist.

listPlaylists :: MonadMPD m => m [PlaylistName]

Retreive a list of stored playlists.

load :: MonadMPD m => PlaylistName -> m ()

Load an existing playlist.

playlistAdd :: MonadMPD m => PlaylistName -> Path -> m [Path]

Like playlistAdd but returns a list of the files added.

playlistAdd_ :: MonadMPD m => PlaylistName -> Path -> m ()

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

playlistClear :: MonadMPD m => PlaylistName -> m ()

Clear a playlist. If the specified playlist does not exist, it will be created.

playlistDelete

Arguments

:: MonadMPD m 
=> PlaylistName 
-> Integer

Playlist position

-> m () 

Remove a song from a playlist.

playlistMove :: MonadMPD m => PlaylistName -> Integer -> Integer -> m ()

Move a song to a given position in the playlist specified.

rename

Arguments

:: MonadMPD m 
=> PlaylistName

Original playlist

-> PlaylistName

New playlist name

-> m () 

Rename an existing playlist.

rm :: MonadMPD m => PlaylistName -> m ()

Delete existing playlist.

save :: MonadMPD m => PlaylistName -> m ()

Save the current playlist.

The music database

count :: MonadMPD m => Query -> m Count

Count the number of entries matching a query.

find :: MonadMPD m => Query -> m [Song]

Search the database for entries exactly matching a query.

findAdd :: MonadMPD m => Query -> m ()

Adds songs matching a query to the current playlist.

list

Arguments

:: MonadMPD m 
=> Metadata

Metadata to list

-> Query 
-> m [String] 

List all metadata of metadata (sic).

listAll :: MonadMPD m => Path -> m [Path]

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

listAllInfo :: MonadMPD m => Path -> m [Song]

Recursive lsInfo.

lsInfo :: MonadMPD m => Path -> m [Entry]

Non-recursively list the contents of a database directory.

search :: MonadMPD m => Query -> m [Song]

Search the database using case insensitive matching.

update :: MonadMPD m => [Path] -> m ()

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

rescan :: MonadMPD m => [Path] -> m ()

Like update but also rescans unmodified files.

Stickers

stickerGet

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Object URI

-> String

Sticker name

-> m [String] 

Reads a sticker value for the specified object.

stickerSet

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Object URI

-> String

Sticker name

-> String

Sticker value

-> m () 

Adds a sticker value to the specified object.

stickerDelete

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Object URI

-> String

Sticker name

-> m () 

Delete a sticker value from the specified object.

stickerList

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Object URI

-> m [(String, String)]

Sticker name/sticker value

Lists the stickers for the specified object.

stickerFind

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Path

-> String

Sticker name

-> m [(String, String)]

URI/sticker value

Searches the sticker database for stickers with the specified name, below the specified path.

Connection

close :: MonadMPD m => m ()

Close the connection.

kill :: MonadMPD m => m ()

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

password :: MonadMPD m => String -> m ()

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

ping :: MonadMPD m => m ()

Check that the server is still responding.

Audio output devices

disableOutput :: MonadMPD m => Int -> m ()

Turn off an output device.

enableOutput :: MonadMPD m => Int -> m ()

Turn on an output device.

outputs :: MonadMPD m => m [Output]

Retrieve information for all output devices.

Reflection

commands :: MonadMPD m => m [String]

Retrieve a list of available commands.

notCommands :: MonadMPD m => m [String]

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

tagTypes :: MonadMPD m => m [String]

Retrieve a list of available song metadata.

urlHandlers :: MonadMPD m => m [String]

Retrieve a list of supported urlhandlers.

decoders :: MonadMPD m => m [(String, [(String, String)])]

Retreive a list of decoder plugins with associated suffix and mime types.