The program uses the DVB hardware to (a) tune to a satellite transponder channel and (b) to extract a MPEG data stream that contains data for audio and video or audio only. The extracted data can be passed to another program (a viewer for example) and/or can be written to disk. The zapdvb tool includes the functionality of the well-known szap, tzap and czap programs - but offers much more functionality. It is very configurable and can support up to four DVB cards!
The user will typically not use the program from the command line. It would be more typical to run it from the zapmcc user interface. Another client of zapdvb is called zapdvb_run and handles timed or periodic recording via atd or cron. The following documentation of command line options should be helpful for users that want to do some testing or implement special purpose solutions.
Instead of running locally zapdvb
can run in remote mode. One instance then
runs as server and another as client; as a result you can watch TV
on a client without DVB hardware. The client instance forwards some
commands to the server so that remote mode is mostly transparent to
the user. Local and remote mode can be mixed, see the
"sourceN=" statements in the zapdvb.conf
file.
The general call syntax is:
zapdvb [options] [channel-name]
A channel-name is looked-up in the
selected channel list. If the name is found, the corresponding
index in the list is used as if -n had been used. If
only a channel-name is given, zapdvb
starts the configured player. A simple example to watch a TV
channel is: zapdvb cnn. Usually channel names are
longer and may contain spaces, which require the use of quoting
(shell rules). Typically you will not specify a full name but a
fragment. The search algorithm ignores the case and searches the
whole channel list (unless it encounters a full match). When at
least the 1st character of the name matches, the algorithm will
consider that entry. It will finally select the channel with the
best match, e.g. the smallest number of unmatched characters.
The following table lists the available options. Note: optional parameters like [file] must follow the option letter without a space!
| Options that select an Action | |
| -h | Display a brief usage summary and quit. |
| -n channel | The index (starting with 1) of a channel relative to the
selected channel list. The -l option can be used to
print the channel indices of a list. If only -n is
given or a channel name is given zapdvb will start
the configured audio or video player and feed it with the MPEG data
stream via stdin (see also -x). |
| -o [file] | Write MPEG data to stdout or a file. This
option is implied (but without a file name) if -z is
not used and when a channel number is given via -n or
when a channel name is specified. When -o is selected
or implied the -r option is implied too. |
| -x cmd | Runs a command (see the comments in zapdvb.conf concerning
quoting and arguments). Example (the quotes are required): -x
"mpg123 -q -" . |
| -x @verb | Can be used in remote mode to execute a command on the server.
The -X option is then used to pass parameters to the
command. Implemented verbs are list (internal),
play (internal), jobs (runs
zapdvb_job --server) and edit (runs
zapdvb_cut --server). The -x and
-X options are internally used by
zapmcc to implement remote mode. |
| -z | Behave like szap/czap/tzap, keep looping but do not play or
store data. This option can be used together with
-r. |
| -S | Used typically by xinetd to run zapdvb in server mode. See: Remote Mode. |
| Hardware or Channel List Selection | |
| -a number | This option is typically used to select a source=
statement from the configuration file. That statement contains all
the required configuration information and in this case the options
-f and -d should not be used. If no source= config
statement is given, the option selects a physical adapter (like
/dev/dvb/adapter0). |
| -f number | If no source= config statement is given, the
option selects a physical frontend (like
/dev/dvb/frontend0). |
| -d number | If no source= config statement is given, the
option selects a physical demux device (like
/dev/dvb/demux0). |
| Miscellaneous | |
| -b [size] | This option enables an output thread which uses a cyclic buffer
with a size given in kByte (default size: 256 for audio, 4096 for
video). Currently (summer 2004) the DVB driver uses an internal
ring buffer of 1.8 MBytes, which might be to small if the system is
under heavy load. The -b option is implied when the
capture feature is enabled (see -s). The config file
can specify the default size, including a value of
0 which is used by default to disable
-b and -s. |
| -c file | Explicitly specify a configuration file. By default
zapdvb first tries to find a local configuration
under $HOME/.zapdvb and if this does not exist it
tries to locate a global zapdvb.conf. The global
configuration is searched in the installation folder (sym links get
dereferenced), /usr/local/bin,
/usr/local/etc and /etc. |
| -k [prio] | The priority controls if another running instance of zapdvb with a lower priority should be terminated so that the new instance can get access to the DVB card. Higher priority is indicated by a higher integer value. A value of 0 never terminates another instance, 1 (the default) is used for cron jobs, 2 is used for atd jobs and 3 is used for life actions. |
| -l [mask] | Output a list channel indices and names on stdout using the selected channel list. The optional mask argument is used to select TV-channels 1 (default), radio-channels 2 or Teletext-channels 4. Any combination can be used. |
| -m maxtime | Give a maximum time to run (in minutes). This feature is typically used for background recording whit atd or cron. After the expiration of maxtime the program terminates with an exit status of 0. |
| -p file | Explicitly specify the path of the process information file.
The default is $HOME/.zapdvb_run . |
| -q | Be quiet, do not write "zapdvb: info:" messages to stderr. |
| -r | Set-up /dev/dvb/adapterX/dvr0 for PES stream
recording (implied by -o) |
| -s [dir] | Enables the capture feature and allows to specify a folder
where the capture files are stored. Usually the folder is given by
the config file so that dir is only used to override that
setting. This option implies -b. Warning: by default the config file disables the
-b option. |
| -y [size] | Allows to specify a threshold value (in kByte) that defers the
writing of MPEG output until the amount of buffered data has
reached this value. If size is not given the default is
24 for audio and 256 for video.
The threshold is limited to 50% of the thread buffer size. If no
-b option is given -y is disabled. This
parameter can be used to prevent players doing odd things on
start-up (like playing a few audio or video frames and then pausing
again). |
| -X option | Can be used to pass additional arguments to the viewer or
player. If used in remote mode with -x @verb the
option argument is interpreted internally. The
option string should be enclosed in quotes. |
The exit codes in the following list are very important for the zapmcc script:
-h
option)As you have seen zapdvb does not
contain any GUI logic. But it offers some trivial help to implement
a GUI. These helpers are not invoked by special option letters
rather than special option values for -k and
-l: the lower 8 bits give the usual integer value,
whereas bit 8 (256), 9 (512) and 10 (1024) cause special behaviour.
Currently the following values are used:
kdialog
--radiolist (in remote mode this command is executed on the
server side).kdialog
--radiolist (in remote mode this command is executed on the
server side).-o: Don't run, create an output
file and print path name (in remote mode this command is executed
on the server side)..-n: Don't run, print the channel
name (in remote mode this command is executed on the server
side).-o: Don't run, delete output file
if one exists (in remote mode this command is executed on the
server side)..-n: Don't run, print the channel
number (in remote mode this command is executed on the server
side).-a): sat, ter,
cab, net.zapdvb cnn # watch a tv channel using a full name zapdvb cn # ... using a name fragment zapdvb "das erst" # ... quoting required here zapdvb sputnik # playing a radio channel zapdvb -n3 # watch a tv channel using a channel number zapdvb -a2 -n1 # using the channel list source2 (config file!) # playing radio in background and switch channel ... zapdvb -k sputnik & # stop running instance, play sputnik ... zapdvb -k hitradio & # stop running instance, play 'hitradio'
zapdvb sputnik -x "lame --mp2input -" >myfile.mp3 # convert radio to mp3 zapdvb sputnik -x "sog -t mp3" >myfile.ogg # convert radio to ogg # special case if 1st arg does not start with "-" (see config comment)... zapdvb sputnik -x "artsdsp artsdsp mpg123 -q -" # using kde artsdsp
zapdvb arte -s"/tmp/capt" # enable capture to folder "/tmp/capt" zapdvb -k513 # use a command to stop capture zapdvb arte -m30 -o"My Recording" # run 30 min, write "My Recording.mpg"
In principle you can configure zapdvb to launch almost any player that can read from stdin. But these players must be "robust", e.g. fault tolerant as the DVB signal may contain invalid data or drop outs. A player that crashes in such situations is no good choice. Currently (summer 2004) Mplayer and mpg123 are the best choice.
| Video Player Problems: | (1) The satellite signal may be of poor quality so that the player eventually gets invalid data. |
| (2) When tuning to a channel or after a drop out the data sent to the player does not necessarily start with a GOP (Group Of Pictures). | |
| (3) Currently (summer 2005) only mplayer offers full support for Monitor- and Video aspects (see Handling Video Aspects). | |
| Audio Player Problems: | (1) The data format is MPEG Layer II (which is not mp3!) - some players do not automatically detect this. |
| (2) The PC clock is not in sync with the transmitter clock, so the player must be able to squeeze or stretch the data (mpg321 fails badly on this). |