/v4l4j

Video library for Java on Linux

Primary LanguageCGNU General Public License v3.0GPL-3.0

Video4Linux4Java (v4l4j) is an open sourced java package providing a simple interface to capture frames from Video4Linux devices. It consists of:

  • a v4l library (libvideo), which is a C wrapper library around the V4L API,
  • a set of java classes that provide access to the libvideo API, and
  • a JNI stub, which fills in the gap between JAVA and libvideo.

Features

  • Captured frames handed out in a ByteBuffer object. Frames are handed in either in raw format or converted to JPEG, RGB24, BGR24, YUV420 or YVU420.
  • Single frame or stream capture
  • Access to all V4L video source controls, even those accessible only through private ioctls, which are exposed as (pseudo-) controls. See TestedHardware in the libvideo directory for a list of detected drivers and exported private ioctls

Roadmap

  • x264 bindings for H.264-encoding
  • A new encoding API that allows the conversion
  • Increased performance on ARM processors, using SIMD and other features through assembly porting of some key methods
  • Improved documentation

Documentation

The latest version of v4l4j and associated documentation (Howtos, API, ...) can always be found at github.com/mailmindlin/v4l4j.

Quick Start

The following installs the dependencies, compiles & install v4l4j and runs a test application, assuming you are running Ubuntu Lucid or Debian: sudo apt-get install openjdk-8-jdk libjpeg-dev build-essential ant libv4l-dev

If you are running Ubuntu Precise or later: sudo apt-get install openjdk-8-jdk libjpeg-turbo8-dev build-essential ant libv4l-dev

Then:

ant clean all
sudo ant install
ant test-gui

If you want to use v4l4j from your own code, jump to the Installing section.

Requirements

v4l4j requires the following:

  • a supported V4L video source (webcam, capture card, tuner card).
  • Sun JAVA JDK 1.8 or OpenJDK8 (it wont compile with earlier versions).
  • the development files of libjpeg, as well as libjpeg itself. It is recommended to use libjpeg-turbo over libjpeg if possible.
  • libv4lconvert (library and header files), part of the v4l-util suite available from linuxtv.org
  • standard build tools (make, gcc, ld) & headers (libc)
  • Apache Ant

Compiling

To compile v4l4j, run ant all in the top-level directory. This will first compile the libvideo shared library and the JNI library libv4l4j.so. It will then compile the java classes and pack them in a JAR file. Both the JNI library libv4l4j.so and the JAR file v4l4j.jar are copied in the top-level directory. libvideo is NOT copied in the top-level directory and remains in libvideo/ .

Installing

v4l4j can be installed by:

  • running sudo ant install. This will copy libvideo's shared library in /usr/lib , the JNI library libv4l4j.so in /usr/lib/jni and v4l4j's JAR file in /usr/share/java. Any of these paths can be changed by modifying the right property in build.properties .
  • Make sure you run sudo ldconfig so libvideo's shared library is added to the cache.

In order to use the v4l4j package from your own Java application, pass the following arguments to the JVM: -Djava.library.path=/usr/lib/jni -cp /usr/share/java/v4l4j.jar (modify the above values if you have changed the default installation directories).

Testing

In order to use the following example applications, make sure you first install v4l4j (see above section). Many example applications are shipped with v4l4j:

  • ant test-fps simply captures frames for 10 seconds and print the frame rate.
  • ant test-gui displays the video stream & video controls in a window.
  • ant deviceInfo displays information about the video device.
  • ant test-server runs a webcam server. The video stream and control list can be accessed from a web browser (use http://ip_address_of_server:8080), or from ffplay using ffplay -f mjpeg http://ip_address_of_server:8080
  • ant test-dual will only run if you have two video devices connected and will display them side by side in a JFrame.
  • ant test-getsnapshot will take a snapshot from a video device and will display it.

By default, tests will use /dev/video0 (assumed to be a webcam) as the video device, and capture resolution will be set to 640x480. You can change any of these settings by editing the values at the bottom of build.properties, or provide those values on the ant command line (-Dtest.device=..., to change the device file, -Dtest.width=... the change the width, -Dtest.height=... for the height and so on).

Debugging

First, if you have already installed v4l4j (with sudo ant install) then you MUST uninstall it with "sudo ant uninstall", otherwise the previous jar file & libraries (without debug statements) will take precedence over the new ones. Then, compile v4l4j to produce extra debug output, useful to troubleshoot issues, with ant clean all-debug. Install it with sudo ant install.

Contact

Feedback is is greatly appreciated to expand the list of platforms and video devices v4l4j has been successfully tested with. Feedback, issues and queries can be submitted as an issue at https://github.com/mailmindlin/v4l4j/issues.

This library was exported from v4l4j.googlecode.com.