THIS PAGE IS UNDER CONSTRUCTION
For the impatient:
ksh> emerge ivtv-utils; ivtv-tune -f XXXX; cat /dev/video0 > myFirstProgram.mpg&; mplayer myFirstProgram.mpg
Below you will find a precise description how to install and use ivtv-utils with a supported TV/RADIO card on a Gentoo system running a recent kernel (>=gentoo-sources-2.6.26). The supported hardware includes general available generic digital video capture devices like the Hauppauge PVR-150 (one tuner), the PVR-500 (two tuners) or the PVR-350 (tv-out). The description applies to PAL users (no need to change any configuration file).
Before kernel 2.6.26 arrived, the ivtv package was needed to enable use of a supported card. That package provided its own kernel modules. In last years, these modules have merged with another project (V4L(1)). Recent kernels >=2.6.26 provide all equivalent modules which supsersede the original ivtv modules. The last version of ivtv that relies on an own modules is media-tv/ivtv-1.2.0-r1 (suitable for Linux kernels 2.6.25). Earlier versions of ivtv supported earlier kernel versions. Since kernel 2.6.26 all required modules are fully available as official kernel modules. As a result, the ivtv package has been cleaned up, and renamed as ivtv-utils. The first release was media-tv/ivtv-utils.1.3.0-r1.
If you intend to use a supported TV/RADIO card but still depend on a kernel prior to version 2.6.26, you are strongly advised to migrate your system to a newer kernel. Although ebuilds for the original ivtv package are still available, installation of ivtv requires much more effort and hocus-pocus compared to installing ivtv-utils. This page no longer supports ivtv, although valuable information can be found in its history.
When ivtv-utils and necessary kernel modules have been properly installed, you will be able to make bareback recordings of TV programs and FM radio stations using the command line of your system (described below). A very neat and user friendly X Window application for recording and viewing recorded TV programs (including lots of other nice things) is offered by the freely available MythTV package. Once you have installed ivtv, and your X Window is up and running, you should be able to emerge mythtv (not covered here).
At the end of this page, the install process of drivers for the TV-Out facility of some cards (e.g. Hauppauge PVR-350) in combination with suitable display adapters will be discussed (see Installing XDriver).
Some variations of cards are specifically designed for and intended to be sold for usa with dedicated (i.e. certified) Microsoft hardware and software. Such cards are equiped with onboard infrared receiver and remote control. These cards, which are denoted with the MCE qualifier, are generally known to work correctly with generic motherboards and ivtv package, but the infrared control is not functional. General infrared control handling (as used by the MythTV package) is available through the lirc package (not covered in this description).
Some cards are equipped with FM radio tuners. If so, you are able to tune into you favorite radio program as well after you have completed the install of your video-card. This also requires that your computer sound system is working properly (preferably alsa). Although installing of the alsa drivers is not covered here, a little section below is dedicated to Tuning your radio.
Package ivtv-utils requires a kernel >=2.6.26, and some video specific kernel modules. The ebuild will check for the appropriate kernel version and the required kernel modules. However, the first, and at the time of writing (late november 2009) the only available ivtv-utils ebuild (1.3.0-r1) was written for kernel 2.6.26. The script builder was unaware that since kernel 2.6.28 the configuration symbol CONFIG_KMOD has been replaced by CONFIG_MODULES. If your kernel is >=2.6.28, you need to tweak the ebuild first a bit.
First make sure you have the latest version of Portage on your system
ksh> emerge --sync
Installing ivtv-utils in ONE easy return
ksh> emerge ivtv-utils
If your kernel version is too old, the script will abort. If your kernel is recent (>=2.6.26), the script will check if all required kernel modules are available. If not, the script will give a verbose listing of which 'symbols' are required, but it will not abort. Despite that not all requirements are met, the software will be compiled normally, but the resulting executables (from the ivtv-utils package, like ivtv-tune) will not work. If your kernel is >=2.6.28, you will never be able to build the package with this ebuild. In that case, proceed with the optional step described below.
Optional (due to flaw in ebuild 1.3.0-r1 for >=2.6.28 kernels)
If your kernel is >=2.6.28, there is a flaw in ebuild 1.3.0-r1 (of which the script builder was unaware at the time he made it). The flaw has not been fixed yet. The easiest way to go around this is to create your own ebuild. This is not as difficult as it sounds, and the steps are: 1) cd to /usr/portage/media-tv/ivtv-utils; 2) make a copy of the ebuild and change CONFIG_MOD into CONFIG_MODULES; 3) finally, create a new Manifest file (which is Portage's way to prevent unwanted tampering with your Portage base).
This trick can be achieved as follows: open a terminal session, and execute the following commands (please check if 1.3.0-r1 is still the latest ebuild, it may have been fixed in later ebuilds):
ksh> cd /usr/portage/media-tv/ivtv-utils ksh> cat ivtv-utils.1.3.0.r1 | sed s/CONFIG_KMOD/CONFIG_MODULES/g > ivtv-utils.1.3.0.r2 ksh> ebuild ivtv-utils manifest
These commands have 'magically' created a 'higher' version (r2) of the original ebuild, which does not suffer from the flaw. Since you have a 'higher' version of the ebuild, this one will be used to build ivtv-utils.
Note: because this is not an official ebuild, it will be removed when you synchronize your portage again, but the software that has been installed with is persistent until you remove it or emerge it again after a new Portage has been sync-ed.
Optional: enabling missing kernel modules
If the ebuild script determines that not all required symbols (which represent one or more kernel modules) are present, the build script will notify this, and continue with compiling the package. As long as you do not fix the missing kernel modules, the software will not work. If you scroll back the log messages from emerge, you can determine what symbols (and hence kernel modules) are missing. If you found out which, it is easy to add them to your system by tweaking your kernel. This is not the subject of this page, but for brevity, it is illustrated here below:
ksh> cd /usr/src/linux # add the appropriate symbols with the configuration program and save your changes ksh> cp arch/x86_64/boot/bzImage /boot/bzImageKeep # make sure you have keep a valid rescue kernel in LILO/Grub ksh> make menuconfig
In the Linux Kernel Configuration application it is straightforward to configure your kernel with the necessary options. Goto 'Device Drivers' ---> 'Multimedia devices' ---> 'Video Capture Adapters' ---> 'Encoders and Decoders'. In the presented form you will be able by guessing to select most of the required kernel modules from the list above. Please be informed that the CONFIG_VIDEO_TUNER option and the CONFIG_VIDEO_TVEEPROM option must be selected one level higher by <M>odularizing the 'Conexant 2388x (bt878 successor) support' option or bttv module which sets both. See bug 153745. Also remember to enable I2C! NOTE: If you are having issues finding any of the modules use the '/' key to search in the kernel config menu and it will give you both the modules location as well as it's dependencies.
After you have saved the alterations you should rebuild and make the necessary kernel modules available:
ksh> make ksh> make modules_install # Make sure your boot device is mounted on /boot !) ksh> cp arch/x86_64/boot/bzImage /boot (or use make install which gives it a proper name also) # replace x86_64 in respect to your architecture (i386, ppc)
Don't forget to reconfigure your boot loader, e.g. if you are using LILO (please be sure to add bzImageKeep as fallback entry first !):
Now you should be able to reboot from you newly prepared kernel image:
Testing the card
If your card is inserted and the TV connector is connected to a coax wall outlet, you should be able to tune your card. In the following example stjûrder 'Omrop Fryslân' will be selected for cable subscribers to the UPC network in the Provinsje Fryslân, The Netherlands):
ksh> ivtv-tune -f 264 /dev/video0: 264.000 MHz (Signal Detected)
Now you can record this program in mpeg-2 format to file:
ksh> cat /dev/video0 > ~/fry.mpg
After you have killed this capturing process (Ctrl+C), you are able to view the recorded program (assuming you already have emerged the basic video player mplayer) with:
ksh> mplayer ~/fry.mpg
Alternatively you can view the program directly (although not simultaneously while recording):
ksh> mplayer /dev/video0
If you are using a twin card (e.g. PVR-500), you can also tune and play with the second tuner, which is identified by '/dev/video1'.
Autoloading of the ivtv modules
To allow autoloading of the ivtv modules at each reboot you should add "ivtv" to /etc/modules.autoload.d/kernel-2.6 (this mimics the modprobe ivtv command above).
ksh> echo ivtv >> /etc/modules.autoload.d/kernel-2.6
Tuning your radio
If your card is equipped with a FM radio tuner, and the sound system is working properly, you should now also be able to listen to your favorite radio station. Though your card may be equipped with both a video and a radio tuner, you can only utilize one at a time! So you can't listen to your favorite radio station and record your favorite tv station at the same time unless you have dual-tuner card (e.g. a Hauppauge PVR-500).
In the following example the tuner will be tuned to the authors favorite rock-and-roll program (STUBRU), available to subscribers to the UPC network in the Provinsje Fryslân, The Netherlands) with:
ksh> ivtv-radio -f 98.4 set to freq 98.40 Running: aplay -f dat < /dev/video24 Playing raw data 'stdin' : Signed 16 bit Little Endian, Rate 48000 Hz, Stereo
This will yield output from the radio tuner in high quality (DAT) to your sound card. Apparently, the (first) FM tuner device is identified by /dev/video24.
If you got fed-up (Ctrl+C) with this station, and decided to make a recording of another favorite station of yours (in this case BBC3 radio, available to subscribers to the UPC network in the Provinsje Fryslân, The Netherlands), proceed as follows:
ksh> ivtv-radio -j 102.6 & ;-- the & will start this as a background process  11914 ksh> arecord -D hw:0,0 -d 3600 -f dat ~/bbc3.dat; kill -9 11914 Recording WAVE '/home2/rec/bb3.dat' : Signed 16 bit Little Endian, Rate 48000 Hz, Stereo
This will record the station for the duration of one hour (3600 seconds), and subsequently remove the ivtv-radio process from your process list. (You may need to tweak the -D hw:0,0 setting for your own system configuration.) Your favorite music player (no not xmms because is recently was revoked from Portage, but audacious) should be able to play this recorded session. You can even listen to it while it is being recorded.
Unfortunately, the major contributing author of this page experiences some 10-12dB attenuation of the FM radio output compared with the TV sound output (as estimated by the necessary up or down swing off the volume control on the pre-amplifier to accomodate the difference while switching between TV and radio). The quality of his FM sound suffers greatly from this. Sound and noise are amplified the same amount (10-12dB) to reach normal listening conditions. In comparison: the quality of the TV sound is amazingly good (never heard it better on a real TV set). The quality of the FM sound is very noisy. I believe I will not use it very often (I assume most of the ivtv users won't, there is not much information on the internet about recording a FM radio station :-).
Please note: if a FM radio tuner is available the card provides a dedicated FM coax connector. The author has experienced that if you supply a combined TV and FM signal (direct cable signal, implicitly no splitter applied by using a wall socket) the FM radio signal is perfectly available through the regular TV connector. If your signal is split in separate TV and FM signals, you must supply the FM signal. If there is no FM signal then the TV sound from the previously tuned program will be heard and the working of ivtv-radio is void! What I mean here is: when you select a FM channel (when the FM signal is not present) you would at least expect that the TV sound ceases, and that is not the case.
I assume this guide was helpfull to you. It should be a sufficient description of how to use your PVR card with >=ivtv-0.8.0. If you have any remarks please send an e-mail to ivtv-gentoo_AT_intervisit_DOT_com.
If you have become interested in ivtv in general, please visit the ivtv website frequently and subscribe to the email@example.com on the Mailinglists page. You should also consider visiting http://gentoo-wiki.com/HARDWARE_PVR_500_Setup where installing ivtv and mythtv are covered. Next on this page you will find a guide installing XDriver, which does not apply to 'regular' PVR-150 and PVR-500 cards but only to the PVR-350. If you experience problems with ivtv and gentoo please check the gentoo bugzilla for open bugs.
The ivtvdev driver is now in portage. It is in testing for ~x86 and ~amd64. It also compiles now for Xorg 7.1.x.
# echo x11-drivers/xf86-video-ivtv ~* >> /etc/portage/package.keywords # emerge xf86-video-ivtv