Up Up Home Home

BoxStar config file tag reference


This is the top-level tag of all boxstar config files.


Profile tags may appear anywhere within a document. The tag's content is a profile name, corresponding to a file in a profiles directory. Each profile is only loaded once (repeated references will be silently ignored) and profiles may refer to other profiles. BoxStar comes with the profiles directfb, dfbmga, ntsc and pal.


Env tags may also appear anywhere within a document and must contain a name attribute. They cause system environment name to be set to value value, which defaults to 1 if the attribute is ommitted. This tag is useful for configuring SDL drivers and external players.



The value of this tag specifies the delay in seconds to wait for more digits when a number is being entered. If no digit is pressed in the meantime the number is assumed to be complete. Default 2.5 secs.


If the value of this option is non-zero the menu item for switching between full screen and windowed mode is hidden.


If the value of this option is non-zero it prevents automatic switching from windowed to full screen while running an external player.


If this tag is present boxstar will use xrandr to change screen mode to try to match the video being played.

If using NVidia's proprietary driver you need to add:

Option  "DynamicTwinView"  "false"
to the "Nvidia" Device section of your X configuration (usually /etc/X11/xorg.conf), otherwise it reports incorrect refresh rates to xrandr. With an LCD panel you should also add:
Option  "FlatPanelProperties"  "Scaling = Native"
otherwise the video card will scale the desired resolution to the panel's native resolution without changing the refresh rate. See the driver's README for details.


Selects the output name to use for xrandr, in case boxstar can not detect the right one automatically. You can find the name by running xrandr and looking for the first word on the lines containing "connected".


The value of this attribute tells boxstar which strategy to use when choosing a mode. The possible values are:

Use the highest available resolution for the refresh rate (23.976 is treated as equivalent to 24 etc). If no modes match the refresh rate, don't change mode. Multiples of refresh rates are considered equivalent ie 25 = 50 etc.
Try to find an exact match for the resolution, and use the highest resolution if there's no match.
If there isn't an exact match use the highest available resolution with the same number of lines, otherwise use the highest available resolution for the refresh rate. This is the default.


This optional attribute instructs boxstar to pause for the given number of seconds (which may be floating point) after changing mode. Use it in case your display takes so long to lock on to mode changes that you would miss the start of videos.


Boxstar doesn't detect the resolution of TV streams from VDR so if you want to use the xrandr feature for VDR you need to specify a mode with this tag's attributes. The above strategy is used in case the exact mode isn't available.



In case some modes available on your monitor or TV are unsuitable for video you can list the only modes which are valid here. Otherwise boxstar will choose from all available modes. If no <narrow_modes> are defined these modes are used for all video, otherwise they are only used for widescreen.


This element's attributes define a mode valid for video playback.


Width in pixels. Compulsory.


Height in pixels. Compulsory.


Refresh rate (Hz/fps). Optional.


This is similar to <video_modes> but used for non-widescreen modes. The reason for having two sets of modes is that it allows some TVs to offer a better choice of aspect ratio settings.



Miscellaneous options pertaining to the display.



The width and height of the display respectively, determining the window size or screen mode. The default is 640x480.


Use a certain refresh rate in fullscreen mode, specified in Hz. Requires xrandr. When using this option, a temporary switch to windowed mode for playing video will not cause a mode change, so you should use a window_width and window_height small enough to fit.



If present these options override width and height when in windowed mode.


The colour depth (number of bits per pixel) to use for the display. The default value is 0, which means use the most appropriate setting for the system.


Set to 1 to make BoxStar take over the whole screen, 0 to use a window (driver permitting). Prior to version 0.6.0 this option was passed on to video players, now you need to add it explicitly to their options.


Sets the number of pixels to leave blank around each edge of the screen. The value inside the tags sets the value for all four edges at once. Each edge may also have its own value by using the following attributes.



A section for configuring how BoxStar uses the SDL library.


Set to 1 to make BoxStar ignore input events from SDL, 0 for normal behaviour.


Affects which keys auto-repeat can be enabled for. Valid values are:

"0" or "none"
No keys auto-repeat
"1" or "cursor"
Only cursor/arrow keys auto-repeat
"2" or "all"
All keys auto-repeat

The default is "all".



The content of these two tags are respectively the delay and interval settings for keyboard auto-repeat in ms. If used, they must both be specified.


Usually BoxStar will retain its SDL surface (ie leaving the window open in a windowed environment). This is inappropriate for some drivers, so setting this option to 1 causes SDL to be temporarily shut down while running external applications such as video players.


Add this tag at the top-level to enable the "devinput" driver. This makes BoxStar respond to Linux input device events, an interface used by some remote controls, especially ones attached to DVB cards. Use either the dev or match attribute but not both. You may specify this tag more than once to use multiple devices.


Use the specified device pseudo-file eg /dev/input/event0.


The value of this attribute is a regular expression. BoxStar scans the names of available input devices and uses the first device to match the expression. You may check the names yourself by reading /proc/bus/input/devices.


Whether boxstar should grab the device for its exclusive use. The default is true. Set to "0" to disable grabbing.


This is the same as SDL's repeat option except that the default is "cursor".


The media section configures a set of entries in the top-level menu for browsing and choosing files such as videos to play.


Defines a DVD drive. When this is opened from the menu BoxStar mounts the disc if necessary and scans its contents, taking appropriate action for DVD video, (X)(S)VCD or data discs. The attributes are mandatory.


The title to use for the drive in the menu.


The system device name eg /dev/dvd.


The mount point for discs eg /media/cdrom0.


The player to use for DVD, defaults to "mplayer". The alternative is "xine". Either way, MPlayer is still used for VCD and the content of data discs.


Identical to a dvd entry but doesn't handle DVD video discs.


When browsing for files, only files matching a regular expression in one of these tags are shown. This is useful to make sure only files whose extension indicates they're a media file eg .mpg or .avi are shown. More than one match tag may be used, or none to show all files. They only affect files, not directories.


Each filemenu tag adds an entry to the top-level menu. When the entry is seelected it opens a submenu to browse for media files in the specified directory. The attributes are mandatory.


The title to be shown in the top-level menu and as the submenu's title.


The directory to start browsing from. You may embed variables and/or use a leading ~ to represent the home directory.


Usually hidden files and directories (whose names start with a period) are not shown. Set this attribute to 1 to show hidden files and directories.


By default each filemenu inherits its <match> regular expressions from the enclosing media section. You may override them for any <filemenu> by giving it its own set of <match> tags.


Configure how BoxStar calls MPlayer.


By default MPlayer's dvd:// input driver is used for DVD, which is limited to playing the default or chosen track. Set this attribute to "1" if you want to try using the dvdnav:// driver instead to navigate menus. This driver is apparently considered unfit for general use so if you want DVD menus you should probably use xine for DVD instead.


Most widescreen TVs have an option or set of options to deal with 4:3 which work better than scaling the picture with the PC hardware or software. Giving this option makes MPlayer assume the TV is 4:3 when playing 4:3 videos and widescreen when playing widescreen videos. You can specify your monitor's aspect ratio as the content of this tag or leave out the content to use the default 16:9.


With this enabled (set the value to 1) BoxStar controls MPlayer via its slave mode. This is useful if you have a remote control and don't want to set up LIRC for MPlayer.


Set to 1 to disable LIRC in MPlayer only when in slave mode. If you want LIRC to always be disabled, do so with .mplayer/config or pass -nolirc in <video_opts>.


A config file with a slavemap section is provided as config/boxstar/mplayerslavemap. You can override it with your own slavemap section; it would be a good idea to use the supplied file as a starting point and example showing all the available action names. If you provide your own it will override all the entries in the provided one.


Maps a BoxStar input action to MPlayer commands. Currently only commands for playing video files are available.


The BoxStar input action name. See the provided map or boxstar/keycodes.py for all available names.


Whether to allow auto-repeat on this key (1 or 0).


The command to send to MPlayer when being used to play a video file. See MPlayer's slave.txt file, which should also be available as tech/slave.txt or tech/slave.txt.gz within your MPlayer package's documentation or its source tree.


As video but used in its place when playing a DVD with dvdnav.


If this attribute is present the command is a quit command which is a special case. If the player process doesn't quit and a quit button is pressed again, the player is sent a TERM signal. If this fails and the button is pressed again it sends a KILL signal.


A set of options (space-separated) to pass to MPlayer to make it analyse a video file instead of playing it. You should not need to change this from the default value of "-ao null -vo null -identify -frames 1 -nolirc".


Add extra options to MPlayer's command line when playing videos.


Add a basic option eg -fs. More than one option may be specified in each tag, separated by spaces.


Set this attribute to 0 if for some reason you need to pass an option containing spaces as a single argument.


Some of MPlayer's options are compound eg to pass parameters to a specific driver or to build a filter chain. The <suboption> tag allows these sorts of options to be built up from separate tags, whereas the basic <option> tag would force you to specify every attribute to the option in one go. For example, to add a crop filter without having to know whether any other video filters have been activated (actually this is a poor example because the order of filters is important):

<suboption name="-vf">crop:640:480</suboption>
If you wanted to configure the dfbmga driver to use PAL independently of other dfbmga parameters:
<suboption name="-vo dfbmga" sep1=":" sep2=":">tvnorm=pal</suboption>


The name of the option.


The separator between the option name and its first parameter. Defaults to a space if not given.


The separator between subsequent parameters. Defaults to a comma if not given.


1 or 0. Enables VDPAU output and automatically tries to select VDPAU codecs.


Configure how BoxStar calls Xine.


Extra options to add to the xine command line. Parsed the same way as Mplayer's video_opts section.


This section is xine's equivalent of mplayer's slavemap section. Read that for details. A config file with default mappings is provided as config/boxstar/xinestdctlmap.


Configures how video players handle being asked to play both NTSC and PAL videos on different occasions. Only properly supported with certain output drivers or when xrandr is enabled. The dfbmga profile enables automatic TV standard switching <auto>1</auto> but that may be overriden by setting it to 0 before including the profile.


Set to 1 to make BoxStar set video players' options to PAL or NTSC, or choose a suitable mode with xrandr, depending on the video type, 0 to use the players' underlying configuration or not switch mode. The default is 0.


If <tvnorm><auto> is enabled this option controls how to deal with 24fps (film-derived) video. Possible values are:

Do nothing, or choose a 24fps compatible mode if available (the default).
Select NTSC standard. This should hopefully cause a form of pulldown to be performed, which may look juddery, but maybe not as noticeable as paldup.
Select PAL standard. This generally forces every 24th frame to be shown twice to make up the 25fps, which tends to cause a jerk once a second.
Select PAL standard and play the video and audio slightly faster to avoid the jerkiness of repeated frames. This is the technique usually used for mastering DVDs and broadcasting although professionals often also use sophisticated filters to avoid the pitch of the sound increasing. Currently only works with MPlayer.


Options to add to an mplayer command line to select PAL or NTSC.


Options to add to an mplayer command line to select PAL.


Used the same way as an mplayer <option>.


Used the same way as an mplayer <suboption>.


Options to add to an mplayer command line to select NTSC. These options have the same semantics as the <pal> element.


Options to add to an mplayer command line when the palspeed <telecine> option is selected. These options have similar semantics to the <pal> element except that the <option> and <suboption> values may contain %f (only once per (sub)option) which will be substituted with the speed factor before being passed to MPlayer.

The default if this tag is omitted is <option>-speed %f -fps 25</option>.


Options to add to a xine command line to select PAL or NTSC. These are similar to the mplayer tvnorm options except xine does not support palspeed.


Add this tag at the top-level to enable boxstar's interface to VDR.

This feature allows BoxStar to control VDR by passing translated key or remote control presses to VDR via its remote plugin or its SVDRP interface (using the HITK command) while running xine or similar for watching VDR's output. To exit VDR mode use the "Power" button.

Using SVDRP is not recommended because it can only support one client at a time so you won't be able to use boxstar at the same time as vdradmin for instance. On the other hand I have found that the remote plugin stops responding every so often and had to keep exiting to boxstar and reentering VDR mode - especially if I press the red button to show progress when playing back a recording. Setting a short timeout should alleviate this problem.


Text to put in the top-level menu item for VDR instead of the default.


If this tag is present its contents are treated as a command to run to watch VDR's output. It will simply be killed when you press the Power button. If the tag is empty the default value is "xine xvdr://localhost:37890" which is suitable for connecting to VDR's xineliboutput plugin on the same machine. Note that this default has changed; it used to use the xine device plugin.


Use this tag if you want boxstar to control VDR via the remote plugin (preferred). It takes these attributes.


The hostname. May also be expressed as a dotted numerical address. Defaults to "localhost".


The port expressed as a number. Defaults to 3333.


Set this to a small value (eg 2 seconds) if you find that VDR keeps becoming unresponsive to keypresses. This is an integer in seconds.

The remote option can have the following child nodes.


Some keys on a remote control may have more than one action assigned to them eg Left/Right = Volume Down/Up. If this child tag option is set to 1 all the actions are sent to VDR. If 0 (default) only the first action is sent.


Define a map of boxstar commands to VDR keystrokes. A default map is provided as config/boxstar/vdrremotemap


A map entry.


The BoxStar input action name. See the provided map or boxstar/keycodes.py for all available names.


The keystroke for the VDR action expressed as the ASCII code in 2 hexadecimal digits.


Use this tag if you want boxstar to control VDR via its SVDRP server (deprecated). It takes these attributes.


The hostname. May also be expressed as a dotted numerical address. Defaults to "localhost".


The port expressed as a number. Defaults to 2001.


VDR usually closes SVDRP connections after 300 seconds. The value can be changed in VDR or set to 0 to disable the timeout. You should either configure boxstar's timeout to a lower value to close the connection itself before VDR does or configure both to 0. The default here is 200.

The SVDRP option can have the following child nodes.


A SVDRP command to send immediately after connecting. No command is sent by default.


A SVDRP command to send immediately before disconnecting. No command is sent by default.


Some keys on a remote control may have more than one action assigned to them eg Left/Right = Volume Down/Up. If this option is set to 1 all the actions are sent to VDR. If 0 (default) only the first action is sent.

Up Up Home Home