<!-- ....................................................................... -->
<!-- slimserver_xml.dtd .................................................... -->
<!-- SlimServer Copyright (C) 2003-2004 Slim Devices Inc.  ................. -->
<!-- ....................................................................... -->

<!--
This DTD describes the data returned by the SlimServer XML skin.

NOTES: 
- URLs returned are already URL escaped. You must escape any element you add,
  however.
- JIC in the comments means Just In Case and relates to information given
  for the sake of completeness with no idea to what it could be used for.
- Skin file information given in the comments is useful for the skin
  development but can be ignored by the skin user.
-->


<!-- ....................................................................... -->
<!-- Status ................................................................ -->
<!-- .......................................................................
Element returned by status.xml requests. Describe a player status and 
the playlist of this player. Also returns info about all the players 
known by the server.
Status.xml uses the player parameter to determine which player to return info
on. If player is absent or wrong, the server will select a player at random.
-->
<!-- (Skin file: status.html) .............................................. -->
<!-- Players known to the server         -->
<!-- Status of the player                -->
<!-- Playlist of the player              -->
<!ELEMENT status (	players, 		
					player_status?, 
					playlist?		
				 )>
				 
				 <!-- Number of players available         -->
				 <!-- <player> element for each player    -->
<!ELEMENT players (	playercount, 	
					player*			
				   )>
				   
<!ELEMENT playercount (#PCDATA)>	<!-- Number of players available         -->

<!-- NOTE: 
The number of <player> elements in <players> is equal to playercount
unless there are synchonized players, which appear only once in the list
as a group.
If there is no player defined on the Server, playercount is 0.
-->
		
<!ELEMENT player (	is_described?,	
					player_id, 		
					player_name?
				  )>
				  
<!ELEMENT is_described EMPTY>		<!-- This page is about this player      -->
<!ELEMENT player_id    (#PCDATA)>	<!-- Player identifier (MAC address)     -->
<!ELEMENT player_name  (#PCDATA)>	<!-- Name of the player if defined       -->

 		<!-- playing, stopping, info     -->
 		<!-- shuffle status              -->
 		<!-- repeat mode                 -->
 		<!-- volume & tone controls      -->
 		<!-- the song being played now   -->
 		
<!ELEMENT player_status	(	transport,
							shuffle, 		
							repeat, 		
							audio,          
							current_song?   
						)>

<!ELEMENT transport	(	mode, 
						playmode,
						play_url?, 
						pause_url?, 
						stop_url?, 
						play_prev_url?, 
						play_next_url?, 
						rate?,
						rateval?
					)>			
<!ELEMENT mode 			(#PCDATA)>	
<!-- Player internal mode. The value "off" can be used to check if the player
is off
-->

<!ELEMENT playing 		EMPTY>		<!-- Player is playing                   -->
<!ELEMENT paused 		EMPTY>		<!-- Player is paused                    -->
<!ELEMENT stopped 		EMPTY>		<!-- Player is stopped                   -->
<!ELEMENT playmode 	    (#PCDATA)>	<!-- the play mode, but inside a tag     -->

<!ELEMENT play_url 		(#PCDATA)>
<!-- URL to start playing the current playlist. Use URLs in browse pages to 
change the playlist.
--> 
<!ELEMENT pause_url 	(#PCDATA)>	<!-- URL to pause the player             -->
<!ELEMENT stop_url 		(#PCDATA)>	<!-- URL to stop the player              -->
<!ELEMENT play_prev_url (#PCDATA)>	<!-- Skip forward                        -->
<!ELEMENT play_next_url (#PCDATA)>	<!-- Skip backward                       -->
<!ELEMENT rate 			(#PCDATA)>  <!-- Playing rate (ffwd, rwd, norm)      -->
<!ELEMENT rateval		(#PCDATA)>  <!-- Playing rate (as a float, 1.0 is play)-->
<!ELEMENT sleeptime		(#PCDATA)>  <!-- Number of minutes set for sleep     -->
<!ELEMENT sleep			(#PCDATA)>  <!-- Number of seconds until sleep       -->


<!ELEMENT shuffle 	( 	(shuffle_off|shuffle_albums|shuffle_songs), 
						shuffle_off_url?, 
						shuffle_albums_url?, 
						shuffle_songs_url? 
					)>
					
<!ELEMENT shuffle_off EMPTY>			<!-- Shuffle off                     -->
<!ELEMENT shuffle_albums EMPTY>			<!-- Shuffle albums on               -->
<!ELEMENT shuffle_songs EMPTY>			<!-- Shuffle songs on                -->
<!ELEMENT shuffle_off_url (#PCDATA)>	<!-- URL to turn shuffle off         -->
<!ELEMENT shuffle_albums_url (#PCDATA)>	<!-- URL to turn shuffle albums on   -->
<!ELEMENT shuffle_songs_url (#PCDATA)>	<!-- URL to turn shuffle songs on    -->


<!ELEMENT repeat 	(	(repeat_one|repeat_all|repeat_off), 
						repeat_one_url?, 
						repeat_all_url?, 
						repeat_off_url?
					)>
					
<!ELEMENT repeat_one EMPTY>				<!-- Repeat one                      -->
<!ELEMENT repeat_all EMPTY>				<!-- Repeat all                      -->
<!ELEMENT repeat_off EMPTY>				<!-- Repeat off                      -->
<!ELEMENT repeat_one_url (#PCDATA)>		<!-- URL to turn repeat one on       -->
<!ELEMENT repeat_all_url (#PCDATA)>		<!-- URL to turn repeat all on       -->
<!ELEMENT repeat_off_url (#PCDATA)>		<!-- URL to turn repeat all off      -->


<!ELEMENT audio 	(	volume, 
						volume_url, 
						bass, 
						bass_url, 
						treble, 
						treble_url
					)>
					
<!ELEMENT volume (#PCDATA)>		<!-- Volume level (0..100)                   -->
<!ELEMENT volume_url (#PCDATA)>	<!-- URL to change volume                    -->
<!ELEMENT bass (#PCDATA)>		<!-- Bass level (0..100, 50=0dB)             -->
<!ELEMENT bass_url (#PCDATA)>	<!-- URL to change bass                      -->
<!ELEMENT treble (#PCDATA)>		<!-- Treble level (0..100, 50=0dB)           -->
<!ELEMENT treble_url (#PCDATA)> <!-- URL to change treble                    -->

<!-- NOTE: 
The URLs to change volume, bass and treble contain a string "__LEVEL__" to be
replaced by the desired level.
-->

<!ELEMENT current_song 	(	playlist_offset, 
							playlist_length,
							remove_url,
							seconds_elapsed, 
							seconds_total, 
							song
						)>
						
<!ELEMENT playlist_offset (#PCDATA)>	
<!-- Song offset in the playlist. 0= first song
-->
<!ELEMENT playlist_length (#PCDATA)>	
<!-- Total number of songs in the playlist
-->
<!ELEMENT remove_url (#PCDATA)>
<!-- URL to remove this song from the playlist 
-->
<!ELEMENT seconds_elapsed (#PCDATA)>	<!-- Seconds elapsed in this song    -->
<!ELEMENT seconds_total (#PCDATA)>		<!-- Number of seconds in song       -->

<!ELEMENT playlist 	(	save_url?, 
						m3u_url, 
						clear_url, 
						offsets, 
						status_entry+
					)>
					
<!ELEMENT save_url (#PCDATA)>
<!-- URL to save the current playlist. A directory for playlist must be defined
in Server Settings for this to appear. See XXX for information on how to name 
the playlist. 
-->

<!-- (Skin file: playlist.html) ............................................ -->

<!ELEMENT m3u_url (#PCDATA)>	<!-- URL to get the playlist in m3u format -->
<!ELEMENT clear_url (#PCDATA)>	
<!-- URL to clear the playlist. The player stops. 
-->

<!-- (Skin file: pagebarheader.html) ....................................... -->

<!ELEMENT offsets 	(	from, 
						to, 
						last
					)>
						
<!ELEMENT from (#PCDATA)>	
<!-- Offset of first song listed in this page. 0 based.
-->
<!ELEMENT to (#PCDATA)>		<!-- Offset of last song listed in this page.    -->
<!ELEMENT last (#PCDATA)>	
<!-- Last song of the playlist. Number of songs is last+1.
-->

<!-- NOTE: 
This element is controlled by the &start and &itemsPerPage parameters.
When present in browse lists (see elements below), it may happen that 
"to" - "last" is smaller than itemsPerPage, because the Server inserts an 
"All songs" or "All items" item.
-->

<!-- (Skin file: status_list.html) ......................................... -->

<!ELEMENT status_entry 	(	offset, 
							playing_now?, 
							remove_url, 
							song
						)>
						
<!ELEMENT offset (#PCDATA)>		<!-- Offset of this item                     -->
<!ELEMENT playing_now EMPTY>	<!-- Present if this is the current song     -->

<!-- ....................................................................... -->
<!-- Hitlist ............................................................... -->
<!-- .......................................................................
Element returned by hitlist.xml requests. Returns stats about Server DB and 
list of most played songs.
Currently, itemsPerPage is not respected in this page (i.e. for the hitlist 
element)
-->
<!-- (Skin file: hitlist.html) ............................................. -->

<!ELEMENT hitlist 	(	songs, 
						albums, 
						artists, 
						genres, 
						hitlist_entry*
					)>


<!ELEMENT songs (#PCDATA)>		<!-- Number of songs in Server DB            -->
<!ELEMENT albums (#PCDATA)>		<!-- Number of albums in Server DB           -->
<!ELEMENT artists (#PCDATA)>	<!-- Number of artists in Server DB          -->
<!ELEMENT genres (#PCDATA)>		<!-- Number of genres in Server DB           -->

<!-- (Skin file: hitlist_list.html) ........................................ -->

<!ELEMENT hitlist_entry 	(	count?, 
								song
							)>

<!ELEMENT count (#PCDATA)>		<!-- Number of times song has been played    -->

<!-- ....................................................................... -->
<!-- Browse ................................................................ -->
<!-- .......................................................................
Element returned by browse.xml and browseid3.xml requests. Browses the Server DB
by directory (browse.xml) or by tag (browseid3.xml).
Counts returned are language dependant strings (i.e. "XXX albums") and 
must be parsed by client. Also counts are very slow to generate and are disabled
in the skin for now.
-->
<!-- (Skin file: browseid3.html.html, (browse.html, browse_playlist.html)).. -->

<!ELEMENT browse (	itunes?, 
					still_scanning?,
					song_count?, 
					artist_count?, 
					album_count?,
					browseby?,
					location?, 
					offsets?,
					coverart?,
					browse_entry*
  				 )>


<!ELEMENT itunes EMPTY>				<!-- Server DB is iTunes based           -->
<!ELEMENT still_scanning EMPTY>		<!-- DB is still being loaded            -->
<!ELEMENT song_count (#PCDATA)>		<!-- Number of songs in returned data    -->
<!ELEMENT artist_count (#PCDATA)>	<!-- Number of artists in returned data  -->
<!ELEMENT album_count (#PCDATA)>	<!-- Number of albums in returned data   -->
<!ELEMENT browseby (#PCDATA)>		
<!-- For browseid3, "BROWSE_BY_GENRE", "BROWSE_BY_ARTIST" or "BROWSE_BY_ALBUM" 
-->
<!ELEMENT location (locator*)>		<!-- Path down followed, see locator     -->
<!ELEMENT coverart (#PCDATA)>		<!-- Coverart URL?                       -->

<!-- (Skin file: browse_pwdlist.html, browseid3_pwdlist.html) .............. -->

<!ELEMENT locator 	(	locator_name, 
						locator_url, 
						(genre, genre_browse_url)?, 
						(artist, artist_browse_url)?, 
						(album, album_browse_url)?
					)>

<!ELEMENT locator_name (#PCDATA)>	
<!-- When browsing by directory, directory name. When browsing by tag, same as 
one of genre/artist/album info. 
-->
<!ELEMENT locator_url (#PCDATA)>
<!-- URL to browse the location (used to go up a level of more) 
-->

<!-- (Skin file: browse_list.html (browse_playlist_list.html)............... -->
<!-- (Skin file: browseid3_pwdlist.html) ................................... -->

<!ELEMENT browse_entry (	(dir|song), 
							replace_url, 
							append_url
						)>
<!-- Genre of the dir (if browsing by tag)  -->
<!-- Artist of the dir (if browsing by tag) -->
<!-- Album of the dir (if browsing by tag)  -->
<!ELEMENT dir (	dir_name, 				
				dir_browse_url, 		
				genre?, 		 
				artist?, 		
				album?			 
			  )>
			  
<!ELEMENT dir_name (#PCDATA)>		<!-- Name of dir/genre/artist/album      -->
<!ELEMENT dir_browse_url (#PCDATA)>	<!-- URL to browse it                    -->

<!ELEMENT replace_url (#PCDATA)>	
<!-- URL to replace the current playlist with the element listed 
(add &player=PLAYER_ID)
-->
<!ELEMENT append_url (#PCDATA)>
<!-- URL to append to the current playlist the element listed 
(add &player=PLAYER_ID) 
-->

<!-- ....................................................................... -->
<!-- Songinfo .............................................................. -->
<!--  Element returned by songinfo.xml requests. Returns all info in the DB for a  song. Must indicate song by path, so better to use songinfo_url links. -->
<!-- (Skin file: songinfo.html) ............................................ -->

<!ELEMENT songinfo (	title,

						(genre, genre_browse_url)?,
						(artist, artist_browse_url)?,
						(album, album_browse_url)?,
						(composer, composer_browse_url)?,
						(conductor, conductor_browse_url)?,
						track?, 
						type?, 
						duration?, 
						year?, 
						comment?, 
						filelength?, 
						bitrate?, 
						tagversion?, 
						modtime?, 
						song_url?, 
						path, 
						coverart?,

						replace_url, 
						append_url
					)>


<!ELEMENT title 			(#PCDATA)>	<!-- Song's title                	 -->
<!ELEMENT info_url 			(#PCDATA)>	<!-- Link to songinfo page         	 -->
<!ELEMENT path 				(#PCDATA)>	<!-- Path to song file (JIC)       	 -->
<!ELEMENT genre 			(#PCDATA)>	<!-- Song's genre                 	 -->
<!ELEMENT genre_browse_url 	(#PCDATA)>	<!-- Link to genre browsing        	 -->
<!ELEMENT album 			(#PCDATA)>	<!-- Song's album                	 -->
<!ELEMENT album_browse_url 	(#PCDATA)>	<!-- Link to album browsing        	 -->
<!ELEMENT artist 			(#PCDATA)>	<!-- Song's artist                	 -->
<!ELEMENT artist_browse_url (#PCDATA)>	<!-- Link to artist browsing     	 -->
<!-- i.e. browse by artists with artist=composer -->
<!ELEMENT composer (#PCDATA)>
<!ELEMENT composer_browse_url (#PCDATA)>
<!ELEMENT conductor (#PCDATA)>
<!ELEMENT conductor_browse_url (#PCDATA)>
<!ELEMENT track (#PCDATA)>
<!ELEMENT type (#PCDATA)>
<!ELEMENT duration (#PCDATA)>				<!-- in mm:ss                    -->
<!ELEMENT year (#PCDATA)>
<!ELEMENT comment (#PCDATA)>
<!ELEMENT filelength (#PCDATA)>				<!-- in bytes                    -->
<!ELEMENT bitrate (#PCDATA)>
<!ELEMENT tagversion (#PCDATA)>
<!ELEMENT modtime (#PCDATA)>
<!ELEMENT song_url (#PCDATA)>
<!ELEMENT mixable (#PCDATA)>

<!-- ....................................................................... -->
<!-- Song .................................................................. -->
<!-- Element returned by search.xml requests. -->
<!-- (Skin file: search.html)............................................... -->

<!ELEMENT search 	(	num_results, 
						query, 
						offsets?, 
						browse_entry*
					)>


<!ELEMENT num_results (#PCDATA)>	<!-- Number of results                   -->
<!ELEMENT query (#PCDATA)>			<!-- Query used                          -->

<!-- ....................................................................... -->
<!-- Song .................................................................. -->
<!-- .......................................................................
Shared element returned in various lists. Partially describes a song and links
to various related tidbits.
-->
<!-- (Skin file: _xml_song.html)............................................ -->

<!ELEMENT song (	title, 
					(info_url, path)?,

					(genre, genre_browse_url)?,
					(artist, artist_browse_url)?,
					(album, album_browse_url)?,
					(composer, composer_browse_url)?,
					(conductor, conductor_browse_url)?,
					track?, 
					type?, 
					duration?, 
					year?, 
					comment?, 
					filelength?, 
					bitrate?, 
					tagversion?, 
					modtime?, 
					song_url?, 
					path?, 
					coverart?,
					mixable?
				)>
				

<!-- ....................................................................... -->
<!-- Badpath................................................................ -->
<!-- .......................................................................
May be returned by any request if server settings or parameters are incorrect.
-->
<!-- (Skin file: badpath.html).............................................. -->

<!ELEMENT badpath EMPTY>

<!-- ....................................................................... -->
<!-- Various................................................................ -->
<!-- ....................................................................... -->

<!-- (browse_list_empty.html)............................................... -->
<!-- no elements -->

<!-- ....................................................................... -->
<!-- Namespace stuff........................................................ -->
<!-- ....................................................................... -->

<!ATTLIST status xmlns CDATA #FIXED "http://www.slimdevices.com/slimserver/xml">
<!ATTLIST search xmlns CDATA #FIXED "http://www.slimdevices.com/slimserver/xml">
<!ATTLIST songinfo xmlns CDATA #FIXED "http://www.slimdevices.com/slimserver/xml">
<!ATTLIST browse xmlns CDATA #FIXED "http://www.slimdevices.com/slimserver/xml">
<!ATTLIST hitlist xmlns CDATA #FIXED "http://www.slimdevices.com/slimserver/xml">
<!ATTLIST badpath xmlns CDATA #FIXED "http://www.slimdevices.com/slimserver/xml">
