| Main page Graphics Photography Music & Audio Audio Plugins Video Tools Web Design Documents Space Astro Amiga Funny Surreal Gallery Links & Contact |
KML 2.4Programmer's Reference ManualVersion 0.3 - 2004-10-10 - Sonny Windstrup, Joachim Michaelis Version 0.4 - 2007-02-06 - Joachim Michaelis This document is also available in a paged version
This document is still rather new. If you find anything wrong or missing, please e-mail me at joamicha(at)cisco.com This document is relevant for:
Legal stuffKML (KiSS Markup Language) is a proprietary scripting language developed and owned by KiSS Technology. KML is still very much "in the works", and the specifications are accordingly still subject to change. This document may be considered a Developer's Alpha Release, and must be considered confidential. It may not be duplicated or re-distributed in any way without prior permission from KiSS Technology. Pre-release developer contact information:
IntroductionWhat is KML?KML was initially developed by KiSS Technology as a simple and efficient platform for interactive online applications on low-cost embedded devices and set-top boxes (STBs). We had already built a network enabled DVD player, the KiSS DP-500 (which was the World's first and so far (Sept 2003) the World's only DivXTM certified DVD player!) - The device was initially capable of using its network connection for retrieval and playback of local media content (MPEG4, MP3, JPEGs, etc) shared from a PC on the same network; a hugely popular feature.The product had to have online applications as an obvious next step up from the local in-home network services. But how to implement them? We considered, most obvious, embedding a 'thin' web client such as Opera or Mozilla Firebird. Other STB manufacturers have tried this approach with limited success. If such an STB web browser could be succesfully implemented, it would have many useful advantages in areas of portability, code maturity, javascript support and general availability of pre-existing content and online applications. However, the web-browser approach was abandoned when we determined that conventional web technology simply don't work very well for STB use. Limited guaranteed TV screen resolution must be considered, as well as numerous other annoyance factors and concerns compromising the would-be usefulness of the solution:
By contrast, DVD-like menus and teletext content works well on a STB. The DVD menus are pretty simple, and are designed to be usable on a lowest-common-denominator TV-set, navigated with basically just the cursor keys on a remote control. DVD graphics can easily be designed to look good on a TV screen using correct gamma, pixel aspect, color space and detail level. KML is designed with these considerations in mind. KML had to be TV-screen compatible and designed to work natively with basic remote control operation. The KML baseline specs are very similar to DVD content : The DP-500 implementation of KML has a pixel resolution and aspect ratio identical to NTSC DVD content (720 x 480 pixels @ 4:3 Pixel aspect (4/3)/(720/480) =~ 0.889 ; 16:9 Pixel aspect (16/9)/(720/480) =~ 1.185 ). Both PAL and NTSC systems use the same pixel resolution on this platform; in PAL mode the video buffers are hardware scaled from NTSC resolution to fit the screen (480 becomes 576 visible scanlines - KML is intended to ultimately not be client implementation specific, but at present it remains tied quite firmly with the KiSS EM85xx/EM86xx hardware platform, namely the KiSS DP-500 and derived products.) The whole of the screen area can be controlled, including the overscan area. For these products, pixel coordinates begins at 0,0 (top left) and ends at 719,479 (bottom right). Overscan is implemented differently on every TV set, so you have to use very conservative allowances for the content area of the screen. Rules of thumb for designing content is to keep text and important graphical elements within the so-called 'title safe' area on a TV screen, which is the middle 80%. (subtract 10% of the screen size from either side and top and bottom). The actual screen edge usually occurs around the Action Safe border which extends to the middle 90% of the display area. Adobe Premiere and AfterEffects both have a title/action-safe overlay box in their preview windows, which may be helpful for content design. The KiSS EM85xx hardware has two video buffers; one for overlay graphics (the OSD - On Screen Display buffer) and one for video/background art (YUV, or video buffer). The OSD buffer consists of a 720x480 pixel 8-bit bitmap spanning the entire scan area of the display. Each pixel may have one of 256 colors. Each of the 256 colors are index-mapped to a set of corresponding RGB 8-bit values and a 4-bit alpha (opacity) value, which is used to control OSD layer pixel transparency (zero alpha allows unobscured see-thru to the video layer beneath). A 'blank' OSD buffer is simply filled with color zero, which has 0% alpha opacity, making it effectively invisible. The default OSD 8-bit palette has all primary and secondary colors with intensity and saturation gradients, as well as a mix of generally useful hues and gradients. Many of the colors exist in semi-transparent versions, and Photoshop color map files and OSD graphics processing macros are available for content developers. OEMs may design their own color palettes. Colors may also be specified as hex triplets (#RRGGBB, web/x-windows style) which are then mapped by the client to the closest matching color index value. KML consists of an XML format data stream retrieved and parsed by a KML client. The data stream can be retrieved from a local file or (more commonly) an online host (via HTTP or HTTPS). The data stream contains instructions for the client to carry out. Typical simple actions/instructions:
Notice, loading a KML "page" does not imply that the client clears the graphics display. Instead, the host has to tell the client specifically to draw a solid filled rectangle spanning the screen with the desired color of transparency in order to clear the screen. This is intentional and serves to allow a response from a host application to only update a portion of the screen. Other types of instructions define event-triggered action blocks. These are simply sequences of instructions like those above, which are performed when certain events occur, such as button presses on the remote control, or the activation of a highlighted menu item. Actions can also be timed to occur at intervals, after a delay, when a page is loaded or unloaded, when a menuitem is highlighted or becomes inactive, or when an audio or video stream stops. A KML action block can make the client load a new KML document for parsing, or render graphics to indicate a state change on a menu item, or control the playback of audio and video streams, etc. Unlike HTML, KML clients aren't themselves supposed to organize content and format quantities of text and embedded graphical content. The host system must manage the entire session and specify pixel coordinates for every element that is to be rendered on the client system screen. If you have content spanning more than a page, this is achived using simulated scroll (retrieving a KML page redrawing the portion of the content that is supposed to move, etc). The current practical implementation solution we use for our own KML applications involves managing virtual screens on the object-oriented host system. A ghost cursor controls the placement of the individual objects, so the content author need not worry about having to keep track of these numbers. This situation is not dissimilar to that of designing an ANSI-type terminal system where the host system also controls screen coordinates of rendered text. Obviously, there are advantages and disadvantage to this model: KML benefits precision control of the user experience - all clients should see the precise same layout and design. The downside is obviously, the client is 'dumb' and by design incapable of reformatting received content intelligently. It is not really a problem since the host system should know enough about the client to support the session and provide the needed intelligence. (The client tells the host system about its own capabilities.) Applications can thus be designed to accomodate a variety of different client types. The long-term goal is to remove all of the client specific details from application design by the use of an sophisticated application support layer that sits between the client and the application. This layer is presently still being developed by KiSS, but a simple prototype of the concept is freely available for content developers to examine. Combined, these features permit the implementation of simple but very persuasive applications. A typical application could be a video on demand service, where a host application on a webserver can present the available video content by generating menus in the form of KML pages which are rendered on the client's OSD graphics layer, perhaps on top of live video loops retrieved from in-player harddisk cache, which could be used for motion background art. By navigating the different KML pages with the remote control, the user can then select a video stream which can subsequently be purchased/activated with a KML scripted action tying in with local DRM/key-exchange functions. Suggested types of applications suitable for KML implementation:
A KML application may be developed using standard off-the-shelf components, and can be hosted on any webserver platform or file system. KML documents can be retrieved by the client using plain vanilla HTTP GETs on port 80. For OEM products, KML documents can be embedded in firmware ROM or system partition on harddisk. We have developed a number of PHP-based tools for assisting development, hosting and deployment of KML-based content, services and applications. These will be made available shortly. The futureIn it's current design, KML can and will be expanded to meet the requirements of both internal development, OEMs and 3rd party developers. The upgrade from KML 2.0 to 2.4 represents such an upgrade, adding all functions required for launching a full-blown video-on-demand service featuring secure payment, user login and playback of DRM protected content.That said, KML is currently far from perfect. Development is tedious. All logic has ot be performed on the server side, making KML applications somewhat slowly reacting and heavy on on server. KML started out as a quick solution to presenting more or less static data on the screen. With the growing complexity of the applications developed in KML and the increasing need for dynamic content and user interaction, the static XML-based nature of KML is reaching it's limit. It is becoming more and more obvious that the solution is to step away from the XML based structure and use a real scripting language as the foundation of KML. Possible scripting languages considered so far are Javascript or Lua. As opposed to html the javascript would be communicating directly with the underlying architechture instead of addressing an html/xml document though some horrible DOM-like method. KML document anatomyKML is implemented as well-formed XML documents with a number of levels of nodes and subnodes describing the client commands. There are currently still no officially endorsed DTDs or schemas provided by KiSS to validate KML documents. Such will be made available when language specifications stabilize. Quick primer on XML: http://studio.tellme.com/general/xmlprimer.html KMLPAGE The KML page should have a proper XML header (UTF-8 encoding recommended ) followed by the Sample valid KML page:
Example:
The BACKGROUND item overwrites the background layer with the black-blue gradient. The FILLRECT item overwrites the 8-bit foreground layer with pen 0 (transparent). The TEXT item prints the text with font 0 (normal sized letters) and pen 255 (white). These items are all in the main part of the KML page. This means, they're executed as the page is parsed. There are no events of any kind on this page, which makes it a dead end. You can basically only press STOP, which shuts down the KML client and reverts the device to normal operation. Usually, KML documents have at least some actions and events associated with remote button presses so that interactive operation is possible. We recommend that pages on logical dead-end paths should be equipped with at least some kind of means for returning the user to the previous page they came from. Fig. 2 shows logical KML document structure.  Order of ExecutionThe main part of a KML page is parsed top-down once the KML page is read by the KML "browser". Action blocks encapsulated by a <![CDATA[ ]]> construction are not parsed at all at this point, so a misspelling or syntax error inside an action block is not discovered when loading a page. Only once you activate the specific action block, the KML inside the CDATA part is parsed. You may want to keep this in mind when testing your KML pages.KML supports variables and setting up events that are called once these variables are set. Due to the top-down order of execution, a variable placed above a corresponding event action block will not get called. If you place the variable change below (after) the action definition, it will work. Event Types and Typical UseKML is able to react on different kinds of events. These events have pieces of KML inside a CDATA construction, which is evaluated once the event it called. The different event types are:
Simple KML CommandsThe commands in this section can all be attached to either the main KMLPAGE node or any of the action blocks on the miscellaneous event nodes. GOTODoes the following:
Notes:Just before unloading present document, ONUNLOAD event action block is executed (if present). Any document retrieved with GOTO will be parsed as a KML document regardless of mimetype and file extension.Usage:
Parameters:
Example:
FILLRECTDraws solid filled rectangle on graphics layer.Notes:Please refer to appendix C for color palette table and 'pen' parameter syntax.Usage:
Parameters:
Parameter data for "coords":
y Pixel Y coordinates of top-left corner w Pixel Width of rectangle h Pixel Height of rectangle Example:
RECTDraws rectangle (1 pixel line diameter) on graphics layer.Notes:Single-pixel horizontal lines flickers on interlaced TVs. Recommended design practice is to make horizontal lines at least two pixels in height. Please refer to appendix C for color palette table and 'pen' parameter syntax.Usage:
Parameters:
Parameter data for "coords":
y Pixel Y coordinates of top-left corner w Pixel Width of rectangle h Pixel Height of rectangle Example:
LINEDraws a 1 pixel thick line on the graphics layer.Notes:Single-pixel horizontal lines flickers on interlaced TVs. Recommended design practice is to make horizontal lines at least two pixels in height. Please refer to appendix C for color palette table and 'pen' parameter syntax.Usage:
Parameters:
Parameter data for "coords":
y1 Pixel Y coordinates of line start x2 Pixel X coordinate of line end y2 Pixel Y coordinates of line end FIPReplaces message on alphanumeric fluorescent display on device front. The front display capabilities vary from device from device, but 7-bit ascii is guaranteed. Using more characters outside this range may work, but you should test on the desired product first.Usage:
Parameters:
Example:
TEXTDraws text on graphics layer.Notes:Currently only 4 "fonts" are available, and they're all derivatives of Verdana, only with varying font sizes. Font 0 is default font (approximately 18 pixels tall) Font 3 is the largest (Approx. 44 pixels tall.) Pixel coordinates refer to top left corner of text, which is left-aligned. Please refer to appendix C for color palette table and 'pen' parameter syntax. There will be many more type options and custom fonts available in the near future.Usage:
Parameters:
Example:
IMAGEDraws a pre-cached GIF image on graphics layer.Notes:The x,y coordinates are specified in pixels within the 720x576 screen area. Images are typically buffered in ram once they've been shown once to speed up performance. The images must currently be .gif in the kml palette (beware of alpha - we recommend using the Tga2Gif tool.)In the future we might add 24 and/or 32-bit png support and perhaps even jpeg support. Usage:
Example:
STOPMEDIAStops the currently playing media stream.Example:
ERRORMEDIAThis is a debug function that you probably don't need to use ever.Example:
MENUSELECTActivates specified menu item.Usage:
Example:
PLAYMEDIAActivates playback of specified media content retrieved via http or from a file on a local file system. Buffering and playback starts immediately. Any audio or video media already playing will be stopped.Video media content is rendered in a seperate video buffer, so that background jpeg images and overlay graphics layer and menu operation are not affected. This is different from the older KiSS products, where the jpeg background would be lost when playuing video. Please refer to Encoding Video section for media compatibility information. Usage:
Parameters:
Notes:If you specify a PLAYMEDIA tag with only the coords attribute set, video position/size is set without interrupting video playback. If coords is omitted when starting new video playback, video size defaults to full-screen playback. Current spec says you have to use complete, absolute URLs when referring to the location of content.Example: Playing an mp3 file
Example: Windowed mode
SEEKMEDIASeekmedia is currently only tested on Windows Media files over the rtsp:// protocol. It performs both relative and absolute positioning in the stream, using either seconds or percent as time units. Please notice that smooth fast forwarding and rewinding is not possible when streaming.Usage:
Examples:
SLEEPThis function causes the KML parser to pause rendering. If for some reason you need a KML page to show up gradually, you can insert small pauses. This is usually not a good idea, but this feature has been requested by 3rd party game developers.Usage:
Parameters:
Action blocks & EventsAction blocks are collections of actions to be carried out when an associated event occurs. According to present specification, the action blocks are container tags with their attached command nodes isolated inside XML CDATA escape blocks. Please refer to W3C spec on CDATA for proper usage: www.w3.org/TR/REC-xml#sec-cdata-sect Most action blocks are tied to specific events and may only be attached to the main KMLPAGE node. Some action blocks are nested with their parent objects such as BUTTON and MENUITEM event types. Menuitems are further described later. KEYThis is the way to make a certain button on the remote control do a certain thing. Notice the number "93". This is the code for the back button. For a complete list of remote button codes, refer to the list of key codes for the full list.
ONUNLOADAdmittedly counter-intuitively labeled, executes when a GOTO command fetches another KML document. (GOTO causes the current KML document to unload.)Suggested use: Stopping media playback, clearing screen, etc. This tag must be in the main part of the KML page (i.e. not inside an action block.) If omitted, nothing is executed at page the page unload event. Usage:
Example:
Notes:If you want to display an icon while the user waits for the next page to show up, this method should do the trick.ONINTERVALWaits for x seconds where x is 100 msec.Notice: You must not use this function on PlayerModel "DP-500", "DP-508", "DP-1500s", "DP-1504", "DP-1504s", "DP-50X" or a "DP-558" with firmware 1.0.6 or older, as these players will flood the server if they encounter this tag. Example (repeat every 5 seconds):
ONTIMERWaits for x seconds where x is 1 msec. For archeologic reasons ONTIMER uses a different timescale than ONINTERVAL.Notice: You must not use this function on PlayerModel "DP-500", "DP-508", "DP-1500s", "DP-1504", "DP-1504s", "DP-50X" or a "DP-558" with firmware 1.0.7 or older, as these players will flood the server if they encounter this tag. Example (wait 5 seconds):
ONMETADATAExecutes when a playing media stream delivers updated metadata information.Notes:Suggested use: Displaying updating meta data on screen during media playback. This action is never activated when no media streams are playing. It is called when metatag-carrying media stream stops for any reason.Usage:
Example:
ONMEDIASTOPPEDExecutes when a PLAYMEDIA file or stream playback completes.Notes:Suggested use: Returning user to different screen when media playback completes Can only occur when media is playing. OnMediaStopped will be aliased with ONMEDIASTOP in future KML versions. ONMEDIASTOPPED is to be deprecated.Usage:
Example:
ON_EVENTExecutes when an event with the specified name is called, or when the contents of a variable with the same name as the specified event changes it's contents.Usage:
Example:
The _doc.paint eventThere is a special event named _doc.paint which occurs whenever the client has damaged the contents of the foreground layer. This happens after an error message or when the on-screen keyboard goes away. The typical use is to redraw the foreground layer whenever this event occurs. Example:
VariablesVAR_SETThis sets a KML variable with the name specified. Among other things, this can be used to set default values of the content of the on-screen keyboard if brought up by the user.Usage:
Notes:
VAR_GETThis prints out the contents of the specified KML variable. Use in conjunction with a TEXT tag.Usage:
Example:
VAR_INPUTThis brings up the on-screen keyboard. The text entered by the user is fed into a KML variable. When the user presses OK or Cancel, the keyboard is no longer there but is still visible on the screen until you erase the left-over graphics. Set up a _doc.paint event and put code in there that redraws the screen, to resolve this.Usage:
Notes:
SUBMITOnce you (or the user) has set some values to their desired values, you can submit these to the server in the same way that you do in HTML using post or get. Important things to understand here are:
Usage:
Differences from html:In HTML you must make a kind of scope outside any submit buttons using the <FORM> tag. We felt that this is rather limiting and not in compliance with what you typically need. That is why there is no <FORM> tag, and the method= and target= attributes have been moved to the SUBMIT actions themselves. This way you can easily send the user in different directions depending on what button is clicked.Control StructuresThis section addresses the more complex parts of KML where several tags address each other in various ways. This should enable you to figure out how to make menus, checkboxes, radiobuttons, links and more. MENUITEMMenuitems are special objects used to draw 'hot spots' for interactive menu navigation. They are comparable to DVD menu hotspots in terms of functionality. Up to 7 action blocks can be associated with any one menuitem: There's one action block for each of the four cursor key directions, so that makes four. These are labeled ONUP, ONDOWN, ONLEFT, ONRIGHT.Then there are two action blocks representing activation and deactivation states of the menu item (Activation means the menu item has been selected. Deactivation means the menu item is no longer active - another item has been selected.) These two action blocks are labened ONHILITE and ONUNHILITE, and are primarily used to draw 'highlight' bars around active menu hotspots. The four cursour directions can be linked to run MENUSELECT on neighboring items. Unless defined otherwise, ONDOWN and ONRIGHT are linked to the 'next' item in order of definition, and ONUP / ONLEFT links to 'previous' items. The automatic linking 'wraps' so when you press DOWN or RIGHT at the last item, the first item becomes active. UP or LEFT similarly makes the last item active when at the first item. The final menuitem event action block is ONCLICK, and it's executed when the ENTER key is pressed on the remote control while the menuitem is highlighted. Notes:Menuitems can be attached only to the KMLPAGE node. There can be as many as 32 menuitems associated with a KMLpage. It is entirely optional whether to attach action blocks to a menuitem or not. When a page with menuitems are loaded, the ONUNHILITE event on every menuitem is executed once.Usage:
Extended usage for KML 2.5:In this example the menu item sets up different actions for Enter (key 115) and play (key 16387). All keys that have been defined globally can be overwritten locally for the specific menu item.
Example:
TEXTSCROLLMaking the client word-wrap text and making it scroll a text area. This is one of the new functions added in KML 2.4.Usage:
Example:The especially relevant parts are marked in orange. Relative URLs must be turned into absolute URLs:
CYCLEITEMUsing cycle items you can make checkboxes, radio buttons and even things that resembles dropdowns in html. A cycleitem can have two or more states, who's appearance has pretty much no limits, as any piece of html can be executes on hilight and un-hilight of the state - just like a menu item. This is one of the new functions added in KML 2.4.Usage:
Example:The especially relevant parts are marked in orange. Relative URLs must be turned into absolute URLs:
ON-SCREEN KEYBOARDHere's a full source listing on how to make an on-screen keyboard and make it submit data back to the server, using the <VAR_INPUT>, <SUBMIT> and <FUNCTION> tags.
Additional FunctionalityCookiesKML 2.4 has limited support for cookies. Currently the cookies expire when the device is turned off, but not at stand-by. This is useful for logins, as your login will basically stay until you unplug and move the device.Setting and reading cookies in KML works just like in HTML. Refer to the programming manual of your server scripting language on more info on how to use cookies. EncryptionThe KML 2.4 client supports SSL encryption as https:// links just like normal web browsers. Whereas KML pages typically run on either port 8888 or port 80, ssl encrypted kml pages are usually exchanged on port 443 just like html.Both POST and GET forms can be submitted in SSL encrypted mode. Remember that the URL string itself is not encrypted itself, so if the values posted contain sensitive information, you should use POST. This goes for both KML and HTML. HTTP vs. RTSP StreamingOlder KiSS players only supported media playback over http. With the introduction of KML 2.4 playback of Windows Media .asx files over the rtsp protocol is now supported. If the player encounters an mms:// link it will assume that rtsp:// can be used, which is usually the case.When streaming over http:// you can use pretty much any audio and video format. Windows Media DRMKML 2.4 capable devics are also Windows Media DRM compliant. The necessary functionality is reflected in the documentation for the PLAYMEDIA tag.Website by Joachim Michaelis
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||