[% pageicon = 'help' %] [% pagetitle = 'XML skin' %] [% techinfo = '1' %] [% PROCESS helpheader.html %]

#### Overview

This document describes the XML skin, that allows the SlimServer to return XML instead of HTML. It is designed to enable the integration of the SlimServer with third party automation tools, such as AMX/Crestron touchpanels, or other "home grown" solutions.

The XML skin only changes what is returned by the Server, and not its interface. Please refer to The SlimServer Web Interface documentation.

#### Usage

Because it is of no interest to human beings, this skin is hidden from the skin list available in the Server preferences. To enable the skin, use URLs with this general form:

    http://server:port/xml/page.xml?parameter=value&...

where `server`, `port`, `page`, and `parameter` must be replaced by appropriate values. For example, to browse the music library (in the following examples, the SlimServer is running on a computer with the IP address of 10.0.1.201 using the default port 9000):

    http://10.0.1.201:9000/xml/browse.xml

The following values are possible for `page`:

- `browse.xml`, to browse the music library following its directory structure
- `browseid3.xml`, to browse the music library following its tag structure (genre, artist, album)
- `search.xml`, to search for artists, album or songs
- `songinfo.xml`, to get the full information on a song
- `status.xml`, to get a player status and its current playlist, if any
- `hitlist.xml`, to get the statistics maintained by the server

For example (result edited for brevity):

    http://10.0.1.201:9000/xml/browse.xml

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE browse SYSTEM "html/slimserver_xml.dtd">
    <browse xmlns="http://www.slimdevices.com/slimserver/xml">
      <offsets>
        <from>0</from>
        <to>7</to>
        <last>194</last>
      </offsets>
      <browse_entry>
        <dir>
          <dir_name>A-Ha</dir_name>
          <dir_browse_url><![CDATA[xml/browse.xml?dir=A-Ha]]></dir_browse_url>
        </dir>
        <replace_url>
          <![CDATA[xml/status.xml?p0=playlist&p1=load&p2=%2fVolumes%2fiMusic%2fiTunes%2fiTunes%20Music%2fA-Ha]]>
        </replace_url>
        <append_url>
          <![CDATA[xml/status.xml?p0=playlist&p1=add&p2=%2fVolumes%2fiMusic%2fiTunes%2fiTunes%20Music%2fA-Ha]]>
        </append_url>
      </browse_entry>
      ...
    </browse>

#### General parameters

The following parameters are applicable to all pages that return many items (potentially all pages except `songinfo.xml`):

- `itemsPerPage=number`, to indicate how many items to return. This way, the Server can be set up with a "human acceptable" value for this setting (say, 100), while a limited automation device can request pages containing only, say, 10 items.
- `start=number`, to indicate which is the first item in the page, useful in conjunction with `itemsPerPage`. This value is an offset, i.e. the first item is 0, and the last `itemsPerPage-1`. Each page returns its position in the entire list; see the `offsets` tag in the example above.

The example above could have been requested as `http://10.0.1.201:9000/xml/ browse.xml?itemsPerPage=8&start=0`.

The following parameter must be added to the page `status.xml`:

- `player=player_id`, to indicate which player we're talking about. If absent, the Server will randomly choose a player.

##### The `include.html` file

The following parameters are set in the XML skin `include.html` file:

- `[SET nopagebar 0]`, to prevent the generation of pagebars. Do not set this to 1 or "ugly" HTML will appear in the XML.
- `[SET includeItemStats 0]`, to prevent the statistics calculations.

If desired, `[SET itemsPerPage number]` could be added instead of adding it to every URL. If a single player is automated, `[SET player player_id]` could be another option.

Be aware that this file is within the Server software release. Any changes will be overwritten by any upgrade to the Server software.

#### Pages parameters

An efficient client can be implemented without knowing much about parameters, as the XML includes special tags (ending in `_url`) containing "links". In our example above, in order to browse the directory "A-Ha", one simply requests the URL indicated by the `dir_browse_url`. Similar tags exists for most operations. The `player` parameter must be added to any URL targetting a player, such as `replace_url` above.

##### `search.xml` parameters

The following parameters must be provided:

- `type=artist` or `type=album` or `type=song`, to search artists, albums or songs, respectively.
- `query=A_WORD+ANOTHER_WORD+...`, to indicate the string searched. Words must be correctly escaped as URL rules dictate and separated by `+`.

##### `hitlist.xml` parameters

`hitlist.xml` takes no parameters.

##### Other pages parameters

Please refer to The SlimServer Web Interface documentation for parameters to the `status.xml` page. Discovering the parameters of the other pages is left as an exercise to the reader.

PS: Seriously, the only way for a client to discover the value of parameters to `browse.xml`, `browseid3.xml` and `songinfo.xml` is to use the XML interface to browse the library in the first place. Therefore, the links will have been calculated for you already in the `_url` tags!.

#### The DTD

The XML skin comes with a heavily commented DTD, indicated in `DOCTYPE` and that can be served by the SlimServer. Please refer to it for more information on the various tags returned.

#### Limitations

The skin does not support:

1. Moodlogic URLs (because I have no way to test and I am unsure how "automated" the Moodlogic software is)
2. Configuring the server and player
3. Item statistics (i.e. this genre includes "12 albums with 130 songs by 10 artists") (`[SET includeItemStats 0]` in include.html)

[% PROCESS helpfooter.html %]