README for the IVTV Devices

Introduction
============
The ivtv modules can be accessed via their device entries, through the
V4L interfaces (versions 1 and 2 are supported) or through a series of
ioctl()s (detailed in README.ioctl). This document describes the devices.

Devices
=======
There may be multiple devices depending on how many cards your system
has installed.

A maximum of 8 cards are allowed at the moment. However, for PVR 350s
the maximum might be 4 or 5 because we run out of available vbi device
numbers. We don't yet know how the v4l layer will handle a case like that.

Cards that don't have a video output capability (i.e. non PVR350 cards)
lack the vbi4, vbi8, video16 and video48 devices. They also do not
support the framebuffer device /dev/fbx for OSD.

The radio0 device may or may not be present, depending on whether the
card has a radio tuner or not. The eeprom output will tell you this.

Here is a list of the base v4l devices:
crw-rw----    1 root     video     81,   0 Jun 19 22:22 /dev/video0
crw-rw----    1 root     video     81,  16 Jun 19 22:22 /dev/video16
crw-rw----    1 root     video     81,  24 Jun 19 22:22 /dev/video24
crw-rw----    1 root     video     81,  32 Jun 19 22:22 /dev/video32
crw-rw----    1 root     video     81,  48 Jun 19 22:22 /dev/video48
crw-rw----    1 root     video     81,  64 Jun 19 22:22 /dev/radio0
crw-rw----    1 root     video     81, 224 Jun 19 22:22 /dev/vbi0
crw-rw----    1 root     video     81, 228 Jun 19 22:22 /dev/vbi4
crw-rw----    1 root     video     81, 232 Jun 19 22:22 /dev/vbi8

Base devices
============

For every extra card you have the numbers increased by one. For example,
/dev/video0 is listed as the 'base' encoding capture device so we have:

 /dev/video0  is the encoding capture device for the first card (card 0)
 /dev/video1  is the encoding capture device for the second card (card 1)
 /dev/video2  is the encoding capture device for the third card (card 2)

Note that if the first card doesn't have a feature (eg no decoder, so no video16,
the second card will still use video17. The simple rule is 'add the card number to
the base device number'. If you have other capture cards (e.g. WinTV PCI) that
are detected first, then you have to tell the ivtv module about it so that it
will start counting at 1 (or 2, or whatever). Otherwise the device numbers can
get confused. See the ivtv_first_minor module option for more information.


/dev/video0
The encoding capture device(s).
Read-only.

Reading from this device results in an encoded mpeg2 capture from the
selected ivtv inputs.  This device multiplexes the selected audio and
video inputs into the mpeg2 stream. Example:

cat /dev/video0 > my.mpg (you need to hit ctrl-c to exit)


/dev/video16
The decoder output device(s)
Write-only.

An mpeg2 stream sent to this device will appear on the selected video
display, audio will appear on the line-out/audio out.  It is only
available for cards that support video out. Example:

dd if=my.mpg of=/dev/video16 bs=64k


/dev/video24
The raw audio capture device(s).
Read-only

The raw audio PCM stereo stream from the currently selected
tuner or audio line-in.  Reading from this device results in a raw
(signed 16 bit Little Endian, 48000 Hz, stereo pcm) capture
from the selected ivtv inputs.  This device only captures audio.


/dev/video32
The raw video capture device(s)
Read-only

The raw YUV video output from the current video input. Apparently the
YUV format is non-standard and you may need special software to read
this.


/dev/video48
The raw video display device(s)
Write-only

Writes a YUV stream to the decoder of the card. Does not currently
work. This is on the TODO list but at a low priority.


/dev/radio0
The radio tuner device(s)
Cannot be read or written.

Used to enable the radio tuner and tune to a frequency. You cannot
read or write audio streams with this device.  Once you use this
device to tune the radio, use /dev/video24 to read the raw pcm stream
or /dev/video0 to get an mpeg2 stream with black video.


/dev/vbi0
The 'vertical blank interval' (Teletext, CC, WSS etc) capture device(s)
Read-only

Captures the raw video data sent during the Vertical Blank
Interval. This data is used to encode teletext, closed captions, VPS,
widescreen signalling, electronic program guide information, and other
services. See also README.vbi


/dev/vbi4
Processed vbi feedback device(s)
Read-only

The sliced VBI data embedded in an MPEG stream is reproduced on this
device. So while playing back a recording on /dev/video16, you can
read the embedded VBI data from /dev/vbi4.


/dev/vbi8
The vbi 'display' device(s)
Write-only

Can be used to send VBI data to the video-out connector. 
See also README.vbi


/dev/fb[x]

This device is a linux framebuffer for the ivtv OSD display.
It is only available for cards that support video out.