Portability | Haskell 98 |
---|---|
Stability | alpha |
Maintainer | bsinclai@turing.une.edu.au |
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/.
- data MPD a
- data MPDError
- data ACKType
- = InvalidArgument
- | InvalidPassword
- | Auth
- | UnknownCommand
- | FileNotFound
- | PlaylistMax
- | System
- | PlaylistLoad
- | Busy
- | NotPlaying
- | FileExists
- | UnknownACK
- type Response a = Either MPDError a
- withMPD :: MPD a -> IO (Response a)
- withMPDEx :: String -> Integer -> IO (Maybe String) -> MPD a -> IO (Response a)
- data State
- data Status = Status {
- stState :: State
- stVolume :: Int
- stRepeat :: Bool
- stRandom :: Bool
- stPlaylistVersion :: Integer
- stPlaylistLength :: Integer
- stSongPos :: Maybe PLIndex
- stSongID :: Maybe PLIndex
- stTime :: (Seconds, Seconds)
- stBitrate :: Int
- stXFadeWidth :: Seconds
- stAudio :: (Int, Int, Int)
- stUpdatingDb :: Integer
- stError :: String
- data Stats = Stats {}
- data Device = Device {
- dOutputID :: Int
- dOutputName :: String
- dOutputEnabled :: Bool
- data Query
- = Query Meta String
- | MultiQuery [Query]
- data Meta
- type Artist = String
- type Album = String
- type Title = String
- type Seconds = Integer
- type PlaylistName = String
- type Path = String
- data PLIndex
- data Song = Song {}
- data Count = Count {}
- disableOutput :: Int -> MPD ()
- enableOutput :: Int -> MPD ()
- kill :: MPD ()
- outputs :: MPD [Device]
- update :: [Path] -> MPD ()
- find :: Query -> MPD [Song]
- list :: Meta -> Maybe Query -> MPD [String]
- listAll :: Path -> MPD [Path]
- listAllInfo :: Path -> MPD [Either Path Song]
- lsInfo :: Path -> MPD [Either Path Song]
- search :: Query -> MPD [Song]
- count :: Query -> MPD Count
- add :: PlaylistName -> Path -> MPD [Path]
- add_ :: PlaylistName -> Path -> MPD ()
- addId :: Path -> MPD Integer
- clear :: PlaylistName -> MPD ()
- currentSong :: MPD (Maybe Song)
- delete :: PlaylistName -> PLIndex -> MPD ()
- load :: PlaylistName -> MPD ()
- move :: PlaylistName -> PLIndex -> Integer -> MPD ()
- playlistInfo :: Maybe PLIndex -> MPD [Song]
- listPlaylist :: PlaylistName -> MPD [Path]
- listPlaylistInfo :: PlaylistName -> MPD [Song]
- playlist :: MPD [(PLIndex, Path)]
- plChanges :: Integer -> MPD [Song]
- plChangesPosId :: Integer -> MPD [(PLIndex, PLIndex)]
- playlistFind :: Query -> MPD [Song]
- playlistSearch :: Query -> MPD [Song]
- rm :: PlaylistName -> MPD ()
- rename :: PlaylistName -> PlaylistName -> MPD ()
- save :: PlaylistName -> MPD ()
- shuffle :: MPD ()
- swap :: PLIndex -> PLIndex -> MPD ()
- crossfade :: Seconds -> MPD ()
- next :: MPD ()
- pause :: Bool -> MPD ()
- play :: Maybe PLIndex -> MPD ()
- previous :: MPD ()
- random :: Bool -> MPD ()
- repeat :: Bool -> MPD ()
- seek :: Maybe PLIndex -> Seconds -> MPD ()
- setVolume :: Int -> MPD ()
- volume :: Int -> MPD ()
- stop :: MPD ()
- clearError :: MPD ()
- close :: MPD ()
- commands :: MPD [String]
- notCommands :: MPD [String]
- password :: String -> MPD ()
- ping :: MPD ()
- reconnect :: MPD ()
- stats :: MPD Stats
- status :: MPD Status
- tagTypes :: MPD [String]
- urlHandlers :: MPD [String]
- addMany :: PlaylistName -> [Path] -> MPD ()
- deleteMany :: PlaylistName -> [PLIndex] -> MPD ()
- complete :: String -> MPD [Either Path Song]
- crop :: Maybe PLIndex -> Maybe PLIndex -> MPD ()
- prune :: MPD ()
- lsDirs :: Path -> MPD [Path]
- lsFiles :: Path -> MPD [Path]
- lsPlaylists :: MPD [PlaylistName]
- findArtist :: Artist -> MPD [Song]
- findAlbum :: Album -> MPD [Song]
- findTitle :: Title -> MPD [Song]
- listArtists :: MPD [Artist]
- listAlbums :: Maybe Artist -> MPD [Album]
- listAlbum :: Artist -> Album -> MPD [Song]
- searchArtist :: Artist -> MPD [Song]
- searchAlbum :: Album -> MPD [Song]
- searchTitle :: Title -> MPD [Song]
- getPlaylist :: MPD [Song]
- toggle :: MPD ()
- updateId :: [Path] -> MPD Integer
Basic data types
The MPD monad is basically a reader and error monad combined.
To use the error throwing/catching capabilities:
import Control.Monad.Error
To run IO actions within the MPD monad:
import Control.Monad.Trans
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
:: String | Host name. |
-> Integer | Port number. |
-> IO (Maybe String) | An action that supplies passwords. |
-> MPD a | The action to run. |
-> IO (Response a) |
Run an MPD action against a server.
Command related data types
Represents the different playback states.
Container for MPD status.
Status | |
|
Container for database statistics.
Stats | |
|
Represents an output device.
Device | |
|
A query is composed of a scope modifier and a query string.
To match entries where album equals "Foo", use:
Query Album "Foo"
To match entries where album equals "Foo" and artist equals "Bar", use:
MultiQuery [Query Album "Foo", Query Artist "Bar"]
Query Meta String | Simple query. |
MultiQuery [Query] | Query with multiple conditions. |
Available metadata types/scope modifiers, used for searching the database for entries with certain metadata values.
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.
Represents a song's playlist index.
Represents a single song item.
Song | |
|
Represents the result of running count
.
Admin commands
disableOutput :: Int -> MPD ()Source
Turn off an output device.
enableOutput :: Int -> MPD ()Source
Turn on an output device.
update :: [Path] -> MPD ()Source
Update the server's database. If no paths are given, all paths will be scanned. Unreadable or non-existent paths are silently ignored.
Database commands
List all metadata of metadata (sic).
listAll :: Path -> MPD [Path]Source
List the songs (without metadata) in a database directory recursively.
lsInfo :: Path -> MPD [Either Path Song]Source
Non-recursively list the contents of a database directory.
Playlist commands
Unless otherwise noted all playlist commands operate on the current playlist.
add_ :: PlaylistName -> Path -> MPD ()Source
Add a song (or a whole directory) to a playlist. Adds to current if no playlist is specified. Will create a new playlist if the one specified does not already exist.
clear :: PlaylistName -> MPD ()Source
Clear a playlist. Clears current playlist if no playlist is specified. If the specified playlist does not exist, it will be created.
currentSong :: MPD (Maybe Song)Source
Get the currently playing song.
delete :: PlaylistName -> PLIndex -> MPD ()Source
Remove a song from a playlist.
If no playlist is specified, current playlist is used.
Note that a playlist position (Pos
) is required when operating on
playlists other than the current.
load :: PlaylistName -> MPD ()Source
Load an existing playlist.
move :: PlaylistName -> PLIndex -> Integer -> MPD ()Source
Move a song to a given position.
Note that a playlist position (Pos
) is required when operating on
playlists other than the current.
playlistInfo :: Maybe PLIndex -> MPD [Song]Source
Retrieve metadata for songs in the current playlist.
listPlaylist :: PlaylistName -> MPD [Path]Source
Retrieve a list of files in a given playlist.
listPlaylistInfo :: PlaylistName -> MPD [Song]Source
Retrieve metadata for files in a given playlist.
playlist :: MPD [(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.
plChanges :: Integer -> MPD [Song]Source
Retrieve a list of changed songs currently in the playlist since a given playlist version.
plChangesPosId :: Integer -> MPD [(PLIndex, PLIndex)]Source
Like plChanges
but only returns positions and ids.
playlistFind :: Query -> MPD [Song]Source
Search for songs in the current playlist with strict matching.
playlistSearch :: Query -> MPD [Song]Source
Search case-insensitively with partial matches for songs in the current playlist.
rm :: PlaylistName -> MPD ()Source
Delete existing playlist.
:: PlaylistName | Original playlist |
-> PlaylistName | New playlist name |
-> MPD () |
Rename an existing playlist.
save :: PlaylistName -> MPD ()Source
Save the current playlist.
Playback commands
seek :: Maybe PLIndex -> Seconds -> MPD ()Source
Seek to some point in a song. Seeks in current song if no position is given.
Increase or decrease volume by a given percent, e.g.
'volume 10' will increase the volume by 10 percent, while
'volume (-10)' will decrease it by the same amount.
Note that this command is only included for completeness sake ; it's
deprecated and may disappear at any time, please use setVolume
instead.
Miscellaneous commands
Clear the current error message in status.
notCommands :: MPD [String]Source
Retrieve a list of unavailable (due to access restrictions) commands.
password :: String -> MPD ()Source
Send password to server to authenticate session. Password is sent as plain text.
urlHandlers :: MPD [String]Source
Retrieve a list of supported urlhandlers.
Extensions/shortcuts
addMany :: PlaylistName -> [Path] -> MPD ()Source
Add a list of songs/folders to a playlist.
Should be more efficient than running add
many times.
deleteMany :: PlaylistName -> [PLIndex] -> MPD ()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 :: String -> MPD [Either Path Song]Source
Returns all songs and directories that match the given partial path name.
lsPlaylists :: MPD [PlaylistName]Source
List all playlists.
findArtist :: Artist -> MPD [Song]Source
Search the database for songs relating to an artist.
listArtists :: MPD [Artist]Source
List the artists in the database.
listAlbums :: Maybe Artist -> MPD [Album]Source
List the albums in the database, optionally matching a given artist.
searchArtist :: Artist -> MPD [Song]Source
Search the database for songs relating to an artist using search
.
searchAlbum :: Album -> MPD [Song]Source
Search the database for songs relating to an album using search
.
searchTitle :: Title -> MPD [Song]Source
Search the database for songs relating to a song title.
getPlaylist :: MPD [Song]Source
Retrieve the current playlist.
Equivalent to playlistinfo Nothing
.