[net-next-2.6.git] / Documentation / video4linux / README.ivtv


ivtv release notes
==================

This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
encoding. Currently the only card featuring full decoding support is the
Hauppauge PVR-350.

NOTE: this driver requires the latest encoder firmware (version 2.06.039, size
376836 bytes). Get the firmware from here:

http://dl.ivtvdriver.org/ivtv/firmware/

NOTE: 'normal' TV applications do not work with this driver, you need
an application that can handle MPEG input such as mplayer, xine, MythTV,
etc.

The primary goal of the IVTV project is to provide a "clean room" Linux
Open Source driver implementation for video capture cards based on the
iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.

Features:
 * Hardware mpeg2 capture of broadcast video (and sound) via the tuner or
   S-Video/Composite and audio line-in.
 * Hardware mpeg2 capture of FM radio where hardware support exists
 * Supports NTSC, PAL, SECAM with stereo sound
 * Supports SAP and bilingual transmissions.
 * Supports raw VBI (closed captions and teletext).
 * Supports sliced VBI (closed captions and teletext) and is able to insert
   this into the captured MPEG stream.
 * Supports raw YUV and PCM input.

Additional features for the PVR-350 (CX23415 based):
 * Provides hardware mpeg2 playback
 * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the
   video signal)
 * Provides a framebuffer (allowing X applications to appear on the video
   device) (this framebuffer is not yet part of the kernel. In the meantime it
   is available from www.ivtvdriver.org).
 * Supports raw YUV output.

IMPORTANT: In case of problems first read this page:
	   http://www.ivtvdriver.org/index.php/Troubleshooting

See also:

Homepage + Wiki
http://www.ivtvdriver.org

IRC
irc://irc.freenode.net/ivtv-dev

----------------------------------------------------------

Devices
=======

A maximum of 12 ivtv boards are allowed at the moment.

Cards that don't have a video output capability (i.e. non PVR350 cards)
lack the vbi8, vbi16, 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.

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/vbi8
crw-rw----    1 root     video     81, 232 Jun 19 22:22 /dev/vbi16

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 confusing. The ivtv
'ivtv_first_minor' module option can be used for that.


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

Reading from this device gets you the MPEG1/2 program stream.
Example:

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


/dev/video16
The decoder output device(s)
Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.

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:

cat my.mpg >/dev/video16


/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.
This device only captures audio. This should be replaced by an ALSA
device in the future.
Note that there is no corresponding raw audio output device, this is
not supported in the decoder firmware.


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

The raw YUV video output from the current video input. The YUV format
is non-standard (V4L2_PIX_FMT_HM12).

Note that the YUV and PCM streams are not synchronized, so they are of
limited use.


/dev/video48
The raw video display device(s)
Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.

Writes a YUV stream to the decoder of the card.


/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 (or sliced) 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.


/dev/vbi8
Processed vbi feedback device(s)
Read-only. Only present if the MPEG decoder (i.e. CX23415) exists.

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/vbi8.


/dev/vbi16
The vbi 'display' device(s)
Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.

Can be used to send sliced VBI data to the video-out connector.

---------------------------------

Hans Verkuil <hverkuil@xs4all.nl>
Commit	Line	Data
a542fe47 HV	1
	2	ivtv release notes
	3	==================
	4
	5	This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
	6	The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
	7	encoding. Currently the only card featuring full decoding support is the
	8	Hauppauge PVR-350.
	9
	10	NOTE: this driver requires the latest encoder firmware (version 2.06.039, size
	11	376836 bytes). Get the firmware from here:
	12
0ea6e611	13	http://dl.ivtvdriver.org/ivtv/firmware/
a542fe47 HV	14
	15	NOTE: 'normal' TV applications do not work with this driver, you need
	16	an application that can handle MPEG input such as mplayer, xine, MythTV,
	17	etc.
	18
	19	The primary goal of the IVTV project is to provide a "clean room" Linux
	20	Open Source driver implementation for video capture cards based on the
	21	iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.
	22
	23	Features:
	24	* Hardware mpeg2 capture of broadcast video (and sound) via the tuner or
	25	S-Video/Composite and audio line-in.
	26	* Hardware mpeg2 capture of FM radio where hardware support exists
	27	* Supports NTSC, PAL, SECAM with stereo sound
	28	* Supports SAP and bilingual transmissions.
	29	* Supports raw VBI (closed captions and teletext).
	30	* Supports sliced VBI (closed captions and teletext) and is able to insert
	31	this into the captured MPEG stream.
	32	* Supports raw YUV and PCM input.
	33
	34	Additional features for the PVR-350 (CX23415 based):
	35	* Provides hardware mpeg2 playback
	36	* Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the
	37	video signal)
	38	* Provides a framebuffer (allowing X applications to appear on the video
	39	device) (this framebuffer is not yet part of the kernel. In the meantime it
	40	is available from www.ivtvdriver.org).
	41	* Supports raw YUV output.
	42
	43	IMPORTANT: In case of problems first read this page:
	44	http://www.ivtvdriver.org/index.php/Troubleshooting
	45
	46	See also:
	47
	48	Homepage + Wiki
	49	http://www.ivtvdriver.org
	50
	51	IRC
	52	irc://irc.freenode.net/ivtv-dev
	53
	54	----------------------------------------------------------
	55
	56	Devices
	57	=======
	58
	59	A maximum of 12 ivtv boards are allowed at the moment.
	60
	61	Cards that don't have a video output capability (i.e. non PVR350 cards)
	62	lack the vbi8, vbi16, video16 and video48 devices. They also do not
	63	support the framebuffer device /dev/fbx for OSD.
	64
	65	The radio0 device may or may not be present, depending on whether the
	66	card has a radio tuner or not.
	67
	68	Here is a list of the base v4l devices:
	69	crw-rw---- 1 root video 81, 0 Jun 19 22:22 /dev/video0
	70	crw-rw---- 1 root video 81, 16 Jun 19 22:22 /dev/video16
	71	crw-rw---- 1 root video 81, 24 Jun 19 22:22 /dev/video24
	72	crw-rw---- 1 root video 81, 32 Jun 19 22:22 /dev/video32
	73	crw-rw---- 1 root video 81, 48 Jun 19 22:22 /dev/video48
	74	crw-rw---- 1 root video 81, 64 Jun 19 22:22 /dev/radio0
	75	crw-rw---- 1 root video 81, 224 Jun 19 22:22 /dev/vbi0
	76	crw-rw---- 1 root video 81, 228 Jun 19 22:22 /dev/vbi8
	77	crw-rw---- 1 root video 81, 232 Jun 19 22:22 /dev/vbi16
78
79	Base devices
80	============
81
82	For every extra card you have the numbers increased by one. For example,
83	/dev/video0 is listed as the 'base' encoding capture device so we have:
84
85	/dev/video0 is the encoding capture device for the first card (card 0)
86	/dev/video1 is the encoding capture device for the second card (card 1)
87	/dev/video2 is the encoding capture device for the third card (card 2)
88
89	Note that if the first card doesn't have a feature (eg no decoder, so no
90	video16, the second card will still use video17. The simple rule is 'add
91	the card number to the base device number'. If you have other capture
92	cards (e.g. WinTV PCI) that are detected first, then you have to tell
93	the ivtv module about it so that it will start counting at 1 (or 2, or
94	whatever). Otherwise the device numbers can get confusing. The ivtv
95	'ivtv_first_minor' module option can be used for that.
96
97
98	/dev/video0
99	The encoding capture device(s).
100	Read-only.
101
102	Reading from this device gets you the MPEG1/2 program stream.
103	Example:
104
105	cat /dev/video0 > my.mpg (you need to hit ctrl-c to exit)
106
107
108	/dev/video16
109	The decoder output device(s)
110	Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
111
112	An mpeg2 stream sent to this device will appear on the selected video
113	display, audio will appear on the line-out/audio out. It is only
114	available for cards that support video out. Example:
115
116	cat my.mpg >/dev/video16
117
118
119	/dev/video24
120	The raw audio capture device(s).
121	Read-only
122
123	The raw audio PCM stereo stream from the currently selected
124	tuner or audio line-in. Reading from this device results in a raw
125	(signed 16 bit Little Endian, 48000 Hz, stereo pcm) capture.
126	This device only captures audio. This should be replaced by an ALSA
127	device in the future.
128	Note that there is no corresponding raw audio output device, this is
129	not supported in the decoder firmware.
130
131
132	/dev/video32
133	The raw video capture device(s)
134	Read-only
135
136	The raw YUV video output from the current video input. The YUV format
137	is non-standard (V4L2_PIX_FMT_HM12).
138
139	Note that the YUV and PCM streams are not synchronized, so they are of
140	limited use.
141
142
143	/dev/video48
144	The raw video display device(s)
145	Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
146
147	Writes a YUV stream to the decoder of the card.
148
149
150	/dev/radio0
151	The radio tuner device(s)
152	Cannot be read or written.
153
154	Used to enable the radio tuner and tune to a frequency. You cannot
155	read or write audio streams with this device. Once you use this
156	device to tune the radio, use /dev/video24 to read the raw pcm stream
157	or /dev/video0 to get an mpeg2 stream with black video.
158
159
160	/dev/vbi0
161	The 'vertical blank interval' (Teletext, CC, WSS etc) capture device(s)
162	Read-only
163
164	Captures the raw (or sliced) video data sent during the Vertical Blank
165	Interval. This data is used to encode teletext, closed captions, VPS,
166	widescreen signalling, electronic program guide information, and other
167	services.
168
169
170	/dev/vbi8
171	Processed vbi feedback device(s)
172	Read-only. Only present if the MPEG decoder (i.e. CX23415) exists.
173
174	The sliced VBI data embedded in an MPEG stream is reproduced on this
175	device. So while playing back a recording on /dev/video16, you can
176	read the embedded VBI data from /dev/vbi8.
177
178
179	/dev/vbi16
180	The vbi 'display' device(s)
181	Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
182
183	Can be used to send sliced VBI data to the video-out connector.
184
185	---------------------------------
186
187	Hans Verkuil <hverkuil@xs4all.nl>