libmpd-0.4.0: An MPD client library.

Stabilityalpha
MaintainerJoachim Fasting <joachim.fasting@gmail.com>

Network.MPD

Contents

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

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.

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)

data MPDError Source

The MPDError type is used to signal errors, both from the MPD and otherwise.

Constructors

NoMPD

MPD not responding

TimedOut

The connection timed out

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 Source

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

type Response = Either MPDErrorSource

A response is either an MPDError or some result.

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.

type Path = StringSource

Used for commands which require a path within the database. If empty, the root path is used.

data Meta Source

Available metadata types/scope modifiers, used for searching the database for entries with certain metadata values.

Instances

Show Meta 
MPDArg Meta 

data ObjectType Source

Object types.

Constructors

SongObj 

Instances

data PLIndex Source

Represents a song's playlist index.

Constructors

Pos Integer

A playlist position index (starting from 0)

ID Integer

A playlist ID number that more robustly identifies a song.

Instances

data State Source

Represents the different playback states.

Constructors

Playing 
Stopped 
Paused 

Instances

data Subsystem Source

Represents the various MPD subsystems.

Constructors

Database

The song database

Update

Database updates

StoredPlaylist

Stored playlists

Playlist

The current playlist

Player

The player

Mixer

The volume mixer

Output

Audio outputs

Options

Playback options

Instances

data ReplayGainMode Source

Constructors

Off

Disable replay gain

TrackMode

Per track mode

AlbumMode

Per album mode

data Count Source

Represents the result of running count.

Constructors

Count 

Fields

cSongs :: Integer

Number of songs matching the query

cPlaytime :: Seconds

Total play time of matching songs

Instances

data Device Source

Represents an output device.

Constructors

Device 

Fields

dOutputID :: Int

Output's ID number

dOutputName :: String

Output's name as defined in the MPD configuration file

dOutputEnabled :: Bool
 

Instances

data Stats Source

Container for database statistics.

Constructors

Stats 

Fields

stsArtists :: Integer

Number of artists.

stsAlbums :: Integer

Number of albums.

stsSongs :: Integer

Number of songs.

stsUptime :: Seconds

Daemon uptime in seconds.

stsPlaytime :: Seconds

Total playing time.

stsDbPlaytime :: Seconds

Total play time of all the songs in the database.

stsDbUpdate :: Integer

Last database update in UNIX time.

Instances

data Song Source

Represents a single song item.

Constructors

Song

Auxiliary song fields

Fields

sgArtist :: String
 
sgAlbum :: String
 
sgTitle :: String
 
sgFilePath :: String
 
sgGenre :: String
 
sgName :: String
 
sgComposer :: String
 
sgPerformer :: String
 
sgLength :: Seconds

Length in seconds

sgDate :: Int

Year

sgTrack :: (Int, Int)

Track number/total tracks

sgDisc :: Maybe (Int, Int)

Position in set/total in set

sgIndex :: Maybe PLIndex
 
sgAux :: [(String, String)]
 

Instances

data Status Source

Container for MPD status.

Constructors

Status 

Fields

stState :: State
 
stVolume :: Int

A percentage (0-100)

stRepeat :: Bool
 
stRandom :: Bool
 
stPlaylistVersion :: Integer

A value that is incremented by the server every time the playlist changes.

stPlaylistLength :: Integer

The number of items in the current playlist.

stSongPos :: Maybe PLIndex

Current song's position in the playlist.

stSongID :: Maybe PLIndex

Current song's playlist ID.

stNextSongPos :: Maybe PLIndex

Next song's position in the playlist.

stNextSongID :: Maybe PLIndex

Next song's playlist ID.

stTime :: (Seconds, Seconds)

Time elapsed/total time.

stBitrate :: Int

Bitrate (in kilobytes per second) of playing song (if any).

stXFadeWidth :: Seconds

Crossfade time.

stAudio :: (Int, Int, Int)

Samplerate/bits/channels for the chosen output device (see mpd.conf).

stUpdatingDb :: Integer

Job ID of currently running update (if any).

stSingle :: Bool

If True, MPD will play only one song and stop after finishing it.

stConsume :: Bool

If True, a song will be removed after it has been played.

stError :: String

Last error message (if any).

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"

Instances

(=?) :: Meta -> 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 :: (Functor m, MonadMPD m) => m (Maybe Song)Source

Get the currently playing song.

idle :: MonadMPD m => m [Subsystem]Source

Wait until there is a noteworthy change in one or more of MPD's susbystems. Note that running this command will block until either idle returns or is cancelled by noidle.

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 PLIndex -> m ()Source

Begin/continue playing.

previous :: MonadMPD m => m ()Source

Play the previous song.

seek :: MonadMPD m => Maybe PLIndex -> Seconds -> m ()Source

Seek to some point in a song. Seeks in current song if no position is given.

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

Arguments

:: MonadMPD m 
=> Path 
-> Maybe Integer

Optional playlist position

-> m Integer 

Like add, but returns a playlist id.

clear :: MonadMPD m => m ()Source

Clear the current playlist.

delete :: MonadMPD m => PLIndex -> m ()Source

Remove a song from the current playlist.

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.

shuffleSource

Arguments

:: MonadMPD m 
=> Maybe (Int, Int)

Optional range (start, end)

-> m () 

Shuffle the playlist.

swap :: MonadMPD m => PLIndex -> PLIndex -> m ()Source

Swap the positions of two songs. Note that the positions must be of the same type, i.e. mixing Pos and ID will result in a no-op.

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

Arguments

:: 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.

renameSource

Arguments

:: 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

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

Arguments

:: MonadMPD m 
=> Meta

Metadata 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.

lsInfo :: MonadMPD m => Path -> m [Either Path Song]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

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Object URI

-> String

Sticker name

-> m [String] 

Reads a sticker value for the specified object.

stickerSetSource

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Object URI

-> String

Sticker name

-> String

Sticker value

-> m () 

Adds a sticker value to the specified object.

stickerDeleteSource

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Object URI

-> String

Sticker name

-> m () 

Delete a sticker value from the specified object.

stickerListSource

Arguments

:: MonadMPD m 
=> ObjectType 
-> String

Object URI

-> m [(String, String)]

Sticker name/sticker value

Lists the stickers for the specified object.

stickerFindSource

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.

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 [Device]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.

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.

crop :: MonadMPD m => Maybe PLIndex -> Maybe PLIndex -> m ()Source

Crop playlist. The bounds are inclusive. If Nothing is passed the cropping will leave your playlist alone on that side. Using ID will automatically find the absolute playlist position and use that as the cropping boundary.

prune :: MonadMPD m => m ()Source

Remove duplicate playlist entries.

lsDirs :: MonadMPD m => Path -> m [Path]Source

List directories non-recursively.

lsFiles :: MonadMPD m => Path -> m [Path]Source

List files non-recursively.

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.

toggle :: MonadMPD m => m ()Source

Toggles play/pause. Plays if stopped.

updateId :: MonadMPD m => [Path] -> m IntegerSource

Like update, but returns the update job id.

volume :: MonadMPD m => Int -> m ()Source

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.