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.

2.1. System Requirements

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

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.

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.

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();
            

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

                    VideoCapture videoCapture = VideoCapture.create(VideoFormat.WMV);
                

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));
                    }
                    }
                

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.