Portability | unportable |
---|---|
Stability | unstable |
Maintainer | Joachim Fasting <joachifm@fastmail.fm> |
Safe Haskell | None |
Network.MPD
Description
An MPD client library. MPD is a daemon for playing music that is controlled over a network socket.
To use the library, do:
import qualified Network.MPD as MPD
- class (Monad m, MonadError MPDError m) => MonadMPD m
- data MPD a
- data MPDError
- = NoMPD
- | ConnectionError IOException
- | 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)
- withMPD_ :: Maybe String -> Maybe String -> MPD a -> IO (Response a)
- withMPDEx :: Host -> Port -> Password -> MPD a -> IO (Response a)
- data Query
- (=?) :: Metadata -> Value -> Query
- (<&>) :: Query -> Query -> Query
- anything :: Query
- class ToString a where
- type Artist = Value
- type Album = Value
- type Title = Value
- newtype PlaylistName = PlaylistName ByteString
- data Path
- 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 Value
- data ObjectType = SongObj
- type Seconds = Integer
- type Decibels = Integer
- data State
- data Subsystem
- data ReplayGainMode
- data Count = Count {}
- data LsResult
- data Device = Device {
- dOutputID :: Int
- dOutputName :: String
- dOutputEnabled :: Bool
- data Song = Song {}
- type Position = Int
- newtype Id = Id Int
- sgGetTag :: Metadata -> Song -> Maybe [Value]
- sgAddTag :: Metadata -> Value -> Song -> Song
- data Stats = Stats {
- stsArtists :: Integer
- stsAlbums :: Integer
- stsSongs :: Integer
- stsUptime :: Seconds
- stsPlaytime :: Seconds
- stsDbPlaytime :: Seconds
- stsDbUpdate :: Integer
- data Status = Status {
- stState :: State
- stVolume :: Maybe Int
- stRepeat :: Bool
- stRandom :: Bool
- stPlaylistVersion :: Integer
- stPlaylistLength :: Integer
- stSongPos :: Maybe Position
- stSongID :: Maybe Id
- stNextSongPos :: Maybe Position
- stNextSongID :: Maybe Id
- stTime :: Maybe (Double, Seconds)
- stBitrate :: Maybe Int
- stXFadeWidth :: Seconds
- stMixRampdB :: Double
- stMixRampDelay :: Double
- stAudio :: (Int, Int, Int)
- stUpdatingDb :: Maybe Integer
- stSingle :: Bool
- stConsume :: Bool
- stError :: Maybe String
- def :: Default a => a
- clearError :: MonadMPD m => m ()
- currentSong :: MonadMPD m => m (Maybe Song)
- idle :: MonadMPD m => [Subsystem] -> m [Subsystem]
- noidle :: MonadMPD m => m ()
- stats :: MonadMPD m => m Stats
- status :: MonadMPD m => m Status
- 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, String)]
- next :: MonadMPD m => m ()
- pause :: MonadMPD m => Bool -> m ()
- play :: MonadMPD m => Maybe Position -> m ()
- playId :: MonadMPD m => Id -> m ()
- previous :: MonadMPD m => m ()
- seek :: MonadMPD m => Position -> Seconds -> m ()
- seekId :: MonadMPD m => Id -> Seconds -> m ()
- stop :: MonadMPD m => m ()
- addId :: MonadMPD m => Path -> Maybe Position -> m Id
- add :: MonadMPD m => Path -> m ()
- clear :: MonadMPD m => m ()
- delete :: MonadMPD m => Position -> m ()
- deleteId :: MonadMPD m => Id -> m ()
- move :: MonadMPD m => Position -> Position -> m ()
- moveId :: MonadMPD m => Id -> Position -> m ()
- playlist :: MonadMPD m => m [(Position, Path)]
- playlistFind :: MonadMPD m => Query -> m [Song]
- playlistInfo :: MonadMPD m => Maybe Position -> m [Song]
- playlistInfoRange :: MonadMPD m => Maybe (Position, Position) -> m [Song]
- playlistId :: MonadMPD m => Maybe Id -> m [Song]
- playlistSearch :: MonadMPD m => Query -> m [Song]
- plChanges :: MonadMPD m => Integer -> m [Song]
- plChangesPosId :: MonadMPD m => Integer -> m [(Position, Id)]
- shuffle :: MonadMPD m => Maybe (Position, Position) -> m ()
- swap :: MonadMPD m => Position -> Position -> m ()
- swapId :: MonadMPD m => Id -> Id -> 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 ()
- playlistClear :: MonadMPD m => PlaylistName -> m ()
- playlistDelete :: MonadMPD m => PlaylistName -> Position -> m ()
- playlistMove :: MonadMPD m => PlaylistName -> Id -> Position -> 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 -> Maybe Artist -> m [Value]
- listAll :: MonadMPD m => Path -> m [Path]
- listAllInfo :: MonadMPD m => Path -> m [LsResult]
- lsInfo :: MonadMPD m => Path -> m [LsResult]
- search :: MonadMPD m => Query -> m [Song]
- update :: MonadMPD m => Maybe Path -> m Integer
- rescan :: MonadMPD m => Maybe Path -> m Integer
- 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)]
- 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)])]
- config :: MonadMPD m => m [(String, String)]
- type ChannelName = String
- type MessageText = String
- subscribe :: MonadMPD m => ChannelName -> m ()
- unsubscribe :: MonadMPD m => ChannelName -> m ()
- channels :: MonadMPD m => m [ChannelName]
- readMessages :: MonadMPD m => m [(ChannelName, MessageText)]
- sendMessage :: MonadMPD m => ChannelName -> MessageText -> m ()
Basic data types
class (Monad m, MonadError MPDError m) => MonadMPD m
A typeclass to allow for multiple implementations of a connection to an MPD server.
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)
data MPDError
The MPDError type is used to signal errors, both from the MPD and otherwise.
Constructors
NoMPD | MPD not responding |
ConnectionError IOException | An error occurred while talking to MPD. |
Unexpected String | MPD returned an unexpected response. This is a bug, either in the library or in MPD itself. |
Custom String | Used for misc. errors |
ACK ACKType String | ACK type and a message from the server |
data ACKType
Represents various MPD errors (aka. ACKs).
Constructors
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) |
Instances
Eq ACKType |
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.
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"
class ToString a where
A type class for values that can be converted to String
s.
newtype PlaylistName
Used for commands which require a playlist name. If empty, the current playlist is used.
Constructors
PlaylistName ByteString |
Instances
Eq PlaylistName | |
Show PlaylistName | |
IsString PlaylistName | |
ToString PlaylistName |
data Path
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.
type Seconds = Integer
type Decibels = Integer
data State
Represents the different playback states.
data Subsystem
Represents the various MPD subsystems.
Constructors
DatabaseS | The song database |
UpdateS | Database updates |
StoredPlaylistS | Stored playlists |
PlaylistS | The current playlist |
PlayerS | The player |
MixerS | The volume mixer |
OutputS | Audio outputs |
OptionsS | Playback options |
StickerS | Sticker database |
SubscriptionS | Subscription |
MessageS | Message on subscribed channel |
data ReplayGainMode
Instances
Eq ReplayGainMode | |
Show ReplayGainMode |
data LsResult
Result of the lsInfo operation
Constructors
LsDirectory Path | Directory |
LsSong Song | Song |
LsPlaylist PlaylistName | Playlist |
data Device
Represents an output device.
Constructors
Device | |
Fields
|
type Position = Int
The position of a song in a playlist.
data Stats
Container for database statistics.
Constructors
Stats | |
Fields
|
data Status
Container for MPD status.
Constructors
Status | |
Fields
|
def :: Default a => a
clearError :: MonadMPD m => m ()
Clear the current error message in status.
currentSong :: MonadMPD m => m (Maybe Song)
Get the currently playing song.
idle :: MonadMPD m => [Subsystem] -> m [Subsystem]
Wait until there is a noteworthy change in one or more of MPD's susbystems.
The first argument is a list of subsystems that should be considered. An empty list specifies that all subsystems should be considered.
A list of subsystems that have noteworthy changes is returned.
Note that running this command will block until either idle
returns or is
cancelled by noidle
.
replayGainMode :: MonadMPD m => ReplayGainMode -> m ()
Set the replay gain mode.
replayGainStatus :: MonadMPD m => m [(String, String)]
Get the replay gain options.
move :: MonadMPD m => Position -> Position -> m ()
Move a song to a given position in the current playlist.
moveId :: MonadMPD m => Id -> Position -> 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 [(Position, Path)]
Warning: this is deprecated; please use playlistInfo
instead.
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]
Search for songs in the current playlist with strict matching.
playlistInfo :: MonadMPD m => Maybe Position -> m [Song]
Retrieve metadata for songs in the current playlist.
playlistInfoRange :: MonadMPD m => Maybe (Position, Position) -> m [Song]
Like playlistInfo
but can restrict to a range of songs.
playlistId :: MonadMPD m => Maybe Id -> m [Song]
Displays a list of songs in the playlist. If id is specified, only its info is returned.
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 [(Position, Id)]
Like plChanges
but only returns positions and ids.
Shuffle the 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 ()
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 -> Position -> m ()
Remove a song from a playlist.
playlistMove :: MonadMPD m => PlaylistName -> Id -> Position -> m ()
Move a song to a given position in the playlist specified.
Arguments
:: MonadMPD m | |
=> PlaylistName | Original playlist |
-> PlaylistName | New playlist name |
-> m () |
Rename an existing playlist.
rm :: MonadMPD m => PlaylistName -> m ()
Delete existing playlist.
save :: MonadMPD m => PlaylistName -> m ()
Save the current playlist.
List all tags of the specified type.
listAll :: MonadMPD m => Path -> m [Path]
List the songs (without metadata) in a database directory recursively.
listAllInfo :: MonadMPD m => Path -> m [LsResult]
Recursive lsInfo
.
lsInfo :: MonadMPD m => Path -> m [LsResult]
Non-recursively list the contents of a database directory.
update :: MonadMPD m => Maybe Path -> m Integer
Update the server's database.
If no path is given, the whole library will be scanned. Unreadable or non-existent paths are silently ignored.
The update job id is returned.
Arguments
:: MonadMPD m | |
=> ObjectType | |
-> String | Object URI |
-> String | Sticker name |
-> m [String] |
Reads a sticker value for the specified object.
Arguments
:: MonadMPD m | |
=> ObjectType | |
-> String | Object URI |
-> String | Sticker name |
-> String | Sticker value |
-> m () |
Adds a sticker value to the specified object.
Arguments
:: MonadMPD m | |
=> ObjectType | |
-> String | Object URI |
-> String | Sticker name |
-> m () |
Delete a sticker value from the specified object.
Arguments
:: MonadMPD m | |
=> ObjectType | |
-> String | Object URI |
-> m [(String, String)] | Sticker name/sticker value |
Lists the stickers for the specified object.
Arguments
:: 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.
password :: MonadMPD m => String -> m ()
Send password to server to authenticate session. Password is sent as plain text.
disableOutput :: MonadMPD m => Int -> m ()
Turn off an output device.
enableOutput :: MonadMPD m => Int -> m ()
Turn on an output device.
notCommands :: MonadMPD m => m [String]
Retrieve a list of unavailable (due to access restrictions) commands.
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.
Types
type ChannelName = String
type MessageText = String
Subscribing to channels
subscribe :: MonadMPD m => ChannelName -> m ()
unsubscribe :: MonadMPD m => ChannelName -> m ()
channels :: MonadMPD m => m [ChannelName]
Communicating with other clients
readMessages :: MonadMPD m => m [(ChannelName, MessageText)]
sendMessage :: MonadMPD m => ChannelName -> MessageText -> m ()