Documentation/media/v4l-drivers/ivtv.rst

   1
   2 The ivtv driver
   3 ===============
   4
   5 Author: Hans Verkuil <hverkuil@xs4all.nl>
   6
   7 This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
   8 The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
   9 encoding. Currently the only card featuring full decoding support is the
  10 Hauppauge PVR-350.
  11
  12 .. note::
  13
  14    #) This driver requires the latest encoder firmware (version 2.06.039, size
  15       376836 bytes). Get the firmware from here:
  16
  17       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.
  22
  23 The primary goal of the IVTV project is to provide a "clean room" Linux
  24 Open Source driver implementation for video capture cards based on the
  25 iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.
  26
  27 Features
  28 --------
  29
  30  * 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
  40 Additional features for the PVR-350 (CX23415 based)
  41 ---------------------------------------------------
  42
  43  * 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
  47    device)
  48  * Supports raw YUV output.
  49
  50 IMPORTANT: In case of problems first read this page:
  51         https://help.ubuntu.com/community/Install_IVTV_Troubleshooting
  52
  53 See also
  54 --------
  55
  56 https://linuxtv.org
  57
  58 IRC
  59 ---
  60
  61 irc://irc.freenode.net/#v4l
  62
  63 ----------------------------------------------------------
  64
  65 Devices
  66 -------
  67
  68 A maximum of 12 ivtv boards are allowed at the moment.
  69
  70 Cards that don't have a video output capability (i.e. non PVR350 cards)
  71 lack the vbi8, vbi16, video16 and video48 devices. They also do not
  72 support the framebuffer device /dev/fbx for OSD.
  73
  74 The radio0 device may or may not be present, depending on whether the
  75 card has a radio tuner or not.
  76
  77 Here is a list of the base v4l devices:
  78
  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
  90
  91 Base devices
  92 ------------
  93
  94 For 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
  97 - /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)
 100
 101 Note that if the first card doesn't have a feature (eg no decoder, so no
 102 video16, the second card will still use video17. The simple rule is 'add
 103 the card number to the base device number'. If you have other capture
 104 cards (e.g. WinTV PCI) that are detected first, then you have to tell
 105 the ivtv module about it so that it will start counting at 1 (or 2, or
 106 whatever). Otherwise the device numbers can get confusing. The ivtv
 107 'ivtv_first_minor' module option can be used for that.
 108
 109
 110 - /dev/video0
 111
 112   The encoding capture device(s).
 113
 114   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)
 122
 123
 124 - /dev/video16
 125
 126   The decoder output device(s)
 127
 128   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
 137
 138
 139 - /dev/video24
 140
 141   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.
 152
 153
 154 - /dev/video32
 155
 156   The raw video capture device(s)
 157
 158   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.
 165
 166
 167 - /dev/video48
 168
 169   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.
 174
 175
 176 - /dev/radio0
 177
 178   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.
 186
 187
 188 - /dev/vbi0
 189
 190   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.
 198
 199
 200 - /dev/vbi8
 201
 202   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.
 209
 210
 211 - /dev/vbi16
 212
 213   The vbi 'display' device(s)
 214
 215   Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
 216
 217   Can be used to send sliced VBI data to the video-out connector.