VBI is an abbreviation of Vertical Blanking Interval, a gap in the sequence of lines of an analog video signal. During VBI no picture information is transmitted, allowing some time while the electron beam of a cathode ray tube TV returns to the top of the screen. Using an oscilloscope you will find here the vertical synchronization pulses and short data packages ASK modulated onto the video signal. These are transmissions of services such as Teletext or Closed Caption.
Subject of this interface type is raw VBI data, as sampled off a video signal, or to be added to a signal for output. The data format is similar to uncompressed video images, a number of lines times a number of samples per line, we call this a VBI image.
Conventionally V4L2 VBI devices are accessed through character
device special files named
major number 81 and minor numbers 224 to 255.
/dev/vbi is typically a symbolic link to the
preferred VBI device. This convention applies to both input and output
To address the problems of finding related video and VBI
devices VBI capturing and output is also available as device function
/dev/video. To capture or output raw VBI
data with these devices applications must call the
ioctl. Accessed as
/dev/vbi, raw VBI capturing
or output is the default device function.
Devices supporting the raw VBI capturing or output API set
V4L2_CAP_VBI_OUTPUT flags, respectively, in the
capabilities field of struct v4l2_capability
returned by the
VIDIOC_QUERYCAP ioctl. At least one of the
read/write, streaming or asynchronous I/O methods must be
supported. VBI devices may or may not have a tuner or modulator.
VBI devices shall support video input or output, tuner or modulator, and controls ioctls as needed. The video standard ioctls provide information vital to program a VBI device, therefore must be supported.
Raw VBI sampling abilities can vary, in particular the sampling frequency. To properly interpret the data V4L2 specifies an ioctl to query the sampling parameters. Moreover, to allow for some flexibility applications can also suggest different parameters.
As usual these parameters are not
open() time to permit Unix tool chains, programming a
device and then reading from it as if it was a plain file. Well
written V4L2 applications should always ensure they really get what
they want, requesting reasonable parameters and then checking if the
actual parameters are suitable.
To query the current raw VBI capture parameters
applications set the
type field of a
struct v4l2_format to
V4L2_BUF_TYPE_VBI_OUTPUT, and call the
VIDIOC_G_FMT ioctl with a pointer to this structure. Drivers fill
the struct v4l2_vbi_format
vbi member of the
To request different parameters applications set the
type field of a struct v4l2_format as above and
initialize all fields of the struct v4l2_vbi_format
vbi member of the
fmt union, or better just modify the
VIDIOC_G_FMT, and call the
VIDIOC_S_FMT ioctl with a pointer to this structure. Drivers return
an EINVAL error code only when the given parameters are ambiguous, otherwise
they modify the parameters according to the hardware capabilities and
return the actual parameters. When the driver allocates resources at
this point, it may return an EBUSY error code to indicate the returned
parameters are valid but the required resources are currently not
available. That may happen for instance when the video and VBI areas
to capture would overlap, or when the driver supports multiple opens
and another process already requested VBI capturing or output. Anyway,
applications must expect other resource allocation points which may
return EBUSY, at the
and the first read(), write() and select() call.
VBI devices must implement both the
VIDIOC_S_FMT ioctl, even if
VIDIOC_S_FMT ignores all requests and always
returns default parameters as
VIDIOC_TRY_FMT is optional.
Table 4.4. struct v4l2_vbi_format
|__u32||Samples per second, i. e. unit 1 Hz.|
Horizontal offset of the VBI image,
relative to the leading edge of the line synchronization pulse and
counted in samples: The first sample in the VBI image will be located
Defines the sample format as in Chapter 2, Image Formats, a four-character-code.[a] Usually this is
|__u32||This is the scanning system line number
associated with the first line of the VBI image, of the first and the
second field respectively. See Figure 4.2, “ITU-R 525 line numbering (M/NTSC and M/PAL)” and
Figure 4.3, “ITU-R 625 line numbering” for valid values.
|__u32||The number of lines in the first and second field image, respectively.|
Drivers should be as flexibility as possible. For example, it may be possible to extend or move the VBI capture window down to the picture area, implementing a 'full field mode' to capture data service transmissions embedded in the picture.
An application can set the first or second
To initialize the
|__u32||See Table 4.5, “Raw VBI Format Flags” below. Currently only drivers set flags, applications must set this field to zero.|
|__u32||This array is reserved for future extensions. Drivers and applications must set it to zero.|
[a] A few devices may be unable to sample VBI data at all but can extend the video capture window to the VBI region.
Table 4.5. Raw VBI Format Flags
This flag indicates hardware which does not properly distinguish between fields. Normally the VBI image stores the first field (lower scanning line numbers) first in memory. This may be a top or bottom field depending on the video standard. When this flag is set the first or second field may be stored first, however the fields are still in correct temporal order with the older field first in memory.[a]
|0x0002||By default the two field images will be passed
sequentially; all lines of the first field followed by all lines of
the second field (compare the section called “Field Order”
[a] Most VBI services transmit on both fields, but
some have different semantics depending on the field number. These
cannot be reliable decoded or encoded when
Remember the VBI image format depends on the selected video standard, therefore the application must choose a new standard or query the current standard first. Attempts to read or write data ahead of format negotiation, or after switching the video standard which may invalidate the negotiated VBI parameters, should be refused by the driver. A format change during active I/O is not permitted.
To assure synchronization with the field number and easier implementation, the smallest unit of data passed at a time is one frame, consisting of two fields of VBI images immediately following in memory.
The total size of a frame computes as follows:
samples_per_line* sample size in bytes
The sample size is most likely always one byte,
applications must check the
field though, to function properly with other drivers.
VIDIOC_STREAMON ioctl and the first read(),
write() and select() call can be resource allocation points returning
an EBUSY error code if the required hardware resources are temporarily
unavailable, for example the device is already in use by another
 ASK: Amplitude-Shift Keying. A high signal level represents a '1' bit, a low level a '0' bit.