Required data not found, document opened from wrong folder or Javascript turned off. Links may be broken and menus will not work, use the site map in (Internet) or (Local) to navigate.

 Browsing the Documentation - Where are you?

Here are some README Files that you might find helpful...

These files are included in the source and binary packages.

More ZapDvb Documentation (separate Package since Version 0.50)

As the amount of documentation increases, the detailed descriptions will be distributed as a separate package.

 What ZapDvb is not ... top

It's difficult to say in a few words what ZapDvb is because it has many facets. So please let us first try to understand what ZapDvb is not:

Coming back to last item, it should be pointed out that many people simply download the binary packages. These are linked against the C library and almost nothing else (although the software itself is written in C++). The SuSE RPMs are known to work for SuSE 9.1 until 9.3 and the Debian DEBs work for Sarge and Knoppix. KDE is supported in versions from 3.2 until 3.4. Just after having installed the packet via rpm or dpkg you should have a working application (preconfigured for ASTRA DVB-S). MPlayer is recommended but not required. You can even dare to ignore missing dependencies (use --nodeps for rpm) and install missing audio players or encoders later. Compiling from source is on the same level of triviality.

 Introduction to ZapDvb top

ZapDvb is a collection of tools that can take care of all the work from loading the DVB drivers (see www.linuxtv.org) until launching a viewer or player. Here is a list of features:

The ZapDvb-Control-Center

As an average user you would like to access your PC's multimedia capabilities in a simple way. For example you might want to

In such a scenario you will probably be focused on content (films or music) and not on technology (like starting or closing players). Obviously you want the CD player to stop automatically when you start watching TV and the TV windows should close automatically when you start playing recorded music. The DVD player and the life radio player should share that behaviour. Also you want primarily to view or to hear something, but you do not explicitly want to start or stop a player.

This leads to the implementation of a work-flow pattern, where each of your actions has a context: Previously started viewers get stopped, new players get started. This includes the capability of handling the following problems:

This lead to the implementation of a priority mechanism based on the assumption that an action with a higher priority should terminate a lower priority action. By default background jobs have a higher priority than life actions - but when you try to start a life action you will be prompted to stop a background job. On the other hand, a starting background job will stop life actions without asking. Background jobs do not affect playback from file, DVD or CD. With the Linux 2.6 kernel (and a 2.6 GHz P4 CPU) there are no problems with these background recording jobs. You can continue to work with your PC as normal and you can even edit videos or play videos. This is an improvement against the 2.4 kernel and the old DVB-drivers! And here the summary:

Recording of video or audio DVB streams

ZapDvb can record audio and video DVB data in background. The recordings are scheduled to run at a given time for a given period of time. If the job is to be executed a single time this is called "timed" and the Linux atd daemon is used. Jobs that should execute more than once (for example every Friday) are called "periodic" and the Linux cron daemon is used. Obviously at and cron need to be installed and must be running.

There is a little helper tool (zapdvb_job) that you could use to manage jobs from a console, but usually you will do this from the ZapDvb-Control-Center. The control center prompts you for details and tries to do it's best to validate your input. The daemons atd or cron must be running while entering new jobs or you will get an error message.

Jobs can have options: Video jobs can split the resulting file into small chunks of 2GByte size and audio jobs can convert the Layer II MPEG data (also called MPEG2) to ogg or mp3 (reducing the file size by a factor of 2). Usually a job only sends an E-Mail when failing, but you can select an option to always send an E-Mail. A very nice (but sometimes confusing) option is automatic system shutdown. You will typically use that feature when recording some late night movie. This feature needs an entry in /etc/sudoers, see the installation instructions or leave that work to the ./setup config program.

The ZapDvb software and the DVB drivers are very stable. So it becomes obvious to install one or more DVB cards in your server (the hardware has become cheap enough). In a private home that server will typically be an old computer with, let us say a 1 GHz P3 CPU, but that should work perfectly well. That server will then automatically record your favorate TV series! Consider using cron jobs to automatically delete the video data after a given time. Be aware that the server will consume electric power which leads to extra costs (50-100 Euro per year).

Editing of recorded Video and Audio Data

Even this is covered by ZapDvb, although in a crude way. But let us start with some nice words:

And now comes the bad news: editing does not take place inside a GUI, it makes use of the Linux bash shell. Very important are the shell's history features (e.g. you can use cursor up/down to recall commands). The editor even manipulates the shell history to save you same typing work! But don't panic, you will not need to type real shell commands. Instead the editor shell gets started with a set of built-in commands including a friendly 'help'. Whenever useful the shell uses KDE dialogs (to ask questions or to load/save files). The zapmcc program can be used to work without KDE or to launch the editor shell from a command window (example: do Alt-F2 and type "zapmcc --edit").

The built-in commands are:

load   to load a file, usually you don't need this explicitly. It is important to know: this command does not cause a delay! All real work will be done when you save your results.
clip for the advanced user, sets a window in input data to make it easier to edit very large files (2 movies in one file).
play start a viewer to search for a position in a movie or to inspect your edits (this also works for audio data)
edit set a list of goto/until pairs that select portions of the input data. Only the selected data will be saved. The command also launches the player trying to help you finding the right positions in the input data.
help tries to give you some syntax help
info shows information (times are rough estimates only)
save save the result to a file or upload to the server. All the commands mentioned before worked instantaneously - it is the save command that does the real work. Data processing itself does not consume too much time, it's the disk IO that typically takes 4 minutes for a movie.
view Selects a view mode to handle zooming and cropping for non-4:3 Video/Monitor Aspect ratios.

All commands can be abbreviated to a single letter. You can use normal shell commands too, see "help shell" for details. A special feature is the viewer integration. If you stop the viewer (best with MPlayer using the ESC key) the editor will display the last viewer position (to stop the audio player use Cntl-C). Instead of typing this into an edit command you can use:

  edit +       # to add the last viewer position to the edit list
  edit -       # to replace the last entry in the edit list

There are certainly more intuitive tools for video and audio editing on the market. But they tend to be very slow because they usually read the data for a 1st time on load and again when saving results. The crazy way of ZapDvb to edit video data is VERY fast and reliable. It must be admitted that the learning curve is a bit steep, but after a while you will like this way of editing videos.

Why is there an extra feature for server uploads? The reason is that samba's smbfs is still broken in kernel 2.6.11 (e.g. SuSE 9.3) and does not allow you to write on shares beyond 2GBytes if you use smbfs-mounted remote shares (you can try the alternative cifs module and protocol on a 2.6.11 or later kernel). Don't get confused: Linux itself can handle large files, KDE mostly does, and even the smbclient program behaves correctly. Another point is the speed on a 100 MBit/s connection: by design the SMB protocol is half duplex (ping-pong) and therefore slower than ftp for example (cifs is slightly better). It would be nice if we could use ftp, but ftp clients usually cannot read from stdin.

Since version 0.40 you can configure ZapDvb in remote mode to act as a server. The destinations and commands for server uploads can be configured in zapdvb.conf. Currently such a command must be capable of reading it's input from stdin. You can also use ssh (and don't care about the encryption features) because it is typically installed on every server. Probably you will also define multiple server commands (one for each film genre). Here are some examples:

  save western:        # saves to the server using the input file's name
  save scifi:st33      # saves to the file as SciFi/st33.mpg

Finally it should not be forgotten to mention that there are plans to write a GUI tool called zapgop that will be integrated into the editor to simplify the work of locating cut positions. The tool will not really play the movie but will contain a mini web server that allows you to display still images in a browser (Konqueror) and to navigate between groups of pictures (the GOPs). An MPEG video consists of such GOPs and cuts can be made only between certain GOPs. Suitable GOPs occur about every 400 ms. ZapDvb has (currently) no way to cut at a finer granularity.

The save command moves the current file to the trash folder (if one is correctly configured). Files in the trash folder are automatically deleted when a given maximum number of files is exceeded or after a given time. See the comments in zapdvb.conf.

Periodic recording via Cron

It is possible to record tv or radio programs repeatedly. Whereas for "one time" recording individual jobs are passed to the "at" daemon (atd), each "periodic recording" job creates a "crontab" entry. This entry is then run by the cron daemon. Technically at and cron are quite different, but ZapDvb hides the technical details. You need to know that the "start time" for cron-jobs is made up from a 24h clock start time like "20:13" and a list of weekdays to specify when the job should run. Monday is 1 ... Sunday is 7. Examples for valid start- times are:

     "18:30 monday"      or    "17:00 monday-friday"   or
     "8:00 tue,wed,thu"  or    "9:00 1-4"              or
     "16:05 daily"       or    "22:30 weekdays"

ZapDvb does not understand all the constructs that cron would allow you - read the crontab manual page and try out what happens. An experienced user could also run "crontab -e" to inspect or modify the entries. Periodic recording creates two problems:

  1. What filenames shall be used for recording?
  2. How to avoid that the disk gets filled up?

Solution (1) - Filenames are generated semi-automatically

The GUI will propose you a filename like "2004_09_11_20_13" which is generated from year/month/day/hour/minute. You should now prefix that name to identify the recording - example: "late_news_2004_09_11_20_13". EACH TIME when the DVB-stream is being recorded, the date/time pattern will be replaced with the actual time. As a result each job creates a file with a unique name. If you use a name without this date/time pattern the file will be overridden each time the job runs. Please read the next paragraph to understand why you should not specify an absolute path as input...

Solution (2) - A daily cron job is run to remove old files

The "videopath=/yourVideoPath" and the "audiopath=/yourAudioPath" configuration entries specify two folders which are automatically used as destination for at and cron jobs. Once a day a cron job will run and delete all files whose names contain the date/time pattern and which are older than a configured number of days. Files with names that do NOT FOLLOW THE PATTERN ARE NOT DELETED. ZapDvb automatically adds filename extensions like ".mpg", ".mp3" and ".ogg" - only these file types will be deleted via cron.

The cron job does even more: after you have edited and saved a video, the original file is automatically moved to a trash folder. When you capture a life program (video or audio) the capture files are stored in a special capture folder. Both locations get inspected by the cron job - and here it deletes all files (that have one of the know extensions, see above) if their (configurable) life time has expired. For security reasons the job runs as user zapdvb and you must create the zapdvb account (or let ./setup config do this for you).

The cron job starts the script zapdvb_job which you could adapt to your needs - but be very careful: it's easy to clean-up a whole hard-disk by a simple typing mistake! For this and other reasons it is recommend to use a separate partition for your audio/video data. This cannot be a FAT partition (file size limit 4 GByte with Kernel 2.6 and a potential crash after 2 GByte with Kernel 2.4). The advantage of a separate partition is that running out of disk space (for automatic recording) cannot harm the rest of your system.

Capturing the current TV or Radio Program

ZapDvb can capture an audio or video stream while a player is running. Captured data is written to disk using a pre-configured folder. Capturing will start automatically when you pause the player! This helps in such situations where the phone rings or something else needs your attention: just pause the player, and let it continue when you are back. You don't have to worry about technical details, the data files get automatically deleted as soon as they are no longer required. If you stop the player (which you also do when zapping to another channel) the data that was captured but not yet sent to the player gets deleted. Cool, isn't it? But what if you want to keep the data for later use...

Advanced Feature (1) - Controlling the Persistence of Capture Data

First you should know that Linux cannot easily remove data from the beginning of a file. For this reason ZapDvb starts a new capture file every 10 minutes. Normally capture files containing data that the player has already played get deleted. Also the maximum number of capture files is limited to a configurable number (default 16 or 2,5 hours). This is done to protect you from filling up your hard-disk with capture data from a paused and forgotten video player.

The GUI shows you an additional entry in the recording menu ("Start and manage recording") when persisting is possible but not yet active: "current program: start capturing". If you click this menu entry capturing is started (if not already running) and all the files starting at the current player position and later will be made persistent. After a while you may find the program boring and will notice that the menu entry has changed to: "current program: stop capturing". If you click again all files starting with the file that comes after the file that the player is currently playing will be made non-persistent.

The important points: the two menu actions refer to what the player is playing and not to the actual DVB-stream. Reason: you could have paused the player and there may be a large time gap between the player time and the DVB-data. Also: the non-persistent files are not deleted before the player has played the data that they contain or before the player terminates. The granularity of the "start/stop" menu actions is very coarse (10 min). You cannot directly use this feature to capture only some of your favorate songs from MTV ...

Advanced Feature (2) - Editing the Captured Files

From a command line you just take the capture files and pass them as arguments to zapcvt. That tool can combine separate input files to a single "virtual file" that can then be edited as if it where a single physical file. This works for MPEG2 video and audio files. Example:

 cd YourCaptureFolder
 zapcvt -m -o/YourVideoFolder/result.mpg -v *.mpg

You can also use the ZapDvb editor (for video and audio). You might call it using Alt-F2 (from KDE) and then type: "zapmcc --edit /home/Video/Capture" (you will use the correct path to your capture data of coarse). Then a selection dialog pops up that allows you to select the files that you want to be included. Now edit the video or audio material as usual. And when finished with editing you can save the result as usual. The program zapcvt takes care of the technical details.

Another procedure to edit capture data: if you launch the editor via the ZapDvb main menu simply cancel the KDE "Open File" dialog and then type "load /home/Video/Capture" on the command line (supply your local path!).

The zapdvb family of programs top

Since version 0.30 the Set-top Box Mode (formerly zaptvout) has been integrated. Future development will cover the problems of the cumbersome kdialog based GUI. Furthermore video editing shall profit from a tool that supports easy locating of GOPs (the potential cut positions that come every 400ms). So newer versions will have two new program components. Here a list of some interesting files:

(1) GUI based user commands

   zapmcc     the zapdvb media control center that can run in KDE or in
              console mode. When running KDE the GUI will be based on KDEs
              ECMA script (some call it Java-Script).
              Currently zapmcc is more a placeholder that calls kzapdvb -
              see below. The current kzapdvbX.desktop files call zapmcc
              so that users will not need to update their desktop icons
              when the new GUI becomes ready.
   kZapDvb.desktop
              a KDE desktop file (menu entry) that launches zapmcc in full
              menu mode.
   kZapDve.desktop
              a KDE desktop file to directly enter the video editor.
   kZapDvj.desktop
              a KDE desktop file to directly enter job management.
   kZapDvr.desktop Radio Menu (this is just an example, see the source)
   kZapDvt.desktop TV Menu (this is just an example, see the source)

(2) Command line tools and utilities for internal use

   zapdvb     the "engine" for all DVB actions except video editing.
   zapcvt     the "engine" for video editing.
   zapgop     (version 0.60!) GUI tool for zapdvb_cut to ease video editing
   zapdvb_gui a bash script for a kdialog based GUI
   zapdvb_box used in tvout mode to start zapdvb in the set-top box mode.
   zapcut_cut this is the video editor, which is and will be based on a
              specially configured bash. When running in KDE mode, some KDE
              dialogs will be used to load or save files or to report errors.
              zapgop (see below) will be integrated into this environment.
   zapdvb_job a bash script to manage at and cron jobs (and daily clean-up)

   zapdvb_gui_en.lang and zapdvb_gui_de.lang
              language support files for zapdvb_gui (send me your translations!)

(3) External tools that are used by zapdvb

   cron and crontab
              for periodic recording, read the man pages for details.
   atd and at
              for timed recordings, read the man pages for details.
   MPlayer    the recommended video player
   xine       an alternative to MPlayer (less stable, takes longer to start)
   kaffeine   another video player based on xine (slower than xine itself)
   mpg123     the recommended sound player (no other working player known)
   sox        a tool used to convert MPEG layer II sound to ogg

(4) The DVB drivers

ZapDvb does not come with private DVB drivers - since kernel 2.6 they are part of the kernel. Unfortunately SuSE 9.1 did not contain a current (working) version of these. Depending on your DVB-card you may need to update the original SuSE drivers to a newer version (see www.linuxtv.org). The drivers that come with Knoppix (3.8 and later) and with Debian Sarge seem to work.

 Release History top

Version 0.42 (July/August 2005):

  - more documentation
  - 'setup scan' provides a simple channel scan
  - 'setup unconfigure' reverts to saved pre-config state
  - zapdvb.conf can link to external files
  - new [zapmcc] section in config file
  - new "artsmode=use" entry for better arts support
  - zapdvb checks for write permission on capture dir

Version 0.41 (July 2005):

  - setup even smarter, does more checks
  - better set-top box configs (menus now at lower right corner)
  - more .desktop files, made them work
  - 1st implementation of LIRC
  - some bug fixes (mostly remote mode)
  - DVD playback can use View modes
  - Juk became the favorate Audio player

Version 0.40 (June/July 2005):

  - Set-top box mode improved (should work out of the box now)
  - Tested on SuSE 9.3 (KDE 3.4)
  - Remote mode introduced (e.g. using DVB card(s) on a server)
  - Again: setup program improved

Version 0.30 (May 2005):

  - Support for Debian (and Knoppix)
  - Monitor and Video Aspects, zapcvt handles tag-info
  - Improved setup program
  - New in Beta7(rc2):
    Editor:         added split/ogg/mp3 options to save command
    Documentation:  completed Editor description
    zapmcc:         added --sorry option (used by current zapdvb.conf)
    zapdvb.conf:    replaced "kdialog ..." with "zapmcc --sorry ..." calls
  - New in Beta6(rc1): minor bug fixes, new algorithm to find channels by name,
    audio recording now supports lame (if installed). The MPEG editor now
    supports mp2 audio.
  - New in Beta5: capturing radio programs is now enabled, the video edit
    shell can now load (multiple) capture files, the audio extension is now
    ".mp2" by default (but can be overridden from config). Some bugs have
    been fixed.
  - New in Beta3: at the end of this file three documentation sections
    were added: "Periodic recording via Cron", "Capturing  the current
    program" and "The zapdvb family of programs"
  - New in Beta3: Most files are now installed to /usr/local/share/zapdvb
    which should not be in the search path. In /usr/local/bin only a few
    links are created. The zapdvb.conf file was moved to the new folder.
  - New in Beta3: DVB-C and DVB-T are now supported - the zapdvb.conf file
    contains some comments to explain how this can be configured (source
    statement to specify DVB type and channel list). The GUI can handle
    multiple adapter types and channel lists.
  - Capturing the current program is now implemented but disabled in the
    default configuration. To enable the feature configure a capture folder.
    See "pathvideo=/example/yourFolder" and "pathcapture=capture". The
    folders must exist and must be writable. Also the "buffersize=0" must
    be commented out or set to any memory size from 1000...20000. The video
    editor can handle (multiple) capture files now. Cancel the KDE Open file
    dialog and type "load YourCaptureFolder" - in the dialog select the files
    to use and proceed as usual.
  - New in Beta3: A daily cron-job to clean up automatically recorded
    files (e.g. names containing a date like 2004_08_22_17_22) is added to
    /etc/cron.daily . The zapdvb.conf allows to specify when such files
    get deleted. Also the video editor automatically uses the trash folder
    into which the original files are moved (this needs to be configured
    or the trash feature is disabled). Files in this trash folder are
    removed after the maximum life time independently from their names.
  - New in Beta3: support for LNB types other than "UNIVERSAL" (see source
    statement in config file).
  - New documentation: README_CHANNELS. This file describes how to use the
    dvbscan tool (from the SuSE dvb rpm for example) to build channel list. As
    zapdvb understands the output format for dvbscan this is not a big issue.
  - By default Radio Recording produces files with the extension ".mp2" as they
    contain MPEG Layer 2 data. Some players do not recognise these files (like
    Noatun in KDE3.2 and play). Eventually the extension ".mp3" could be used -
    see the config file comment on how to do this.
  - Managing Periodic recording via cron and Timed recording via atd are now
    fully supported by the kzapdvb GUI.
  - Xine and Kaffeine can be used to watch life tv and to play video files. Video
    editing works with the exception of fast play. The SuSE versions of Xine and
    Kaffeine cannot play DVDs. Automatic player detection is supported. Edit your
    favorate player options in zapdvb.conf!