# The &kalva; handbook

## Introduction

&kalva; is a simple to use and easy to setup videorecorder for the K Desktop Environment. It is using the console tool MEncoder from the MPlayer package to do the real work. You can schedule a movierecording by choosing the date from a calender (will be passed to at) and a serial recording by choosing the days of the week (feeds your crontab).

You can manage your serial- and movie recordings.

You can store the MEncoder Options in hardware- and quality profiles. You can use different quality profiles for special purposes (f.i record a movie without deinterlacing and in 16/9, record sport broadcasts in 4/3 with 50Hz, record normal tv broadcasts deinterlaced and in 4/9 etc.).

You can easily share your profiles and your channellist via New Stuff (take a look at www.kde-files.org for channellists, hardware profiles and quality profiles).

&kalva; can import channellists from e.g. xawtv or xawtv4 and generate a knew one using scantv. You can edit and store that list. You might as well download a channellist from www.kde-files.org (KHotNewStuff).

&kalva; has a DCOP interface. This is meant as a convinient way to support recording for external apps like xmltv browsers (f.i. KTvSchedule). If You want to use the DCOP interface You can push &kalva; into KDE's systemtray (works just like with JuK or amaroK).

## using &kalva;

### Befor you start

&kalva; uses MPlayer and MEncoder to do the real work. These tools support any TV card that is supported by v4l or v4l2. You need a functioning tv setup. The card normally is set up via /etc/modprobe.conf or a configfile that is included by modprobe.conf (SuSE-users have to look at /etc/modprobe.conf.local).

### First setup

First of all you need a channellist. &kalva; provides many ways to help you to get a channellist. You might use scantv to create a channellist. The scan takes a while. Don't forget to save your channellist.

If you create a new channellist you should consider uploading it to www.kde-files.org. You can make live easier for other users that live nearby. This is a nice and very simple way to contribute a little but helpfull piece of work.

You should at least once open the preferences dialog. &kalva; comes with sane defaults, so hitting the defaults button and closing the dialog via "OK" should be sufficient to enable recording.

To get more flexibility I recommend to install some quality profiles. You will get the benefit of different profiles that where created by users who know about usefull parameters for different purposes.

### Watch TV

The TV viewer of &kalva; is meant as a convenient way to preview the results of the choosen hardware- and quality profile. &kalva; launches an external MPlayer window which shows the active station if you push the button. You can change the station of the running MPlayer by changing to Kalva's main window and choosing a different station from the list. Toggle between fullscreen and window mode by typing "f" into the MPlayer window. Quit the MPlayer with "q".

The TV viewer The TV viewer

### Record immediate

Choose a station. Give your recording a title, tell &kalva; how long it shall record and push the record button. &kalva; will immediately record a video by running an mencoder command.

Record immediate Record immediate

### Record movie

Choose a station. Give your recording a title, tell &kalva; how long it shall record and the time the movie starts. Choose the day from the calender. Push the record button. &kalva; will pass the mencoder command to at. The recording will be issued by atd when the time has come.

Record movie Record movie

### Manage movie recordings

For changing an allready scheduled movie recording open the movie manager and choose the movie you want to manage. &kalva; fills the parameters of the scheduled movie into the record movie tab. Make your changes and hit the record button. The movie recording will be scheduled with the new values.

The movie manager shows the new scheduled movie.

For deleting an allready scheduled movie recordings open the movie manager and choose the movie you want to delete. &kalva; fills the parameters of the scheduled movie into the record movie tab. Hit the delete button. The at job for the movie recording will be deleted.

The movie manager will be reread to reflect the changes.

The number behind the starttime is the id of the atjob. If you want to learn more about how &kalva; schedules the movies you might read the manpage of the console tools atd, at, atq and atrm.

Manage movie recordings Manage movie recordings

### Record serial

Choose a station. Give your recording a title, tell &kalva; how long it shall record and the time the movie starts. Select the days of the week the serial is broadcasted. Push the record button. &kalva; will pass the mencoder command to cron. The recordings will be issued by crond when the time has come.

Record serial Record serial

### Manage serial recordings

For changing an allready scheduled set of serial recording open the serial manager and choose the serial you want to manage. &kalva; fills the parameters of the scheduled serial into the record serial tab. Make your changes and hit the record button. The serial recordings will be scheduled with the new values.

The serial manager shows the new scheduled serial.

For deleting an allready scheduled set of serial recordings open the serial manager and choose the serial you want to delete. &kalva; fills the parameters of the scheduled serial into the record serial tab. Hit the delete button. The crontab entry for the serial recordings will be deleted.

The serial manager will be reread to reflect the changes.

If you want to learn more about how &kalva; schedules serials you might read the manpage of the console tools crond and crontab.

Manage movie recordings Manage movie recordings

## Settings

### General settings

Tell &kalva; the directory for your video collection.

If you are an experienced MEncoder user let &kalva; show the build command befor it gets executed. That enables you to apply options to the command that are not supported by &kalva;. If you have such options and you need them for allmost any recording you should let me know about. I might consider to incorporate those options into kalva's quality profile options.

You can setup if the external MPlayer shall be run fullscreen or in window mode.

You can set up the verbosity level of the MEncoder. To see the MEncoder's output start kalva from a konsole.

&kalva; can prepend "sudo nice -value" to the command. To activate this feature use a value greater zero. Please beware that this will probably not increase the video quality. I really do not recommended to use this.

General settings General settings

### Hardware settings

Here you can setup options that are specific for your hardware. You can store those options into a hardware profile.

You can download and install hardware profiles.

If you have created a new hardware profile you should consider to upload that to www.kde-files.org. You may make live a lot easier for other users with similar hardware. This is a nice and quite easy way to commit a little piece of work.

TODO: describe all the options provided by the different tabs... If you like to help fill up the missing documentations your contributions would be very much appreciated.

Hardware settings Hardware settings

### Quality settings

Here you can setup options that control the quality of the recordings.

You can download and install quality profiles.

If you have created a new quality profile for a special purpose you should consider to upload that to www.kde-files.org. You may make live a lot easier for other users. This is a nice way to commit a valuable piece of work.

TODO: describe all the options provided by the different tabs... If you like to help fill up the missing documentations your contributions would be very much appreciated.

Quality settings Quality settings

### Channellists

Here you can choose a channellist.

You can download and install channellists.

If you have created a new channellist you should consider to upload that to www.kde-files.org. You may make live a lot easier for other users. This is a nice way to commit a little piece of work.

Channellists Channellists

You can edit the choosen channellist. Don't forget to save the channellist if you have applied changes.

Edit channellist edit channellist

### Component settings

&kalva; is a frontend to a set of console tools. Adapt the path to a component if it is not installed into the standardpath on your system.

Component settings Component settings

## Command reference

### The main window of &kalva;

#### The File menu

&Ctrl;S File Channellist Save

- Save your channellist. You will get a dialog, that asks for some informations about the channellist.

&Ctrl;N File Channellist Scan with scantv

- Let scantv scan the tv card for a new channellist. The scan process takes a while, so please be patient. Don't forget to save the created channellist.

File Channellist Import xawtv from file

- Opens a file selector to import a channellist in xawtv's format

File Channellist Import xawtv (~/xawtvrc)

- Imports the channellist from xawtv

File Channellist Import xawtv4 from file

- Opens a file selector to import a channellist in xawtv4's format

File Channellist Import xawtv4 (~/xawtv/tv_channel)

- Imports the channellist from xawtv4

File Channellist Export not jet

- This could be provided if someone volonteers to write an export filter for a channellist. The interessted hacker might take a look into the plugin sources.

&Ctrl;Q File Quit

- Quits &kalva;

#### The Settings menu

Settings Dock in systemtray

- Creates a symbol in kicker's systemtray.

Settings Keep in systemtray on close

- The application resides in the systemtray on close. Use this if you want to keep kalva in the background waiting for DCOP calls (f.i. via the xmltv-browser KTvSchedule).

#### The Help menu

&help.menu.documentation;

## Developer's Guide to &kalva;

TODO: Write a description of the DCOP interface.

TODO: Write a description of the channellists interface for filter plugins and a howto write im- and export filters.

## Frequently asked questions

What is the use of the bar above the programming part that gives the channel name and channel freq ? it is exactly the same than in the listview?

The recorder, the player and the channellist are independent objects. The recorder and the player have no access to the channellist. The bar reflects the selection and is filled via signals and slots in kalva_viewer. It provides these informations to the recorder / player.

In the movie tag, you have this calendar view. Why having the quit and configure button there? Wouldn't it be better to create a toolbar?

These Icons in the toolbar have nothing to do with the calender. As the calender brings everything with it that it needs, I don't see any usefull actions for the toolbar that deal with the active tabs.

The quit button shouldn't be there according to some HIGs. That is my stubborness, I miss this feature that was eliminated from so many kde apps...

The other is there because one has to open the prefs for changing profiles. As Kalva can provide many profiles for different purposes (16/9, 4/3, 50Hz non interlaced for sport broadcasts...), I want the prefs window to be close at hand.

## Credits and License

&kalva;

Program copyright 2005 Andreas Silberstorff ml@andreas-silberstorff.de

Contributors:

- Birgit Silberstorff

  Many thanks to the best of all wifes and mothers for her stoic endurance and patience with me hacking all through the spare time that we should have spend together...

- Lara Silberstorff

  for being the cutest daughter. Recording "Petzi and his friends" was the initial reason for what has now become &kalva;

- Matthias Wieser

  provided many patches and very valuable hints concerning the MEncoder and MPlayer options. Without his help the quality- and hardware profiles wouldn't have evolved that fast.

- Michael Reiher

  provided patches that showed where the flaws in the aumix implementation lay. He also did help me very much to fix the geometry issues kalva had in versions prior to 0.7.90.

- Tux the Linux Penguin tux@linux.org

Documentation copyright 2005 Andreas Silberstorff ml@andreas-silberstorff.de

&underFDL; &underGPL;

## Installation

### How to obtain &kalva;

You find &kalva; Sourcetarball and SuSE-RPMs at the &kalva; project site

### Requirements

MPlayer of course. The MPlayer package includes the MEcoder, which is the working horse of &kalva;.

date is used to put the day and time of the recording into the filename for the video.

at is used to schedule movie recordings.

cron is used to schedule serial recordings.

perl is needed for perl-setup-crontab.

perl-setup-crontab is the interface of &kalva; to your crontab.

aumix is optional. It can be used to switch the audio channel to recording, mute it when recording and raise the input gain. Beware that aumix does not support all mixer channels. It might be that your tv card uses a channel aumix can not set (like mine, my tv card is on video).

You also need at least the kde libraries if you want to use &kalva;. &kalva; needs &kde; 3.x. Recommended is at least &kde; 3.4.0.

&kalva; itself can be downloaded as binary RPM (SuSE) or sourcetarball from the &kalva; project site.

A list of frequent changes is available at http://kalva.berlios.de/#vlast.

### Compiliation and installation

&install.compile.documentation;

### Configuration

If you don't want to use a binary I recommend using kdevelop. &kalva; was developed using this great IDE!

If you want to keep on the track for the bleeding edge of Kalva you find it in KDE-SVN (trunc/playground/multimedia/kalva)

The docbook source of this documentation is available in KDE-SVN (trunc/playground/multimedia/doc/kalva/index.docbook)

&documentation.index;