Up Up Home Home

BoxStar config files


BoxStar uses XML configuration files. They are more complicated than simple key-value config files but more flexible. The top-level tag of each file is always <boxstar>; other tags depend on the content. See the example for a good overview. There is also a reference detailing all the tags.

Other examples are provided with the distribution in the config/examples subdirectory. When you see example files referred to in this guide, look for them there.

Quick start

As a bare minimum the following piece of XML should get you started. For a more complete example which should be more useful as the basis for your own config, make a copy of sample_config.txt and edit it for your needs. Please do read the rest of this page and those it links to.

<?xml version="1.0" standalone="yes"?>
        <dvd title="Watch DVD" dev="/dev/dvd" mount="/media/cdrom0"/>
        <filemenu title="Browse home directory" dir="~" />


Having a single configurarion file just wouldn't be complicated enough! The files fall into two sets of categories.

Base directories

The first set of categories is based around who the files are aimed at and this determines which base directory is used. The base locations follow the XDG Base Directory specification with BoxStar's unique name being boxstar.sourceforge.net. This is explained further below.

In descending order of priority:

  1. Files for a specific user
  2. Files for a specific system
  3. "Factory" defaults

Files for a specific user

The base directory for these is ${XDG_CONFIG_HOME}/boxstar.sourceforge.net, or ~/.config/boxstar.sourceforge.net if XDG_CONFIG_HOME is unset.

This is the location for files written by the user or files automatically generated while boxstar is running eg input device keymaps.

Files for a specific system

The base directory for these is ${XDG_CONFIG_DIRS}/boxstar.sourceforge.net, or /etc/xdg/boxstar.sourceforge.net if XDG_CONFIG_DIRS is unset. XDG_CONFIG_DIRS is actually a path ie it may contain a number of directories separated by colons, each of which will be scanned for configuration files.

The system administrator can add config files here if more than one user is likely to use BoxStar. For effectively single user systems it's best to ignore this location and stick to the user base location.

"Factory" defaults

BoxStar's distribution directory contains a subdirectory called config which is the base directory for config files supplied with BoxStar. For example this contains an MPlayer slave map to save beginners writing one; but if users don't like the mappings they can replace it in their own config files.

At the moment BoxStar always runs straight from its distribution directory ie where you unpack the distribution tarball. This will always remain one possible way of running BoxStar, but if and when packages such as .rpm and .deb are written this location is likely to change to /usr/share/boxstar/config.

All files from any of the above locations are loaded, apart from unreferenced profiles. Options from locations with higher priorities take precedence over options with the same tags from lower priority locations.

Within each base directory there are other categories:


Profiles belong in a subdirectory of one of the above base locations called profiles. The file's leafname is the same as the profile name.

Generated config files

BoxStar may generate its own config files; these are always saved in the user base directory. For example, input device keymaps are saved in ${XDG_CONFIG_HOME}/boxstar.sourceforge.net/input_maps/ in a subdirectory named after the software module controlling it and a file named after the device.

Miscellaneous config files

These are the files you write yourself. They belong in a subdirectory called boxstar eg ${XDG_CONFIG_HOME}/boxstar.sourceforge.net/boxstar/ but you may choose any leafname for them. Later on the package will include a daemon for making TV recordings, called boxstard for short; files for configuring it will belong in the subdirectory boxstard.

This gives you the choice of putting all your settings in one large file or splitting them up into subsections.

Example file

See separate page.

Tag reference

See separate page.

Setting up external dependencies

BoxStar depends on a number of other libraries and devices which may need setting up. Here are some tips.


There's a whole page dedicated to SDL, but don't worry, you can ignore most of the complicated stuff for many drivers.

TV out

Setting up a video card for TV out in Linux can be a bit tricky, not least getting a card with decent quality output in the first place. I've written a HOWTO on the subject.

DVB card

I've written a DVB card HOWTO as well. It's aimed at a specific model of card, but much of the information is general and applicable to other cards. BoxStar doesn't support DVB functionality yet except that it can make use of the remotes that come with most models with the input device event module. See the VDR page for details on how to use that program in conjunction with boxstar for full DVB PVR functionality.

Up Up Home Home