Basic Usage
The Capture class only requires a video device and/or audio device to begin capturing. The Filters class provides lists of the installed video and audio devices.
// Remember to add a reference to DirectX.Capture.dll using DirectX.Capture ... Capture capture = new Capture( Filters.VideoInputDevices[0], Filters.AudioInputDevices[0] ); capture.Start(); ... capture.Stop();
This will capture video and audio using the first video and audio devices installed on the system. To capture video only, pass a null as the second parameter of the constructor.
The class is initialized to a valid temporary file in the Windows temp folder. To capture to a different file, set the Capture.Filename property before you begin capturing. Remember to add DirectX.Capture.dll to your project references.
Setting Common Properties
The example below shows how to change video and audio settings. Properties such as Capture.FrameRate and AudioSampleSize allow you to programmatically adjust the capture. Use Capture.VideoCaps and Capture.AudioCaps to determine valid values for these properties.
Capture capture = new Capture( Filters.VideoInputDevices[0], Filters.AudioInputDevices[1] ); capture.VideoCompressor = Filters.VideoCompressors[0]; capture.AudioCompressor = Filters.AudioCompressors[0]; capture.FrameRate = 29.997; capture.FrameSize = new Size( 640, 480 ); capture.AudioSamplingRate = 44100; capture.AudioSampleSize = 16; capture.Filename = "C:\MyVideo.avi"; capture.Start(); ... capture.Stop();
The example above also shows the use of video and audio compressors. In most cases you will want to use compressors. Uncompressed video can easily consume over a 1GB of disk space per minute. Whenever possible, set the Capture.VideoCompressor and Capture.AudioCompressor properties as early as possible. Changing them requires the internal filter graph to be rebuilt which often causes most of the other properties to be reset to default values.
Listing Devices
Use the Filters.VideoInputDevices collection to list video capture devices installed on the system.
foreach ( Filter f in Filters.VideoInputDevices ) { Debug.WriteLine( f.Name ); }
The Filters class also provides collections for audio capture devices, video compressors and audio compressors. Preview
Video preview is controled with the Capture.PreviewWindow property. Setting this property to a visible control will immediately begin preview. Set to null to stop the preview.
// Enable preview capture.PreviewWindow = myPanel; // Disable preview capture.PreviewWindow = null;
The control used must have a window handle (HWND), good controls to use are the Panel or the form itself.
Retrieving or changing video/audio settings such as FrameRate, FrameSize, AudioSamplingRate, and AudioSampleSize will cause the preview window to flash. This is beacuse the preview must be temporarily stopped. Disable the preview if you need to access several properties at the same time.
Property Pages
Property pages exposed by the devices and compressors are available through the Capture.PropertyPages collection.
// Display the first property page capture.PropertyPages[0].Show();
The property pages will often expose more settings than the Capture class does directly. Some examples are brightness, color space, audio balance and bass boost. The disadvantage to using the property pages is the user's choices cannot be saved and later restored. The exception to this is the video and audio compressor property pages. Most compressors support the saving and restoring state, see the PropertyPage.State property for more information.
Changes made in the property page will be reflected immediately in the Capture class properties (e.g. Capture.FrameSize). However, the reverse is not always true. A change made directly to FrameSize, for example, may not be reflected in the associated property page. Fortunately, the filter will use requested FrameSize even though the property page shows otherwise.
Saving and Restoring Settings
To save the user's choice of devices and compressors, save Filter.MonikerString and user it later to recreate the Filter object.
To save a user's choices from a property page use PropertyPage.State. However, only the audio and video compressor property pages support this.
The last items to save are the video and audio settings such as FrameSize and AudioSamplingRate. When restoring, remember to restore these properties after setting the video and audio compressors.
// Disable preview capture.PreviewWindow = null; // Save settings string videoDevice = capture.VideoDevice.MonikerString; string audioDevice = capture.AudioDevice.MonikerString; string videoCompressor = capture.VideoCompressor.MonikerString; string audioCompressor = capture.AudioCompressor.MonikerString; double frameRate = capture.FrameRate; Size frameSize = capture.FrameSize; short audioChannels = capture.AudioChannels; short audioSampleSize = capture.AudioSampleSize; int audioSamplingRate = capture.AudioSamplingRate; ArrayList pages = new ArrayList(); foreach ( PropertyPage p in capture.PropertyPages ) { if ( p.SupportsPersisting ) pages.Add( p.State ); } // Restore settings Capture capture = new Capture( new Filter( videoDevice), new Filter( audioDevice) ); capture.VideoCompressor = new Filter( videoCompressor ); capture.AudioCompressor = new Filter( audioCompressor ); capture.FrameRate = frameRate; capture.FrameSize = frameSize; capture.AudioChannels = audioChannels; capture.AudioSampleSize = audioSampleSize; capture.AudioSamplingRate = audioSamplingRate; foreach ( PropertyPage p in capture.PropertyPages ) { if ( p.SupportsPersisting ) { p.State = (byte[]) pages[0] pages.RemoveAt( 0 ); } } // Enable preview capture.PreviewWindow = myPanel;
TV Tuner
To access the TV Tuner, use the Capture.Tuner property. If the device does not have a TV tuner, this property will be null. See DirectX.Capture.Tuner.Channel, DirectX.Capture.Tuner.InputType and DirectX.Capture.Tuner.SignalPresent for more information.
// Change to channel 5 capture.Tuner.Channel = 5;
Troubleshooting
This class library uses COM Interop to access the full capabilities of DirectShow, so if there is another application that can successfully use a hardware device then it should be possible to modify this class library to use the device.
Try the AMCap sample from the DirectX SDK (DX9\Samples\C++\DirectShow\Bin\AMCap.exe) or Virtual VCR from http://www.DigTV.ws
Credits
This class library would not be possible without the DShowNET project by NETMaster: http://www.codeproject.com/useritems/directshownet.asp
Documentation is generated by nDoc available at http://ndoc.sourceforge.net
Feedback
Feel free to send comments and questions to me at [email protected]. If the the topic may be of interest to others, post your question on the www.codeproject.com page for DirectX.Capture.