Stability | alpha |
---|---|
Maintainer | Joachim Fasting <joachim.fasting@gmail.com> |
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
- class (Monad m, MonadError MPDError m) => MonadMPD m where
- data MPD a
- data MPDError
- 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 Meta
- data ObjectType = SongObj
- type Seconds = Integer
- data PLIndex
- data State
- data Subsystem
- data ReplayGainMode
- data Count = Count {}
- defaultCount :: Count
- data Device = Device {
- dOutputID :: Int
- dOutputName :: String
- dOutputEnabled :: Bool
- defaultDevice :: Device
- data Stats = Stats {}
- defaultStats :: Stats
- data Song = Song {}
- defaultSong :: Song
- data Status = Status {
- stState :: State
- stVolume :: Int
- stRepeat :: Bool
- stRandom :: Bool
- stPlaylistVersion :: Integer
- stPlaylistLength :: Integer
- stSongPos :: Maybe PLIndex
- stSongID :: Maybe PLIndex
- stNextSongPos :: Maybe PLIndex
- stNextSongID :: Maybe PLIndex
- stTime :: (Seconds, Seconds)
- stBitrate :: Int
- stXFadeWidth :: Seconds
- stAudio :: (Int, Int, Int)
- stUpdatingDb :: Integer
- stSingle :: Bool
- stConsume :: Bool
- stError :: String
- defaultStatus :: Status
- data Query
- (=?) :: Meta -> String -> Query
- (<&>) :: Query -> Query -> Query
- anything :: Query
- clearError :: MonadMPD m => m ()
- currentSong :: (Functor m, MonadMPD m) => m (Maybe Song)
- idle :: 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 PLIndex -> m ()
- previous :: MonadMPD m => m ()
- seek :: MonadMPD m => Maybe PLIndex -> Seconds -> m ()
- stop :: MonadMPD m => m ()
- add :: MonadMPD m => Path -> m [Path]
- add_ :: MonadMPD m => Path -> m ()
- addId :: MonadMPD m => Path -> Maybe Integer -> m Integer
- clear :: MonadMPD m => m ()
- delete :: MonadMPD m => PLIndex -> m ()
- move :: MonadMPD m => PLIndex -> Integer -> m ()
- playlist :: MonadMPD m => m [(PLIndex, Path)]
- playlistFind :: MonadMPD m => Query -> m [Song]
- playlistInfo :: MonadMPD m => Maybe (Either PLIndex (Int, Int)) -> m [Song]
- playlistSearch :: MonadMPD m => Query -> m [Song]
- plChanges :: MonadMPD m => Integer -> m [Song]
- plChangesPosId :: MonadMPD m => Integer -> m [(PLIndex, PLIndex)]
- shuffle :: MonadMPD m => Maybe (Int, Int) -> m ()
- swap :: MonadMPD m => PLIndex -> PLIndex -> 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 => Meta -> Query -> m [String]
- listAll :: MonadMPD m => Path -> m [Path]
- listAllInfo :: MonadMPD m => Path -> m [Either Path Song]
- lsInfo :: MonadMPD m => Path -> m [Either Path Song]
- 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 [Device]
- 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)])]
- addMany :: MonadMPD m => PlaylistName -> [Path] -> m ()
- deleteMany :: MonadMPD m => PlaylistName -> [PLIndex] -> m ()
- complete :: MonadMPD m => String -> m [Either Path Song]
- crop :: MonadMPD m => Maybe PLIndex -> Maybe PLIndex -> m ()
- prune :: MonadMPD m => m ()
- lsDirs :: MonadMPD m => Path -> m [Path]
- lsFiles :: MonadMPD m => Path -> m [Path]
- lsPlaylists :: MonadMPD m => m [PlaylistName]
- listArtists :: MonadMPD m => m [Artist]
- listAlbums :: MonadMPD m => Maybe Artist -> m [Album]
- listAlbum :: MonadMPD m => Artist -> Album -> m [Song]
- getPlaylist :: MonadMPD m => m [Song]
- toggle :: MonadMPD m => m ()
- updateId :: MonadMPD m => [Path] -> m Integer
- volume :: MonadMPD m => Int -> m ()
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.
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)
The MPDError type is used to signal errors, both from the MPD and otherwise.
Represents various MPD errors (aka. ACKs).
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) |
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 PlaylistName = StringSource
Used for commands which require a playlist name. If empty, the current playlist is used.
Used for commands which require a path within the database. If empty, the root path is used.
Available metadata types/scope modifiers, used for searching the database for entries with certain metadata values.
Represents a song's playlist index.
Represents the different playback states.
Represents the various MPD subsystems.
data ReplayGainMode Source
Represents the result of running count
.
Represents an output device.
Device | |
|
Container for database statistics.
Stats | |
|
Represents a single song item.
Song | Auxiliary song fields |
|
Container for MPD status.
Status | |
|
Query interface
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"
Querying MPD's status
clearError :: MonadMPD m => m ()Source
Clear the current error message in status.
Playback options
replayGainMode :: MonadMPD m => ReplayGainMode -> m ()Source
Set the replay gain mode.
replayGainStatus :: MonadMPD m => m [String]Source
Get the replay gain options.
Controlling playback
seek :: MonadMPD m => Maybe PLIndex -> Seconds -> m ()Source
Seek to some point in a song. Seeks in current song if no position is given.
The current playlist
Like add
, but returns a playlist id.
move :: MonadMPD m => PLIndex -> Integer -> m ()Source
Move a song to a given position in the current playlist.
playlist :: MonadMPD m => m [(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.
playlistFind :: MonadMPD m => Query -> m [Song]Source
Search for songs in the current playlist with strict matching.
playlistInfo :: MonadMPD m => Maybe (Either PLIndex (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 [(PLIndex, PLIndex)]Source
Like plChanges
but only returns positions and ids.
Shuffle the playlist.
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.
:: 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.
:: 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
find :: MonadMPD m => Query -> m [Song]Source
Search the database for entries exactly matching a query.
List all metadata of metadata (sic).
listAll :: MonadMPD m => Path -> m [Path]Source
List the songs (without metadata) in a database directory recursively.
lsInfo :: MonadMPD m => Path -> m [Either Path Song]Source
Non-recursively list the contents of a database directory.
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.
Stickers
:: MonadMPD m | |
=> ObjectType | |
-> String | Object URI |
-> String | Sticker name |
-> m [String] |
Reads a sticker value for the specified object.
:: MonadMPD m | |
=> ObjectType | |
-> String | Object URI |
-> String | Sticker name |
-> String | Sticker value |
-> m () |
Adds a sticker value to the specified object.
:: MonadMPD m | |
=> ObjectType | |
-> String | Object URI |
-> String | Sticker name |
-> m () |
Delete a sticker value from the specified object.
:: MonadMPD m | |
=> ObjectType | |
-> String | Object URI |
-> m [(String, String)] | Sticker name/sticker value |
Lists the stickers for the specified object.
:: 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
password :: MonadMPD m => String -> m ()Source
Send password to server to authenticate session. Password is sent as plain text.
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.
Reflection
notCommands :: MonadMPD m => m [String]Source
Retrieve a list of unavailable (due to access restrictions) commands.
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.
Extensions/shortcuts
addMany :: MonadMPD m => PlaylistName -> [Path] -> m ()Source
Add a list of songs/folders to a playlist.
Should be more efficient than running add
many times.
deleteMany :: MonadMPD m => PlaylistName -> [PLIndex] -> m ()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 :: MonadMPD m => String -> m [Either Path Song]Source
Returns all songs and directories that match the given partial path name.
lsPlaylists :: MonadMPD m => m [PlaylistName]Source
List all playlists.
listArtists :: MonadMPD m => m [Artist]Source
List the artists in the database.
listAlbums :: MonadMPD m => Maybe Artist -> m [Album]Source
List the albums in the database, optionally matching a given artist.
listAlbum :: MonadMPD m => Artist -> Album -> m [Song]Source
List the songs in an album of some artist.
getPlaylist :: MonadMPD m => m [Song]Source
Retrieve the current playlist.
Equivalent to playlistinfo Nothing
.