================= README for kissdx ================= kissdx is a PC-Link clone for KiSS media players, based for the most part on kissd, with enhancements from / inspired by wizd. In addition lots of new features have since been added to kissdx. Graphics code taken from gd, as per this notice in gd documentation: "Permission has been granted to copy, distribute and modify gd in any context without fee, including a commercial application, provided that this notice is present in user-accessible supporting documentation." References: kissd: http://www.popies.net/kissd/ armlink: http://home20.inet.tele.dk/horneckernet/html/fritidogferie/armlink.htm wizd: http://wizd.sourceforge.net/ gd: http://www.boutell.com/gd/ kissdx: http://kissdx.vidartysse.net/ Please refer to kissd / PC-link documentation for basic functionality, like how to set up the very important kissd.conf file (or kissdx.conf as per v0.12-4). kissdx is an enhanced kissd. The enhancements are: 1. Support for playing the VOB/IFO/BUP files in a VIDEO_TS folder as if it was a DVD This functionality is based on code from wizd, which again depends on libdvdread. 2. Support for playing DVD ISO images This functionality is based on code from wizd, which again depends on libdvdread. 3. Supports wildcard pattern for subtitle files, thus relaxing the strict naming convention for subtitle files normally required by by KiSS players. 4. Support for scaling of pictures to better fit the TV screen, and to avoid problems with some files. 5. Support for caching of scaled pictures to speed up the display of pictures that have already been displayed once. This includes pre-caching of the next picture to be displayed, to speed up sequential browsing / slideshow. 6. Arbitrary character set translation between server and player. 7. Location for persistent data can be specified in configuration file to allow read-only media paths with full functionality 8. Configuration changes are recognised without the need for a restart. Just scan for available servers on your player, and all listening kissdx servers will re-read their configuration files. 9. The viewing of hidden content can optionally be controlled from the KiSS player's remote. 10. Support for playing all mp3 or ogg files in a directory back-to-back, ie. without a pause between each track. Great for live albums! ---------------------------------- Notes on DVD image/folder playback ---------------------------------- The current implementation is a bit crude, but given the limitations of KiSS PC-link server protocol and KiSS player GUI it is about as good as it can get: - There is no real DVD player functionality - No DVD menus - No subtitles - No language support - No chapter navigation - No angles, etc. - In-stream instructions are not processed - the entire VOB stream is served to the player, start to end. Basically, what it does is this: - A DVD (an ISO file or a folder with a VIDEO_TS subfolder) is presented on the player as a folder, with a special prefix to identify it: {kissdx-ISO} for ISO images {kissdx-DIR} for folders with a VIDEO_TS subfolder - The user selects the folder on the player, and all titles of the DVD are listed. - A title can be selected for playback, which will start playing back the entire VOB file set that the title belongs to, from start to end. Selecting title 1 will play the entire main movie on most DVDs tested. ------------------------------------ Notes on playback of audio playlists ------------------------------------ The m3u and pls formats are supported. A playlist is presented on the player as a folder, with a special prefix to identify it: {kissdx-M3U} for m3u playlists {kissdx-PLS} for pls playlists Select the folder on the player to display the contents of the playlist. --------------------------------- Notes on the scaled picture cache --------------------------------- When caching of scaled pictures is enabled, a picture will be placed in the cache the first time it is displayed. Subsequent viewing of the same picture will be quicker, especially on slow servers like the NSLU2. If the picture scaling settings are changed, all the pictures in the cache are invalidated and will be re-scaled and re-cached the next time they are requested. Conversely, changing picture scaling settings back to their previous values will make valid again all cached pictures that have been scaled with those values. When a limit on cache size has been set, the GNU Linux sort command must exist in PATH for cache trimming to operate at all. Even if you don't want to use the cache, a cache size of 1 is recommended if you use the picture scaling feature. With the cache completely disabled, picture scaling will be performed twice per request and performance will suffer accordingly. See DevDocs/piccache-specification.txt for details of the implementation. ------------------------------------ Notes on back-to-back audio playback ------------------------------------ When listing an audio directory that contains mp3 and / or ogg files, kissdx will present an additional entry for mp3 and / or ogg files, looking like this: {kissdx-B2B}folder name.mp3 {kissdx-B2B}folder name.ogg The user selects this file for playback of all mp3 or ogg files in that directory back-to-back. The current implementation simply concatenates all individual media files into a bigger combined pseudo-file that is presented to the KiSS player. No mangling of metadata (MP3 ID tags, etc.) is performed by kissdx. Thus, for MP3 playback the combined file will look like the last media file in the set, and for OGG it will look like the first one. The total playback time is calculated by the player and may be wrong, but relative seeking inside the combined file still works. ------------ Known issues ------------ DVD playback is a bit crude, as noted above. Some DVDs can be played with good results, others without sound, etc. YMMV. Running under Cygwin with caching of scaled pictures enabled, the cache may grow beyond the cache size limit and never be trimmed, and the message "Input file specified two times" will appear in kissdx output. This is caused by kissdx running Windows' sort program instead of the GNU Linux sort program included with Cygwin. Solution: Either edit your PATH so that C:\cygwin\bin (or equivalent) appears before C:\WINDOWS\system32 (or equivalent), or run kissdx in a Cygwin window. To start a Cygwin window and run kissdx automatically, create a batch file modelled on Cygwin's cygwin.bat, but with a bash startup line like this instead of the default one: bash --login -i -c "'/cygdrive/c/Program Files/kissdx/kissdx.exe' %*" Back-to-back audio playback will present the player with metadata that does not correctly describe the combined file. Playback still works, tested only on a DP-600. Back-to-back audio playback can be very slow to start, especiallyi if there are many media files in the combined file, especially on Windows, and especially with OGG files. This is due to files being opened and closed all the time as the player requests data from very many locations in the combined file, as it is analyzing the file. ------------------------- Installation instructions ------------------------- 0. On Optware platforms or other big-endian linux ARM platforms you can install kissdx using the ipkg packaging tool. On Optware (see http://www.nslu2-linux.org/wiki/Optware/HomePage) just issue the following commands: ipkg update ipkg install kissdx On other big-endian linux ARM platforms you can install from the current package file over the net with this command: ipkg install http://kissdx.vidartysse.net/kissdx_0.13-8b-1_armeb.ipk On other platforms, follow the steps below. 1. Download the source code and compile it on your target system, or cross-compile it for your target if you have the environment for that. OR If you have a NSLU2 running Unslung (or another big-endian linux), Grab the NSLU2 executable from subdirectory bin-NSLU2-Unslung in the downloaded archive, and install it where you please on your slug, e.g. in /opt/bin/. OR If you want to run kissdx on Windows (under Cygwin), Grab the Windows executable from subdirectory bin-Windows-Cygwin in the downloaded archive, and install it where you please on your machine, e.g. in C:\Program Files\kissdx. Install Cygwin from http://www.cygwin.com/. 2. Make sure that you have the necessary libraries installed. kissdx depends on the development packages for libdvdread for playing DVD ISOs and VOBs libjpeg for rescaling jpeg images libiconv for character set translation between player and server On an Unslung NSLU2 this is simply a case of installing the packages, with these commands: ipkg update ipkg install libdvdread ipkg install libjpeg NSLU2 Unslung has iconv included, but you may want to install additional code pages / character sets: ipkg update ipkg install gconv-modules Other Linux distros may have libiconv included, and you won't find a package for it. If that is the case, you may also need to remove -liconv from the $(CC) line in the Makefile. NSLU2 Unslung is based on Busybox, which has a crippled sort command. You must get the coreutils package to have the proper sort command: ipkg update ipkg install coreutils Also make sure that /opt/bin is in the PATH variable for the new sort command to be used by kissdx. 3. Follow the same procedure you would for installing kissd: The easy way: - Unpack the downloaded archive into a new directory - cd to that new directory/kissdx - Run these commands: make sudo make install Manually (if you are replacing kissd on your system with kissdx): - Stop kissd if it's running - Place kissdx in the directory that kissd is currently in - Delete kissd from that directory (or rename it for backup) - Rename kissdx to kissd, effectively replacing kissd in place - Start kissd (which is now actually kissdx) Manually (if there's no kissd on your system already): - Place kissdx in /opt/bin/ (as noted above) - Place kissdx.conf in /etc/ - To have kissdx start automatically when your system starts, create a file /opt/etc/init.d/S83kissdx with the following two lines in it: export LD_LIBRARY_PATH="/opt/lib" /opt/bin/kissdx -kd >/dev/null 2>&1 Make the file executable with this command: chmod 0755 /opt/etc/init.d/S83kissdx 4. Revise the file types (extensions) configured in kissd.conf to make sure they match your needs. Also check that the other settings fit your needs. 5. The first time you start kissdx after installing it, or after changing settings in the config file, start it manually by executing the following command: /opt/bin/kissdx -k Check the output on your screen for error messages while testing out its features on you KiSS player. When you are satisfied that kissdx works, stop it with Ctrl-C and type the following command to launch it in the background as a daemon: /opt/etc/init.d/S83kissdx 6. Report and check up on any problems / bugs / feature requests at http://www.vidartysse.net/BUGS/ Best of luck! __Vidar__