Documentation/media/v4l-drivers/ivtv.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 The ivtv driver
   4 ===============
   5
   6 Author: Hans Verkuil <hverkuil@xs4all.nl>
   7
   8 This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
   9 The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
  10 encoding. Currently the only card featuring full decoding support is the
  11 Hauppauge 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
  24 The primary goal of the IVTV project is to provide a "clean room" Linux
  25 Open Source driver implementation for video capture cards based on the
  26 iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.
  27
  28 Features
  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
  41 Additional 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
  51 IMPORTANT: In case of problems first read this page:
  52         https://help.ubuntu.com/community/Install_IVTV_Troubleshooting
  53
  54 See also
  55 --------
  56
  57 https://linuxtv.org
  58
  59 IRC
  60 ---
  61
  62 irc://irc.freenode.net/#v4l
  63
  64 ----------------------------------------------------------
  65
  66 Devices
  67 -------
  68
  69 A maximum of 12 ivtv boards are allowed at the moment.
  70
  71 Cards that don't have a video output capability (i.e. non PVR350 cards)
  72 lack the vbi8, vbi16, video16 and video48 devices. They also do not
  73 support the framebuffer device /dev/fbx for OSD.
  74
  75 The radio0 device may or may not be present, depending on whether the
  76 card has a radio tuner or not.
  77
  78 Here 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
  92 Base devices
  93 ------------
  94
  95 For 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
 102 Note that if the first card doesn't have a feature (eg no decoder, so no
 103 video16, the second card will still use video17. The simple rule is 'add
 104 the card number to the base device number'. If you have other capture
 105 cards (e.g. WinTV PCI) that are detected first, then you have to tell
 106 the ivtv module about it so that it will start counting at 1 (or 2, or
 107 whatever). 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 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.
 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.