source: multimedia/libdriv/v4l-utils.xml@ 418e7853

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY v4l-download-http "https://www.linuxtv.org/downloads/v4l-utils/v4l-utils-&v4l-utils-version;.tar.xz">
  <!ENTITY v4l-download-ftp  " ">
  <!ENTITY v4l-md5sum        "6716de513a1fd2e1edb404a46a455855">
  <!ENTITY v4l-size          "1.2 MB">
  <!ENTITY v4l-buildsize     "34 MB">
  <!ENTITY v4l-time          "0.4 SBU (using parallelism=4)">
]>

<sect1 id="v4l-utils" xreflabel="v4l-utils-&v4l-utils-version;">
  <?dbhtml filename="v4l-utils.html" ?>


  <title>v4l-utils-&v4l-utils-version;</title>

  <indexterm zone="v4l-utils">
    <primary sortas="a-v4l-utils">v4l-utils</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to v4l-utils</title>

    <para>
      <application>v4l-utils</application> provides a series of utilities for
      media devices, allowing the ability to handle the proprietary formats 
      available from most webcams (libv4l), and providing tools to test V4L devices.
    </para>

    &lfs122_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&v4l-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&v4l-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &v4l-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &v4l-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &v4l-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &v4l-time;
        </para>
      </listitem>
    </itemizedlist>
<!--
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist>
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/v4l-utils-&v4l-utils-version;-upstream_fixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->
    <bridgehead renderas="sect3">v4l-utils Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="alsa-lib"/>,
      <xref linkend="glu"/>, and
      <xref linkend="libjpeg"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="doxygen"/>,
      <xref linkend="qt6"/> (for qv4l2 and qvidcap),
      <xref linkend="sdl2"/>,
      both <xref linkend="llvm"/> (with Clang and target BPF)
      and <ulink url='https://github.com/libbpf/libbpf'>libbpf</ulink>
      (for infrared remote control decoders based on BPF), and
      <ulink url="https://github.com/libsdl-org/SDL_image">SDL_image</ulink>
    </para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of v4l-utils</title>

    <note>
      <para>
        If you've installed both LLVM and libbpf (not in BLFS), either
        enable the BPF target (via
        <option>-D LLVM_TARGETS_TO_BUILD=</option>) when building LLVM, or
        disable the infrared remote control decoders based on BPF:
      </para>

      <!-- not "nodump" because it's harmless for BLFS anyway -->
      <screen><userinput>sed -i '/^ir_bpf_enabled/s/=.*/= false/' utils/keytable/meson.build</userinput></screen>
    </note>

    <para>
      Install <application>v4l-utils</application> by running
      the following commands:
    </para>

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup ..            \
      --prefix=/usr       \
      --buildtype=release \
      -D gconv=disabled   \
      -D doxygen-doc=disabled &amp;&amp;
ninja</userinput></screen>

    <para>
      This package does not come with a test suite.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>ninja install</userinput></screen>

    <para>
      If you also wish to install the contrib programs, add:
    </para>

<screen role="root"><userinput>for prog in v4l2gl v4l2grab
do
   cp -v contrib/test/$prog /usr/bin
done</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <!-- Please do NOT touch this unless you've tried a DESTDIR installation
         and you really understand what will be going on:

         Without this option the package will overwrite
         /usr/lib/gconv/gconv-modules which is a part of the **Glibc**
         installation and break iconv (both the command iconv(1) and the
         Glibc function iconv(3)).  Then some BLFS packages will FTBFS or
         fail a dozen of tests etc.

         Already reported as https://lore.kernel.org/linux-media/3ffb1568a9ff6c0b6f5424de3a0fafb24e7b3ac0.camel@xry111.site/.

         Debian and Gentoo also have -D gconv=disabled.  Fedora manually
         moves the gconv-modules file in a DESTDIR installation.  IMO it's
         completely stupid to have an installation conflicting with Glibc in
         the default configuration, but they just completely ignore my
         report and rely on the distro maintainers to resolve the issue,
         even without mentioning the conflict in README.md, nor INSTALL.md.
         This is the worst upstream behavior I've ever seen.  -->
    <para>
      <parameter>-D gconv=disabled</parameter>: This switch disables
      the erroneous installation of gconv-modules that would break glibc.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          cec-compliance,
          cec-ctl,
          cec-follower,
          cx18-ctl,
          decode_tm6000,
          dvb-fe-tool,
          dvb-format-convert,
          dvbv5-daemon,
          dvbv5-scan,
          dvbv5-zap,
          ir-ctl,
          ir-keytable,
          ivtv-ctl,
          media-ctl,
          qv4l2,
          qvidcap,
          rds-ctl,
          v4l2-compliance,
          v4l2-ctl,
          v4l2-dbg,
          v4l2gl,
          v4l2grab, and
          v4l2-sysfs-path
        </seg>
        <seg>
          libdvbv5.so,
          libv4l1.so,
          libv4l2.so,
          libv4l2rds.so,
          libv4lconvert.so,
          v4l1compat.so, and
          v4l2convert.so
        </seg>
        <seg>
          /etc/rc_keymaps,
          /lib/udev/rc_keymaps,
          /usr/include/libdvbv5, and
          /usr/lib/libv4l
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="cx18-ctl">
        <term><command>cx18-ctl</command></term>
        <listitem>
          <para>
            is a tool to handle cx18 based devices
          </para>
          <indexterm zone="v4l-utils cx18-ctl">
            <primary sortas="b-cx18-ctl">cx18-ctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="decode_tm6000">
        <term><command>decode_tm6000</command></term>
        <listitem>
          <para>
            decodes multiplexed formats from TM5600/TM6000 USB devices
          </para>
          <indexterm zone="v4l-utils decode_tm6000">
            <primary sortas="b-decode_tm6000">decode_tm6000</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dvb-fe-tool">
        <term><command>dvb-fe-tool</command></term>
        <listitem>
          <para>
            is a command line tool for digital TV services
          </para>
          <indexterm zone="v4l-utils dvb-fe-tool">
            <primary sortas="b-dvb-fe-tool">dvb-fe-tool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dvb-format-convert">
        <term><command>dvb-format-convert</command></term>
        <listitem>
          <para>
            is a tool meant to convert among different file formats.  It is
            compliant with version 5 of the DVB API
          </para>
          <indexterm zone="v4l-utils dvb-format-convert">
            <primary sortas="b-dvb-format-convert">dvb-format-convert</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dvbv5-scan">
        <term><command>dvbv5-scan</command></term>
        <listitem>
          <para>
            is a command line frequency scanning tool for digital TV
            services that are compliant with version 5 of the DVB API
          </para>
          <indexterm zone="v4l-utils dvbv5-scan">
            <primary sortas="b-dvbv5-scan">dvbv5-scan</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dvbv5-zap">
        <term><command>dvbv5-zap</command></term>
        <listitem>
          <para>
            is a command line tuning tool for digital TV services
            that is compliant with version 5 of the DVB API
          </para>
          <indexterm zone="v4l-utils dvbv5-zap">
            <primary sortas="b-dvbv5-zap">dvbv5-zap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ir-keytable">
        <term><command>ir-keytable</command></term>
        <listitem>
          <para>
            is a tool that lists the Remote Controller devices, allows one
            to get/set IR keycode/scancode tables, test events generated by
            IR, and to adjust other Remote Controller options
          </para>
          <indexterm zone="v4l-utils ir-keytable">
            <primary sortas="b-ir-keytable">ir-keytable</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ivtv-ctl">
        <term><command>ivtv-ctl</command></term>
        <listitem>
          <para>
            is a utility that can control many card settings, like changing
            the inputs from tuner to svideo or composite, setting video
            resolution or changing video mode (PAL, SECAM, NTSC)
          </para>
          <indexterm zone="v4l-utils ivtv-ctl">
            <primary sortas="b-ivtv-ctl">ivtv-ctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="media-ctl">
        <term><command>media-ctl</command></term>
        <listitem>
          <para>
            is a utility used to configure V4L2 devices
          </para>
          <indexterm zone="v4l-utils media-ctl">
            <primary sortas="b-media-ctl">media-ctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qv4l2">
        <term><command>qv4l2</command></term>
        <listitem>
          <para>
            is used to test video4linux capture devices
          </para>
          <indexterm zone="v4l-utils qv4l2">
            <primary sortas="b-qv4l2">qv4l2</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qvidcap">
        <term><command>qvidcap</command></term>
        <listitem>
          <para>
            is used to capture video from a V4L2 device
          </para>
          <indexterm zone="v4l-utils qvidcap">
            <primary sortas="b-qvidcap">qvidcap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rds-ctl">
        <term><command>rds-ctl</command></term>
        <listitem>
          <para>
            is a utility for decoding raw RDS data from V4L2 Radio devices
            and offers simple ways to access the received RDS information
          </para>
          <indexterm zone="v4l-utils rds-ctl">
            <primary sortas="b-rds-ctl">rds-ctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="v4l2-compliance">
        <term><command>v4l2-compliance</command></term>
        <listitem>
          <para>
            is a compliance test tool
          </para>
          <indexterm zone="v4l-utils v4l2-compliance">
            <primary sortas="b-v4l2-compliance">v4l2-compliance</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="v4l2-ctl">
        <term><command>v4l2-ctl</command></term>
        <listitem>
          <para>
            is a tool to control v4l2 controls from the cmdline
          </para>
          <indexterm zone="v4l-utils v4l2-ctl">
            <primary sortas="b-v4l2-ctl">v4l2-ctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="v4l2-dbg">
        <term><command>v4l2-dbg</command></term>
        <listitem>
          <para>
            is a tool to directly get and set registers of v4l2 devices
          </para>
          <indexterm zone="v4l-utils v4l2-dbg">
            <primary sortas="b-v4l2-dbg">v4l2-dbg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="v4l2gl">
        <term><command>v4l2gl</command></term>
        <listitem>
          <para>
            captures images using libv4l and stores them as PPM files
          </para>
          <indexterm zone="v4l-utils v4l2gl">
            <primary sortas="b-v4l2gl">v4l2gl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="v4l2grab">
        <term><command>v4l2grab</command></term>
        <listitem>
          <para>
            captures images using libv4l and stores them as PPM files, while
            also allowing for additional options such as setting the amount of
            frames captured and saving the file as a RAW file
          </para>
          <indexterm zone="v4l-utils v4l2grab">
            <primary sortas="b-v4l2grab">v4l2grab</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="v4l2-sysfs-path">
        <term><command>v4l2-sysfs-path</command></term>
        <listitem>
          <para>
            checks the media devices installed on a machine and the
            corresponding device nodes
          </para>
          <indexterm zone="v4l-utils v4l2-sysfs-path">
            <primary sortas="b-v4l2-sysfs-path">v4l2-sysfs-path</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>