mpd-class :: Documentation :: v1.1 :: USAGE
========================================================
* mpd.class.php - PHP Object Interface to the MPD Music Player Daemon
* USAGE Version 1.1, released 09/23/2003
* Copyright (C) 2003 Benjamin Carlisle (bcarlisle@24oz.com)
* http://mpd.24oz.com/
========================================================

[NOTES]
The following document outlines the object properties and methods of the mpd.class.php PHP class. Please note that this PHP class relies heavily on the functionality within MPD, and that this document reflects the functionality as of the current release of MPD (0.8.7).

There are other object functions/properties that are not included in this documentation. They are either unsupported, untested, or, most likely, intended for calling within the object itself. You should be able to get along fine using only what is described below.


[OBJECT INSTANTIATION]
mpd(host,port)
Object constructor. When called, it will initialize all object variables and attempt to connect using the arguments supplied. If the connection attempt succeeds, data will be retrieved from the server and all appropriate class properties will be set.
 ARGUMENTS
    host - the hostname upon which MPD is running
    port - the TCP port on which MPD is listening
 RETURNS
    mpd Object, upon success
 EXAMPLE
    $mpdObject = new mpd('localhost',2100);

[PROPERTIES]
The MPD Object, once instantiated, has the following properties:
  mpd_class_version - The current version of MPD-Class.
  connected - TRUE if it has properly connected to MPD, FALSE otherwise.
  volume - The volume setting on MPD (1-100).
  repeat - The status of the repeat (loop) flag. Either 1 (on) or 0 (off).
  mpd_version - The version string as returned by MPD.
  uptime - The number of seconds since the MPD server was started.
  playtime - The number of elapsed seconds MPD has been actively playing.
  num_songs - The number of tracks in the MPD database.
  num_artists - The number of artists in the MPD database.
  num_albums - The number of albums in the MPD database.
  playlist_count - The number of tracks in the MPD playlist.
  state - The current state of the MPD. Use constants:
     MPD_STATE_PLAYING, MPD_STATE_STOPPED, MPD_STATE_PAUSED
  num_songs_played - Number of songs played since MPD was started.
  current_track_id - The playlist index of the currently playing track.
  current_track_length - The length, in seconds, of the playing track.
  current_track_pos - The position, in elapsed seconds, of the playing track.
  errStr - The last error message returned. Empty if there was no error.
  playlist - An multidimensional array containing the current playlist.
[METHODS]
Methods available for this class have been classified into several groups.

- Mixer Control Methods - For configuring mixer settings
- Player Control Methods - For controlling playback
- Playlist Maintenence Methods - For maintaining the MPD playlist, as well as stored M3U playlists.
- Searching/Browsing Methods - For locating tracks
- MPD Control Methods - Miscellaneous MPD control
- Other/Advanced Methods - Stuff that shouldn't be necessary, but are included ;)

For the most part, you will not need the Other methods. They are included for Compatibility, as well as for use in my own code. You can do anything you need without using them, but use at your own risk!

Mixer Control Methods
SetVolume(vol) - Sets the mixer volume on the MPD to <vol>. 
  RETURNS
   NULL, upon failure
  EXAMPLE
   $mpdObject->SetVolume(75);
AdjustVolume(vol) - Adjusts the mixer volume on the MPD by <vol>. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->AdjustVolume(-20);
SetRepeat(1|0) - Sets the repeat (loop) status to 1 (ON) or 0 (OFF). 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->SetRepeat(1);
Player Control Methods
Play() - Begins playing the songs in the MPD playlist. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->Play();
Pause() - Toggles pausing on the MPD. Calling it once will pause the player, calling it again will unpause. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->Pause();
Stop() - Stops playing the MPD. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->Stop();
Next() - Skips to the next song in the MPD playlist. If not playing, returns an error. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->Next();
Previous() - Skips to the previous song in the MPD playlist. If not playing, returns an error. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->Previous();
SkipTo(idx) - Skips directly to the <idx> song in the playlist. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->SkipTo(4);
Playlist Maintenence Methods
PLAdd(file) - Adds the file <file> to the end of the playlist. <file> must be a song in the MPD database. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->PLAdd("U2 - Pride.mp3");
PLAddBulk(fileArray) - Adds each track listed in a single-dimensional <fileArray>, which contains filenames of tracks to add, to the end of the playlist. This is used to add many, many songs to the playlist in one swoop. 
   RETURNS
    NULL, upon failure adding any track.
   EXAMPLE
    $mpdObject->PLAddBulk($songArray);
PLRemove(idx) - Removes the track located at position <idx> from the playlist. This will shift the tracks behind it up one position. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->PLRemove(2);
PLClear() - Clears the playlist entirely and stops playing MPD (if appropriate). 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->PLClear();
PLSave(file) - Saves the playlist to <file>.m3u for later retrieval. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->PLSave("mysongs");
PLLoad(file) - Retrieves the playlist from <file>.m3u and loads it into the current playlist. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->PLLoad("mysongs");
PLShuffle() - Randomly reorders the songs in the playlist. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->PLShuffle();
MPD Control Methods
Shutdown() - Shuts down the MPD server (aka sends the KILL command). This closes the current connection, and prevents future communication with the server. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->Shutdown();
DBRefresh() - Causes MPD to refresh the database of its tracks. 
   RETURNS
    NULL, upon failure
   EXAMPLE
    $mpdObject->DBRefresh();
Searching/Browsing Methods
Search(type,string) - Searches the MPD database. The search <type> should be one of the following:
   MPD_SEARCH_ARTIST, MPD_SEARCH_TITLE, MPD_SEARCH_ALBUM
The search <string> is a case-insensitive locator string. Anything that contains <string> will be returned in the results. 
   RETURNS
    Array containing search results, upon success.
    NULL, upon failure
   EXAMPLE
    $results = $mpdObject->Search(MPD_SEARCH_ARTIST,"Met");
Find(type,string) - Similar to Search(), Find() looks for exact matches in the MPD database. The find <type> should be one of the following:
   MPD_SEARCH_ARTIST, MPD_SEARCH_TITLE, MPD_SEARCH_ALBUM
The find <string> is a case-insensitive locator string. Anything that exactly matches <string> will be returned in the results. 
   RETURNS
    Array containing find results, upon success.
    NULL, upon failure
   EXAMPLE
    $results = $mpdObject->Find(MPD_SEARCH_ARTIST,"Metallica");
GetDir(dir) - Retrieves a database directory listing of the <dir> directory. If no directory is specified, the directory listing is at the base of the database directory path. 
   RETURNS
    Array containing directory results, upon success.
    NULL, upon failure
   EXAMPLE
    $humorArray = $mpdObject->GetDir("Humor");
Disconnect() - Close the connection to the MPD server. 
   RETURNS
    Nothing
   EXAMPLE
    $mpdObject->Disconnect();
Other/Advanced Methods
SendCommand(cmd,arg1,arg2...) - Sends a generic command to the MPD server. Several command constants are pre-defined for use (see MPD_CMD_* constant definitions in mpd.class.php). 
   RETURNS
    String containing server response, upon success
    NULL, upon failure.
   EXAMPLE
    $response = $mpdObject->SendCommand("mycommand");
QueueCommand(cmd,arg1,arg2...) - Queues a generic command for later sending to the MPD server. The CommandQueue can hold as many commands as needed, and are sent all at once, in the order they are queued, using the SendCommandQueue() method. The syntax for queueing commands is identical to SendCommand(). 
   RETURNS
    NULL, upon failure.
    TRUE, otherwise.
   EXAMPLE
    $response = $mpdObject->QueueCommand(MPD_CMD_ADD,"myfile.mp3");
SendCommandQueue() - Sends all commands in the Command Queue to the MPD server. 
   RETURNS
    NULL, upon the failure of any command in the queue.
    TRUE, otherwise.
   EXAMPLE
    $mpdObject->QueueCommand(MPD_CMD_ADD,"myfile.mp3");
	$mpdObject->QueueCommand(MPD_CMD_VOL,"+20");
	$mpdObject->SendCommandQueue();
RefreshInfo() - Retrieves all object data from the MPD and stores it in each of the object properties. Note: As of version 1.1, this is automatically called upon initial connection to the MPD server; there is little need to use it. 
 RETURNS
   TRUE, upon success
   NULL, upon failure
 EXAMPLE
   $mpdObject->RefreshInfo();
Copyright 2003-2004 © B. Carlisle