README for the IVTV Radio Support

Hans Verkuil (hverkuil@xs4all.nl)
Usage info for new version added by Adam Forsyth (agforsyth@gmail.com)

Introduction
============

This document describes the ivtv PVR-350 radio support and the (very) simple
radio utility.

The ivtv driver supports only the v4l2 API for the radio functionality, so
you need to find a radio application that can use that API. My experience
with several of the radio applications is that they are either too old (i.e.
they only support v4l), cannot do the simplest task (scanning for stations)
properly, or tend to crash a lot. I've added a very simple radio utility
that at least supports v4l2 and doesn't crash.

Usage: ivtv-radio <options>
Possible options are:
    -d <device>    Radio control device (default: /dev/radio0)
    -s             Scan for channels
    -a             Scan for frequencies
                   Use if Scan for channels is missing stuff
                   If e.g. 90.9, 91.1, 91.3 all exist use this
    -f <freq>      Tune to a specific frequency
    -j             Just tune (don't try to play the audio)
                   You'll have to play the audio yourself (see README.radio)
    -P             Use passthrough mode of card
    -g             Enable channel changing for passthrough mode
    -h             Display this help message
    -i <device>    PCM audio capture device (default: /dev/video24)
    -c <command>   Command to play audio.  This will be processed by
                   the shell, after substituting %s with the audio device.
                   Default: "aplay -f dat < %s"

Some examples:

ivtv-radio -s                  Scans for channels.
ivtv-radio -f 93.1             Plays the specified frequency with aplay.
ivtv-radio -f 93.1 -P -g       Outputs the sound through the card audio out
                               and give you a prompt allowing you to change
                               frequencies.
ivtv-radio -f 93.1 -j -g       Gives you a prompt allowing you to change
                               frequencies, but lets you play the sound
                               with whatever program you want to use.

When you press Ctrl-C to stop the radio utility you will get the sound of
the current TV channel instead. On rare occasions I've seen read errors
when trying to read from /dev/video24. Using 'cat </dev/video0 >/dev/video16'
for a few seconds seems to fix the problem and I can use /dev/video24 again.

If you use the '-g' option and you select an out-of-range frequency (e.g. 0),
then for some reason changing to a valid frequency will fail. The only solution
I know is to break off the radio application and start it again. There is still
something strange in the radio tuner support.

Driver Implementation Details
=============================

The tuner in the ivtv cards has to be switched from TV to FM mode, which means
that it is not possible to listen to the radio and watch TV at the same time.
So, when you open the /dev/radio0 device the tuner is switched to FM mode,
and after closing it it goes back to TV mode. You can open the radio device
only once, the second time it will return EBUSY (just like the bttv driver).
The last selected TV and radio frequencies are remembered and restored when
closing/opening the radio device.