ivtv.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3The ivtv driver
  4===============
  5
  6Author: Hans Verkuil <hverkuil@kernel.org>
  7
  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
 13.. note::
 14
 15   #) This driver requires the latest encoder firmware (version 2.06.039, size
 16      376836 bytes). Get the firmware from here:
 17
 18      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.
 23
 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
 28Features
 29--------
 30
 31 * 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
 41Additional features for the PVR-350 (CX23415 based)
 42---------------------------------------------------
 43
 44 * 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
 48   device)
 49 * Supports raw YUV output.
 50
 51IMPORTANT: In case of problems first read this page:
 52	https://help.ubuntu.com/community/Install_IVTV_Troubleshooting
 53
 54See also
 55--------
 56
 57https://linuxtv.org
 58
 59IRC
 60---
 61
 62irc://irc.freenode.net/#v4l
 63
 64----------------------------------------------------------
 65
 66Devices
 67-------
 68
 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:
 79
 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
 91
 92Base devices
 93------------
 94
 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
 98- /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)
101
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
111- /dev/video0
112
113  The encoding capture device(s).
114
115  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)
123
124
125- /dev/video16
126
127  The decoder output device(s)
128
129  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
138
139
140- /dev/video24
141
142  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.
153
154
155- /dev/video32
156
157  The raw video capture device(s)
158
159  Read-only
160
161  The raw YUV video output from the current video input. The YUV format
162  is a 16x16 linear tiled NV12 format (V4L2_PIX_FMT_NV12_16L16)
163
164  Note that the YUV and PCM streams are not synchronized, so they are of
165  limited use.
166
167
168- /dev/video48
169
170  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.
175
176
177- /dev/radio0
178
179  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.
187
188
189- /dev/vbi0
190
191  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.
199
200
201- /dev/vbi8
202
203  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.
210
211
212- /dev/vbi16
213
214  The vbi 'display' device(s)
215
216  Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
217
218  Can be used to send sliced VBI data to the video-out connector.