docu by: Alexander Rawass (firstname.lastname@example.org)
if anyone can write a better documentation - please do it and tell
To configure Avicap, press the right mouse button and select 'Configure'
from the pop-up menu.
If overlay mode is enabled, the overlay TV-picture may be drawn above
the menues, so can't read/use them.
Best is, to go to the very right of the TV-window and click right mouse
there, so the menu will pop up beside the TV window.
The configure dialog will show these Tabs:
you can set up your v4l device here, select video input, color mode, capturing
size and color space
- Destination file
this will be the default destination file if you do 'Capture Avi'
- never overwrite existing files
<does not work fully yet>
- Directory Pool
you can add directories there that you want to use for your recordings
you should always use segmentation, because the filesystem you might use
might not allow files greater than 2 or 4MB or whatever
I've set the segmentation size to 1900000 Kb (1.9GB), so I can be sure
that the files work fine on linux as well as my windows-partitions
- Video Compression Format
you can select between different video-encoders and there options, when
you press 'Change'
- Video frame rate
- Audio compression format
is not yet implemented
you can only record to uncompressed PCM audio, you have to recompress
the audio later with tools like qtrecompress, mencoder or transcode or else
- Audio format
- you can limit the duration and file size of your recordings
I might advise you to leave these options unchecked, but others might
if you want to record for a specific time, better use the programmable
to limit the size of the file, so that your HD doesn't overflow, better
use segmentation together with the Directory Pool
- Shutdown & Resume
here you can allow Avicap to shutdown/poweroff and poweron/reboot your
read here in full length about the shutdown
& resume modes
read this, if you want to know about the options to configure shutdown & resume
- Log to file
all important actions get logged into ~/.avm/avicap-userlog.log
you have to restart avicap for changes to have effect
- Password Lock
here you can set the Lock password or lock avicap
if Avicap is locked, programs which are blocked by the EPG cannot be watched
The direcory pool is a list of directories, where you want Avicap to save
Enter the name of a directory and select, how much space should be always
free on this device, then click 'add'
The directory will be shown in the Direcory pool table, along with the
keep-free setting and the currently free disk space.
You can enable or disable each entry per checkbox, disabled entries will
not be used for saving.
With these checkboxes, you can easilty disable a directory for now and
turn it on back later.
To actually use the DirPool feature, you have to learn about the 'special
way' Avicap uses to select how your files are named, and in which dir they
Naming your files
Avicap saves files in different ways, depending on the way you name them
(either in the Configure/File/File Destionation dialog or in the Timertable/Filename
- absolute or relative paths (filename starts with either '/' or '.')
the file will get written to that absolute or relative path, like you'd
the filename might get changed if you enabled 'never overwrite existing
- filename has no path and ends on .avi
avicap will select the 'best' directory
from the dirpool and write the file into that direcory
- movie.avi -> /path/from/dirpool/movie.avi
- movie123.avi -> /another/path/from/dirpool/movie123.avi
- filename has got no path and hasn't got an .avi ending
avicap will select the 'best' directory from the dirpool
avicap will append the current date as '-yymmdd-hhmmss.avi' to the filename
- movie -> /path/from/dirpool/movie-030401-190000.avi
- movie347beta -> /another/path/from/dirpool/movie347beta-030402-201500.avi
- no filename at all
avicap will select the 'best' directory from the dirpool
avicap will name the file 'avicap-yymmdd-hhmmss.avi' , depending on your
use this to never care for filenames any more
no example ;-)
If you use absolute or relative paths, the dirpool doesn't get used and
Avicap also doesn't check for free space on disk or segements to different
When you use the dirpool, avicap will try to find a directory with enough
free space and then segments there.
It is recommended to not use absolute/relative paths at all.
How Avicap finds the 'best' directory
Avicap will select the directory from the dirpool as 'best' , where Avicap
has the most free space to write to.
Avicap respect the 'keep free' setting, and will stop recording into that
directory if the 'keep free' limit is reached.
Avicap will then try to select another dir from the dirpool, and continue
the current recording by segmenting it.
<noy yet> If Avicap cannot find free space anymore, avicap will abort
the current recording and disable all other recordings, then it will go into
shutdown (if selected).
The password lock is a feature for parents, who don't have the time to care
about their children and simply park them before the TV (or rather Avicap),
so they don't have to communicate with their children.
If you don't want to care what your children are watching, or if you have
better things to do than be with your children, you can use the password
lock to simply forbid your children to watch any TV shows you don't like
them to watch.
Setting up your unix system for use with password lock
First, you need separate accounts for parent 'parent' and child 'child'.
Install avicap as root like you normally do.
Now change the owner of your /dev/video device to 'parent' and make sure
that your children have no access to /dev/video at all.
Then make sure that the home dir of 'parent', the dir ~parent/.avm and especially
~parent/.avm/default and ~parent/.avm/avicap-regexps
are not readable (or writable) for your children.
Then change (as root) the owner of the avicap binary (usually /usr/local/bin/avicap
) to 'parent' and set the setuid-bit on the binary.
That way, when avicap is started, it runs as user 'parent'
Now start avicap as parent.
Go to config/others and do 'Set Password'
You get prompted for a password, enter it twice and click the button.
Then click 'press to lock'.
After that, Avicap will get locked, with those effects:
Your children can now use Avicap to watch TV, but it is not possible for
them to switch to a blocked channel.
- the epg window will start up
- on a channel switch, avicap will verify what program/show is currently
running on this channel.
- if the current program is blocked in the EPG, avicap will not allow
to switch to that channel
- avicap won't allow free editing of the regexps file (deleting blocked
regeps is not possible)
- avicap won't allow changing of the EPG provider
- avicap won't allow unlocking unless password given
- at a restart of avicap, avicap is still locked
WARNING: the timertable has still full access to all channels YET!!
You have to have a valid EPG provier, you should have sensible regexps for
blocking, and you should make sure that the epg xml date is updated at least
If the epg data doesn't get updated, or if avicap cannot find the epg xml
file, the lock will not be able to block channels any more.
Make also sure that your children also cannot read/write the epg xml data
and the nxtvepg data directory etc
If you've got ideas to improve security or a flaw in the password lock feature,
- your children could download, compile, run or use other TV software
BUT since /dev/video is setuid of 'parent', only TV software which runs as
root or 'parent' can access the video device, and your children have to get
root access for that
- the password is saved into the file ~parent/.avm/default unencrypted
BUT, if the permissions of 'parent' and its subdirs are okay, it is not possible
for your children to read or write this file
- the regexps in ~parent/avicap-regexps can also not be edited or read
without special permissions
- you should set the umask of 'parent' to secure values