libmpd-0.5.0: An MPD client library.ContentsIndex
Network.MPD
Stabilityalpha
MaintainerJoachim Fasting <joachim.fasting@gmail.com>
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 avoid name clashes with the standard Prelude functions, do:

 import qualified Network.MPD as MPD
Synopsis
class (Monad m, MonadError MPDError m) => MonadMPD m where
close :: m ()
data MPD a
data MPDError
= NoMPD
| TimedOut
| Unexpected String
| Custom String
| ACK ACKType String
data ACKType
= InvalidArgument
| InvalidPassword
| Auth
| UnknownCommand
| FileNotFound
| PlaylistMax
| System
| PlaylistLoad
| Busy
| NotPlaying
| FileExists
| UnknownACK
type Response = Either MPDError
type Host = String
type Port = Integer
type Password = String
withMPD :: MPD a -> IO (Response a)
withMPDEx :: Host -> Port -> Password -> MPD a -> IO (Response a)
type Artist = String
type Album = String
type Title = String
type PlaylistName = String
type Path = String
data Metadata
= Artist
| ArtistSort
| Album
| AlbumArtist
| AlbumArtistSort
| Title
| Track
| Name
| Genre
| Date
| Composer
| Performer
| Comment
| Disc
| MUSICBRAINZ_ARTISTID
| MUSICBRAINZ_ALBUMID
| MUSICBRAINZ_ALBUMARTISTID
| MUSICBRAINZ_TRACKID
data ObjectType = SongObj
type Seconds = Integer
data State
= Playing
| Stopped
| Paused
data Subsystem
= DatabaseS
| UpdateS
| StoredPlaylistS
| PlaylistS
| PlayerS
| MixerS
| OutputS
| OptionsS
data ReplayGainMode
= Off
| TrackMode
| AlbumMode
data Count = Count {
cSongs :: Integer
cPlaytime :: Seconds
}
data Output = Output {
outID :: Int
outName :: String
outEnabled :: Bool
}
data Song = Song {
sgFilePath :: String
sgTags :: Map Metadata [String]
sgLastModified :: Maybe UTCTime
sgLength :: Seconds
sgIndex :: Maybe (Int, Int)
}
sgGet :: Metadata -> Song -> Maybe [String]
data Playlist = Playlist {
plName :: String
plLastModified :: Maybe UTCTime
}
data Entry
= SongE Song
| PlaylistE Playlist
| DirectoryE String
data Stats = Stats {
stsArtists :: Integer
stsAlbums :: Integer
stsSongs :: Integer
stsUptime :: Seconds
stsPlaytime :: Seconds
stsDbPlaytime :: Seconds
stsDbUpdate :: Integer
}
data Status = Status {
stState :: State
stVolume :: Int
stRepeat :: Bool
stRandom :: Bool
stPlaylistID :: Integer
stPlaylistLength :: Integer
stSongPos :: Maybe Int
stSongID :: Maybe Int
stNextSongPos :: Maybe Int
stNextSongID :: Maybe Int
stTime :: (Double, Seconds)
stBitrate :: Int
stXFadeWidth :: Seconds
stMixRampdB :: Double
stMixRampDelay :: Double
stAudio :: (Int, Int, Int)
stUpdatingDb :: Integer
stSingle :: Bool
stConsume :: Bool
stError :: Maybe String
}
data Query
(=?) :: Metadata -> String -> Query
(<&>) :: Query -> Query -> Query
anything :: Query
clearError :: MonadMPD m => m ()
currentSong :: MonadMPD m => m (Maybe Song)
idle :: MonadMPD m => [Subsystem] -> m ()
getIdle :: MonadMPD m => m [Subsystem]
noidle :: MonadMPD m => m ()
status :: MonadMPD m => m Status
stats :: MonadMPD m => m Stats
consume :: MonadMPD m => Bool -> m ()
crossfade :: MonadMPD m => Seconds -> m ()
random :: MonadMPD m => Bool -> m ()
repeat :: MonadMPD m => Bool -> m ()
setVolume :: MonadMPD m => Int -> m ()
single :: MonadMPD m => Bool -> m ()
replayGainMode :: MonadMPD m => ReplayGainMode -> m ()
replayGainStatus :: MonadMPD m => m [String]
next :: MonadMPD m => m ()
pause :: MonadMPD m => Bool -> m ()
play :: MonadMPD m => Maybe Int -> m ()
playId :: MonadMPD m => Int -> m ()
previous :: MonadMPD m => m ()
seek :: MonadMPD m => Int -> Seconds -> m ()
seekId :: MonadMPD m => Int -> Seconds -> m ()
stop :: MonadMPD m => m ()
add :: MonadMPD m => Path -> m [Path]
add_ :: MonadMPD m => Path -> m ()
addId :: MonadMPD m => Path -> Maybe Integer -> m Int
clear :: MonadMPD m => m ()
delete :: MonadMPD m => Int -> m ()
deleteId :: MonadMPD m => Int -> m ()
move :: MonadMPD m => Int -> Int -> m ()
moveId :: MonadMPD m => Int -> Int -> m ()
playlist :: MonadMPD m => m [(Int, Path)]
playlistId :: MonadMPD m => Maybe Int -> m [Song]
playlistFind :: MonadMPD m => Query -> m [Song]
playlistInfo :: MonadMPD m => Maybe (Int, Int) -> m [Song]
playlistSearch :: MonadMPD m => Query -> m [Song]
plChanges :: MonadMPD m => Integer -> m [Song]
plChangesPosId :: MonadMPD m => Integer -> m [(Int, Int)]
shuffle :: MonadMPD m => Maybe (Int, Int) -> m ()
swap :: MonadMPD m => Int -> Int -> m ()
swapId :: MonadMPD m => Int -> Int -> m ()
listPlaylist :: MonadMPD m => PlaylistName -> m [Path]
listPlaylistInfo :: MonadMPD m => PlaylistName -> m [Song]
listPlaylists :: MonadMPD m => m [PlaylistName]
load :: MonadMPD m => PlaylistName -> m ()
playlistAdd :: MonadMPD m => PlaylistName -> Path -> m [Path]
playlistAdd_ :: MonadMPD m => PlaylistName -> Path -> m ()
playlistClear :: MonadMPD m => PlaylistName -> m ()
playlistDelete :: MonadMPD m => PlaylistName -> Integer -> m ()
playlistMove :: MonadMPD m => PlaylistName -> Integer -> Integer -> m ()
rename :: MonadMPD m => PlaylistName -> PlaylistName -> m ()
rm :: MonadMPD m => PlaylistName -> m ()
save :: MonadMPD m => PlaylistName -> m ()
count :: MonadMPD m => Query -> m Count
find :: MonadMPD m => Query -> m [Song]
findAdd :: MonadMPD m => Query -> m ()
list :: MonadMPD m => Metadata -> Query -> m [String]
listAll :: MonadMPD m => Path -> m [Path]
listAllInfo :: MonadMPD m => Path -> m [Song]
lsInfo :: MonadMPD m => Path -> m [Entry]
search :: MonadMPD m => Query -> m [Song]
update :: MonadMPD m => [Path] -> m ()
rescan :: MonadMPD m => [Path] -> m ()
stickerGet :: MonadMPD m => ObjectType -> String -> String -> m [String]
stickerSet :: MonadMPD m => ObjectType -> String -> String -> String -> m ()
stickerDelete :: MonadMPD m => ObjectType -> String -> String -> m ()
stickerList :: MonadMPD m => ObjectType -> String -> m [(String, String)]
stickerFind :: MonadMPD m => ObjectType -> String -> String -> m [(String, String)]
close :: MonadMPD m => m ()
kill :: MonadMPD m => m ()
password :: MonadMPD m => String -> m ()
ping :: MonadMPD m => m ()
disableOutput :: MonadMPD m => Int -> m ()
enableOutput :: MonadMPD m => Int -> m ()
outputs :: MonadMPD m => m [Output]
commands :: MonadMPD m => m [String]
notCommands :: MonadMPD m => m [String]
tagTypes :: MonadMPD m => m [String]
urlHandlers :: MonadMPD m => m [String]
decoders :: MonadMPD m => m [(String, [(String, String)])]
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.
show/hide 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)
show/hide Instances
data MPDError
The MPDError type is used to signal errors, both from the MPD and otherwise.
Constructors
NoMPDMPD not responding
TimedOutThe connection timed out
Unexpected StringMPD returned an unexpected response. This is a bug, either in the library or in MPD itself.
Custom StringUsed for misc. errors
ACK ACKType StringACK type and a message from the server
show/hide Instances
data ACKType
Represents various MPD errors (aka. ACKs).
Constructors
InvalidArgumentInvalid argument passed (ACK 2)
InvalidPasswordInvalid password supplied (ACK 3)
AuthAuthentication required (ACK 4)
UnknownCommandUnknown command (ACK 5)
FileNotFoundFile or directory not found ACK 50)
PlaylistMaxPlaylist at maximum size (ACK 51)
SystemA system error (ACK 52)
PlaylistLoadPlaylist loading failed (ACK 53)
BusyUpdate already running (ACK 54)
NotPlayingAn operation requiring playback got interrupted (ACK 55)
FileExistsFile already exists (ACK 56)
UnknownACKAn unknown ACK (aka. bug)
show/hide Instances
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.
Constructors
Artist
ArtistSort
Album
AlbumArtist
AlbumArtistSort
Title
Track
Name
Genre
Date
Composer
Performer
Comment
Disc
MUSICBRAINZ_ARTISTID
MUSICBRAINZ_ALBUMID
MUSICBRAINZ_ALBUMARTISTID
MUSICBRAINZ_TRACKID
show/hide Instances
data ObjectType
Object types.
Constructors
SongObj
show/hide Instances
type Seconds = Integer
data State
Represents the different playback states.
Constructors
Playing
Stopped
Paused
show/hide Instances
data Subsystem
Represents the various MPD subsystems.
Constructors
DatabaseSThe song database
UpdateSDatabase updates
StoredPlaylistSStored playlists
PlaylistSThe current playlist
PlayerSThe player
MixerSThe volume mixer
OutputSAudio outputs
OptionsSPlayback options
show/hide Instances
data ReplayGainMode
Constructors
OffDisable replay gain
TrackModePer track mode
AlbumModePer album mode
show/hide Instances
data Count
Represents the result of running count.
Constructors
Count
cSongs :: IntegerNumber of songs matching the query
cPlaytime :: SecondsTotal play time of matching songs
show/hide Instances
data Output
Represents an output device.
Constructors
Output
outID :: IntOutput's ID number
outName :: StringOutput's name as defined in the MPD configuration file
outEnabled :: Bool
show/hide Instances
data Song
Represents a single song item.
Constructors
Song
sgFilePath :: String
sgTags :: Map Metadata [String]Map of available tags (multiple occurences of one tag type allowed)
sgLastModified :: Maybe UTCTimeLast modification date
sgLength :: SecondsLength of the song in seconds
sgIndex :: Maybe (Int, Int)Position/ID in playlist
show/hide Instances
sgGet :: Metadata -> Song -> Maybe [String]
Get list of specific tag type
data Playlist
Represents a single playlist item.
Constructors
Playlist
plName :: String
plLastModified :: Maybe UTCTime
show/hide Instances
data Entry
Represents a single item in database.
Constructors
SongE Song
PlaylistE Playlist
DirectoryE String
show/hide Instances
data Stats
Container for database statistics.
Constructors
Stats
stsArtists :: IntegerNumber of artists.
stsAlbums :: IntegerNumber of albums.
stsSongs :: IntegerNumber of songs.
stsUptime :: SecondsDaemon uptime in seconds.
stsPlaytime :: SecondsTotal playing time.
stsDbPlaytime :: SecondsTotal play time of all the songs in the database.
stsDbUpdate :: IntegerLast database update in UNIX time.
show/hide Instances
data Status
Container for MPD status.
Constructors
Status
stState :: State
stVolume :: IntA percentage (0-100)
stRepeat :: Bool
stRandom :: Bool
stPlaylistID :: IntegerA value that is incremented by the server every time the playlist changes.
stPlaylistLength :: IntegerThe number of items in the current playlist.
stSongPos :: Maybe IntCurrent song's position in the playlist.
stSongID :: Maybe IntCurrent song's playlist ID.
stNextSongPos :: Maybe IntNext song's position in the playlist.
stNextSongID :: Maybe IntNext song's playlist ID.
stTime :: (Double, Seconds)Time elapsed/total time.
stBitrate :: IntBitrate (in kilobytes per second) of playing song (if any).
stXFadeWidth :: SecondsCrossfade time.
stMixRampdB :: DoubleMixRamp threshold in dB
stMixRampDelay :: DoubleMixRamp extra delay in seconds
stAudio :: (Int, Int, Int)Samplerate/bits/channels for the chosen output device (see mpd.conf).
stUpdatingDb :: IntegerJob ID of currently running update (if any).
stSingle :: BoolIf True, MPD will play only one song and stop after finishing it.
stConsume :: BoolIf True, a song will be removed after it has been played.
stError :: Maybe StringLast error message (if any).
show/hide Instances
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"
show/hide Instances
(=?) :: 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
:: MonadMPD m
=> Path
-> Maybe IntegerOptional 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
:: 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
:: MonadMPD m
=> PlaylistName
-> IntegerPlaylist 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
:: MonadMPD m
=> PlaylistNameOriginal playlist
-> PlaylistNameNew 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
:: MonadMPD m
=> MetadataMetadata 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
:: MonadMPD m
=> ObjectType
-> StringObject URI
-> StringSticker name
-> m [String]
Reads a sticker value for the specified object.
stickerSet
:: MonadMPD m
=> ObjectType
-> StringObject URI
-> StringSticker name
-> StringSticker value
-> m ()
Adds a sticker value to the specified object.
stickerDelete
:: MonadMPD m
=> ObjectType
-> StringObject URI
-> StringSticker name
-> m ()
Delete a sticker value from the specified object.
stickerList
:: MonadMPD m
=> ObjectType
-> StringObject URI
-> m [(String, String)]Sticker name/sticker value
Lists the stickers for the specified object.
stickerFind
:: MonadMPD m
=> ObjectType
-> StringPath
-> StringSticker 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.
Produced by Haddock version 2.7.2