libmpd-0.5.0: An MPD client library.Source codeContentsIndex
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 whereSource
A typeclass to allow for multiple implementations of a connection to an MPD server.
Methods
close :: m ()Source
Close the connection.
show/hide Instances
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)
show/hide Instances
data MPDError Source
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 Source
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 MPDErrorSource
A response is either an MPDError or some result.
type Host = StringSource
type Port = IntegerSource
type Password = StringSource
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 :: Host -> Port -> Password -> MPD a -> IO (Response a)Source
The most configurable API for running an MPD action.
Command related data types
type Artist = StringSource
type Album = StringSource
type Title = StringSource
type PlaylistName = StringSource
Used for commands which require a playlist name. If empty, the current playlist is used.
type Path = StringSource
Used for commands which require a path within the database. If empty, the root path is used.
data Metadata Source
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 Source
Object types.
Constructors
SongObj
show/hide Instances
type Seconds = IntegerSource
data State Source
Represents the different playback states.
Constructors
Playing
Stopped
Paused
show/hide Instances
data Subsystem Source
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 Source
Constructors
OffDisable replay gain
TrackModePer track mode
AlbumModePer album mode
show/hide Instances
data Count Source
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 Source
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 Source
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]Source
Get list of specific tag type
data Playlist Source
Represents a single playlist item.
Constructors
Playlist
plName :: String
plLastModified :: Maybe UTCTime
show/hide Instances
data Entry Source
Represents a single item in database.
Constructors
SongE Song
PlaylistE Playlist
DirectoryE String
show/hide Instances
data Stats Source
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 Source
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 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"
show/hide Instances
(=?) :: Metadata -> String -> QuerySource
Create a query.
(<&>) :: Query -> Query -> QuerySource
Combine queries.
anything :: QuerySource
An empty query. Matches anything.
Querying MPD's status
clearError :: MonadMPD m => m ()Source
Clear the current error message in status.
currentSong :: MonadMPD m => m (Maybe Song)Source
Get the current song.
idle :: MonadMPD m => [Subsystem] -> m ()Source
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]Source
Get idle notifications. If there is no notifications ready at the moment, this function will block until they show up.
noidle :: MonadMPD m => m ()Source
Cancel idle.
status :: MonadMPD m => m StatusSource
Get the server's status.
stats :: MonadMPD m => m StatsSource
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 => Int -> 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 => Int -> 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.
addIdSource
:: MonadMPD m
=> Path
-> Maybe IntegerOptional playlist position
-> m Int
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 => Int -> 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 => Int -> 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 Int -> 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, Int)]Source
Like plChanges but only returns positions and ids.
shuffleSource
:: 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 => Int -> Int -> 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.
playlistDeleteSource
:: MonadMPD m
=> PlaylistName
-> IntegerPlaylist 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.
renameSource
:: MonadMPD m
=> PlaylistNameOriginal playlist
-> PlaylistNameNew 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 CountSource
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.
listSource
:: MonadMPD m
=> MetadataMetadata to list
-> Query
-> m [String]
List all metadata of metadata (sic).
listAll :: MonadMPD m => Path -> m [Path]Source
List the songs (without metadata) in a database directory recursively.
listAllInfo :: MonadMPD m => Path -> m [Song]Source
Recursive lsInfo.
lsInfo :: MonadMPD m => Path -> m [Entry]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
stickerGetSource
:: MonadMPD m
=> ObjectType
-> StringObject URI
-> StringSticker name
-> m [String]
Reads a sticker value for the specified object.
stickerSetSource
:: MonadMPD m
=> ObjectType
-> StringObject URI
-> StringSticker name
-> StringSticker value
-> m ()
Adds a sticker value to the specified object.
stickerDeleteSource
:: MonadMPD m
=> ObjectType
-> StringObject URI
-> StringSticker name
-> m ()
Delete a sticker value from the specified object.
stickerListSource
:: MonadMPD m
=> ObjectType
-> StringObject URI
-> m [(String, String)]Sticker name/sticker value
Lists the stickers for the specified object.
stickerFindSource
:: 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 ()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 [Output]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.
Produced by Haddock version 2.6.1