API Versions: {Current Stable (3.4.x)} {Development (3.5.x)}
Compatible Versions: >= 350001
Ampache Provides an API for pulling out it's meta data in the form of simple XML documents. This was originally created for use by Amarok, but there is no reason it couldn't be used to create other front-ends to the Ampache data. Access to the API is controlled by the Internal Access Control Lists. The KEY defined in the ACL is the passphrase that must be used to establish an API session. Currently all requests are limited to a maximum of 5000 results for performance reasons. To get additional results pass offset as an additional parameter. If you have any questions or requests for this API please submit a Feature Request.
The handshake is a combination of the following three things
The key that must be passed to Ampache is SHA256(TIME+KEY) where KEY is SHA256('PASSWORD'). Below is a PHP example
$time = time();
$key = hash('sha256','mypassword');
$passphrase = hash('sha256',$time . $key);
Once you've generated the encoded call the following URL localhost/ampache is the location of your Ampache installation
http://localhost/ampache/server/xml.server.php?action=handshake&auth=$passphrase×tamp=$timestamp&version=350001&user=vollmerk
If your Password, IP and Username match a row in the Access List the following will be returned
<root>
<auth>AUTHENTICATION TOKEN</auth>
<version>APIVERSION</version>
<update>Last Update RFC2822 Date</update>
<add>Last Add RFC2822 Date</add>
<songs>Total # of Songs</songs>
<artists>Total # of Artists</artists>
<albums>Total # of Albums</albums>
<tags>Total # of Tags</tags>
</root>
All future interactions with the Ampache API must include the TOKEN as a get variable named 'AUTH'.
All errors will be returned as an XML document as specified in the XMLAPI Error Document. When possible the text part of the message will be translated into the users configured language.
All methods must be passed as action=METHODNAME. All methods except the handshake can take an optional offset=XXX and limit=XXX. The limit determines the maximum number of results returned. The offset will tell Ampache where to start in the result set. For Example if there are 100 total results and you set the Offset to 50, and the limit to 50 Ampache will return results 50 - 100. The default limit is 5000. The default offset is 0
For the purpose of this example the Ampache host is 'localhost' and the path to Ampache is /ampache
Requesting all genres who's name starts with Rock
http://localhost/ampache/server/xml.server.php?action=genres&auth=1234567890123456789012345678901&filter=Rock
Requesting all song titles, with an offset of 5000
localhost/ampache/server/xml.server.php?action=songs&auth=12345678901234567890123456789012&offset=5000
All XML Documents that have a <tag> element may have 0 or more tag elements associated with them. Each tag element has an attribute count that indicates the number of people who have specified this tag.
Artists XML Document. ID's are Ampache's unique Identifier for the artist.
<root>
<artist id="12039">
<name>Metallica</name>
<albums># of Albums</albums>
<songs># of Songs</songs>
<tag id="2481" count="2">Rock & Roll</tag>
<tag id="2482" count="1">Rock</tag>
<tag id="2483" count="1">Roll</tag>
</artist>
<artist id="129348">
<name>AC/DC</name>
<albums># of Albums</albums>
<songs># of Songs</songs>
<tag id="2481" count="2">Rock & Roll</tag>
<tag id="2482" count="2">Rock</tag>
<tag id="2483" count="1">Roll</tag>
</artist>
</root>
Album XML Document. ID's are Ampache's unique identifier for the album and artist associated.
<root>
<album id="2910">
<name>Back in Black</name>
<artist id="129348">AC/DC</artist>
<year>1984</year>
<tracks>12</tracks>
<disk>1</disk>
<tag id="2481" count="2">Rock & Roll</tag>
<tag id="2482" count="1">Rock</tag>
<tag id="2483" count="1">Roll</tag>
<art>http://localhost/image.php?id=129348</art>
</album>
</root>
Single Song XML document, includes references to its parent objects.
<root>
<song id="3180">
<title>Hells Bells</title>
<artist id="129348">AC/DC</artist>
<album id="2910">Back in Black</album>
<tag id="2481" count="3">Rock & Roll</tag>
<tag id="2482" count="1">Rock</tag>
<tag id="2483" count="1">Roll</tag>
<track>4</track>
<time>234</time>
<url>http://localhost/play/index.php?song=123908</url>
<size>Song Filesize in Bytes</size>
<art>http://localhost/image.php?id=129348</art>
<preciserating>3</preciserating>
<rating>2.9</rating>
</song>
</root>
Tag XML Document, includes counts for it's child objects
<root>
<tag id="2481">
<name>Rock & Roll</name>
<albums>84</albums>
<artists>29</artists>
<songs>239</songs>
</tag>
</root>
Playlist XML Document, includes counts for it's child objects
<root>
<playlist id="1234">
<name>The Good Stuff</name>
<owner>Karl Vollmer</owner>
<items>50</items>
<tag id="2481" count="2">Rock & Roll</tag>
<tag id="2482" count="2">Rock</tag>
<tag id="2483" count="1">Roll</tag>
<type>Public</type>
</playlist>
</root>