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 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
- data Subsystem
- data ReplayGainMode
- data Count = Count {}
- data Output = Output {}
- data Song = Song {}
- sgGet :: Metadata -> Song -> Maybe [String]
- data Playlist = Playlist {}
- data Entry
- data Stats = Stats {}
- 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.
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 the different playback states.
Represents the various MPD subsystems.
data ReplayGainMode Source
Represents the result of running count
.
Represents an output device.
Represents a single song item.
Represents a single playlist item.
Represents a single item in database.
Container for database statistics.
Stats | |
|
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.
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.
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
The current playlist
Like add
, but returns a playlist id.
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.
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 [Entry]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.