These files are included in the source and binary packages.
As the amount of documentation increases, the detailed descriptions will be distributed as a separate package.
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.
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:
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:
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).
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.
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:
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...
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.
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...
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 ...
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!).
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:
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)
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!)
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
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.
- 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
- 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
- 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
- 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!