KML - The Missing Manual Søren Roug

Copyright © 2004 Søren Roug
Revision History
Revision 1:     	7 Oct 2004	
First draft
Revision 2	       24 Oct 2004	
Investigate           PLAYMEDIA and use of KML on CD-ROM
Revision 3	       27 Oct 2004	
Investigate ONMETADATA and SYSTEM

There has been a fair deal of material written on KISS Products, but very little for the people actually writing KML for the players. The purpose of this document is to document what is known. All information in this document has been tried on a DP-558, or has been found on the Internet.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available from www.fsf.org entitled "GNU Free Documentation License".

1. Quick Introduction

KML stands for Kiss Markup Language. A code in development at KiSS technology that allows internet to be used on the KiSS. It's like your browser is loading HTML pages, KiSS players can load KML pages on the internet. Features for KML are only limited by the developers imagination and can be used for a wider range of adjustments for KiSS players with Ethernet connection. These KISS players can connect to websites and read pages authored in KML. KML is an XML format. You make one file per screen you want to display.

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<KMLPAGE version='2.0'>
(...add page content...)
</KMLPAGE>

This very simple example renders a blue screen fading to black, with a plain white text in the top left hand corner stating 'Hello World!'.

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<KMLPAGE version="2.0">
<BACKGROUND vgradient="0,0,0-0,0,128" />
<FILLRECT coords="0,0,719,479" pen="0" />
<TEXT coords="60,60" font="0" pen="255">Hello world!</TEXT>
</KMLPAGE>

2. Longer introduction

2.1. Client Versions

DP-558 has KML client version 2.1. Others have version 2.0.

2.2. How to get started

If you own a DP-558 you can set up a webserver on port 8888 on the host that runs PC-Link. Then click on the Menu button on the remote, scroll down to Online KML-services, and select PC-Link KML Start page. The player will then fetch the /index.kml file from the webserver. You can type in one of the examples in the document to get started.

One might make the assumption, that it is possible to create an index.kml on a CD-ROM and then insert the CD-ROM into the player to get a standalone application, but this doesn't work.

2.3. How the player accesss the website

The player makes a HTTP 1.0 GET request to the website and automatically adds some information about your player. /index.kml?PlayerID=ugeodosahwis&PlayerBrand=KiSS&PlayerModel=DP-558&PlayerLanguage=4&PlayerFirmware=105&ScreenWidth=720&ScreenHeight=576&ScreenForm=4x3

If possible set the mime-type to text/xml of the page. That way Internet Explorer and Mozilla will display the KML as XML when you look at the page. The player doesn't care.

3. KML Commands in alphabetical order

BACKGROUND

Name BACKGROUND -- Set the screen background

<BACKGROUND {href=" url" | gradiant=" 1,2,3-4,5,6" | vgradiant=" 1,2,3-4,5,6" |  hgradiant=" 1,2,3-4,5,6" | wgradiant=" 1,2,3-4,5,6"/> }

Description

<BACKGROUND> sets the background. The url can point to JPG or GIF. If the image is smaller than the size of the screen, then it is centered. Setting the background doesn't clear the content.

FILLRECT

Name FILLRECT -- Draw filled rectangle Synopsis

<FILLRECT coords=" x,y,w,h" pen="colour" /> Description

Draws a filled rectangle in the pen colour. The coordinates are x, y, width and height. Bottom right corner on NTSC televisions is 720,480. On European PAL it is 720,576. Useful to blank the screen.

FIP

Name FIP -- Set text on front panel Synopsis

<FIP speed='a' intensity='b'> Description

Parameters: speed (a) - For scrolling messages (texts longer than available display space) number of 'ticks' between updating scroll position. Each tick is about 1/10 second. Thus, a scroll speed of 2 means at every other 'tick' the scroll message advances one position. If parameter is omitted, assumed to be 5 (~ 0.5 sec between scroll position advance) intensity (b) - The VFD display om the DP-5xx platform has 8 intensities, with 0 being dark and 7 being bright. If parameter omitted, assumed to be 7 (brightest). Example

<FIP speed='2' intensity='6'>Add SCROLLING MESSAGE HERE</FIP>

GOTO

Name GOTO -- Jump to target Synopsis

<GOTO href="http://go to where" /> Description

Does the following: 1. Cancels all events associated with current KML document 2. Unloads (discards) current KML document 3. Loads new KML document. Node Parameters: href Location of KML document to be loaded [opened]. <GOTO href='$$PREVIOUSDOCUMENT$$' /> is possible. Example

IMAGE

Name IMAGE -- Display a GIF image Synopsis

<IMAGE id=" logo" coords=" 74,84" [src=" http://which graphic.gif" /> ] Description

Displays a GIF image at the coordinates. The src attribute is available from version 2.1. If 'id' is used, the image must have been loaded in an earlier LOADIMAGE command with matching 'id' attribute.

KEY

Name KEY -- Set action for key Synopsis

<KEY id="key_id"> Description

KEY sets the action for a button on the remote. The id must be a numeric value from the list of key ids. Example

  <ONCLICK><![CDATA[ <GOTO href='http://...' />]]></ONCLICK>

</KEY>

LINE

Name LINE -- Draw line Synopsis

<LINE coords="100,100,400,100" pen="255" /> Description

Draws a one-pixel wide line.

LOADIMAGE

Name LOADIMAGE -- Fetch image from webserver Synopsis

<LOADIMAGE id=" logo" href=" http://which graphic.gif" /> Description

Loads a GIF image from the URL given into a buffer in the player. The image can then be used by the <IMAGE/> element.

Be aware that on older players the ability to overwrite, update or delete loaded images from the KML image buffer is missing. This means, as soon as the ~20 image buffers are spent, you can load no new images.

You preload and display GIFs with separate commands, example:

From version 2.1, you can load the image directly from the IMAGE command.

Relative URLs are not available in version 2.1, but will come in version 2.5.

MENUITEM

Name MENUITEM -- Define menu item Synopsis

<MENUITEM id="itemid"> Description

The player has builtin support for menus. If you define a number of menu items in the KML page, the player will automatically make the first one active, i.e. execute the commands associated with the ONHILITE eventhandler.

The down and right buttons are by default set to jump to the next menu item. Up and left are set to jump to the previous menu item. Example

 <ONRIGHT><![CDATA[
   <MENUSELECT item='14' />
 ]]></ONRIGHT>
 <ONCLICK><![CDATA[
   <GOTO href='http://webpage/playerinfo.kml' />
 ]]></ONCLICK>
 <ONHILITE><![CDATA[
   <TEXT coords='220,176' font='0' pen='47'>Player information</TEXT>
 ]]></ONHILITE>
 <ONUNHILITE><![CDATA[
   <TEXT coords='220,176' font='0' pen='255'>Player information</TEXT>
 ]]></ONUNHILITE>

</MENUITEM>

MENUSELECT

Name MENUSELECT -- Jump to menu item Synopsis

<MENUSELECT item="one"/> Description

This command makes the menu item referenced in the item attribute the active one. Example

 <ONCLICK><![CDATA[<MENUSELECT item='menu5' />]]></ONCLICK>

</KEY>

ONCLICK

Name ONCLICK -- Eventhandler for click or Enter Synopsis

<ONCLICK> Description

ONCLICK is used inside MENUITEM and KEY elements. It encapsulates the actions to execute when the user clicks on the Enter button. If ONCLICK is used inside KEY, then it is the button number from KEY command that triggers the action. Example

<ONCLICK><![CDATA[

   <GOTO href='http://webpage/playerinfo.kml' />

]]></ONCLICK>

ONDOWN

Name ONDOWN -- Eventhandler for down button Synopsis

<ONDOWN> Example

<ONDOWN><![CDATA[

     (...commands to be executed...)

]]></ONDOWN>

=

ONHILITE === Name ONHILITE -- Eventhandler for activation of menu item Synopsis

<ONHILITE> Description

Onhilite is used inside MENUITEM elements. It encapsulates the actions to execute when the user high-lights the menuitem. These are usually something that display the item as active. Example

<ONHILITE><![CDATA[

     <TEXT coords='110,340' font='0' pen='255'>Menu text</TEXT>

]]></ONHILITE>

ONINTERVAL

Name ONINTERVAL -- Eventhandler Synopsis

<ONINTERVAL interval="number"> Description

Number is a number 1..10. The block inside is executed everytime the interval is over.

ONLEFT

Name ONLEFT -- Eventhandler for left button Synopsis

<ONLEFT> Description

<ONLEFT><![CDATA[ (...commands to be executed...) ]]></ONLEFT> Example

<ONLEFT><![CDATA[

   <MENUSELECT item='item5' />

]]></ONLEFT>

ONMEDIASTOPPED

Name ONMEDIASTOPPED -- Eventhandler to trigger when media stops Synopsis

<ONMEDIASTOPPED> Description

<ONMEDIASTOPPED><![CDATA[

     (...commands to be executed...)

]]></ONMEDIASTOPPED>

Example

<ONMEDIASTOPPED><![CDATA[

     <FIP speed='1' intensity='7'>STOPPED</FIP>

]]></ONMEDIASTOPPED>

=

ONMETADATA === Name ONMETADATA -- Eventhandler media streams Synopsis

<ONMETADATA> Description

This is an eventhandler for metadata coming from shoutcast audio streams. Interjected into the stream are blocks containing information about the song, station etc. You can set up the ONMETADATA handler to catch this data and display it. The protocol isn't officially documented. The Kiss player can extract title, bitrate, genre and URL and will set the variables $$MP3_TITLE$$, $$MP3_BITRATE$$, $$MP3_GENRE$$ and $$MP3_URL$$.

For more information see the ShoutCast metadata protocol document on the Internet. Example

<ONMETADATA><![CDATA[ <FILLRECT coords='0,395,719,85' pen='0' /> <TEXT coords="76,406" font="0" pen="118"> $$MP3_TITLE$$ </TEXT> ]]></ONMETADATA>

ONRIGHT

Name ONRIGHT -- Eventhandler for right button Synopsis

<ONRIGHT> Example

<ONRIGHT><![CDATA[

     (...commands to be executed...)

]]></ONRIGHT>

ONTIMER

Name ONTIMER -- Set a timer Synopsis

<ONTIMER timeout="num"> Description

Set some actions to happen in the future. The timeout is in milliseconds. Example

<ONTIMER timeout='1000'><![CDATA[

 <MENUSELECT item='14' />

]]></ONTIMER>

ONUNHILITE

Name ONUNHILITE -- Eventhandler for deactivation of menu item Synopsis

<ONUNHILITE> Description

Onunhilite is used inside MENUITEM elements. It encapsulates the actions to execute when the user leaves the menuitem. These ara usually something that visually show that the item is now inactive. Example

<ONUNHILITE><![CDATA[

     <TEXT coords='110,340' font='0' pen='255'>Menu text</TEXT>

]]></ONUNHILITE>

ONUNLOAD

Name ONUNLOAD -- Eventhandler Synopsis

<ONUNLOAD> Description

... Example

<ONUNLOAD><![CDATA[

     (...commands to be executed...)

]]></ONUNLOAD>

ONUP

Name ONUP -- Eventhandler for up button Synopsis

<ONUP> Description

This command describes what should happen when the user clicks on the up button. The default action for menu items is to go to the preceeding menu item. Example

<ONUP><![CDATA[

     (...commands to be executed...)

]]></ONUP>

PLAYMEDIA

Name PLAYMEDIA -- Play multimedia file from address Synopsis

<PLAYMEDIA href="http://tothefile.pls" /> Description

Media must be a Shoutcast playlist (.pls) file. Each file inside the PLS file must point to a Shoutcast stream. Pointing to an MP3 file appears not to work. Example

RECT

Name RECT -- Draw rectangle Synopsis

<RECT coords="100,100,400,100" pen="255" /> Description

Draws rectangle (1 pixel line width) on graphics layer. Parameters:

   coords Placement and size of rectangle.

   pen Color or palette index.

Parameter data for "coords" :

   x Pixel X coordinate of top-left corner

   y Pixel Y coordinates of top-left corner

   w Pixel Width of rectangle

   h Pixel Height of rectangle

Example

Draws a 400 x 100 white rectangle.

STOPMEDIA

Name STOPMEDIA -- Stop play of multimedia file Synopsis

<STOPMEDIA/> Description

...

SYSTEM

Name SYSTEM -- System function Synopsis

Only works from local KML-pages, containing "file://" in the URL. If the URL starts with "http://" SYSTEM is ignored.

=

TEXT === Name TEXT -- Display text at coordinate Synopsis

<TEXT coords='101,180' font='size' pen='colour'> Description

The font attribute can be from 0 to 3. Zero is the small font, and three is the largest font. The "4" font has some strange glyphs. Text does not wrap if it is longer than screen width. Example

<TEXT coords='101,250' font='0' pen='31'> Text here will show Small! </TEXT>

UNLOADIMAGE

Name UNLOADIMAGE -- Remove image from buffer Synopsis

<UNLOADIMAGE id="imageid"/> Description

There are 24 buffers available for images on the player. This command frees one buffer. The buffers are presumably cleared when the player is directed to another page. 4. Colour Codes

DP-5xx OSD graphics are 8-bit. All images and graphics on the 8-bit OSD layer share a common 256-colour palette. Each colour entry in the palette has an associated alpha (opacity) value as well. Newer KiSS products based on the EM86xx chip will have full 32-bit colour (24-bit RGB + 8-bit alpha), but this is not an option on the DP-5xx. The GIF decoder discards the palette bundled with the image, and makes no attempt to re-map the image to the common system palette either.

KiSS currently has no plans for changing the colour table, the behavior of the GIF decoder, or providing KML options for letting individual KML sites alter the colour table, the main reason being that the colour table is shared with menus and everything else that happens on the OSD layer. Instead you should adapt your 8-bit artwork for the OSD to fit the existing palette.

5. Button Codes 5.1. Key IDs :

ID Button 73 Button 0 74 Button 1 75 Button 2 76 Button 3 77 Button 4 79 Button 5 80 Button 6 81 Button 7 82 Button 8 83 Button 9 84 Button TITLE MENU 93 Button RETURN 94 Button << 95 Button >> 96 Button STEP 97 Button AUDIO 98 Button SUBPIC 99 Button ZOOM 100 Button ANGLE 101 Button REPEAT 102 Button MARK 103 Button CLEAR 104 Button SRCH 768 Button SETUP 16387 Button PLAY/PAUSE 16388 Button NEXT 16389 Button PREVIOUS

5.2. Button Codes

Button Code Name Button SHOW_ONE_KEYDOWN 1 SHOW_TWO_KEYDOWN 2 SHOW_THREE_KEYDOWN 3 SHOW_FOUR_KEYDOWN 4 SHOW_FIVE_KEYDOWN 5 SHOW_SIX_KEYDOWN 6 SHOW_SEVEN_KEYDOWN 7 SHOW_EIGHT_KEYDOWN 8 SHOW_NINE_KEYDOWN 9 SHOW_ZERO_KEYDOWN 0 SHOW_TITLE_KEYDOWN Title Menu SHOW_MENU_KEYDOWN Root Menu SHOW_RETURN_KEYDOWN Return SHOW_UP_KEYDOWN Up SHOW_DOWN_KEYDOWN Down SHOW_LEFT_KEYDOWN Left SHOW_RIGHT_KEYDOWN Right SHOW_ENTER_KEYDOWN Enter SHOW_REV_KEYDOWN Fast Reverse SHOW_PLAY_KEYDOWN Play/Pause SHOW_FWD_KEYDOWN Fast Forward SHOW_PREV_KEYDOWN Previous SHOW_NEXT_KEYDOWN Next SHOW_STEP_KEYDOWN Single Step SHOW_AUDIO_KEYDOWN Audio SHOW_SUBTITLE_KEYDOWN Subtitle SHOW_ANGLE_KEYDOWN Angle SHOW_ZOOM_KEYDOWN Zoom SHOW_REPEAT_KEYDOWN Repeat SHOW_BOOKMARK_KEYDOWN Bookmark SHOW_SETUP_KEYDOWN Setup SHOW_CLEAR_KEYDOWN Clear SHOW_SEARCH_KEYDOWN Search

6. Examples

Example 1. One-item menu

This example shows a menu item that highlights when selected.

<?xml version='1.0' encoding='UTF-8' standalone='yes'?> <KMLPAGE version='2.0'> <FILLRECT coords="0,0,719,479" pen="0" /> <MENUITEM id="1">

 <ONCLICK><![CDATA[ <GOTO href='http://www.movimu.com/kml/kml-index.php' /> ]]></ONCLICK>
 <ONHILITE><![CDATA[ <TEXT coords='220,108' font='0' pen='47'>Craig's portal</TEXT>
         ]]></ONHILITE>
 <ONUNHILITE><![CDATA[ <TEXT coords='220,108' font='0' pen='255'>Craig's portal</TEXT>
         ]]></ONUNHILITE>

</MENUITEM> </KMLPAGE>

Example 2. Shoutcast PLS file

Shoutcast PLS file for PLAYMEDIA action.

[playlist] numberofentries=4 File1=http://64.236.34.67:80/stream/1038 Title1=(#1 - 792/13658) HitzRadio.com - #1 For All The Hits! Length1=-1 File2=http://64.236.34.196:80/stream/1038 Title2=(#2 - 1268/21073) HitzRadio.com - #1 For All The Hits! Length2=-1 File3=http://64.236.34.97:80/stream/1038 Title3=(#3 - 1531/22082) HitzRadio.com - #1 For All The Hits! Length3=-1 File4=http://205.188.234.38:8070 Title4=(#4 - 10/10) HitzRadio.com - #1 For All The Hits! Length4=-1 Version=2

Explanation of entries:

[playlist]: Signifies that this is a playlist. This is case sensitive.

File#=: Location of the file in any of the formats described above. This is also case sensitive. Also the # sign after "File" signifies what file number it is. The first file in the playlist is "File1", the second is "File2" and so on.

Title#=: Title to display. This is usually the title read from the file name or ID3 tags. Like the other fields, this is case sensitive. This also can be the name of a stream. Like "File#" the pound sign (#) is replaced by the entry number that is in the playlist.

Length#=": Length in seconds, this is also case sensitive. On the last entry there is a negative one, this is usually seen on streams, it tells the program to ignore the time entry. Like "File#" the pound sign (#) is replaced by the entry number that is in the playlist.

NumberOfEntries=#: The total number of entries in the playlist. This should match the last number on the "File#", "Title#", and "Length#" fields. Also case sensitive.

Version=2: This required entry near the bottom tells the player what format the PLS is in. Older versions of the PLS format did not include this. Like everything else, it is case sensitive.

KML the missing manuel

Contents