Introduction and Concepts top

The Configuration Files

ZapDvb starts searching for it's global configuration files in the folder where the executable is installed (e.g. /usr/local/share/zapdvb). These files may contain (relative) links to the sub-folders data and config, see below. If the configuration is not found, the local folder and the home folder are also searched. Alternately you can use a private configuration file, see below.

With the exception of the channel lists the syntax of the config files uses the .ini style which is very easy to understand: the structure is made up by sections and the entries contained in these sections look like assignment statements. Such statements are often referred to as value.

Strings can be quoted in a C-Style fashion (example: "\"" stands for a string containing a single quote). Comments can be started anywhere using the # (hash) character and run until the end of line.

Global and Private Configurations

The ZapDvb configuration is preferably kept in a single large configuration file (zapdvb.conf) that is shared by all users. Unfortunately this makes it difficult to experiment with multiple channels lists. So as a first extension it is possible to keep channel lists and view format definitions in external files (in the config folder for example). Furthermore it is possible to use a private configuration in ~/.zapdvb (if such a file is found it overrides the global config). The private configuration is searched first.

The Folders data, home and config

You should not modify files in the data folder, a software upgrade simply replaces these files so that your changes get lost. The purpose of this folder is to contain example data that can be used by the setup program. The whole folder is removed on uninstall.

The home folder is used for Set-top Box mode. The main purpose of this folder is to contain the .kde configuration. The folder can be created by the setup program and will never be overridden or removed automatically. Please do not use this folder to store Video data!

Keep your config files in the config folder. This folder will never be overridden or removed automatically. It is also searched by the zapmcc program for LIRC configuration files. Your global zapdvb.conf should make use of config when using external files.

How to Persist your Configuration Changes

Please do not edit the original /usr/local/share/zapdvb/zapdvb.conf! Your changes would get overridden by the next software upgrade. Put your version into config, rename the original to zapdvb.conf.dist and create a symbolic link. Future software upgrades will re-use your configuration and write their version to zapdvb.conf.dist:

   cd /usr/local/share/zapdvb
   
   # 1st create your own config version ...
   cp zapdvb.conf config
   mv zapdvb.conf zapdvb.conf.dist
   ln -s config/zapdvb.conf 
   
   # now it's safe to edit your version ...
   vi zapdvb.conf

zapdvb.conf is divided into Sections

Each section starts with a line containing the section's name included in rectangular braces ([views] for example). The order of sections is important (incremental parsing) and should be:

 [zapmcc] the shared Definitions Section top

Summary

This section contains definitions that are shared by all applications of the ZapDvb family. The following values are defined and will be described in more detail in the text below:

Details

The mainuser is mandatory for the Family Mode and the Server Mode (making DVB-cards available to remote clients). The zapdvb account itself is also used by the automatic cleanup job (launched daily via cron). Some entries in /etc/sudoers are required and the mainuser must be have a home directory that is read- and writable by all zapdvb users. See README_INSTALL for details.

# If the "mainuser=" is set, zapdvb can be used by more than one user. Jobs
# will be run under the mainuser account.

    mainuser=zapdvb                  # no default value (e.g. off)

# The following is used as umask if files are created. The default is 2:

    maskuser=2                       # world can read (default)
  # maskuser=3                       # exclude world from access

The automaxage value defines a maximum time to live (in days) for files that is used by a cron-job that will be started daily (see /etc/crontab.daily/zapdvb_clean). That cron-job periodically deletes audio and video files with names that were automatically generated (like hello_2004_08_29_18_44.mpg). The cron job is created by the setup program at installation time but it does not run unless a mainuser is configured.

# Automaxage controls automatic clean-ups (needs mainuser account):

    automaxage=8                     # no default value (e.g. off)

These values enable a lot of functionality like capture or background recording. These features are disabled by default as there are no defaults. The setup program should be used to create the actual folders (giving them a group ownership of "video" or "audio" and adjusting permissions). ZapDvb will not work if capture is enabled but the capture folder is unaccessible for the user!

# Recorded videos will be stored here (no default)

    pathvideo=/home/video
  # pathvideo=/mnt/dvb/Video         # recommended: use a partition (dvb)
  # pathvideo="/home/My Video Files" # single spaces may space work (or not)

# recorded audio files will be stored here (no default)

    pathaudio=/home/music
  # pathvideo=/mnt/dvb/Music         # recommended: use a partition (dvb)

# A sub-folder in pathvideo and pathaudio or an absolute path name to which
# original files are moved when edits are saved. Files herein get cleaned-up
# automatically even if they were no automatically created  (no default):

    pathtrash=trash                  # one trash in Video, one in Music!
  # pathvideo=/mnt/dvb/Trash         # recommended: use a partition (dvb)
                                     # Warning: this would work only if both
                                     # folders are on the same partition!
  # pathtrash=.trash                 # you want to make it hidden?

# The numeric argument sets the maximum number for files that the
# MPEG editor leaves in the trash folder:

    filetrash=8                      # no default value (e.g. off)

# A sub-folder in pathvideo or an absolute path name for files that are
# created while capturing life data. The filecapture parameter sets a
# limit for the number of capture files (default 15 for 150 minutes).
# An empty "pathcapture=" disables the "-s" command line arg (only if
# no dir is given) without a warning:

    pathcapture=                     # disable capturing by default
  # pathcapture=capture              # one capt. in Video, one in Music!
  # pathvideo=/mnt/dvb/Capture       # recommended: use a partition (dvb)

    filecapture=15                   # zapdvb creates one file every 10 min!

The native DVB audio format is MPEG Layer 2. The file extension should thus be "mp2". Unfortunately some programs do not understand this. As a work around you may choose "mp3" (internally these programs will have to know that the data is MPEG Layer 2).

# Most tools detect the MPEG Layer automatically from the data, and do not
# rely on the extension. "mp2" would be correct, "mp3" might work better:

  # audioext=".mp3"                  # the default is ".mp2"

KDE has the stupid feature (or bug?) to attempt opening all files in the history of the open file dialog. This can cause a very long delay if these files are stored on a server and if automount and/or disk spin-down are used.

# KDE: The open/save can cause a very long delay for files on a server.
# Define a regular expression to remove file entries from history:

  # a simple folder:
  # kdenohistory="/home/ServerFolder/"

  # a list of folders:
  # kdenohistory="/home/(Video|Musi[ck])/Server/"
  # kdenohistory="/(home/Video/Server|home/Musi[ck]/Server|\.automount)/"

KDE uses the arts sound daemon which will by default block the DSP device. Arts can be configured to release the DSP device after an idle period, but this may cause noise and delay. Is should be better to call MPlayer with the "-ao arts" option if arts support is compiled in (but see below). Kaffeine as a KDE app can handle arts internally. Some other applications do not support arts but can run with the artsdsp wrapper (mpg123 for example).

# The artsmode parameter controls how zapmcc will handle arts:

  # artsmode=suspend                 # suspend arts (default)
  # artsmode=native                  # don't suspend and use arts_xxxx
    artsmode=mixed                   # suspend arts  and use arts_xxxx

# You can use specify the use of options or artsdsp with tags like
# arts_mplayer or arts_mpg123:

    arts_mplayer=-ao arts -delay 0.23 # add these options to mplayer
    arts_mpg123=artsdsp               # wrap mpg123 using artsdsp

Some arts problems: unfortunately arts has a high latency, mplayer's arts support is broken and arts itself is quite instable. Currently the artsdsp program does not work with mplayer at all, "-ao arts" does not synchronise audio and video properly and using "-ao arts -delay 0.23" breaks the video timings.

A complex GUI is fine when you use it in a desktop environment with a mouse. This is in contrast to a Set-top Box where you will use an infrared control (via LIRC). The later requires a simple GUI take can easily be used without a mouse. Usually (menumode=auto which is the default) the zapmcc program will select the desktop mode and will enable LIRC when used with the --lirc option. In Set-top Box mode the zapdvb_box program will select set-top mode and will enable LIRC. The menumode value can be used to override this behaviour...

# Can be used to force a specific GUI mode ...

  # menumode=auto                    # leave decisions to zapmcc (default)
  # menumode=desktop                 # may have complex GUI, LIRC optional
    menumode=lirc                    # use LIRC, show simple context menus
  # menumode=settop                  # like lirc plus special items

 [zapdvb] the TV and Radio Settings Section top

Summary

zapdvb is the component that fetches data from a DVB stream and launches a player for life actions or writes the data to disk for background recording. The following values can be used to configure the zapdvb behaviour:

Details

Up to four channel lists can be managed by zapdvb and zapmcc. For each list one source statement is required. The statement specifies the location of the channel data (section or file) some parameters for DVB tuning and a text that is to be displayed by the GUI. An important point is: some data from the source statements is interpreted by the GUI and determines what kind of dialogs are shown.

It's also worth mentioning that the channel lists are only loosely related to physical adapters. Instead they serve as a logical grouping mechanism that also allows you to split very long lists into smaller pieces.

The following box presents a DVB-S example, a DVB-T example and demonstrates the configuration of a client that remotely uses the DVB equipment on a server:

  # src     section_name       type adapter mask friendly_name  lnbtype
    source0=channels           sat  0       3    ""             UNIVERSAL
  
  # src     path_name          type adapter mask friendly_name
    source1=config/dvb_t.conf  ter  1       1    "Terrestrial"
  
  # src     server_name        type adapter mask friendly_name  port
    source2=alpha              net  0       3    "Server"       1650

With DVB-S you have the extra pleasure to specify the right LNB type (Low Noise Block Converter). The LNB translates the quite high down-link frequency of a satellite into a lower intermediate frequency that is compatible with cheap cables and cheap electronics. But zapdvb must tell the DVB card to tune to the right intermediate frequency, and these frequencies differ between LNB types. Also the UNIVERSAL LNBs are capable of switching between two down-link frequencies (Lo- and Hi-Band). The following is a list of supported LNB types:

# LNB type  description                 frequencies...

# UNIVERSAL (default, works with ASTRA)  9750000, 10600000, 11700000
# DBS       (?)                         11250000
# STANDARD  (for the US),               10000000
# ENHANCED  (good enough for ASTRA)      9750000
# C-BAND    (?)                          5150000

For a computer without DVB hardware one might disable the life TV and Radio menus in the GUI using a special source statement:

# if you run zapdvb without DVB hardware use an empty entry:

    source0=       # disables life tv/radio actions

To watch TV zapdvb must launch a video player. The cmdvideo0 ... cmdvideo3 values are used to configure which player is started and what arguments it receives. You can have up to four entries, the first player that is found will be used. See below what happens if the first argument of the player does not start with a minus sign. Here some examples (each value must be given in a single line, remove the extra line break if you copy the example):

# Video Player examples - NO EXTRA LINE BREAKS PLEASE!
    
    cmdvideo0=mplayer -really-quiet -nojoystick -nolirc -fs -zoom
              -cache 2048 -vc mpeg12 -vop lavcdeint -autosync 0 -
    
    # alternate players ...
    cmdvideo1=xine -D --no-logo --no-splash -f stdin://mpeg2
    cmdvideo2=kaffeine --nofork -p -f stdin://mpeg2
    
    # friendly error message if no player is installed ...
    cmdvideo3=zapmcc --sorry "No video player found:" 
              "Please install mplayer or xine"

The same rules apply for the audio player for the cmdaudio0 ... cmdaudio3 values:

# Audio Player examples - NO EXTRA LINE BREAKS PLEASE!

  # no other working audio player is known, mp321 does not work!
    cmdaudio0=mpg123 -q -
    cmdaudio3=zapmcc --sorry "No audio player found:" 
              "Please install mpg123"

Warning #1: The examples above used a short hand notation where one argument was left out. This worked because in all cases the second argument started with a minus sign. In the full syntax the first parameter, which specifies the program's file, should be followed by the program's name. But as mentioned for the examples the program name could be automatically inserted (taken from the file name).

Warning #2:Some program names are known to zapdvb (or are used elsewhere in the configuration). If you want to experiment with multiple program versions you should use something like:

# Using the full syntax (2nd arg is the program name):

  #           file to execute  name     arguments
    cmdvideo0=/tmp/myOwnPlayer mplayer  -cache 2048 -
    cmdaudio0=mpg123-oss       mpg123   -q -

The DVB drivers in the kernel use only a moderately large data buffer. This buffer can easily overflow when your file-system is busy while recording or when your player stops for a moment. By default zapdvb maintains a dynamic buffer and uses an extra thread to write data asynchronously to the disk or to the player. If your kernel or C-lib have problems with threads you may disable buffering, but buffering is mandatory for capture mode.

# This value specifies the default buffer size for the "-b" command line
# arg. A size of 0 turns default buffering off (-bN will override again).
# For audio channels the buffersize gets divided by 8 ...

  # buffersize=2048                  # use 2 MBytes (default)
  # buffersize=3072                  # also a reasonable buffer size
  # buffersize=0                     # disable buffering

 [zapcvt] Player and Editor Settings top

Summary

zapcvt is the component that is used for MPEG editing and for MPEG playback (recorded video or DVD). The following values can be used to configure the zapcvt behaviour:

Details

For the details of the cmdXXXN values please refer to the description given in [zapdvb], the same rules apply. Some extra considerations are:

• The mode cmdhighX can be used for various playback purposes, see zapcvt documentation.
• The modes cmdprevX and cmdfastX are used by the MPEG editor only.
• For cmdprevX no deinterlacing should be used unless you have a reasonably fast CPU.
• For cmdfastX sound should be disabled.
• Important: cmdvdvdX is used by zapmcc to play DVDs.
• Important: cmdplayX is used by zapmcc to play recorded video files.

The server_xxx values are used by the MPEG editor and provide a simple way to upload data to a server. Two upload methods are supported: ssh and zapdvb running in server mode. The value names must start with server_ and until now xxx was used as a place holder but should be replaced with a genre name. Inside the editor the "save -" command can be used to get a list of upload locations (e.g. genres). From the command line "zapcvt -l512" would list the uploads:

### There are two types of upload definitions:
#   (1) commands that take input via stdin used (ssh for example)
#   (2) zapdvb in server mode (specifies a sourceN statement using @)

### server definition examples (type 1):
    server_action  = ssh jpf@alpha "cat - > \"/export/Video/Action/$saveto\""
    server_andere  = ssh jpf@alpha "cat - > \"/export/Video/Andere/$saveto\""
    server_historie= ssh jpf@alpha "cat - > \"/export/Video/Historie/$saveto\""
    server_scifi   = ssh jpf@alpha "cat - > \"/export/Video/SciFi/$saveto\""
    server_trick   = ssh jpf@alpha "cat - > \"/export/Video/Trick/$saveto\""
    server_western = ssh jpf@alpha "cat - > \"/export/Video/Western/$saveto\""

### server definition examples (type 2, requires remote mode installation):
#   server_action  = @source1 "/export/Video/Action/$saveto"
#   server_andere  = @source1 "/export/Video/Andere/$saveto"
#   server_historie= @source1 "/export/Video/Historie/$saveto"
#   server_scifi   = @source1 "/export/Video/SciFi/$saveto"
#   server_trick   = @source1 "/export/Video/Trick/$saveto"
#   server_western = @source1 "/export/Video/Western/$saveto"

 [zapgop] The User Interface Server top

Summary

The user interface server zapgop is not yet implemented

# Header

    xxxx=nn                         # detail

 [views] Handling Aspect Ratios top

Summary

The "View Format" mechanism implemented by ZapDvb is much more powerful than the minimal aspect information contained in the MPEG data. Using it is optional, and you probably won't be interested in this section if your display has an aspect ratio of 4:3. This README text is focussed on configuration not on background details - please refer to Handling Video Aspects (aspect.html) in the documentation.

While a set of view formats is always related to the movie aspect ratios, the set itself is abstract and needs a specific monitor aspect to be implemented. So the monitoraspect value is the most important one. Even without using view formats the monitor aspect will improve the display on non 4:3 monitors.

Video files can be tagged with the name of a view format (other tags like genre or year are also possible but currently not directly covered by ZapDvb). The important piece of information is: the format description (e.g. parameters for zooming and cropping) are not stored in the tag info but in the configuration section that is described here.

### un-comment one 'monitoraspect=' to enable the GUI aspect dialog...
  
  # monitoraspect=0          # Turn GUI dialog on but do not pass
                             # this value to the player
    monitoraspect=1.78       # 16:9
  # monitoraspect=1.67       # 15:9 (nice TV Format)
  # monitoraspect=1.33       # 4:3  (most Computer Monitors)
  # monitoraspect=1.2        # 5:4  (nice Computer Format)
  
### the format to be used for unknown format names...
    defaultview=norm

The set of view formats defined in this document is working well in most cases, but please feel free to invent your own. Beware: once you have started to tag your video collection with view format names it will become difficult to change things! Every unknown view format will get mapped to the mode defined by the defaultview value.

Details

Here an example for a 4:3 monitor (remark: you might leave out zoom for a workstation display). It should be mentioned again that all view names that are not defined here but are found in tag information get mapped to the defaultview:

## Example for a 4:3 Monitor (a Common Case)...
   format_none=- -    -   -   -  -  -    -  "Standard  auto (unverändert)"
   format_norm=- -    -   0   1  -  0    -  "Standard   4:3 (normal)"
 # format_zoom=- -    -   0   6  -  -    -  "Standard   4:3 (vergrössert)"
   format_high=- -    -  10   1  -  0 0.95  "Kinofilm  11:9"
   format_xtra=- -    -   4  59  -  - 1.05  "Breitwand 15:9"
   format_wide=- -    -   4  73  -  - 1.05  "Breitwand 16:9"
   format_cine=- -    -   8  88  -  - 1.05  "Super Breitwand"
   format_tv16=- - 1.78   4   0  -  - 1.05  "Fernsehen 16:9"
   format_tv1x=- - 1.78   8  20  -  - 1.05  "Fernsehen 16:9 (super breit)"

While most computer monitors use the 4:3 format the 16:9 format is very common for TV Sets:

## Example for a 16:9 TV Set (a Common Case)...
   format_none=- -    -   -   -  -  -    -  "Standard  auto (original)"
   format_norm=- -    -   0   1  -  0  .95  "Standard   4:3 (normal)"
   format_zoom=- -    -   0   6  -  -  .95  "Standard   4:3 (zoomed)"
   format_high=- -    -  10   1  -  -  .95  "Cinema     11:9"
   format_xtra=- -    -   4  59  -  -  .95  "Widescreen 15:9"
   format_wide=- -    -   4  73  -  -    -  "Widescreen 16:9"
   format_cine=- -    -   8  88  -  - 1.05  "Super wide"
   format_tv16=- - 1.78   4   0  -  -    -  "Tv 16:9"
   format_tv1x=- - 1.78   8  20  -  - 1.05  "TV 16:9 (super wide)"

The two monitor aspects mentioned above are no-compromise choices. A computer monitor with a 5:4 aspect ratio is often better suited for text processing:

## Example for a 5:4 Monitor (cool but rare)...
   format_none=- -    -   -   -  -  -    -  "Standard  auto (unverändert)"
   format_norm=- -    -   0   1  -  0 1.05  "Standard   4:3 (normal)"
 # format_zoom=- -    -   0   6  -  -    -  "Standard   4:3 (vergrössert)"
   format_high=- -    -  10   1  -  -    -  "Kinofilm  11:9"
   format_xtra=- -    -   4  59  -  - 1.05  "Breitwand 15:9"
   format_wide=- -    -   4  73  -  - 1.05  "Breitwand 16:9"
   format_cine=- -    -   8  88  -  - 1.05  "Super Breitwand"
   format_tv16=- - 1.78   4   0  -  - 1.05  "Fernsehen 16:9"
   format_tv1x=- - 1.78   8  20  -  - 1.05  "Fernsehen 16:9 (super breit)"

For a TV set 15:9 is a good compromise between the old 4:3 TV standard and the upcoming 16:9 format:

## Example for a 15:9 TV Set (cool but rare)...
   format_none=- -    -   -   -  -  -    -  "Standard  auto (unverändert)"
   format_norm=- -    -   0   1  -  0  .95  "Standard   4:3 (normal)"
   format_zoom=- -    -   0   6  -  -  .95  "Standard   4:3 (vergrössert)"
   format_high=- -    -  10   1  -  -  .95  "Kinofilm  11:9"
   format_xtra=- -    -   4  59  -  -    -  "Breitwand 15:9"
   format_wide=- -    -   4  73  -  - 1.05  "Breitwand 16:9"
   format_cine=- -    -   8  88  -  - 1.05  "Super Breitwand"
   format_tv16=- - 1.78   4   0  -  - 1.05  "Fernsehen 16:9"
   format_tv1x=- - 1.78   8  20  -  - 1.05  "Fernsehen 16:9 (super breit)"

Currently the handling of view formats and monitor aspects is only supported by mplayer. The Xine player does not provide enough support to pass the aspects parameters via the command line. Eventually such parameters could be passed using a config file, zapcvt therefore starts the player with an argument to load a config file that includes the name of the view format, see the error messages.

 [channels] Satellite Channel Lists top

The section name channels in not hard coded, it is just an example of where to place an internal satellite channel list. The actual name that you choose must match a source statement, see above. Here a few examples to illustrate the format, for details please refer to README_CHANNELS:

[channels]
Das Erste:11837:h:0:27500:101:102:1:28106
ZDF:11954:h:0:27500:110:120:1:28006
3sat:11954:h:0:27500:210:220:1:28007

 [channelt] Terrestrial Channel Lists top

The section name channelt in not hard coded, it is just an example of where to place an internal terrestrial channel list. The actual name that you choose must match a source statement, see above. Here a few examples to illustrate the format, for details please refer to README_CHANNELS:

[channelt]
# The DVB-T format is (no line break!)...
BBC World:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_16:
          TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:49:50:16387

 [channelc] Cable Channel Lists top

The section name channelc in not hard coded, it is just an example of where to place an internal cable channel list. The actual name that you choose must match a source statement, see above. Here a few examples to illustrate the format, for details please refer to README_CHANNELS:

[channelc]
arte:410000000:INVERSION_OFF:6900000:FEC_NONE:QAM_64:401:403
SPUTNIK:426000000:INVERSION_OFF:6900000:FEC_NONE:QAM_64:0:1201