blob: 3ba464c4f9bf7ed77c7dc42cde79ae599ed88dca [file] [log] [blame]
Hans Verkuila542fe42007-03-10 13:56:56 -03001
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -03002The ivtv driver
3===============
4
5Author: Hans Verkuil <hverkuil@xs4all.nl>
Hans Verkuila542fe42007-03-10 13:56:56 -03006
7This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
8The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
9encoding. Currently the only card featuring full decoding support is the
10Hauppauge PVR-350.
11
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030012.. note::
Hans Verkuila542fe42007-03-10 13:56:56 -030013
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030014 #) This driver requires the latest encoder firmware (version 2.06.039, size
15 376836 bytes). Get the firmware from here:
Hans Verkuila542fe42007-03-10 13:56:56 -030016
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030017 https://linuxtv.org/downloads/firmware/#conexant
18
19 #) 'normal' TV applications do not work with this driver, you need
20 an application that can handle MPEG input such as mplayer, xine, MythTV,
21 etc.
Hans Verkuila542fe42007-03-10 13:56:56 -030022
23The primary goal of the IVTV project is to provide a "clean room" Linux
24Open Source driver implementation for video capture cards based on the
25iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.
26
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030027Features
28--------
29
Hans Verkuila542fe42007-03-10 13:56:56 -030030 * Hardware mpeg2 capture of broadcast video (and sound) via the tuner or
31 S-Video/Composite and audio line-in.
32 * Hardware mpeg2 capture of FM radio where hardware support exists
33 * Supports NTSC, PAL, SECAM with stereo sound
34 * Supports SAP and bilingual transmissions.
35 * Supports raw VBI (closed captions and teletext).
36 * Supports sliced VBI (closed captions and teletext) and is able to insert
37 this into the captured MPEG stream.
38 * Supports raw YUV and PCM input.
39
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030040Additional features for the PVR-350 (CX23415 based)
41---------------------------------------------------
42
Hans Verkuila542fe42007-03-10 13:56:56 -030043 * Provides hardware mpeg2 playback
44 * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the
45 video signal)
46 * Provides a framebuffer (allowing X applications to appear on the video
Paul Cassellae45c2be2011-02-08 21:07:00 -030047 device)
Hans Verkuila542fe42007-03-10 13:56:56 -030048 * Supports raw YUV output.
49
50IMPORTANT: In case of problems first read this page:
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030051 https://help.ubuntu.com/community/Install_IVTV_Troubleshooting
Hans Verkuila542fe42007-03-10 13:56:56 -030052
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030053See also
54--------
Hans Verkuila542fe42007-03-10 13:56:56 -030055
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030056https://linuxtv.org
Hans Verkuila542fe42007-03-10 13:56:56 -030057
58IRC
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030059---
60
61irc://irc.freenode.net/#v4l
Hans Verkuila542fe42007-03-10 13:56:56 -030062
63----------------------------------------------------------
64
65Devices
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030066-------
Hans Verkuila542fe42007-03-10 13:56:56 -030067
68A maximum of 12 ivtv boards are allowed at the moment.
69
70Cards that don't have a video output capability (i.e. non PVR350 cards)
71lack the vbi8, vbi16, video16 and video48 devices. They also do not
72support the framebuffer device /dev/fbx for OSD.
73
74The radio0 device may or may not be present, depending on whether the
75card has a radio tuner or not.
76
77Here is a list of the base v4l devices:
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030078
79.. code-block:: none
80
81 crw-rw---- 1 root video 81, 0 Jun 19 22:22 /dev/video0
82 crw-rw---- 1 root video 81, 16 Jun 19 22:22 /dev/video16
83 crw-rw---- 1 root video 81, 24 Jun 19 22:22 /dev/video24
84 crw-rw---- 1 root video 81, 32 Jun 19 22:22 /dev/video32
85 crw-rw---- 1 root video 81, 48 Jun 19 22:22 /dev/video48
86 crw-rw---- 1 root video 81, 64 Jun 19 22:22 /dev/radio0
87 crw-rw---- 1 root video 81, 224 Jun 19 22:22 /dev/vbi0
88 crw-rw---- 1 root video 81, 228 Jun 19 22:22 /dev/vbi8
89 crw-rw---- 1 root video 81, 232 Jun 19 22:22 /dev/vbi16
Hans Verkuila542fe42007-03-10 13:56:56 -030090
91Base devices
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030092------------
Hans Verkuila542fe42007-03-10 13:56:56 -030093
94For every extra card you have the numbers increased by one. For example,
95/dev/video0 is listed as the 'base' encoding capture device so we have:
96
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030097- /dev/video0 is the encoding capture device for the first card (card 0)
98- /dev/video1 is the encoding capture device for the second card (card 1)
99- /dev/video2 is the encoding capture device for the third card (card 2)
Hans Verkuila542fe42007-03-10 13:56:56 -0300100
101Note that if the first card doesn't have a feature (eg no decoder, so no
102video16, the second card will still use video17. The simple rule is 'add
103the card number to the base device number'. If you have other capture
104cards (e.g. WinTV PCI) that are detected first, then you have to tell
105the ivtv module about it so that it will start counting at 1 (or 2, or
106whatever). Otherwise the device numbers can get confusing. The ivtv
107'ivtv_first_minor' module option can be used for that.
108
109
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300110- /dev/video0
Hans Verkuila542fe42007-03-10 13:56:56 -0300111
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300112 The encoding capture device(s).
Hans Verkuila542fe42007-03-10 13:56:56 -0300113
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300114 Read-only.
115
116 Reading from this device gets you the MPEG1/2 program stream.
117 Example:
118
119 .. code-block:: none
120
121 cat /dev/video0 > my.mpg (you need to hit ctrl-c to exit)
Hans Verkuila542fe42007-03-10 13:56:56 -0300122
123
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300124- /dev/video16
Hans Verkuila542fe42007-03-10 13:56:56 -0300125
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300126 The decoder output device(s)
Hans Verkuila542fe42007-03-10 13:56:56 -0300127
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300128 Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
129
130 An mpeg2 stream sent to this device will appear on the selected video
131 display, audio will appear on the line-out/audio out. It is only
132 available for cards that support video out. Example:
133
134 .. code-block:: none
135
136 cat my.mpg >/dev/video16
Hans Verkuila542fe42007-03-10 13:56:56 -0300137
138
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300139- /dev/video24
Hans Verkuila542fe42007-03-10 13:56:56 -0300140
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300141 The raw audio capture device(s).
142
143 Read-only
144
145 The raw audio PCM stereo stream from the currently selected
146 tuner or audio line-in. Reading from this device results in a raw
147 (signed 16 bit Little Endian, 48000 Hz, stereo pcm) capture.
148 This device only captures audio. This should be replaced by an ALSA
149 device in the future.
150 Note that there is no corresponding raw audio output device, this is
151 not supported in the decoder firmware.
Hans Verkuila542fe42007-03-10 13:56:56 -0300152
153
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300154- /dev/video32
Hans Verkuila542fe42007-03-10 13:56:56 -0300155
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300156 The raw video capture device(s)
Hans Verkuila542fe42007-03-10 13:56:56 -0300157
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300158 Read-only
159
160 The raw YUV video output from the current video input. The YUV format
161 is non-standard (V4L2_PIX_FMT_HM12).
162
163 Note that the YUV and PCM streams are not synchronized, so they are of
164 limited use.
Hans Verkuila542fe42007-03-10 13:56:56 -0300165
166
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300167- /dev/video48
Hans Verkuila542fe42007-03-10 13:56:56 -0300168
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300169 The raw video display device(s)
170
171 Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
172
173 Writes a YUV stream to the decoder of the card.
Hans Verkuila542fe42007-03-10 13:56:56 -0300174
175
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300176- /dev/radio0
Hans Verkuila542fe42007-03-10 13:56:56 -0300177
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300178 The radio tuner device(s)
179
180 Cannot be read or written.
181
182 Used to enable the radio tuner and tune to a frequency. You cannot
183 read or write audio streams with this device. Once you use this
184 device to tune the radio, use /dev/video24 to read the raw pcm stream
185 or /dev/video0 to get an mpeg2 stream with black video.
Hans Verkuila542fe42007-03-10 13:56:56 -0300186
187
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300188- /dev/vbi0
Hans Verkuila542fe42007-03-10 13:56:56 -0300189
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300190 The 'vertical blank interval' (Teletext, CC, WSS etc) capture device(s)
191
192 Read-only
193
194 Captures the raw (or sliced) video data sent during the Vertical Blank
195 Interval. This data is used to encode teletext, closed captions, VPS,
196 widescreen signalling, electronic program guide information, and other
197 services.
Hans Verkuila542fe42007-03-10 13:56:56 -0300198
199
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300200- /dev/vbi8
Hans Verkuila542fe42007-03-10 13:56:56 -0300201
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300202 Processed vbi feedback device(s)
203
204 Read-only. Only present if the MPEG decoder (i.e. CX23415) exists.
205
206 The sliced VBI data embedded in an MPEG stream is reproduced on this
207 device. So while playing back a recording on /dev/video16, you can
208 read the embedded VBI data from /dev/vbi8.
Hans Verkuila542fe42007-03-10 13:56:56 -0300209
210
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300211- /dev/vbi16
Hans Verkuila542fe42007-03-10 13:56:56 -0300212
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300213 The vbi 'display' device(s)
Hans Verkuila542fe42007-03-10 13:56:56 -0300214
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300215 Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
Hans Verkuila542fe42007-03-10 13:56:56 -0300216
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300217 Can be used to send sliced VBI data to the video-out connector.