1# v4l-utils 2 3Linux utilities and libraries to handle media devices (TV devices, capture 4devices, radio devices, remote controllers). 5 6You can always find the latest development v4l-utils in the git repo: 7[http://git.linuxtv.org/v4l-utils.git](http://git.linuxtv.org/v4l-utils.git). 8 9Those utilities follow the latest Linux Kernel media API, as documented at: 10[http://linuxtv.org/downloads/v4l-dvb-apis/](http://linuxtv.org/downloads/v4l-dvb-apis/). 11 12Any questions/remarks/patches can be sent to the linux-media mailinglist. See 13[https://linuxtv.org/lists.php](https://linuxtv.org/lists.php) for more 14information about the mailinglist. 15 16There is also a wiki page for the v4l-utils: 17[https://linuxtv.org/wiki/index.php/V4l-utils](https://linuxtv.org/wiki/index.php/V4l-utils). 18 19## Building 20 21v4l-utils uses the meson build system. 22 23A number of packages is required to fully build v4l-utils. The first step is to 24install those packages. The package names are different on each distro. 25 26On Debian and derivated distributions, you need to install the following 27packages with `apt-get` or `aptitude`: 28 29``` 30debhelper doxygen gcc git graphviz libasound2-dev libjpeg-dev 31libqt5opengl5-dev libudev-dev libx11-dev meson pkg-config 32qtbase5-dev udev libsdl2-dev libbpf-dev llvm clang 33``` 34 35On Fedora, the package list for a minimal install with `dnf` or `yum` is: 36 37``` 38gcc gcc-c++ gettext-devel git meson perl which 39``` 40 41(git is only requiried if you're cloning from the main git repository at 42linuxtv.org). 43 44And, to be able to compile it with all usual functionality with qt5, you'll need 45also: 46 47``` 48alsa-lib-devel doxygen libjpeg-turbo-devel qt5-qtbase-devel libudev-devel 49mesa-libGLU-devel 50``` 51 52The v4l2-tracer also needs the json-c library. On Debian: `libjson-c-dev' ; on 53Fedora: `json-c-devel`. 54 55After downloading and installing the needed packages on your distribution, you 56should run: 57 58``` 59meson build/ 60ninja -C build/ 61``` 62 63And, to install on your system: 64 65``` 66sudo ninja -C build/ install 67``` 68 69### Optional features 70 71Please notice that there's an extra feature to add an extra table to decode 72Japanese DVB tables via iconv. This is meant to be used when the iconv itself 73doesn't come with the *ARIB-STD-B24* and *EN300-468-TAB00* tables. 74 75gconv is an auto feature, so it will be auto-enabled in case the dependencies 76are satisfied. However, the gconv feature can be forced to enabled by running 77the following command during configuration step: 78 79``` 80meson configure -Dgconv=enabled build/ 81``` 82 83## Versioning 84 85The v4l-utils doesn't quite follow the release versioning defined at 86[semver.org](https://semver.org/). 87 88Instead, since version 1.0, it uses `MAJOR.MINOR.PATCH`. Where: 89 90* `MINOR` - an odd number means a development version. When the development is 91closed, we release an even numbered version and start a newer odd version; 92 93* `MAJOR` - It is incremented when `MINOR` number starts to be too big. The last 94change occurred from 0.9.x to 1.0. 95 96* All numbers start with 0. 97 98All versions have their own tags, except for the current development version 99(with uses the master branch at the git tree). 100 101The `PATCH` meaning actually depends if the version is stable or development. 102 103* For even `MAJOR.MINOR` versions (1.0, 1.2, 1.4, 1.6, ...): `PATCH` is 104incremented when just bug fixes are added; 105 106* For odd `MAJOR.MINOR` versions (1.1, 1.3, 1.5, 1.7, ...): `PATCH` is 107incremented for release candidate versions. 108 109### API/ABI stability: 110 111There should not have any API/ABI changes when `PATCH` is incremented. 112 113When `MAJOR` and/or `MINOR` are incremented, the API/ABI for the libraries might 114change, although we do all the efforts for not doing it, except when inevitable. 115 116The `TODO` files should specify the events that will generate API/ABI breaks. 117 118## Media libraries 119 120There are currently three media libraries defined at `lib/` directory, meant to 121be used internally and by other applications. 122 123### libv4l 124 125This library is meant to be used by applications that need to talk with V4L2 126devices (webcams, analog TV, stream grabbers). 127 128It can be found on the following directories: 129 130``` 131lib/libv4l1/ 132lib/libv4l2/ 133lib/libv4l-mplane/ 134lib/libv4lconvert/ 135``` 136 137See `README.libv4l` for more information on libv4l. 138 139The libv4l is released under the GNU Lesser General Public License. 140 141### libdvbv5 142 143This library is meant to be used by digital TV applications that need to talk 144with media hardware. 145 146Full documentation is provided via Doxygen. Building documentation is enabled 147by the auto feature: `doxygen-doc`. If enabled, it will be built within the 148project. 149 150It is possible to generate documentation in html, man pages and pdf formats. 151 152The documentation is also available via web, at: 153[http://linuxtv.org/docs/libdvbv5/](http://linuxtv.org/docs/libdvbv5/). 154 155It can be found on the following directory `lib/libdvbv5/`. 156 157The libdvbv5 is released under GPL version 2. 158 159### libv4l2rds 160 161This library provides support for RDS radio applications. 162 163It can be found on the following directory `lib/libv4l2rds/`. 164 165The libv4l is released under the GNU Lesser General Public License. 166 167## Utilities 168 169The utilities are stored under `utils/` directory. 170 171The (for now for v4l-utils private use only) libv4l2util library is released 172under the GNU Lesser General Public License, all other code is released under 173the GNU General Public License. 174 175v4l-utils includes the following utilities: 176 177### decode\_tm6000 178 179Decodes tm6000 proprietary format streams. 180 181Installed under `<prefix>/bin`. 182 183### ir-keytable 184 185Dump, Load or Modify ir receiver input tables. The ir tables for remotes which 186are known by the kernel (and loaded by default depending on dvb card type) can 187be found under `utils/keytable/keycodes`. 188 189v4l-keytable does not get installed during the install step. 190 191### ir-ctl 192 193A swiss-knife tool to handle raw IR and to set lirc options. 194 195### qv4l2 196 197QT v4l2 control panel application. 198 199Installed under `<prefix>/bin`. 200 201### rds-saa6588 202 203Poll i2c RDS receiver [Philips saa6588]. 204 205rds-saa6588 does not get installed during the install step. 206 207### v4l2-compliance 208 209Tool to test v4l2 API compliance of drivers. 210 211Installed under `<prefix>/bin`. 212 213### v4l2-ctl 214 215Tool to control v4l2 controls from the cmdline. 216 217Installed under `<prefix>/bin`. 218 219### v4l2-dbg 220 221Tool to directly get and set registers of v4l2 devices, this requires a 222*kernel >= 2.6.29* with the `ADV_DEBUG` option enabled. This tool can only be 223used by root and is meant for development purposes only! 224 225Installed under `<prefix>/sbin`. 226 227### v4l2-sysfs-path 228 229*FIXME* add description. 230 231Installed under `<prefix>/bin`. 232 233### v4l2-tracer 234 235Tool to trace, record and replay userspace applications that implement the v4l2 236memory-to-memory stateless video decoder interface. 237 238Installed by `make install` under `<prefix>/bin`. 239 240### xc3028-firmware 241 242Xceive XC2028/3028 tuner module firmware manipulation tool. 243 244xc3028-firmware does not get installed during the install step. 245 246## Syncing with Kernel 247 248There are a number of files on this package that depends on the Linux Kernel. 249 250In order to make easier to keep it in sync, there's a target on this package to 251do the synchronism. 252 253For the sync to work, you need to run it on with 64 bits userspace and be sure 254that glibc has the development package for 32 bits. 255 256For Fedora, this is provided via this package: *glibc-devel.i686* 257 258There are some steps required: 259 2601. At the Kernel git tree: 261 262 We need to sanitize the headers to be installed. To do that, you should run: 263 264 ``` 265 make headers_install INSTALL_HDR_PATH=usr/ 266 ``` 267 268 This will create the dir `usr/` inside the Kernel tree. 269 2701. Be sure that you have installed both glibc development packages for 32 and 64 271bits, as otherwise the next step will fail. 272 2731. At v4l-utils tree: 274 275 ``` 276 ./sync-with-kernel.sh location/of/the/kernel/tree 277 ``` 278 279 Alternatively, steps 1 to 3 can be replaced with: 280 281 ``` 282 KERNEL_DIR=location/of/the/kernel/tree && (cd $KERNEL_DIR && make headers_install INSTALL_HDR_PATH=usr/) && ./sync-with-kernel.sh $KERNEL_DIR 283 ``` 284 2851. Remove the `usr/` from the Kernel tree. 286