mirror of
https://github.com/Yetangitu/ampache
synced 2025-10-05 02:39:47 +02:00
378 lines
10 KiB
Text
378 lines
10 KiB
Text
========================================================
|
|
* mpd.class.php - PHP Object Interface to the MPD Music Player Daemon
|
|
* USAGE Version 1.2, released 05/05/2004
|
|
* Copyright (C) 2003-2004 Benjamin Carlisle (bcarlisle@24oz.com)
|
|
* http://mpd.24oz.com/ | http://www.musicpd.org/
|
|
========================================================
|
|
|
|
[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.10.3).
|
|
|
|
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,[password])
|
|
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.
|
|
Note: if you're using MPD with a password, you must supply a password with at least read
|
|
access to properly connect.
|
|
|
|
|
|
ARGUMENTS
|
|
host - the hostname upon which MPD is running
|
|
port - the TCP port on which MPD is listening
|
|
password (optional) - Authentication password for MPD server
|
|
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.
|
|
mpd_version - The version string as returned by MPD.
|
|
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).
|
|
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
|
|
Disconnect() -
|
|
Close the connection to the MPD server.
|
|
|
|
RETURNS
|
|
Nothing
|
|
EXAMPLE
|
|
$mpdObject->Disconnect();
|
|
|
|
|
|
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");
|
|
|
|
|
|
GetArtists() -
|
|
Retrieves a list of all artists in the database.
|
|
|
|
RETURNS
|
|
Array single-dimensional containing the list of artists, upon success.
|
|
NULL, upon failure
|
|
EXAMPLE
|
|
$artistArray = $mpdObject->GetArtists();
|
|
|
|
|
|
GetAlbums([artist]) -
|
|
Retrieves a list of all albums in the database by a particular <artist> If no
|
|
artist is specified, all albums in the database are returned.
|
|
|
|
RETURNS
|
|
Array single-dimensional containing list of albums, upon success.
|
|
NULL, upon failure
|
|
EXAMPLE
|
|
$allAlbumArray = $mpdObject->GetAlbums();
|
|
|
|
|
|
|
|
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();
|
|
|
|
|
|
|
|
|
|
|