blob: 7b8775d20214380a9f5b84e9d52660d66be47937 [file] [log] [blame]
Mauro Carvalho Chehabf2ac8ce2018-08-30 10:20:04 -04001.. SPDX-License-Identifier: GPL-2.0
2
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -03003The ivtv driver
4===============
5
6Author: Hans Verkuil <hverkuil@xs4all.nl>
Hans Verkuila542fe42007-03-10 13:56:56 -03007
8This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
9The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
10encoding. Currently the only card featuring full decoding support is the
11Hauppauge PVR-350.
12
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030013.. note::
Hans Verkuila542fe42007-03-10 13:56:56 -030014
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030015 #) This driver requires the latest encoder firmware (version 2.06.039, size
16 376836 bytes). Get the firmware from here:
Hans Verkuila542fe42007-03-10 13:56:56 -030017
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030018 https://linuxtv.org/downloads/firmware/#conexant
19
20 #) 'normal' TV applications do not work with this driver, you need
21 an application that can handle MPEG input such as mplayer, xine, MythTV,
22 etc.
Hans Verkuila542fe42007-03-10 13:56:56 -030023
24The primary goal of the IVTV project is to provide a "clean room" Linux
25Open Source driver implementation for video capture cards based on the
26iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.
27
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030028Features
29--------
30
Hans Verkuila542fe42007-03-10 13:56:56 -030031 * Hardware mpeg2 capture of broadcast video (and sound) via the tuner or
32 S-Video/Composite and audio line-in.
33 * Hardware mpeg2 capture of FM radio where hardware support exists
34 * Supports NTSC, PAL, SECAM with stereo sound
35 * Supports SAP and bilingual transmissions.
36 * Supports raw VBI (closed captions and teletext).
37 * Supports sliced VBI (closed captions and teletext) and is able to insert
38 this into the captured MPEG stream.
39 * Supports raw YUV and PCM input.
40
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030041Additional features for the PVR-350 (CX23415 based)
42---------------------------------------------------
43
Hans Verkuila542fe42007-03-10 13:56:56 -030044 * Provides hardware mpeg2 playback
45 * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the
46 video signal)
47 * Provides a framebuffer (allowing X applications to appear on the video
Paul Cassellae45c2be2011-02-08 21:07:00 -030048 device)
Hans Verkuila542fe42007-03-10 13:56:56 -030049 * Supports raw YUV output.
50
51IMPORTANT: In case of problems first read this page:
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030052 https://help.ubuntu.com/community/Install_IVTV_Troubleshooting
Hans Verkuila542fe42007-03-10 13:56:56 -030053
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030054See also
55--------
Hans Verkuila542fe42007-03-10 13:56:56 -030056
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030057https://linuxtv.org
Hans Verkuila542fe42007-03-10 13:56:56 -030058
59IRC
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030060---
61
62irc://irc.freenode.net/#v4l
Hans Verkuila542fe42007-03-10 13:56:56 -030063
64----------------------------------------------------------
65
66Devices
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030067-------
Hans Verkuila542fe42007-03-10 13:56:56 -030068
69A maximum of 12 ivtv boards are allowed at the moment.
70
71Cards that don't have a video output capability (i.e. non PVR350 cards)
72lack the vbi8, vbi16, video16 and video48 devices. They also do not
73support the framebuffer device /dev/fbx for OSD.
74
75The radio0 device may or may not be present, depending on whether the
76card has a radio tuner or not.
77
78Here is a list of the base v4l devices:
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030079
80.. code-block:: none
81
82 crw-rw---- 1 root video 81, 0 Jun 19 22:22 /dev/video0
83 crw-rw---- 1 root video 81, 16 Jun 19 22:22 /dev/video16
84 crw-rw---- 1 root video 81, 24 Jun 19 22:22 /dev/video24
85 crw-rw---- 1 root video 81, 32 Jun 19 22:22 /dev/video32
86 crw-rw---- 1 root video 81, 48 Jun 19 22:22 /dev/video48
87 crw-rw---- 1 root video 81, 64 Jun 19 22:22 /dev/radio0
88 crw-rw---- 1 root video 81, 224 Jun 19 22:22 /dev/vbi0
89 crw-rw---- 1 root video 81, 228 Jun 19 22:22 /dev/vbi8
90 crw-rw---- 1 root video 81, 232 Jun 19 22:22 /dev/vbi16
Hans Verkuila542fe42007-03-10 13:56:56 -030091
92Base devices
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030093------------
Hans Verkuila542fe42007-03-10 13:56:56 -030094
95For every extra card you have the numbers increased by one. For example,
96/dev/video0 is listed as the 'base' encoding capture device so we have:
97
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -030098- /dev/video0 is the encoding capture device for the first card (card 0)
99- /dev/video1 is the encoding capture device for the second card (card 1)
100- /dev/video2 is the encoding capture device for the third card (card 2)
Hans Verkuila542fe42007-03-10 13:56:56 -0300101
102Note that if the first card doesn't have a feature (eg no decoder, so no
103video16, the second card will still use video17. The simple rule is 'add
104the card number to the base device number'. If you have other capture
105cards (e.g. WinTV PCI) that are detected first, then you have to tell
106the ivtv module about it so that it will start counting at 1 (or 2, or
107whatever). Otherwise the device numbers can get confusing. The ivtv
108'ivtv_first_minor' module option can be used for that.
109
110
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300111- /dev/video0
Hans Verkuila542fe42007-03-10 13:56:56 -0300112
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300113 The encoding capture device(s).
Hans Verkuila542fe42007-03-10 13:56:56 -0300114
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300115 Read-only.
116
117 Reading from this device gets you the MPEG1/2 program stream.
118 Example:
119
120 .. code-block:: none
121
122 cat /dev/video0 > my.mpg (you need to hit ctrl-c to exit)
Hans Verkuila542fe42007-03-10 13:56:56 -0300123
124
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300125- /dev/video16
Hans Verkuila542fe42007-03-10 13:56:56 -0300126
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300127 The decoder output device(s)
Hans Verkuila542fe42007-03-10 13:56:56 -0300128
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300129 Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
130
131 An mpeg2 stream sent to this device will appear on the selected video
132 display, audio will appear on the line-out/audio out. It is only
133 available for cards that support video out. Example:
134
135 .. code-block:: none
136
137 cat my.mpg >/dev/video16
Hans Verkuila542fe42007-03-10 13:56:56 -0300138
139
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300140- /dev/video24
Hans Verkuila542fe42007-03-10 13:56:56 -0300141
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300142 The raw audio capture device(s).
143
144 Read-only
145
146 The raw audio PCM stereo stream from the currently selected
147 tuner or audio line-in. Reading from this device results in a raw
148 (signed 16 bit Little Endian, 48000 Hz, stereo pcm) capture.
149 This device only captures audio. This should be replaced by an ALSA
150 device in the future.
151 Note that there is no corresponding raw audio output device, this is
152 not supported in the decoder firmware.
Hans Verkuila542fe42007-03-10 13:56:56 -0300153
154
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300155- /dev/video32
Hans Verkuila542fe42007-03-10 13:56:56 -0300156
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300157 The raw video capture device(s)
Hans Verkuila542fe42007-03-10 13:56:56 -0300158
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300159 Read-only
160
161 The raw YUV video output from the current video input. The YUV format
162 is non-standard (V4L2_PIX_FMT_HM12).
163
164 Note that the YUV and PCM streams are not synchronized, so they are of
165 limited use.
Hans Verkuila542fe42007-03-10 13:56:56 -0300166
167
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300168- /dev/video48
Hans Verkuila542fe42007-03-10 13:56:56 -0300169
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300170 The raw video display device(s)
171
172 Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
173
174 Writes a YUV stream to the decoder of the card.
Hans Verkuila542fe42007-03-10 13:56:56 -0300175
176
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300177- /dev/radio0
Hans Verkuila542fe42007-03-10 13:56:56 -0300178
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300179 The radio tuner device(s)
180
181 Cannot be read or written.
182
183 Used to enable the radio tuner and tune to a frequency. You cannot
184 read or write audio streams with this device. Once you use this
185 device to tune the radio, use /dev/video24 to read the raw pcm stream
186 or /dev/video0 to get an mpeg2 stream with black video.
Hans Verkuila542fe42007-03-10 13:56:56 -0300187
188
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300189- /dev/vbi0
Hans Verkuila542fe42007-03-10 13:56:56 -0300190
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300191 The 'vertical blank interval' (Teletext, CC, WSS etc) capture device(s)
192
193 Read-only
194
195 Captures the raw (or sliced) video data sent during the Vertical Blank
196 Interval. This data is used to encode teletext, closed captions, VPS,
197 widescreen signalling, electronic program guide information, and other
198 services.
Hans Verkuila542fe42007-03-10 13:56:56 -0300199
200
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300201- /dev/vbi8
Hans Verkuila542fe42007-03-10 13:56:56 -0300202
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300203 Processed vbi feedback device(s)
204
205 Read-only. Only present if the MPEG decoder (i.e. CX23415) exists.
206
207 The sliced VBI data embedded in an MPEG stream is reproduced on this
208 device. So while playing back a recording on /dev/video16, you can
209 read the embedded VBI data from /dev/vbi8.
Hans Verkuila542fe42007-03-10 13:56:56 -0300210
211
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300212- /dev/vbi16
Hans Verkuila542fe42007-03-10 13:56:56 -0300213
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300214 The vbi 'display' device(s)
Hans Verkuila542fe42007-03-10 13:56:56 -0300215
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300216 Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
Hans Verkuila542fe42007-03-10 13:56:56 -0300217
Mauro Carvalho Chehab2a744b02016-07-17 18:13:46 -0300218 Can be used to send sliced VBI data to the video-out connector.