OSTBOX documentation


OSTBox is (yet another) set-top box program. It is designed around xml and javascript : it's interface is a collection of xml pages with embeded javascript code.

Here is what ostbox can do for the moment :

It will (soon) have the following functionnality :

A detailled TODO list and release schedule is available here.

Internaly, OSTBox is divided into three parts :


2.1. Requirements

You will need the following library installed (with headers) :

You need to have a running X Server. You do not need a window manager since it is useless and could cause more trouble.

LIRC support is also required, unless you can configure your remote to send keyboard events in X.

For sound, you need alsa drivers and alsa-utils installed. (oss won't do.)

If you plane to use a dvb card, you'll probably need the tzap/scan utility installed.

2.2. Compilation


  	$ ./configure --prefix=/usr
  	$ make
  	$ make install
  	$ ostbox

Usefull keys:


3.1. Installation settings

In this chapter, you'll configure some parameter specific to your system. All these settings are available in the setup/Installation settings menu.


Choose your language with the language option. English is the default one. Select the desired language or use back to cancel.

Photos directory

This items let you specify the directory under which you store your photo albums. You'll be able to browse this directory, watch its image files (jpg, png, ...) and its video files (avi, mpg, wmv)

NOTE : Your system is supposed to use unicode encoding for path names. If this is not the case, you may have problems with paths which have non ascii characters.

Music directory

This items let you specify the directory under which you store your music files. You'll be able to listen to music files under this directory, and watch their covers (jpg, png, ...)

Video directory

This items let you specify the directory under which you store your video files.

OST-Box will detect records from TV, and correctly report them, if the file name respect the following notation : ` YYYY.MM.DD-HH.MM-Channel-title.avi`

Video player

Currently, ostbox need to use an external program to play video. This option let you specify the path to this tool. Default value will use mplayer.

X11 key grabbing

This option is only usefull if you intend to control ostbox with a keyboard (in fact something which is not a lirc device; on some system you can have a remote device configured as a keyboard).

When this option is enabled, ostbox will intercept some keys when it starts an external program. The key intercepted are those used to change volume, and to change channel (when playing tv/radio).

Power control mode

OST-Box has two different type of power off :

3.2. Appearance

Visual settings of ostbox can be adjusted within the interface, under the setup/Appearance menu.

Screen resolution

In the appearance menu, you can adjust screen resolution.

When choosing a screen resolution, keep in mind that ostbox has no support for hardware scaling of video (for the moment). So bigger resolution will results in higger CPU usage when viewing video.

Ideally, the resolution you choose should match the size of the video stream you will be watching to. For a good experience, you should also configure your X-Server to support only this resolution, in order to avoid any resolution switch when using external tools.

It is also possible to switch between fullscreen or window mode. Most people will want to run ostbox fullscreen. However, it can be usefull to run it in a window when playing with settings.


You can adjust fonts family and sizes. ost-box can use any truetype fonts. It comes with two fonts, but you replace them with your own fonts.


With the skin option, you can switch between two different looks for the UI.

3.3. Controls

It is really easy to configure ostbox to use your lirc remote, once you have lirc running.

You can verify that lirc is running fine by running the irw tools (which comes with the lirc daemon). When you press any key on your remote, this tool should display something on stdout. If this is ok, you are ready to configure your remote within ostbox...

Adding a remote

In the setup menu, choose Remotes and Keyboard. Click the New remote button (using left, right and enter keyboard keys). You'll be asked to hit a key on your remote. When it's done, your remote will appear in the remote liste.

Configuring keys of your remote

Once your remote is added, you must map its keys to ostbox functions. To do so, select your remote on the remote list (using up and down arrow keys), then click the Configure button.

You'll get to the following screen:

There, you must select each a function (with the up/down/enter keys) and hit the associated remote key when asked to.

You can leave a function without key if you want.

You can also associate one remote key to multiple functions. In this case, When you'll hit the key, ostbox will decide which function is invoked depending on what your're actually doing.

When you're done , click the Apply button. You'll now be able to test your remote keys... However, most of the time, you'll find that keys on your remote are repeated too quickly... Read on !

LIRC finetuning

Because remote reception is generally not perfect, most remote send fast codes, which result in lots of event at lirc level. OST-Box can filter lirc events, in order to give a smooth feeling.

In the setup menu, choose LIRC settings. You'll get a page where you can tune the lirc filter :

All the parameters will affect your lirc remote(s) responsivity :

3.4. TV Configuration

OST-Box support multiple source for audio/video stream. You can configure it to use multiple dvb cards, webtv, ...

OST-Box also includes support for TV program browsing (EPG).

3.4.1. Principle

OST-Box stream access is configured in a single file : channels.xml. For the moment, you have to create this file yourself and this chapter will describe how to proceed. In the future, OST-Box will provide simple way to configure a TV card, web ressources, ...

The channels.xml describe tuners (which can be TV card or anything which can provide some stream), frequency available on tuners, and channels. A channel is associated to one or more frequency, plus various informations like display name, EPG source, ...

So you'll have to create a "tuner" for each source (one tuner for each TV card, one tuner for webtv, ...). Each tuner can work in three different mode :

3.4.2. The channels.xml file

The channels.xml file is located under the ~/.ostbox directory. It will contain description of all streamed media you'll be able to access from ost-box.

Currently, there is no automated way to configure it, so you'll have to do it by hand. In the future release, that configuration will be possible directly from ostbox interface.

I am very interested in your channels.xml file. I'd like to collect them in order to add "template" tuners in future release, to make configuration easy in common cases !

Example of file

This is my own (simplified) channels.xml. It uses two tuners, one using the media-helper, and the other relying on xawtv.

      	<!-- Tuner for using the dvbt-0 card, with internal media helper and viewer -->
          <tuner name="DVB-T" id="dvbt0">
  	    <!-- this tuner is watched using internal viewer -->
  	    <!-- This is the mrl to use to open the media -->
  	    <!-- definition for the media-helper -->
  	    <helper type="external" port="18422">
  		    <!-- Command to tune a channel -->
  		    <command>tzap -c ~/.tzap/channels.conf -r "$FREQUENCY"</command>
  		    <!-- where to read data from when command is running. If unspecified, use command stdout -->
  	    <!-- Timeout for first data (tuning timeout) -->
  	    <helper-client-option name="max-initial-delay">5000</helper-client-option>
  	    <!-- No timeout after first data is received. -->
  	    <helper-client-option name="max-live-delay">0</helper-client-option>
  	    <!-- List of frequency available with this tuner. -->
  	    <!-- This must match your ~/.tzap/channels.conf -->
  	    <frequency id="TF1" />
  	<!-- tuner for analog tv (xawtv) -->
          <!-- it requires xawtv and xawtv-remote command -->
          <tuner name="video4linux" id="v4l0">
  		<!-- This tuner is watched by starting an external viewer -->
                  <!-- start xawtv -->
                  <start-command>xawtv -nogl -fullscreen -nodga -noxv -c /dev/video0 "$CHANNEL"</start-command>
                  <start-command-env name="CHANNEL">frequency.get("id")</start-command-env>
                  <!-- stop xawtv -->
                  <stop-command>xawtv-remote "quit"</stop-command>
                  <!-- how to display a message -->
                  <report-command>xawtv-remote msg "$TEXT"</report-command>
                  <report-command-env name="TEXT">text</report-command-env>
  		<!-- List of frequency available with this tuner. -->
                  <!-- This must match your ~/.xawtv -->
                  <frequency id="TF1" />
          <!-- channels definitions -->
          <channel id="TF1">                                              <!-- Id just have to be uniq -->
                  <display>TF1</display>                                  <!-- This will be displayed when switching channel -->
                  <shortcut>1</shortcut>                                  <!-- Enter this on lirc to activate this channel -->
  		<xmltv-mode>manual-display</xmltv-mode>			<!-- Method for matching xmltv channels -->
                  <xmltv-manual>tf1</xmltv-manual>			<!-- xmltv display -->
                  <frequency tuner-id="dvbt0" frequency-id="TF1"/>	<!-- This channel is available as TF1 on the dvbt0 tuner -->
                  <frequency tuner-id="v4l0" frequency-id="TF1"/>         <!-- and it is also available as TF1 on the v4l0 tuner -->

3.4.3. Configuration of tuner using internal helper/viewer

Configuring the media helper

The media-helper is the program which provides timeshifting and recording facility. It will collect the mpeg (or other format) stream, either directly or throught a capture program, and it will buffer the stream for live/timeshifted watching and/or write it to the disk for recording purpose.

The media helper configuration is introduced within the tuner, with the <helper> tag. This tag must have two attributes:

The command tag introduce the command used to get the stream. This command will get executed by the shell, with variable expansion. So you can refer here to the following environnment variables :

The fifo tag tell the media helper to read its output from a fifo file (or a dvb device). The path is given by the text found in the tag.

The autofifo tag tell the media helper to create a temporary fifo file, and read the data from it. In this case, the FIFO_PATH environnment variable must be used by the command to know where it should send data.

If neither fifo or autofifo tag are present, data are just read from stdout of the command.

The option tag let you specify option for the helper, in the form <option name='name' value='value'/>. These option will be available to the command in the corresponding OPT_name environnment variable. Some of them have a special meaning to the helper. They are :

Configuring the internal viewer

For the tuner to use the internal viewer, you must put internal-video in the type tag :

  	<tuner name="DVB-T" id="dvbt0">

You must also provide a jsmrl tag, which will be used to pass the mrl to the xine engine. It is javascript code, but it should be kept simple... The following example is to use it for playing stream from the media-helper. You can change the mpeg-ts demuxer to something else if you want to adapt to other stream than dvb-t.


The internal viewer is base on xinelib. It should support any format supported by xinelib on your system. However, you may have to provide a xine.cfg file for it to use correctly your hardware. The simplest solution is to take the one resulting from xine-ui execution in ~/.xine/config :

  	cp ~/.xine/config ~/.ostbox/xine.cfg

You can configure deinterlacing, by setting an option tag, either at the tuner level or at the frequency level. The option will look like :

  	<tuner name="DVB-T" id="dvbt0">
  		<option name="">method=Linear;enabled=1;pulldown=vektor;framerate_mode=full;judder_correction=1;use_progressive_frame_flag=1;chroma_filter=0;cheap_mode=0</option>

Supported methods are thoses supported by xine tvtime plugin (use_vo_driver, Linear, LinearBlend, Greedy, Greedy2Frame, Weave, LineDoubler, Vertical, ScalerBob, GreedyH, TomsMoComp)

3.4.4. Configuration of tuner with internal helper/external viewer

This configuration is almost the same than the previous one, except that you have to specify commands to control the viewer.

For the tuner to use the external viewer, you must put external-video in the type tag :

  	<tuner name="DVB-T" id="dvbt0">

Also, you'll have to configure the viewer so that it won't use lirc keys already used by ost-box (channel switch, back, power, volume level adjusting). In the simplest case, disabling lirc on the viewer program will do it.


The <start-command> tag let you specify the command to use to start the viewer. This command will get executed by the shell, with variable expansion.

The <start-command-env> tag let you set environnment variable from javascript code. These variables will be usable in the start-command. Interresting code snippet are :


The <stop-command> tag let you specify the command to use to stop the viewer. This command will get executed by the shell, with variable expansion. You can use <stop-command-env> to set environnment variable.


The <report-command> tag let you specify a command to display text in the viewer screen. This command will get executed by the shell, with variable expansion. The <report-command-env> tag let you set environnment variable from javascript code. These variables will be usable in the start-command. In this case, interresting code snippet are :

The following example show <report-command> tag to display text in running xawtv :

  		<!-- display a message -->
                  <report-command>xawtv-remote msg "$TEXT"</report-command>
                  <report-command-env name="TEXT">text</report-command-env>

3.4.5. Configuration of tuner with external viewer

If you don't want to use media-helper for a tuner, just don't put the <helper> tag. In this case, additionnal commands are available :


The <check-command> tag let you specify a command to check that the tuner is available. This command will get executed by the shell, with variable expansion. You can use <check-command-env> to set environnment variable.

This can be used to make ostbox cooperate with and external recorder program, which would create a lock. In the following example, if the file /var/lock/dvr0 exists, ostbox will not use this tuner :

  	<check-command>test ! -e /var/lock/dvr0</check-command>


The <sync-command> tag let you specify a command which will tune the tuner. This command will get executed by the shell, with variable expansion. You can use <sync-command-env> to set environnment variable.

tzap is typically such a command. When it terminates, the player is terminated as well. You can make ost-box wait for a particular output from this command, before starting player. Use the <sync-command-ok-re> tag to specify a regular exception to wait for. If none is specified, the player is started as soon as the sync-command.

3.4.6. Configuration of channels

In the channels.xml file, you'll have to create a <channel> entry, and associate it to the tuner's frequency you've created.

This way, you can associate a channel to multiple frequency. OST-Box will always use the first, unless it is not available (because precommand fails, or a record is already running on the tuner for a different channel)

You can set a shortcut for the channel. This will be the number you'll have to enter on your remote to get directly to this channel.

For example :

  	<channel id="France 2">
  		<display>France 2</display>
  		<frequency tuner-id="dvbt0" frequency-id="France 2"/>
  		<frequency tuner-id="v4l0" frequency-id="FRANCE2"/>

3.5. EPG configuration

OST-Box can use EPG information in the xmltv format. It will read the ~/.ostbox/guide.xml file and use it for displaying EPG information, either in the TV menu, or in the channel selector window (when switching channel).

The guide.xml will be re-read each time its modification time change. So you can create a cron job to update it in background.

You must configure the matching between the channels you defined in your channels.xml and the channel found in your EPG file. To do this, you must add two tag on each <channel> tag of your channels.xml :


The <xmltv-mode> tag specify on which information the matching can be done. In the xmltv, two information can be used :

You can decide to match on the id, by using <xmltv-mode>manual-id</xmltv-mode>. You can decide to match on the display, by using <xmltv-mode>manual-display</xmltv-mode>.


The <xmltv-mode> tag specify the id, or the display name to search in the EPG for this channel.


The following extract is the configuration of the "France 2" channel. In the xmltv produced by my grabber, this channel has the id C2.telepoche.com, which is not intuitive. The channel's display-name is france2, so I decided to match on this one :

  	<channel id="France 2">
  		<display>France 2</display>
  		<frequency tuner-id="xine-dvbt0" frequency-id="France 2"/>
  		<frequency tuner-id="v4l0" frequency-id="FRANCE2"/>

4. Troubleshooting

4.1. Debug output

You can get some information by starting ostbox with the -v switch.

There is also an integrated javascript debugger, but this one really lacks documentation !

4.2. Common problems

After upgrading to 0.3, OST-Box doesn't react to keys anymore.

The key naming scheme has changed. We switched from SDL to X11 key names. As a result, key configuration for the keyboard is not compatible between 0.2 and 0.3+ versions... The simple way to recover is to remove the file ~/.ostbox/map.xml and restart ostbox. This will reset any key settings. You'll then have to reconfigure any lirc remote in the setup menu.

The keypad is not working correctly in other applications when ost-box is running.

Since version 0.3, ost-box uses some keys for the channel browser. These key are grabbed, so that if you hit them from anywhere, they will popup the channel selector, in the ostbox window or in the current TV/Radio viewer. If you don't use the channel selector and want to disable this behaviour, you can disable key grabbing in the configuration menu.

Internationnal keys are not working properly

It's a bug in SDL's keyboard handling code. Older version of SDL did not get correct unicode value from X11. It has been fixed in version 1.2.11 of SDL.

Cannot install rpm files

In order to correctly install FC5 rpm of ostbox, you'll need to install some perl package : perl-DateManip, perl-HTML-Tree.

OST-Box does not return to full screen or loose X11 focus after a program ran.

It is a problem with the window manager. icewm is know to cause trouble. KDE, Gnome, Fluxbox or blackbox are OK. The best is to use ostbox without any window manager, at fullscreen and in the default X11 resolution.

Can I run ost-box without X (in a framebuffer for example) ?

Not really... It would basically work, but some functionnality relies on X11 (such as screen power control, key grabbing in other apps). However, I never tried... Feedback is welcome !

My locale is not UTF8. Some character are not correctly displayed !!!

Encoding other than UTF8 are not supported for the moment. It is on my far futur TODO list... However, if you feel brave, you can try to modify utils/ls.pl to convert on the fly file name encoding (only the display tag must be converted). You'll also have to adapt the displayBinaryPath function so that it convert from your locale to utf8... If it works, send me a patch !

===OST-Box crash during startup, right after the message "registerOstboxPlugin(0x8xxxxxxx)"

I guess you are Italian ! There is a bug in the italian translation of xinelib. As a result, when your locale is set to IT, xine-lib crashes when registering a static plugin. The simple workaround you can try is to start ost-box without any language setting :

          LANG=C ostbox

This bug was reported to the xinehq, so it may be fixed in xinelib 1.1.4

5. Extending ostbox

5.1. Languages support

Currently, six languages are available. If your one is missing, it is really easy to add a new language.

To do so, you must add a language tag for your language into /usr/share/ostbox/ostbox-i18n-c.xml, then create the corresponding ostbox-i18n-XX.xml file. To do so, grab a copy of an existing translation (like ostbox-i18n-fr.xml, since it will probably always be up to date...)

When you're done, don't forget to send me your translation file, so that I can include it in next release...