-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | An MPD client library.
--   
--   A client library for MPD, the Music Player Daemon
--   (<a>http://www.musicpd.org/</a>).
@package libmpd
@version 0.2.1


-- | An MPD client library. MPD is a daemon for playing music that is
--   controlled over a network socket. Its site is at
--   <a>http://www.musicpd.org/</a>.
module Network.MPD

-- | The MPD monad is basically a reader and error monad combined.
--   
--   To use the error throwing/catching capabilities:
--   
--   <pre>
--   import Control.Monad.Error
--   </pre>
--   
--   To run IO actions within the MPD monad:
--   
--   <pre>
--   import Control.Monad.Trans
--   </pre>
data MPD a

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

-- | MPD not responding
NoMPD :: MPDError

-- | The connection timed out
TimedOut :: MPDError

-- | MPD returned an unexpected response. This is a bug, either in the
--   library or in MPD itself.
Unexpected :: String -> MPDError

-- | Used for misc. errors
Custom :: String -> MPDError

-- | ACK type and a message from the server
ACK :: ACKType -> String -> MPDError

-- | Represents various MPD errors (aka. ACKs).
data ACKType

-- | Invalid argument passed (ACK 2)
InvalidArgument :: ACKType

-- | Invalid password supplied (ACK 3)
InvalidPassword :: ACKType

-- | Authentication required (ACK 4)
Auth :: ACKType

-- | Unknown command (ACK 5)
UnknownCommand :: ACKType

-- | File or directory not found ACK 50)
FileNotFound :: ACKType

-- | Playlist at maximum size (ACK 51)
PlaylistMax :: ACKType

-- | A system error (ACK 52)
System :: ACKType

-- | Playlist loading failed (ACK 53)
PlaylistLoad :: ACKType

-- | Update already running (ACK 54)
Busy :: ACKType

-- | An operation requiring playback got interrupted (ACK 55)
NotPlaying :: ACKType

-- | File already exists (ACK 56)
FileExists :: ACKType

-- | An unknown ACK (aka. bug)
UnknownACK :: ACKType

-- | A response is either an <a>MPDError</a> or some result.
type Response a = Either MPDError a

-- | A wrapper for <a>withMPDEx</a> 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:
--   
--   <pre>
--   withMPD $ play Nothing
--   withMPD $ add_ "" "tool" &gt;&gt; play Nothing &gt;&gt; currentSong
--   </pre>
withMPD :: MPD a -> IO (Response a)

-- | Run an MPD action against a server.
withMPDEx :: String -> Integer -> IO (Maybe String) -> MPD a -> IO (Response a)

-- | Represents the different playback states.
data State
Playing :: State
Stopped :: State
Paused :: State

-- | Container for MPD status.
data Status
Status :: State -> Int -> Bool -> Bool -> Integer -> Integer -> Maybe PLIndex -> Maybe PLIndex -> (Seconds, Seconds) -> Int -> Seconds -> (Int, Int, Int) -> Integer -> String -> Status
stState :: Status -> State

-- | A percentage (0-100)
stVolume :: Status -> Int
stRepeat :: Status -> Bool
stRandom :: Status -> Bool

-- | A value that is incremented by the server every time the playlist
--   changes.
stPlaylistVersion :: Status -> Integer

-- | The number of items in the current playlist.
stPlaylistLength :: Status -> Integer

-- | Current song's position in the playlist.
stSongPos :: Status -> Maybe PLIndex

-- | Current song's playlist ID.
stSongID :: Status -> Maybe PLIndex

-- | Time elapsed/total time.
stTime :: Status -> (Seconds, Seconds)

-- | Bitrate (in kilobytes per second) of playing song (if any).
stBitrate :: Status -> Int

-- | Crossfade time.
stXFadeWidth :: Status -> Seconds

-- | Samplerate/bits/channels for the chosen output device (see mpd.conf).
stAudio :: Status -> (Int, Int, Int)

-- | Job ID of currently running update (if any).
stUpdatingDb :: Status -> Integer

-- | Last error message (if any).
stError :: Status -> String

-- | Container for database statistics.
data Stats
Stats :: Integer -> Integer -> Integer -> Seconds -> Seconds -> Seconds -> Integer -> Stats

-- | Number of artists.
stsArtists :: Stats -> Integer

-- | Number of albums.
stsAlbums :: Stats -> Integer

-- | Number of songs.
stsSongs :: Stats -> Integer

-- | Daemon uptime in seconds.
stsUptime :: Stats -> Seconds

-- | Total playing time.
stsPlaytime :: Stats -> Seconds

-- | Total play time of all the songs in the database.
stsDbPlaytime :: Stats -> Seconds

-- | Last database update in UNIX time.
stsDbUpdate :: Stats -> Integer

-- | Represents an output device.
data Device
Device :: Int -> String -> Bool -> Device

-- | Output's ID number
dOutputID :: Device -> Int

-- | Output's name as defined in the MPD configuration file
dOutputName :: Device -> String
dOutputEnabled :: Device -> Bool

-- | A query is composed of a scope modifier and a query string.
--   
--   To match entries where album equals "Foo", use:
--   
--   <pre>
--   Query Album "Foo"
--   </pre>
--   
--   To match entries where album equals "Foo" and artist equals "Bar",
--   use:
--   
--   <pre>
--   MultiQuery [Query Album "Foo", Query Artist "Bar"]
--   </pre>
data Query

-- | Simple query.
Query :: Meta -> String -> Query

-- | Query with multiple conditions.
MultiQuery :: [Query] -> Query

-- | Available metadata types/scope modifiers, used for searching the
--   database for entries with certain metadata values.
data Meta
Artist :: Meta
Album :: Meta
Title :: Meta
Track :: Meta
Name :: Meta
Genre :: Meta
Date :: Meta
Composer :: Meta
Performer :: Meta
Disc :: Meta
Any :: Meta
Filename :: Meta
type Artist = String
type Album = String
type Title = String
type Seconds = Integer

-- | Used for commands which require a playlist name. If empty, the current
--   playlist is used.
type PlaylistName = String

-- | Used for commands which require a path within the database. If empty,
--   the root path is used.
type Path = String

-- | Represents a song's playlist index.
data PLIndex

-- | A playlist position index (starting from 0)
Pos :: Integer -> PLIndex

-- | A playlist ID number that more robustly identifies a song.
ID :: Integer -> PLIndex

-- | Represents a single song item.
data Song
Song :: String -> String -> String -> String -> String -> String -> String -> String -> Seconds -> Int -> (Int, Int) -> (Int, Int) -> Maybe PLIndex -> Song
sgArtist :: Song -> String
sgAlbum :: Song -> String
sgTitle :: Song -> String
sgFilePath :: Song -> String
sgGenre :: Song -> String
sgName :: Song -> String
sgComposer :: Song -> String
sgPerformer :: Song -> String

-- | Length in seconds
sgLength :: Song -> Seconds

-- | Year
sgDate :: Song -> Int

-- | Track number/total tracks
sgTrack :: Song -> (Int, Int)

-- | Position in set/total in set
sgDisc :: Song -> (Int, Int)
sgIndex :: Song -> Maybe PLIndex

-- | Represents the result of running <tt>count</tt>.
data Count
Count :: Integer -> Seconds -> Count

-- | Number of songs matching the query
cSongs :: Count -> Integer

-- | Total play time of matching songs
cPlaytime :: Count -> Seconds

-- | Turn off an output device.
disableOutput :: Int -> MPD ()

-- | Turn on an output device.
enableOutput :: Int -> MPD ()

-- | Kill the server. Obviously, the connection is then invalid.
kill :: MPD ()

-- | Retrieve information for all output devices.
outputs :: MPD [Device]

-- | Update the server's database. If no paths are given, all paths will be
--   scanned. Unreadable or non-existent paths are silently ignored.
update :: [Path] -> MPD ()

-- | Search the database for entries exactly matching a query.
find :: Query -> MPD [Song]

-- | List all metadata of metadata (sic).
list :: Meta -> Maybe Query -> MPD [String]

-- | List the songs (without metadata) in a database directory recursively.
listAll :: Path -> MPD [Path]

-- | Recursive <a>lsInfo</a>.
listAllInfo :: Path -> MPD [Either Path Song]

-- | Non-recursively list the contents of a database directory.
lsInfo :: Path -> MPD [Either Path Song]

-- | Search the database using case insensitive matching.
search :: Query -> MPD [Song]

-- | Count the number of entries matching a query.
count :: Query -> MPD Count

-- | Like <a>add_</a> but returns a list of the files added.
add :: PlaylistName -> Path -> MPD [Path]

-- | 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.
add_ :: PlaylistName -> Path -> MPD ()

-- | Like <a>add</a>, but returns a playlist id.
addId :: Path -> MPD Integer

-- | Clear a playlist. Clears current playlist if no playlist is specified.
--   If the specified playlist does not exist, it will be created.
clear :: PlaylistName -> MPD ()

-- | Get the currently playing song.
currentSong :: MPD (Maybe Song)

-- | Remove a song from a playlist. If no playlist is specified, current
--   playlist is used. Note that a playlist position (<a>Pos</a>) is
--   required when operating on playlists other than the current.
delete :: PlaylistName -> PLIndex -> MPD ()

-- | Load an existing playlist.
load :: PlaylistName -> MPD ()

-- | Move a song to a given position. Note that a playlist position
--   (<a>Pos</a>) is required when operating on playlists other than the
--   current.
move :: PlaylistName -> PLIndex -> Integer -> MPD ()

-- | Retrieve metadata for songs in the current playlist.
playlistInfo :: Maybe PLIndex -> MPD [Song]

-- | Retrieve a list of files in a given playlist.
listPlaylist :: PlaylistName -> MPD [Path]

-- | Retrieve metadata for files in a given playlist.
listPlaylistInfo :: PlaylistName -> MPD [Song]

-- | 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
--   <a>playlistInfo</a> instead.
playlist :: MPD [(PLIndex, Path)]

-- | Retrieve a list of changed songs currently in the playlist since a
--   given playlist version.
plChanges :: Integer -> MPD [Song]

-- | Like <a>plChanges</a> but only returns positions and ids.
plChangesPosId :: Integer -> MPD [(PLIndex, PLIndex)]

-- | Search for songs in the current playlist with strict matching.
playlistFind :: Query -> MPD [Song]

-- | Search case-insensitively with partial matches for songs in the
--   current playlist.
playlistSearch :: Query -> MPD [Song]

-- | Delete existing playlist.
rm :: PlaylistName -> MPD ()

-- | Rename an existing playlist.
rename :: PlaylistName -> PlaylistName -> MPD ()

-- | Save the current playlist.
save :: PlaylistName -> MPD ()

-- | Shuffle the playlist.
shuffle :: MPD ()

-- | Swap the positions of two songs. Note that the positions must be of
--   the same type, i.e. mixing <a>Pos</a> and <a>ID</a> will result in a
--   no-op.
swap :: PLIndex -> PLIndex -> MPD ()

-- | Set crossfading between songs.
crossfade :: Seconds -> MPD ()

-- | Play the next song.
next :: MPD ()

-- | Pause playing.
pause :: Bool -> MPD ()

-- | Begin/continue playing.
play :: Maybe PLIndex -> MPD ()

-- | Play the previous song.
previous :: MPD ()

-- | Set random playing.
random :: Bool -> MPD ()

-- | Set repeating.
repeat :: Bool -> MPD ()

-- | Seek to some point in a song. Seeks in current song if no position is
--   given.
seek :: Maybe PLIndex -> Seconds -> MPD ()

-- | Set the volume (0-100 percent).
setVolume :: Int -> MPD ()

-- | 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 <a>setVolume</a> instead.
volume :: Int -> MPD ()

-- | Stop playing.
stop :: MPD ()

-- | Clear the current error message in status.
clearError :: MPD ()

-- | Close an MPD connection.
close :: MPD ()

-- | Retrieve a list of available commands.
commands :: MPD [String]

-- | Retrieve a list of unavailable (due to access restrictions) commands.
notCommands :: MPD [String]

-- | Send password to server to authenticate session. Password is sent as
--   plain text.
password :: String -> MPD ()

-- | Check that the server is still responding.
ping :: MPD ()

-- | Refresh a connection.
reconnect :: MPD ()

-- | Get server statistics.
stats :: MPD Stats

-- | Get the server's status.
status :: MPD Status

-- | Retrieve a list of available song metadata.
tagTypes :: MPD [String]

-- | Retrieve a list of supported urlhandlers.
urlHandlers :: MPD [String]

-- | Add a list of songs/folders to a playlist. Should be more efficient
--   than running <a>add</a> many times.
addMany :: PlaylistName -> [Path] -> MPD ()

-- | 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
--   <a>prune</a> for this).
deleteMany :: PlaylistName -> [PLIndex] -> MPD ()

-- | Returns all songs and directories that match the given partial path
--   name.
complete :: String -> MPD [Either Path Song]

-- | Crop playlist. The bounds are inclusive. If <a>Nothing</a> or
--   <a>ID</a> is passed the cropping will leave your playlist alone on
--   that side.
crop :: Maybe PLIndex -> Maybe PLIndex -> MPD ()

-- | Remove duplicate playlist entries.
prune :: MPD ()

-- | List directories non-recursively.
lsDirs :: Path -> MPD [Path]

-- | List files non-recursively.
lsFiles :: Path -> MPD [Path]

-- | List all playlists.
lsPlaylists :: MPD [PlaylistName]

-- | Search the database for songs relating to an artist.
findArtist :: Artist -> MPD [Song]

-- | Search the database for songs relating to an album.
findAlbum :: Album -> MPD [Song]

-- | Search the database for songs relating to a song title.
findTitle :: Title -> MPD [Song]

-- | List the artists in the database.
listArtists :: MPD [Artist]

-- | List the albums in the database, optionally matching a given artist.
listAlbums :: Maybe Artist -> MPD [Album]

-- | List the songs in an album of some artist.
listAlbum :: Artist -> Album -> MPD [Song]

-- | Search the database for songs relating to an artist using
--   <a>search</a>.
searchArtist :: Artist -> MPD [Song]

-- | Search the database for songs relating to an album using
--   <a>search</a>.
searchAlbum :: Album -> MPD [Song]

-- | Search the database for songs relating to a song title.
searchTitle :: Title -> MPD [Song]

-- | Retrieve the current playlist. Equivalent to <tt>playlistinfo
--   Nothing</tt>.
getPlaylist :: MPD [Song]

-- | Toggles play/pause. Plays if stopped.
toggle :: MPD ()

-- | Like <a>update</a>, but returns the update job id.
updateId :: [Path] -> MPD Integer