Configuration options

Configuration reference for kissdx v0.14

Configuration of kissdx is done by editing the configuration file kissdx.conf. [File:V0.14.png]]Note that multiple locations of the kissdx configuration file is supported. The search order is as follows (1 is read first, 4 is read last if not found in 1,2 or 3):

  1. location specified in command line argument: kissdx -c full-path-to-config-file
  2.  ~/.kissdx (~/ means /home/{your_user}/ )
  3.  ./kissdx.conf (./ means the current directory)
  4.  /etc/kissdx.conf 

On Optware platforms the normal location is /opt/etc/, not /etc/.

Each line in the configuration file must be on the following form:

  keyword = value

There must be at least one space or Tab characer before and after the equal sign. Lines starting with a # character are comment lines and will be ignored by kissdx. Reserved keywords of the kissdx configuration are displayed in bold in the examples below.

Notice that any unknown keyword will prevent kissdx streaming server from starting properly. Check the output from kissdx (in your syslog or in console output) to see a detailed description and information to help you optimise your configuration. If you see the message "Error(s) in the configuration file prevent kissdx from using the file", there is something wrong with your kissdx.conf, and kissdx will not start / will not re-load the configuration.

Specifying media repositories

kissdx operates by serving media files to a KiSS media player from media repositories. You must tell kissdx where to look for those media files in the file system. This is done by setting media paths in the configuration options below.
Media paths are full paths (not relative to kissdx executable or current directory). A trailing slash is optional.

• Special advice for Cygwin users

Windows path syntax C:\path can be used.

  audiopath   = /media/audio
  videopath   = /media/video
  picturepath = /media/picture

Each of the options above can be specified more than once in the configuration. If you need to access multiple directories for a repository type (e.g. you have two directories containing audio files), just repeat the setting as necessary, specifying the other directories. The first directory specified will be presented as the root folder on the player. The subsequent directories will be presented as subfolders of the root.

• Since version 0.11-3

You can limit the allowed filename extensions (file types) for each media file repository by specifying a list of file types (comma separated, no spaces, case insensitive).

Omit a setting to have kissdx send ALL files to the player in the corresponding directory listings, whether files are playable or not.

NOTE: Sending all files to the player may cause a firmware bug in KiSS players to show up: Sporadically some file names are not listed, even if they are playable files.

These are the recommended defaults:

   audiofileextensions   = mp3,ogg,wma,wav
   videofileextensions   = mpg,mpeg,vob,avi,wmv,ts,mp4,divx
   picturefileextensions = jpg,jpeg,png,bmp

Persistent storage

Since version 0.13-8For certain operations, kissdx will need a place to store its own files. The persistentstoragepath option should be used to set up a persistent storage area for kissdx.

The persistent storage area is currently used to support the Streaming history feature and the Picture Caching feature. Those features can be used even without a persistent storage area, in which case kissdx will save data in hidden folders in the media repository instead. Read-only media repositories (like CD and DVD drives) will then disable these features, because kissdx can not save data in those locations. To avoid these limitations and keep your media directories clean, configure persistentstoragepath to point to a writable folder on the server.

Special advice for Cygwin usersWindows path syntax C:\path can be used.

Default value: If the option is omitted, kissdx will use the media repositories (picturepath, etc.) for persistent storage.

   persistentstoragepath = /var/kissdx 

Since version 0.14A PID file can be written by kissdx on startup. This will let users and other programs see which process is currently the kissdx daemon process. This file is not needed by any kissdx component. The file will be deleted when kissdx is terminated in a controlled fashion.

Default value: If the option is omitted, kissdx will not write a PID file.

   pidfilepath = /var/run/kissdx.pid

Streaming history

Since version 0.12-4The streaming history feature is activated by specifying a value other than 0 for the max_recent_files option. This will make kissdx show an extra history folder in the root of each media repository. Selecting this folder on the player will display a list of the files that were most recently played, providing direct access to play them again.

   max_recent_files = 30

Note that a Persistent storage location should be defined to manage where the history files are stored.

Since version 0.14The name of the history folder can be customised using the recentlyusedfoldername option that supports national language. Default value is '[Recently used]'

   recentlyusedfoldername = [Recently played]

Character set handling

Since version 0.13-5When data is sent to and received from the media player, in some scenarios the file names must be translated from one character set to another. Whether and how this should be done depends on how the files were stored on the media server, and which character set the player uses.

Both settings below must be specified for translation between server and player to take place. Example:

   server_character_set = CP850
   client_character_set = ISO-8859-1

Since version 0.14In addition, config_character_set should be specified if the configuration file is being edited with a character set that is different from that on the player:

   config_character_set = ISO-8859-1

Since version 0.14Similarly, if playlists are being edited with a character set that is different from that on the player, the playlist_character_set option should be specified:

   playlist_character_set = ISO-8859-1

The values specified must be iconv character set names. Refer to http://www.gnu.org/software/libiconv/ for valid names.

Special advice for Optware usersTo get additional character sets onto a NSLU2 NAS server running Unslung, run this command: ipkg install gconv-modules.

Picture handling

Since version 0.13-6Without the picture scaling options below, kissdx will simply serve picture files directly from disk as is, perhaps causing unnecessary network traffic and hence long delays while serving pictures much bigger than the TV screen on which they are viewed.

Luckily, for jpeg images, kissdx can re-scale each picture to better fit the display screen. The picture scaling options specify screen width / screen height in pixels, and an optional zoom percentage. You must specify both picturetargetwidth and picturetargetheight to enable picture scaling.

The picturemaxzoompercent option can be used e.g. to enlarge and crop 4:3 pictures on a 16:9 screen. It specifies how many percent of the original image can be cropped (removed) at the horizontal or vertical edges to make it better fill the canvas of the target screen, thus reducing or completely removing the black bars at the top/bottom or left/right of the picture. Do not confuse this setting with the zoom function on the player.

   picturetargetwidth    = 1280
   picturetargetheight   = 720
   picturemaxzoompercent = 20

When picture scaling is enabled, a picturecachesize of at least 1 should be used (see below) - or else the scaling will be performed twice every time a picture is requested by the player, with bad performance as a result.

In addition to scaling, kissdx can cache the scaled pictures so the scaling won't be performed each time the picture is requested by the player. This gives much better performance when a picture is requested a second time, and it's perfect for the automatic slide show on the player because kissdx will pre-scale and pre-cache the next picture to be displayed, having it ready to be sent when the player requests it.

You activate the picture caching feature by setting picturecachesize to a value other than 0. Set it to -1 for no limit. Note that a Persistent storage location should be defined to manage where the cache is created.

   picturecachesize = -1

The scaled picture cache must be trimmed on a regular basis to enforce the picturecachesize limit (unless it has been set to -1). By default this will be done every five minutes. You can adjust the period (in minutes) between each time the size of the scaled picture cache will be trimmed down to the maximum size defined by picturecachesize.

   picturecachetrimminginterval = 5

Generally a higher number gives better performance. If set to 0, maximum cache size will be enforced every time a picture is viewed, potentially giving very bad performance if combined with a large picturecachesize.

Audio handling

There are no settings specifically covering audio handling in this version of kissdx.

Video handling

Since version 0.13-6When playing AVI video files, a KiSS player will look for subtitle files having the exact same name as the AVI file but with a filename extension of srt, sub, and others instead of avi.

kissdx can be configured to relax this strict naming scheme. Instead of looking for subtitle files exactly as the player requests them, kissdx can serve any subtitle files that acutally exist and match a given pattern containing wildcards.

kissdx will send up to 7 subtitle files that match the pattern after the colon in the value for the subtitlefilemapping setting. The subtitle files don't have to be of the type that the player requests. kissdx will send the files that are actually present on the disk.

   subtitlefilemapping = *:{name}*.*

The pattern may contain variables that will be substituted with parts of the video filename/path:

{name}

   filename without extension (most likely to be used) 

{ext}

   extension (not likely to be used) 

{path}

   path (to the left of filename, no trailing slash.) 
   If used in pattern, pattern must describe entire path. 
   If not used, the path of the video file will be inserted before pattern. 

If this setting is omitted, a value of *:{name}*.* is assumed.

Since version 0.14When kissdx plays video from DVD folders or DVD ISO images, it normally uses libdvdread to access the DVD contents. An alternative method, libdvdnav, can be selected:

   dvdaccessmethod = libdvdnav

NOTE: libdvdnav is not fully supported yet (experimental). It is being introduced in an effort to handle DVD navigation and playback better.

Generic media file handling

Since version 0.14Older KiSS players do not list some file types even if their contents can be played. Typical examples are .ts video files and .wav audio files. Renaming the file on the server to a supported file type will normally let the player use it. This renaming can be done automatically by kissdx:

   renamefiletypes = ts:mpg,wav:mp3

This option must be specified as a comma-separated list of renaming instructions. Each renaming instruction has the form oldfiletype:newfiletype.

Disk image handling

Since version 0.13-6kissdx can play DVD contents from image files. A list of filename extensions that are to be seen as image files by kissdx can be specified (comma separated, no spaces, case insensitive). Without any setting, only files with the .iso extension will be interpreted as ISO images.

   isofileextensions = iso,img

Player display

These options cover special features of kissdx that relate to how or what data is displayed on the player.

Since version 0.13-9You may come across a situation where some content should not be displayed at all times. By default, kissdx will not display folders or files whose names start with a dot (.). Specifying enablehiddenfilestext = 'gui-text' will make available a pseudo-file in the Pictures root folder with this name: "gui-text.jpeg"

When selecting this file on the player, the ability to view hidden content will be toggled on/off, and a picture describing the new state (on or off) displayed.

   enablehiddenfilestext = Show it all

If enablehiddenfilestext is specified, then enablehiddenfilesminutes can be specified to set a timeout period of n. Then n minutes after the viewing of hidden content was turned on, it will be automatically turned back off.

   enablehiddenfilesminutes = 1

Since version 0.14The listhiddenentries option can be used to turn on the display of hidden content by default:

   listhiddenentries = yes

Since version 0.14On newer firmwares for the DP-600 and 1600 players, the file listings are automatically sorted alphabetically by the player. This will mess up special sequencing done by kissdx (like placing the [Recently used] folder at the top). To overcome this, kissdx can add sequence numbers to the start of all folder names and file names:

   displaysequencenumbers = yes

Since version 0.14When listing PC-Link servers on the player, you see the signature of the kissdx server. While the default signature contains useful info, you may want to customise it to your needs, like this:

  serversignature = My kissdx {Version} {VersionDate}) @ {ShortHostName} {ConfigReloadStatus}

The serversignature setting is a string containing replacement tokens that will be replaced by actual data when the signature is sent to the player. The default value is "{ShortHostName} - kissdx {Version},{VersionDate} {ConfigReloadStatus}".

The following case sensitive replacement tokens are supported:

{FullHostName}

   The full name of the server (FQDN (Fully Qualified Domain Name)) on which kissdx is running, e.g. 'myserver.mynet.lan' 

{ShortHostName}

   The short name of the server on which kissdx is running, e.g. 'myserver' 

{Version}

   The running version of kissdx. 

{VersionDate}

   The release date of the running version of kissdx. 

{ConfigReloadStatus}

   The result of the automatic reloading of the configuration file that was performed in response to this server signature request from the player: 
   (OK) means the configuration file loaded ok. 
   (conf!) means there was a problem and the syslog or console output should be consulted. 
   Note that if configautoload = no has been set, then a UDP request does not reload the configuration and the server signature does not display (OK) or (conf!). 

Configuration loading

Since version 0.14 The decision on manual vs. automatic reloading of the configuration settings from kissdx.conf depends on your environment and needs.

If you need to refresh the kissdx configuration frequently without stopping kissdx services, the configautoload option can be set to yes, to enable automatic reloading of the configuration each time any KiSS player displays the menu "Search PC-Link server" (UDP broadcast request):

   configautoload = yes

On the other hand, if you need a stable kissdx service even if its configuration file is modified, then the configautoload option should be set to no, to prevent automatic reloading:

   configautoload = no

In both situations, the administration facilities offer you the possibility to manually reload the configuration from the kissdx.conf file. Take care to note which kissdx.conf will be loaded on your system. Refer to the description of the RELOAD_CONFIG administration command for details on search order.

Specific to new KiSS players: As described above, newer versions of kissdx can automatically reload the configuration from the configuration file each time a PC-Link server discovery request is received from a KiSS player on the network. This approach works fine for most players, but with the newer fimwares on DP-600 and 1600 (KNAS firware), the player will send these requests very frequently, maybe every 10 seconds. That causes a lot of unnecessary re-reading of the configuration file, and we lose control of when the configuration is reloaded. In this scenario you probably do not want the configuration file to be automatically reloaded.

The default value for this setting is no.

Note that a controlled configuration reloading can now be done with the following administration command:

./kissdx -m mymediaserver -s reload_config

Extending kissdx using triggers

It is possible to extend or customise the processing done by kissdx, using triggers that will be executed as the user operates the KiSS player. A typical application is to resize or pre-process a picture into a temporary file, or do some other processing on a media file before kissdx gets its hands on it.

Pre and post triggers are called before and after a GET or SIZE TCP command from the player. Those scripts need the filename as an argument and return the new (temporary) filename on stdout and a exit status of 0 to proceed. An non zero exit status will cause the GET/SIZE to fail.

Special advice for Cygwin usersWindows path syntax C:\path can be used.

   pretrigger  = /usr/local/bin/kissd-pretrigger
   posttrigger = /usr/local/bin/kissd-posttrigger

Since version 0.14It is also possible to have trigger scripts run when a folder is selected on the player:

   directorypretrigger  = /usr/local/bin/kissd-directorypretrigger
   directoryposttrigger = /usr/local/bin/kissd-directoryposttrigger

The directory pretrigger script will be called just before a directory is to be listed.

The directory posttrigger script will be called just after a directory has been listed.

The same rules apply for directory triggers as for file triggers:

   The selected directory name is passed in parameter 1 to the script.
   The script must return the new (maybe temporary, maybe virtual) directory name on stdout and exit with status 0 for the folder to be listed. 

KML server

kissdx can serve as a KML proxy by listening on the KML server port and forwarding a KML index page request to a specified KML page.

You activate this feature by setting kmlforwardurl to a URL to redirect to when the KiSS player requests a "KML homepage" menu:

   kmlforwardurl = http://tinystocks.com/k/kiss.php

Administration server

Since version 0.14kissdx can be managed locally or remotely using a second kissdx instance to send administration commands to the running kissdx daemon.

This feature works by kissdx listening for commands on a TCP port and sending replies back using a command protocol. The feature is enabled with the adminserver_port setting. We recommend to use the tcp port 8003.

   adminserver_port = 8003

A kissdx daemon configured with the setting above can be managed remotely by issuing a kissdx utility command like this:

   ./kissdx -m mymediaserver -p 8003 -s reload_config

The above command will instruct the kissdx daemon running on the mymediaserver computer to immediately re-read its configuration file.

Check out the Management guide for details on management commands.

Networking

This section specifies how kissdx behaves on the network.

Since version 0.13-8The networktimeoutinterval option can be used to specify a timeout period (in seconds) to clean up waiting processes.

    networktimeoutinterval = 3600

This option is normally only needed if the KiSS player does not close all connections properly. Such erroneous behaviour has been confirmed when playing ogg Vorbis audio files on a DP-600 with 3.0.34 firmware. In this scenario this setting will clean up hanging kissdx processes, but the DP-600 will still have problems after playing many .ogg files, so it's not a perfect solution. Upgrade to KNAS firmware to resolve this.

No option or a value of 0 or less will disable timeout checking.

Since version 0.14On a multi-homed system (a server with multiple network adapters installed) it may be desirable to control which interface kissdx listens on when waiting for commands from the player, to restrict access. We can do this by setting the listenaddress option to the desired server IP address:

    listenaddress = 192.168.1.2

The value specified must be a valid IP address for the server. Set it to 0.0.0.0 to listen on all interfaces. This is the default.

• Tips:

   Set it to 127.0.0.1 to listen only locally. Not very convenient since the player can not connect... 
   Setting it to your KiSS player's IP is not correct. It should be a local address that receives the TCP requests. 

Retrieved from "http://www.famille-kahn.com/kissdxmanual/Kissdx_user_manual:_Configuration_options"