Stability	alpha
Maintainer	Joachim Fasting <joachim.fasting@gmail.com>
Safe Haskell	None

Network.MPD

Contents

Basic data types
Connections
Command related data types
Query interface
Querying MPD's status
Playback options
Controlling playback
The current playlist
Stored playlist
The music database
Stickers
Connection
Audio output devices
Reflection

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 use the library, do:

 {-# LANGUAGE OverloadedStrings #-}
 import qualified Network.MPD as MPD

Synopsis

Basic data types

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

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

Methods

close :: m ()Source

Close the connection.

Instances

MonadMPD MPD

data MPD a Source

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 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
Typeable MPDError
Exception 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 = Either MPDError Source

A response is either an MPDError or some result.

type Host = String Source

type Port = Integer Source

type Password = String Source

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

withMPD_Source

Arguments

:: Maybe String	optional override for MPD_HOST
-> Maybe String	optional override for MPD_PORT
-> MPD a
-> IO (Response a)

Same as withMPD, but takes optional arguments that override MPD_HOST and MPD_PORT.

This is e.g. useful for clients that optionally take --port and --host as command line arguments, and fall back to withMPD's defaults if those arguments are not given.

withMPDEx :: Host -> Port -> Password -> MPD a -> IO (Response a)Source

The most configurable API for running an MPD action.

Command related data types

class ToString a whereSource

A type class for values that can be converted to Strings.

Methods

toString :: a -> String Source

Convert given value to String.

toText :: a -> Text Source

Convert given value to Text.

toUtf8 :: a -> ByteString Source

Convert given value an UTF-8 encoded ByteString.

Instances

ToString Value
ToString Path
ToString PlaylistName

type Artist = Value Source

type Album = Value Source

type Title = Value Source

newtype PlaylistName Source

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

Constructors

PlaylistName ByteString

Instances

Eq PlaylistName
Show PlaylistName
IsString PlaylistName
MPDArg PlaylistName
ToString PlaylistName

newtype Path Source

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

Constructors

Path ByteString

Instances

Eq Path
Show Path
IsString Path
MPDArg Path
ToString Path

data Metadata Source

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

Constructors

Artist
Album	ArtistSort
Title	AlbumArtist \| AlbumArtistSort
Track
Name
Genre
Date
Composer
Performer
Disc	Comment
MUSICBRAINZ_ARTISTID
MUSICBRAINZ_TRACKID	MUSICBRAINZ_ALBUMID \| MUSICBRAINZ_ALBUMARTISTID

Instances

Bounded Metadata
Enum Metadata
Eq Metadata
Ord Metadata
Show Metadata
MPDArg Metadata

newtype Value Source

A metadata value.

Constructors

Value ByteString

Instances

Eq Value
Show Value
IsString Value
MPDArg Value
ToString Value

data ObjectType Source

Object types.

Constructors

SongObj

Instances

Eq ObjectType
Show ObjectType
MPDArg ObjectType

type Seconds = Integer Source

data State Source

Represents the different playback states.

Constructors

Playing
Stopped
Paused

Instances

Eq State
Show State

data Subsystem Source

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 Source

Constructors

Off	Disable replay gain
TrackMode	Per track mode
AlbumMode	Per album mode

Instances

Eq ReplayGainMode
Show ReplayGainMode
MPDArg ReplayGainMode

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

defaultCount :: Count Source

data LsResult Source

Result of the lsInfo operation

Constructors

LsDirectory Path	Directory
LsSong Song	Song
LsPlaylist PlaylistName	Playlist

Instances

Eq LsResult
Show LsResult

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

defaultDevice :: Device Source

data Song Source

Represents a single song item.

Constructors

Song
Fields sgFilePath :: Path sgTags :: Map Metadata [Value] 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 sgId :: Maybe Id Id in playlist sgIndex :: Maybe Int Position in playlist

Instances

Eq Song
Show Song

newtype Id Source

Constructors

Id Int

Instances

Eq Id
Show Id
MPDArg Id

sgGetTag :: Metadata -> Song -> Maybe [Value]Source

Get list of specific tag type

sgAddTag :: Metadata -> Value -> Song -> Song Source

Add metadata tag value.

defaultSong :: Path -> Song Source

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

defaultStats :: Stats Source

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 Int: Current song's position in the playlist.
stSongID :: Maybe Id: Current song's playlist ID.
stNextSongPos :: Maybe Int: Next song's position in the playlist.
stNextSongID :: Maybe Id: 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

defaultStatus :: Status Source

Query interface

data Query Source

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 -> Value -> Query Source

Create a query.

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

Combine queries.

anything :: Query Source

An empty query. Matches anything.

Querying MPD's status

clearError :: MonadMPD m => m ()Source

Clear the current error message in status.

currentSong :: (Functor m, MonadMPD m) => m (Maybe Song)Source

Get the currently playing song.

idle :: MonadMPD m => [Subsystem] -> m [Subsystem]Source

Wait until there is a noteworthy change in one or more of MPD's susbystems.

The first argument is a list of subsystems that should be considered. An empty list specifies that all subsystems should be considered.

A list of subsystems that have noteworthy changes is returned.

Note that running this command will block until either idle returns or is cancelled by noidle.

noidle :: MonadMPD m => m ()Source

Cancel idle.

status :: MonadMPD m => m Status Source

Get the server's status.

stats :: MonadMPD m => m Stats Source

Get server statistics.

Playback options

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

Set consume mode

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

Set crossfading between songs.

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

Set random playing.

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

Set repeating.

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

Set the volume (0-100 percent).

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

Set single mode

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

Set the replay gain mode.

replayGainStatus :: MonadMPD m => m [String]Source

Get the replay gain options.

Controlling playback

next :: MonadMPD m => m ()Source

Play the next song.

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

Pause playing.

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

Begin/continue playing.

playId :: MonadMPD m => Id -> m ()Source

Play a file with given id.

previous :: MonadMPD m => m ()Source

Play the previous song.

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

Seek to some point in a song.

seekId :: MonadMPD m => Id -> Seconds -> m ()Source

Seek to some point in a song (id version)

stop :: MonadMPD m => m ()Source

Stop playing.

The current playlist

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

Like add_ but returns a list of the files added.

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

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

addId Source

Arguments

:: MonadMPD m
=> Path
-> Maybe Integer	Optional playlist position
-> m Id

Like add, but returns a playlist id.

clear :: MonadMPD m => m ()Source

Clear the current playlist.

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

Remove a song from the current playlist.

deleteId :: MonadMPD m => Id -> m ()Source

Remove a song from the current playlist.

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

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

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

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

playlistId :: MonadMPD m => Maybe Id -> m [Song]Source

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

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

Search for songs in the current playlist with strict matching.

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

Retrieve metadata for songs in the current playlist.

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

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

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

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

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

Like plChanges but only returns positions and ids.

shuffle Source

Arguments

:: MonadMPD m
=> Maybe (Int, Int)	Optional range (start, end)
-> m ()

Shuffle the playlist.

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

Swap the positions of two songs.

swapId :: MonadMPD m => Id -> Id -> m ()Source

Swap the positions of two songs (Id version

Stored playlist

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

Retrieve a list of files in a given playlist.

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

Retrieve metadata for files in a given playlist.

listPlaylists :: MonadMPD m => m [PlaylistName]Source

Retreive a list of stored playlists.

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

Load an existing playlist.

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

Like playlistAdd but returns a list of the files added.

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

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 ()Source

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

playlistDelete Source

Arguments

:: MonadMPD m
=> PlaylistName
-> Integer	Playlist position
-> m ()

Remove a song from a playlist.

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

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

rename Source

Arguments

:: MonadMPD m
=> PlaylistName	Original playlist
-> PlaylistName	New playlist name
-> m ()

Rename an existing playlist.

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

Delete existing playlist.

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

Save the current playlist.

The music database

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

Count the number of entries matching a query.

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

Search the database for entries exactly matching a query.

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

Adds songs matching a query to the current playlist.

list Source

Arguments

:: MonadMPD m
=> Metadata	Metadata to list
-> Query
-> m [Value]

List all tags of the specified type.

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

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

listAllInfo :: MonadMPD m => Path -> m [LsResult]Source

Recursive lsInfo.

lsInfo :: MonadMPD m => Path -> m [LsResult]Source

Non-recursively list the contents of a database directory.

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

Search the database using case insensitive matching.

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

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 ()Source

Like update but also rescans unmodified files.

Stickers

stickerGet Source

Arguments

:: MonadMPD m
=> ObjectType
-> String	Object URI
-> String	Sticker name
-> m [String]

Reads a sticker value for the specified object.

stickerSet Source

Arguments

:: MonadMPD m
=> ObjectType
-> String	Object URI
-> String	Sticker name
-> String	Sticker value
-> m ()

Adds a sticker value to the specified object.

stickerDelete Source

Arguments

:: MonadMPD m
=> ObjectType
-> String	Object URI
-> String	Sticker name
-> m ()

Delete a sticker value from the specified object.

stickerList Source

Arguments

:: MonadMPD m
=> ObjectType
-> String	Object URI
-> m [(String, String)]	Sticker name/sticker value

Lists the stickers for the specified object.

stickerFind Source

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 ()Source

Close the connection.

kill :: MonadMPD m => m ()Source

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

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

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

ping :: MonadMPD m => m ()Source

Check that the server is still responding.

Audio output devices

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

Turn off an output device.

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

Turn on an output device.

outputs :: MonadMPD m => m [Device]Source

Retrieve information for all output devices.

Reflection

commands :: MonadMPD m => m [String]Source

Retrieve a list of available commands.

notCommands :: MonadMPD m => m [String]Source

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

tagTypes :: MonadMPD m => m [String]Source

Retrieve a list of available song metadata.

urlHandlers :: MonadMPD m => m [String]Source

Retrieve a list of supported urlhandlers.

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

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