de.humatic.dsj
Class DSCapture

java.lang.Object
  java.awt.Component
      java.awt.Canvas
          de.humatic.dsj.DSFiltergraph
              de.humatic.dsj.DSCapture

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

public class DSCapture
extends DSFiltergraph

DSCapture provides access to DirectShow audio and video capture devices. This should get all devices in a particular system, including TV capture boards etc.
DSCapture uses the DSFilterInfo class to handle the separate devices, their downstream pins (outputs) and the formats those can deliver.

See Also:

Serialized Form

Nested Class Summary

class

DSCapture.CaptureDevice Nested class, extending DSFilter and wrapping a capture device, that has been added to the graph.

Nested classes/interfaces inherited from class de.humatic.dsj.DSFiltergraph

DSFiltergraph.DSAudioStream

Nested classes/interfaces inherited from class java.awt.Canvas

java.awt.Canvas.AccessibleAWTCanvas

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

static int	ARMED Software operation mode
static int	MAX_RESIZEABLE DSCapture DD7 / D3D9 specific setup flag
static int	MST_AUDIO Sync options
static int	MST_NONE Sync options
static int	MST_VIDEO Sync options
static int	PREVIEW Software operation mode
static int	RECORDING Software operation mode
static int	RESOLVE_INPUTS
static int	RESOLVE_OUTPUTS
static int	SKIP_AUDIO Device groups for optional skiping on query
static int	SKIP_BDA Device groups for optional skiping on query
static int	SKIP_VIDEO Device groups for optional skiping on query
static int	SKIP_XBARS Device groups for optional skiping on query
static int	STILL_ENABLED

Fields inherited from class de.humatic.dsj.DSFiltergraph

ACTIVATING, ANAMORPHIC, ASYNC_BUFFER_GET, ASYNC_BUFFER_REQ, AUDIO_BUFFER_REQUEST, BDA, BDA_PRG_CHANGED, BDA_SCAN_PROGRESS, BDA_SCANNED_FREQ, BDA_SIG_REC, BUFFER_COMPLETE, BUFFERING, CALLER, CAP_STATE_CHANGED, CAPTURE, CLOSED, CLOSING, COMP_AUDIO_BUFFER_REQ, COMP_BUFFER_FILLED, COMP_VIDEO_BUFFER_REQ, D3D9, DD7, DECKLINK, DELIVER_AUDIO, DES_ERROR, DONE, DV, DV_STATE_CHANGED, DVD, DVD_FORMAT_CHANGED, DVD_MENU_ENABLED, E_CANT_PUMP_AUDIO, E_INIT_HEADLESS, EDITABLE, ENTER_FS, EPG, EVR, EXIT_FS, EXPORT_DONE, EXPORT_FINISHING, EXPORT_PROGRESS, EXPORT_STARTED, EXT_API_EVENT, FILTER_CHANGED, FORMAT_CHANGED, FRAME_CALLBACK, FRAME_LOCKED, FRAME_NOTIFY, GD, GE_DEVICE_CONNECTED, GE_DEVICE_LOST, GE_REF_REC_STOPPED, GRAPH, GRAPH_CHANGED, GRAPH_ERROR, GRAPH_EVENT, HDV, HDV_STATE_CHANGED, HEADLESS, INDEXER_DONE, INDEXER_STARTED, INIT_MUTED, INIT_PAUSED, INITIALIZED, IP_READY, J2D, JAVA_AUTODRAW, JAVA_POLL, JAVA_POLL_RGB, JAVASOUND, KEY_EVENT, KF_NOTIFY, LOCK_BUFFER, LOOP, MGD, MOUSE_ENABLED, MOUSE_EVENT, MOVIE, NATIVE_FORCE_GDI, NIO_UPDATE, NO_AMW, NO_SYNC, NULL, ONESHOT, OVERLAY, OVERLAY_BUFFER_REQUEST, PLAYLIST_PARSED, RENDER_NATIVE, RESTART_REQ, RGB32, RTCP_EVENT, RTMP_EVENT, RTMP_SO_CHANGED, RTMP_STATE_CHANGED, SAMPLE_BUFFER_FILLED, SAVE_DONE, SAVE_STARTED, SBE, SBE_REC_STATE_CHANGED, SERVICE_ERROR, SERVICE_EVENT, SINK_ERROR, SINK_STATE_CHANGED, SIZE_CHANGED, SOURCE_ERROR, SOURCE_STATE_CHANGED, SOURCE_STATE_NOTIFY, SOURCE_USER_DATA, STILL_IMG_RECEIVED, STREAM_SEEK, SUBCLASS_EVENT, SWING, SYNC_BUFFER_REQ, TABLE_RECEIVED, TIME_FORMAT_CHANGED, TRANS_IN_PLACE, TRANSPORT, TS_BUFFER_FILLED, type, VIDEO_BUFFER_REQUEST, VMR_EMBED, VMR7, VMR9, VPJ, YUV, YUV_ORG

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

DSCapture(int flags, DSFilterInfo videoDeviceInfo, boolean captureAudioFromVideoDevice, DSFilterInfo audioDeviceInfo, java.beans.PropertyChangeListener pcl)
Creates a DSCapture object that uses the video & audio devices described by the given DSFilterInfos.

DSCapture(int flags, java.beans.PropertyChangeListener pcl)
Creates a DSCapture object using the first (Windows default) video and audio capture devices.
%flags - rendering mode and additional graph options, see DSFiltergraph.

Method Summary

DSCapture.CaptureDevice	activateDevice(DSFilterInfo info)
void	captureMPEG(java.lang.String fileName, int mpegFlags, boolean preview) Captures from a devices MPEG pin or an eventual additional hardware or software MPEG Encoder "belonging" to the device.
void	changeCaptureFile(java.lang.String newPath, boolean startRecording) Once a capture file, compression etc.
static DSCapture	fromUserDialog(java.awt.Frame dialogParent, int flags, java.beans.PropertyChangeListener pcl) Presents a dialog that users can select video and audio devices from and preconfigure those in terms of output formats.
DSCapture.CaptureDevice	getActiveAudioDevice()
int[]	getActiveDeviceIndices() Returns the index into video and audio devices for the currently active devices.
DSCapture.CaptureDevice	getActiveVideoDevice()
int[]	getFrameDropInfo() Returns the number of captured & dropped frames from a video device when recording.
int	getState() Returns the current state of the class, i.e PREVIEW, ARMED or RECORDING
void	lockVolume(float volume) Locks the audio volume over multiple state changes.
static DSFilterInfo[][]	queryDevices() This no parameter device query version calls through to queryDevices(1) and returns resolved DSFilterInfos including pin and format information.
static DSFilterInfo[][]	queryDevices(int flags) Static method to retrieve information about the system's capture capabilities without creating concrete device instances.
void	record() Toggles recording when capture file has been set.
void	setCaptureFile(java.lang.String fileName, DSFilterInfo videoEncoder, DSFilterInfo audioEncoder, boolean preview) Sets the file captured data will be written to. When %preview is set to true dsj will allways try to keep preview going while waiting for the command that starts recording and during grabbing.
void	setMasterStream(int stream) Sets the "master stream" used for synchronizing audio and video on capture.
void	setPreview() Reset the graph into preview mode after a capture file had been set.

Methods inherited from class de.humatic.dsj.DSFiltergraph

addColorSpaceConverter, addFilterToGraph, addNotify, addPropertyChangeListener, asComponent, connectDump, connectSink, createDSFiltergraph, dispose, dumpGraph, findFilterByName, findRenderer, flipImage, getActive, getAspectLocked, getAspectRatio, getAudioProperties, getAudioStream, getBitDepth, getData, getDataSize, getDisplaySize, getDuration, getEffectiveFrameRate, getFrameRate, getFullScreenWindow, getID, getImage, getInfo, getLoop, getMediaDimension, getMinimumSize, getOutFlags, getPan, getPreferredSize, getRate, getRendererControls, getTime, getVolume, getYUVType, goFullScreen, graphChanged, hasMediaOfType, insertFilter, insertOverlayFilter, insertSampleAccessFilter, insertTransInPlaceFilter, isFullScreen, isSubGraph, leaveFullScreen, listFilters, lockAspectRatio, paint, pause, play, queryCapability, redraw, register, reloadFilter, removeFilter, removeNotify, removePropertyChangeListener, removeSink, setAudioRenderer, setAviExportOptions, setBounds, setClockSource, setEvent, setLoop, setPan, setPreferredSize, setRate, setTimeValue, setVolume, step, stop, tearDown, update

Methods inherited from class java.awt.Canvas

createBufferStrategy, createBufferStrategy, getAccessibleContext, getBufferStrategy

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PREVIEW

public static final int PREVIEW

Software operation mode

See Also:

Constant Field Values

ARMED

public static final int ARMED

Software operation mode

See Also:

Constant Field Values

RECORDING

public static final int RECORDING

Software operation mode

See Also:

Constant Field Values

MST_NONE

public static final int MST_NONE

Sync options

See Also:

Constant Field Values

MST_VIDEO

public static final int MST_VIDEO

Sync options

See Also:

Constant Field Values

MST_AUDIO

public static final int MST_AUDIO

Sync options

See Also:

Constant Field Values

RESOLVE_OUTPUTS

public static final int RESOLVE_OUTPUTS

See Also:

Constant Field Values

RESOLVE_INPUTS

public static final int RESOLVE_INPUTS

See Also:

Constant Field Values

SKIP_VIDEO

public static final int SKIP_VIDEO

Device groups for optional skiping on query

See Also:

Constant Field Values

SKIP_AUDIO

public static final int SKIP_AUDIO

Device groups for optional skiping on query

See Also:

Constant Field Values

SKIP_XBARS

public static final int SKIP_XBARS

Device groups for optional skiping on query

See Also:

Constant Field Values

SKIP_BDA

public static final int SKIP_BDA

Device groups for optional skiping on query

See Also:

Constant Field Values

MAX_RESIZEABLE

public static final int MAX_RESIZEABLE

DSCapture DD7 / D3D9 specific setup flag

See Also:

Constant Field Values

STILL_ENABLED

public static final int STILL_ENABLED

See Also:

Constant Field Values

Constructor Detail

DSCapture

public DSCapture(int flags,
                 DSFilterInfo videoDeviceInfo,
                 boolean captureAudioFromVideoDevice,
                 DSFilterInfo audioDeviceInfo,
                 java.beans.PropertyChangeListener pcl)
          throws DSJException

Creates a DSCapture object that uses the video & audio devices described by the given DSFilterInfos. The queryDevices() method is the easiest way to get hold of a list of installed capture devices.
Both info arguments may be null in which case the default devices will be used. To explicitely NOT render either video or audio, pass the DSFilterInfo.doNotRender() dummy object.
The boolean parameter lets you render both video and audio from the video device if this is an MPEG or DV device or it exposes a crossbar interface and has both video & audio outputs like most combined TV/analogue video boards have.
Unlike webcams, where a build in microphone mostly presents a separate audio capture filter, these "audio devices" will not show up in audio device queries. If you use this option the AudioDeviceInfo parameter should be DSFilterInfo.doNotRender(). The boolean should not be set to true for plain videodevices.
%flags - rendering mode and additional graph options, see DSFiltergraph.
To use specific demultiplexer and decoder filters with mpeg capture devices, enter those into the DSCapture node of the xml setup file.
There are two additional flags that can be used (i.e. OR combined with the usual rendering mode flags) with DSCapture:
DSCapture.MAX_RESIZEABLE - reserves enough memory space for NIO data transfer to enable a video capture object being resized by format changes to its maximal size (which these days may be up to 1600*1200 pixels or more). Without this flag the resizing reserve is 4 times the initial size.
DSCapture.STILL_ENABLED - prepares for capturing still images from a device's still pin (as present on some webcams). Still pins usually offer much higher maximum resolutions. Be aware that you will not be able to get those at video framerates.

Throws:

DSJException

DSCapture

public DSCapture(int flags,
                 java.beans.PropertyChangeListener pcl)
          throws DSJException

Creates a DSCapture object using the first (Windows default) video and audio capture devices.
%flags - rendering mode and additional graph options, see DSFiltergraph.

Throws:

DSJException

Method Detail

fromUserDialog

public static DSCapture fromUserDialog(java.awt.Frame dialogParent,
                                       int flags,
                                       java.beans.PropertyChangeListener pcl)
                                throws DSJException

Presents a dialog that users can select video and audio devices from and preconfigure those in terms of output formats. Most of the source code for this dialog is given in the main dsj demo.
%flags - rendering mode and additional graph options, see DSFiltergraph.

Throws:

DSJException

queryDevices

public static DSFilterInfo[][] queryDevices()

This no parameter device query version calls through to queryDevices(1) and returns resolved DSFilterInfos including pin and format information.

queryDevices

public static DSFilterInfo[][] queryDevices(int flags)

Static method to retrieve information about the system's capture capabilities without creating concrete device instances. The returned two-dimensional array holds filter infos for video devices in slot 0, for audio devices in slot 1.
Set the %flags to 1 when you need full information on a device's output pins and formats for either informational purposes or to start capture with a different format than the device's default. If you are interested in devices' input pins also set he second bit (i.e.: flags = 3)
It's recommended to only use 0 and reject the filter resolving when you otherwise experience problems. Another possible use case for less deep lookups is repeated background queries to detect devices that have been attached or removed. For this scenario it may be useful to only do a basic query (queryDevices(0)) and only go and get the details, when something has changed. For this case it may also be a good idea to skip resolving of crossbars (queryDevices(16)) as those may impose minor memory leaking on queries. See next paragraph.
Bits 3 to 6 allow for certain groups of devices to be excluded on queries: OR combine %flags with on of the SKIP_ constants to skip video or audio devices, crossbars and TVTuners or hybrid BDA / capture devices.
Note that when dsj fully resolves the device-infos the returned array may contain a third slot holding devices that drivers are installed for, but that are not currently available (most likely USB boxes). When %flags is 0 on query these devices will appear in the regular listings. Trying to activate them will throw an exception.

getActiveVideoDevice

public DSCapture.CaptureDevice getActiveVideoDevice()

getActiveAudioDevice

public DSCapture.CaptureDevice getActiveAudioDevice()

activateDevice

public DSCapture.CaptureDevice activateDevice(DSFilterInfo info)

setPreview

public void setPreview()

Reset the graph into preview mode after a capture file had been set. The current state will change to PREVIEW.

getActiveDeviceIndices

public int[] getActiveDeviceIndices()

Returns the index into video and audio devices for the currently active devices. This is merely for GUI setting purposes.

setCaptureFile

public void setCaptureFile(java.lang.String fileName,
                           DSFilterInfo videoEncoder,
                           DSFilterInfo audioEncoder,
                           boolean preview)

Sets the file captured data will be written to.
When %preview is set to true dsj will allways try to keep preview going while waiting for the command that starts recording and during grabbing. There are however devices that can not control capture and preview separately or may feature data formats for preview that dsj does not support. In such a case dsj will capture to file without updating the preview display or may only show a preview while capture is running.
%video & audioEncoder: DSFilterInfos as derived from DSEnvironment.getEncoders (DSFilterInfo.doNotRender() to write out uncompressed data). The format of the encoded output may further be specified by setting the preferred Format on the FilterInfo's downstream Pin (DSFilterInfo.SHOW_USER_DIALOG to bring up the native propety page of the encoder if available).
To capture to WindowsMedia do not use any of the encoder FilterInfos. Instead proceed like this:
- make sure your output file has an .asf, .wmv or .wma ending.
- leave both encoder parameters set to null (will then use a default - relatively low quality, 320*240 sized - WMV8 system profile) OR:
- use DSFilterInfo.doNotRender() with preferredFormat set to SHOW_USER_DIALOG for the videoEncoder parameter (will let you pick a WM System profile from a dialog). OR:
- use a custom WM profile for the videoEncoder parameter via DSFilterInfo.filterInfoForProfile(...).
To capture audio only DSCapture should be set up without video device. (use DSFilterInfo.doNotRender() on construction).

To actually start & pause grabbing call record.
When done, close the file by calling stop() on the filtergraph or setPreview() on DSCapture.

Please also see DSFiltergraph.setAviExportOptions for some additional recording related options.
Some devices may require that you explicitely set an outputformat or framerate before capturing and may lead to unsatisfying results without doing so. High numbers of dropped frames returned from getFrameDropInfo usually point to this requirement..
After calling setCaptureFile(..) the current state of the class will change to ARMED.

changeCaptureFile

public void changeCaptureFile(java.lang.String newPath,
                              boolean startRecording)

Once a capture file, compression etc. have been set using setCaptureFile(...) this method can be used to change the target file without reseting to preview mode and rebuilding the filtergraph.
This is not frame accurate, you will loose frames between files.

captureMPEG

public void captureMPEG(java.lang.String fileName,
                        int mpegFlags,
                        boolean preview)
                 throws DSJException

Captures from a devices MPEG pin or an eventual additional hardware or software MPEG Encoder "belonging" to the device. This method will likely only work with devices that either only have a MPEG output directly on the device filter or with Hauppauge cards (whose specific implementation of the mpeg encoder as a separate DirectShow filter has been taken care of). For devices that use additional filters that dsj does not know about, it will likely fail.
Note that you essentially need to fully resolve the device's FilterInfo (during queryDevices) before calling this. FilterInfos originating from some other method than queryDevices may not hold all the information this method will check for and thus may also fail.
%mpegFlags controls the output format of the MPEGEncoder. For Hauppauge devices with hardware encoder 0 sets it up to output program streams, 1 will output transport streams. Hauppauge devices with software encoder seem to (pre)select between mpeg1 & 2 by the incoming format. DSFilterInfo.SHOW_USER_DLG can be used to bring up the encoder's properties dialog.

Throws:

DSJException

record

public void record()

Toggles recording when capture file has been set. The current state will change between ARMED and RECORDING.

getState

public int getState()

Returns the current state of the class, i.e PREVIEW, ARMED or RECORDING

getFrameDropInfo

public int[] getFrameDropInfo()
                       throws DSJException

Returns the number of captured & dropped frames from a video device when recording. Counters are relative to the moment the graph changed to running state (usually when setCaptureFile was called).

Throws:

DSJException

setMasterStream

public void setMasterStream(int stream)
                     throws DSJException

Sets the "master stream" used for synchronizing audio and video on capture. The default is MST_AUDIO. To change this this method must be called before setting a capture file.

Throws:

DSJException

lockVolume

public void lockVolume(float volume)
                throws DSJException

Locks the audio volume over multiple state changes. Call this to avoid having to set the volume to any desired value when changing between preview and capture. To disable the feature once it has been set, call lockVolume(-1).

Throws:

DSJException