.. highlight:: rst

.. _v4l2caps:

########
v4l2caps
########

**Video for Linux capture plugin**


Description
===========

Video for Linux is a video capture application programming interface(API) and
library for Linux. The library supports many USB web cams, TV tuners as
well as other devices and is the common way to access multimedia devices under
Linux. The v4l2caps plugin uses the Video for Linux API to capture frames from
compatible hardware devices and stores each frame into CAPS.
Available resolutions, pixel formats and other parameters depend on the used
device. See the manual of the hardware manufacturer for more details.
The capture process of the plugin gets a frame in a given sampling interval.
For each frame a new ANY packet is created which uses the sampling time
of the frame as start and end time for the packet. In addition the format of the
packet is set to the selected pixel format. Frame drops may occur when the
storage system is not fast enough to handle incoming data.

Examples
========

To capture 15 images per second (the maximum number of images depends on your hardware) and store the output into CAPS use:

.. code-block:: sh

  $ v4l2caps -s SW.HMA.317.CAM --interval 15/1



Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/v4l2caps.cfg`
| :file:`etc/global.cfg`
| :file:`etc/v4l2caps.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/v4l2caps.cfg`

v4l2caps inherits :ref:`global options<global-configuration>`.

.. note::

   Modules/plugins may require a license file. The default path to license
   files is :file:`@DATADIR@/licenses/` which can be overridden by global
   configuration of the parameter :confval:`gempa.licensePath`. Example: ::

      gempa.licensePath = @CONFIGDIR@/licenses



.. confval:: host

   Type: *string*

   Data output host
   Default is ``localhost``.

.. confval:: port

   Type: *uint*

   Data output host
   Default is ``18003``.

.. confval:: streamID

   Type: *string*

   Stream ID to use, format is [net.sta.loc.cha]


.. confval:: resolution

   Type: *string*

   Resolution to use


.. confval:: outputFormat

   Type: *string*

   Output format to use [rgb, jpg]


.. confval:: outputQuality

   Type: *int*

   Output quality to use [0\-100]
   Default is ``100``.

.. confval:: interval

   Type: *uint*

   Sampling interval to use, format is [Denominator\/Numerator]


.. confval:: pixelFormat

   Type: *string*

   Pixel format to use, expected as four character code[ABCD]


.. confval:: count

   Type: *uint*

   Number of frames to grab
   Default is ``0``.

.. confval:: skip

   Type: *uint*

   Number of frames to skip
   Default is ``0``.

.. confval:: bufferSize

   Type: *uint*

   Size \(bytes\) of the internal buffer to keep still unconfirmed packages
   Default is ``1048576``.

.. confval:: device

   Type: *string*

   Video device name
   Default is ``/dev/video0``.

.. confval:: io

   Type: *uint*

   I\/O method. 0: Use read function, 1: Use memory mapped buffers
   Default is ``1``.


Command-Line Options
====================

.. option:: -b, --buffer-size arg

   Size \(bytes\) of the internal buffer to keep still unconfirmed packages

.. option:: -c, --count arg

   Number of frames to grab

.. option:: --config arg

   Path to configuration file

.. option:: -d, --device arg

   Video device name

.. option:: --dump arg

   Dump output to file

.. option:: -f, --pixel-format arg

   Pixel format to use, expected as four character code[ABCD]

.. option:: -F, --output-format arg

   Output format to use [rgb, jpg]

.. option:: -H, --host arg

   Data output host

.. option:: -h, --help arg

   Print help

.. option:: --info arg

   Print device info

.. option:: -i, --interval arg

   Sampling interval to use, format is [Denominator\/Numerator]

.. option:: --io arg

   I\/O method. 0: Use read function, 1: Use memory mapped buffers [default]

.. option:: -p, --port arg

   Data output port

.. option:: -q, --output-quality arg

   Output quality to use [0\-100]

.. option:: -r, --resolution arg

   Resolution to use

.. option:: -s, --stream-id arg

   Stream ID to use, format is [net.sta.loc.cha]

.. option:: -S, --skip arg

   Number of frames to skip