## Configuring Avicap

docu by: Alexander Rawass (alexannika@users.sourceforge.net)
if anyone can write a better documentation - please do it and tell me
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:

- Device
  you can set up your v4l device here, select video input, color mode, capturing size and color space
- File

- 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
- Segmentation
  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

- Video Compression Format
  you can select between different video-encoders and there options, when you press 'Change'
- Video frame rate

- Audio

- 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

- Limits

- you can limit the duration and file size of your recordings
  I might advise you to leave these options unchecked, but others might think different
  if you want to record for a specific time, better use the programmable timertable
  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 computer automatically
  read here in full length about the shutdown & resume modes
  read this, if you want to know about the options to configure shutdown & resume
- other

- 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

### Directory Pool

The direcory pool is a list of directories, where you want Avicap to save your recordings.
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 go:

#### 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 entry:

- absolute or relative paths (filename starts with either '/' or '.')
  the file will get written to that absolute or relative path, like you'd expect it
  the filename might get changed if you enabled 'never overwrite existing files'
  examples:
  - /home/alex/video/record/movie.avi
  - /windata/record/movie.avi
  - ./movie.avi
  - ./subdir/movie.avi

- filename has no path and ends on .avi
  avicap will select the 'best' directory from the dirpool and write the file into that direcory
  examples:

- 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
  examples:

- 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 date
  use this to never care for filenames any more
  no example ;-)

Warning:
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 directory
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).

### Password Lock

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 the files
~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:

- 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

Your children can now use Avicap to watch TV, but it is not possible for them to switch to a blocked channel.
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 every day.
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
Security thoughts:

- 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 (yet)
  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

If you've got ideas to improve security or a flaw in the password lock feature, tell us.