JxCapture 3 Programmer's Guide


Version: 3.4
Last Updated: August 25, 2016

Chapter 1. Introduction


JxCapture 3 is a cross-platform* library that provides a comprehensive screen capture API for Java applications.

The JxCapture 3 distribution contains code samples demonstrating some API features and a demo application (JxCapture 3 Demo) allowing you to easily capture whatever you want on the screen in many different ways, including:

  • full-screen capture (available on multiple monitors)

  • active window capture

  • capture hidden/offscreen windows (available for Windows platform)

  • rectangular region capture

  • inclusion of the mouse pointer to the capture

* - The current version of JxCapture 3 supports Windows and Mac OS X platforms. Support for more platforms is considered.

1.1. About this Guide

This guide introduces JxCapture 3, describes its architecture, concepts and principles, requirements for using the product as well as provides sufficient information you need to know to start working with JxCapture 3.

This document covers all platform versions of JxCapture 3. In cases where functions treat a particular platform in a specific way, or specific configuration settings are needed, these are marked accordingly.

1.2. About JxCapture 3

JxCapture 3 is a cross-platform library that provides a comprehensive screen capture API for Java applications. It allows to capture any graphic element on a screen, whether an entire window or just a single object on it, and then save the resulting capture objecet as image file, or covert it to Java BufferedImage object.

Apart from image capturing, new JxCapture 3 also intoduces ability to record video screen capture to different video formats, depending on a runing platforms. Audio also can be recored from any audio recording device available in a system.

Chapter 2. Getting Started


2.1. System Requirements

The following are general requirements for running JxCapture 3 on the following supported platforms:

JxCapture System Requirements

There are no any specific memory or hardware requirements for developing an application based on JxCapture 3.

2.2. Package Contents

The JxCapture 3 package consists of the following files:

  • JxCapture 3 library - jxcapture-3.x.jar

  • JNIWrapper 3 library - jniwrap-3.x.jar

  • SLF4J logging facade - ( slf4j-api-1.5.8.jar andslf4j-simple-1.5.8.jar)

All the files need to be placed in appropriate locations. Please see the section "Configuring JxCapture 3" for more details about the product installation instructions. The package may also contain other files providing some useful information for you, for example the Readme.txt file.

Chapter 3. Configuring JxCapture 3


3.1. Library JAR Files

All these JxCapture 3 libraries must be included to a Java application class path.

3.2. JxCapture 3 License Files

When you purchase a license file, you get two JARs: development.jar and runtime.jar. You just need to include one of these JAR into your application class path.

You need to use the development.jar to use JxCapture for development purposes.

The runtime.jar should be used when you distribute your software with JxCapture enclosed. For example you can include runtime.jar into class path of your application production version.

Chapter 4. JxCapture 3 Architecture


The JxCapture 3 library constits of two base classes: ImageCapture abstract class and itsimplementation, and new VideoCapture class and its implementaitons for different plafroms.

Both these classes provide appropritate factory methods.

Chapter 5. Image Capturing in JxCapture 3


In second version of JxCapture, the API of the product has been changed significantly. Basically the API was simplified, clarified and made more convenient comparing to previous version. However main functionality of JxCapture still remains the same: it is designed for making snapshots. The detailed information about new featues and abilities is described below.

The process of making image snapshots now consists of four main steps:

  • Create an ImageCapture object for a required capture area:

    
                            ImageCapture imageCapture = ImageCapture.create(new CaptureArea.FullScreen());
                            

  • Taking a snapshot:

    
                            imageCapture.takeSnapshot();
                            

  • Processing image capture, for example saving the snapthot to a file:

    
                            imageCapture.save(new File("FullScreen.jpg"), ImageFormat.JPEG);
                            

  • And finally releasing the snapshot memory:

    
                            imageCapture.release();
                            

Before saving image capture to a file, it can be resized to the required dimensions, which may be quite useful, for instance, when you need to create a thumbnail image:


                imageCapture.resize(new Dimensions(320, 240));
            

5.1. Capture Areas in JxCapture 3

JxCapture 3 provides following areas for image cpaturing:

  • FullScreen - can be used for full sreen Image and Video capturing on multiple monitors configuration;

  • Desktop - can be used when Image or Video capture must be taken from a particular desktop;

  • Rect - can be used to specify a particular rectangular area for capturing;

  • WindowRect - can be used to specify a particular window or its rectangular area for capturing;

5.2. Supported Image Formats

JxCapture 3 supports several image formats which can be used during saving image capture object to a file. Supported image formats are defined in ImageFormat class:

  • PNG

  • JPEG

  • GIF

  • BMP

One of these formats can be specified in the ImageCapture.save(File, ImageFormat) method to convert image capture object to the appropriate image format:


                    imageCapture.save(new File("FileName.png"), ImageFormat.PNG);
                

5.3. Image interpolation modes

JxCapture 3 API supports following interpolation modes which are defined in InterpolationMode class:

  • Bilinear

  • Bicubic

  • NearestNeighbor

  • HighQualityBilinear

  • HighQualityBicubic

One of these interpolation modes can be used for resizing of image capture object by the ImageCapture.resize(Dimension, InterpolationMode) method to resize image capture to the required dimensions:


                    imageCapture.resize(new Dimension(640, 480), InterpolationMode.HighQualityBilinear);
                

5.4. Basic Image Capture

The following example demonstrates how to capture desktop capture and save it to a file in PNG format:


                ImageCapture imageCapture = ImageCapture.create(new CaptureArea.Desktop());
                imageCapture.takeSnapshot().save(new File("Desktop.png"), ImageFormat.PNG);
                imageCapture.release();
            

If you need to capture an active window, use WindowManager class to find the required window first:


                WindowManager windowManager = WindowManager.getInstance();
                Window notepad = (Window) windowManager.findWindow("Untitled - Notepad");
                if (notepad == null) {
                throw new RuntimeException("Notepad window was not found");
                }
                // Capturing 640x480 rectangular area of a requied window
                ImageCapture imageCapture = ImageCapture.create(new CaptureArea.WindowRect(notepad, new Dimension(640,
                480)));
                imageCapture.takeSnapshot().save(new File("Notepad.jpg"), ImageFormat.JPEG, CompressionQuality.BEST);
                imageCapture.release();
            

5.5. Advanced Image Capture

Sometimes it's required to capture only a particular rectangular screen area. In such cases the appropriate captrure area object instance should be created:


                ImageCapture imageCapture = ImageCapture.create(new CaptureArea.Rect(0, 0, 800, 600));
            

After taking a snapshot you can perform the following operations with it:

  • Save snapshot to a file specifying file name and image format::

    
                            imageCapture.save(new File("Result.png"), ImageFormat.PNG);
                            

  • Copy snapshot to system clipboard

    
                            imageCapture.copyToClipboard();
                            

  • Or convert this snapshot to a Java BufferedImageobject:

    
                            BufferedImage image = imageCapture.getImage();
                            

The image capture object can also be resized to a requreied dimensions using various InterpolationMode's. Such ability can be used when you need, for instance, to create an image thumbnail, for example:


                imageCapture.resize(new Dimension(320, 240));
                // OR
                imageCapture.resize(new Dimension(320, 240), InterpolationMode.HighQualityBilinear);
            

And finally each unused image capture object must be released explicitly with its release() method:


                imageCapture.release();
            

Chapter 6. Video Capture in JxCapture


Information about using various Video capture modes is given below.

6.1. Video Capture Formats

For each supported platform JxCapture 3 provides support of its native video formats. For Windows systems it'sWMV, for Mac OS X -MP4. For Windows systems JxCapture also provides the ability to create video capture in AVI formts. All supported video formats are defined in VideoFormat class:

  • WMV - supported on Windows platforms

  • AVI - supported on Windows platforms

  • MP4 - supported on Mac OS X platforms

To create a video capture object for a required video format you can use the appropriate VideoCapture.create(VideoFormat) factory method, for example:

                    VideoCapture videoCapture = VideoCapture.create(VideoFormat.WMV);
                
If there is no appropritate video capture objects available for the specified video format - the appropriate exception will be thrown.

6.2. Configuring Video Capture

Simple capture operations do not require user interaction and are intended to capture a specified area on the screen, such as full screen or an active window.

The following sample demonstrates how you can create a platform specific full screen video capture:


                // Create a platform depended video capture
                VideoCapture videoCapture = VideoCapture.create();
                videoCapture.setCaptureArea(new CaptureArea.FullScreen());

                // Get the list of codecs provided by video capture object
                java.util.List<Codec> videoCodecs = videoCapture.getVideoCodecs();
                // Use first codec from the list of available ones
                Codec videoCodec = videoCodecs.get(0);

                // Configure video encoding parameters:
                EncodingParameters encodingParameters = new EncodingParameters(new File("Desktop." +
                videoCapture.getVideoFormat().getId()));
                // Resize captured video to 800x600
                encodingParameters.setDimensions(new Dimension(800, 600));
                encodingParameters.setBitrate(800000);
                encodingParameters.setFramerate(10);
                // Specify codec for video encoding
                encodingParameters.setCodec(videoCodec);

                // Start video capture
                videoCapture.start(encodingParameters);

                System.out.println("Recording started. Press 'Enter' to terminate.");
                System.in.read();

                // Stop video capture
                videoCapture.stop();
            

If you need to capture an active window (i.e. the window the user is currently working with), use WindowManager class to find the required window first:


                WindowManager windowManager = WindowManager.getInstance();
                Window notepad = (Window) windowManager.findWindow("Untitled - Notepad");
                if (notepad == null) {
                throw new RuntimeException("Notepad window was not found");
                }
                videoCapture.setCaptureArea(new CaptureArea.WindowRect(explorerWindow));
            

Video capturing in JxCapture 3 supports all possible capture areas. When it's required, for example, to capture only particular rectangular screen area, then the appropriate captrure area object instance should be created:


                    ImageCapture imageCapture = ImageCapture.create(new CaptureArea.Rect(0, 0, 800, 600));
                

6.3. Video Capture with Audio

JxCapture 3 provides the abilities for capturing video with audio. To enable audio recording you need to specify audio source device, and the required audio codec itself. Following example demonstrates the technique:


                    List<AudioSource> audioSources = AudioSource.getAvailable();
                    if (!audioSources.isEmpty()) {
                    // Make sure that this video capture instance suppors provides any audio codecs
                    List<AudioCodec> audioCodecs = videoCapture.getAudioCodecs();
                    if (!audioCodecs.isEmpty()) {
                    // Enable and configure audio encoding
                    AudioEncodingParameters audioEncoding = new AudioEncodingParameters();
                    encodingParameters.setAudioEncoding(audioEncoding);

                    // Use first audio source for audio recording
                    videoCapture.setAudioSource(audioSources.get(0));

                    // Use first audio codec for audio encoding
                    audioEncoding.setCodec(audioCodecs.get(0));
                    }
                    }
                

Chapter 7. Using JxCapture 3 in Java Web Start Applications


This section describes the way of deploying your applications that use JxCapture 3 with the help of Java Web Start (JWS).

One of the major requirements for any JWS application is that all its resources are to be located inside signed JAR files. Although JAR files can be signed many times, JWS does not accept files with more than one signature. It is also mandatory that all application JAR files are signed with the same signature.

All JxCapture libraries are supplied already signed, and signing them with a new signature makes them unacceptable for JWS. Fortunately, there is a simple solution. The main idea is to use the <extension> tag in the .jnlp file and to create two different .jnlp files for your application. One .jnlp file should contain your application files and the other -- JxCapture resources. This technique is demonstrated in the example below. The first file is the application .jnlp file (demo.jnlp):

<?xml version="1.0" encoding="utf-8"?>
            <jnlp spec="1.0+" codebase="http://www.teamdev.com/" href="demo.jnlp">
            <information>
            <title>JxCapture Demo Application</title>
            <vendor>TeamDev Ltd.</vendor>
            <description>JxCapture Demo Application</description>
            <description kind="short">The demo of JxCapture library</description>
            <offline-allowed/>
            </information>
            <security>
            <all-permissions/>
            </security>
            <resources>
            <j2se version="1.5+" initial-heap-size="256m"/>
            <jar href="demo.jar"/><!-- demo.jar is your jar file signed with your own signature-->
            <extension name="jnw" href="jnw.jnlp"/>
            </resources>
            <component-desc/>
            <application-desc main-class="com.teamdev.jxcapture.image.demo.JxCaptureDemo"/>
            </jnlp>

The <extension> tag above makes a reference to the other jnw.jnlp file which is declared in the following way:

<?xml version="1.0" encoding="utf-8"?>
            <jnlp spec="1.0+" codebase="http://www.teamdev.com/" href="jnw.jnlp">
            <information>
            <title>JxCapture resources</title>
            <vendor>TeamDev Ltd.</vendor>
            <description>JxCapture Application</description>
            <description kind="short">JxCapture Application</description>
            <offline-allowed/>
            </information>
            <security>
            <all-permissions/>
            </security>
            <resources>
            <jar href="jniwrap-3.8.jar"/>
            <jar href="jxcapture-2.0.jar"/>
            </resources>
            <component-desc/>
            </jnlp>

The second jnw.jnlp file represents the JxCapture resource bundle for redistribution as part of another JWS application.

After you've configured the .jnlp files, place them in your Web site and create a link to your main .jnlp file that will also download JxCapture resources by the reference.

Chapter 8. Using JxCapture 3 in Applets


To use JxCapture 3 in applets, follow these instructions:

  1. Prepend the following code to the method to start the applet method:

    AppletHelper.getInstance().start();

    This call starts a NativeResourceCollector thread of JNIWrapper.

  2. Append the following code to the method to stop the applet method:

    AppletHelper.getInstance().stop();

    This call stops a NativeResourceCollector thread of JNIWrapper.

  3. The license files ( licenses.jar can be included to your JWS application class path.

  4. application.jar should be signed and should reference the JxCapture 3 library in its manifest file by setting the class path variable. Signing of JxCapture 3 libraries is not necessary as they are already signed.

The sample build file that prepares an applet library is shown below:

<project name="Applet Sample" default="build" basedir=".">
            <property name="certificate" value=".keystore"/>
            <property name="appletClasses" value="classes"/>
            <target name="build">
            <jar destfile="sample.jar">
            <fileset dir="${appletClasses}" includes="AppletSample.class"/>
            <manifest>
            <attribute name="Class-Path" value="jniwrap-3.8.jar; slf4j-api-1.5.8.jar; slf4j-simple-1.5.8.jar;
            licenses.jar; jxcapture-2.0.jar"/>
            </jar>
            <signjar jar="sample.jar" alias="your_alias" keystore="${certificate}" storepass="your_storepass"
            keypass="your_keypass" />
            </target>
            </project>

Below is given the applet usage sample:

<html>
            <body><h1>Applet Sample</h1>
            <p>
            <applet docbase="http://your_url" code="AppletSample.class" width="400" height="300"
            archive="sample.jar"/>
            </body>
            </html>

Chapter 9. Support


If you have any problems or questions regarding JxCapture 3, please check the documents listed below:

  • Installation instructions

  • Programmer's Guide

If none of the above resources contain the answer to your questions, please e-mail us at:

jxcapture-support@teamdev.com

If you want to discuss topics related to JxCapture, please visit a specialized forum on the TeamDev integrated customer support and troubleshooting center at:

http://support.teamdev.com/jxcapture

9.1. Reporting Problems

If you find any bugs, please submit the issue to us using a special report form on the TeamDev integrated customer support and troubleshooting center at:

http://support.teamdev.com/forms/reportForm.jsf

The form will help you provide all necessary information.

Chapter 10. Where to Get a New Version


To get the latest version of JxCapture 3, please visit:

http://www.teamdev.com/jxcapture/

Copyright © 2002-2017 TeamDev Ltd.