###
TVideoGrabber
Version 4.04 - March 9, 2002

Home page: http://www.delphicity.com
mirror: http://www.delphicity.info

Contact: contact@delphicity.com or contact@delphicity.info
Support: support@delphicity.com or support@delphicity.info

- ### Description - Features

- ### System requirements

- ### how does TVideoGrabber work?

- ### Installation

- ### Quick start guide

- ### Procedures and functions

- ### Public properties

- ### Published properties

- ### Events

- ### Enumerated types

- ### FAQ

- ### Registration

- ### License agreement

DESCRIPTION
TVideoGrabber is a VCL component for Delphi or C++ Builder. Based on DirectX8, WDM compliant, TVideoGrabber allows you to add video capture capabilities in your project. TVideograbber accepts video devices, DV devices and TV capture devices connected through Firewire, USB, PCI or PC-Card. With TVideoGrabber you can: CAPTURE VIDEO STREAMS to AVI files, with or without audio stream, CAPTURE FRAMES to TBitmap, BMP or JPEG files, individually or automatically using the burst mode. BMP or JPEG file names can be automatically created on a sequential or time basis, COMPRESS the captured AVI, on the fly or after capture, using the available codecs on your platform. Additional codecs like MPEG4 and DivX can be installed and are automatically recognized by TVideoGrabber, GET the number of delivered frames and dropped frames, PREVIEW the video streams in a window or in full screen mode. AVI capture and frame capture work even if the component is not visible, PLAY the video files at their nominal rate, slower, faster, in a window or in full screen mode, CHOOSE - the settings of video devices, audio devices and video compressors, - the audio and video formats, - the video frame rate, - the Digital Video (DV) preview and capture size, and the capture mode (interleaved or separated audio/video), - etc... TVideoGrabber saves you having to tangle with DirectX8 and DirectShow. Most common parameters can be simply set from the Object Inspector.
SYSTEM REQUIREMENTS
Delphi 5, Delphi 6, C++ Builder 5 Windows 95/98/NT/ME/2000/XP DirectX 8 recommended CPU: 1 GHz or higher

###

REGISTRATION

Click here to register.

HOW DOES TVIDEOGRABBER WORK

TVideoGrabber modes:

TVideoGrabber mainly works in 2 modes: preview and AVI capture.

- the preview can be started by StartPreview and stopped by StopPreview,
- the AVI capture can be started by StartCapture and stopped by StopCapture.

If you do not want the preview to start automatically, disable the AutoStartPreview property.

frame capture:

Whatever the device is in preview mode or AVI capture mode, TVideoGrabber is able to capture frames using CaptureFrameTo if FrameGrabberEnabled is true.

Take a look at the AllFrame demo included in the package. This very simple demo uses 10 lines of code to capture continuously all the frames, returns them as TBitmap and display them in a contiguous TImage component.

The frames captured are returned asynchronously by the OnFrameCaptureCompleted event.
They can be returned as memory TBitmap or written directly to disk as BMP files or a JPEG files, according to the TFrameCaptureDest parameter passed when calling CaptureFrameTo.

For BMP or JPEG files, the file name is usually generated automatically, but you can give your own file name to CaptureFrameTo if you need to capture only a single frame (with BurstMode disabled).

Passing a file name does not suit to the burst mode, simply because more than 1 file is returned. In this case call CaptureFrameTo with and empty string as file name and let TVideoGrabber generate filenames automatically according to the StoragePath, AutoFileName and AutoFilePrefix properties.

You can choose to capture frames on the TVideoGrabber's capture stream or on its preview stream, according to the FrameGrabberOnCaptureStream.

If the preview stream is an overlay, frames cannot be captured on this stream. In this case the frames are automatically captured on the capture stream, no matter to the FrameGrabberOnCaptureStream state.

Reciprocally, if the frame capture cannot be inserted on the capture stream, it is automatically moved to the preview stream, if possible.

If you do not want to preview the video but want to capture frames, simply disable the Visible property, because stopping the preview stream using StopPreview will stop the frame capture as well.

audio/video compression:

Btw, the codecs are those available on the current platform. DivX codec is available for download at http://www.divx.com/download/index.php. For MPEG-4 codecs, go to http://www.microsoft.com | Downloads | Download Center | Windows Media Player Codecs.

Codecs can be applied "on the fly", while capturing, or after capture according to the CompressionMode property.
- of course, the "on the fly" method requires CPU, but less disk access because the file to write is smaller,
- the "after capture" methods recompress the file after capture, so it creates big uncompressed files before recompressing. Capture and/or preview are not available during recompression.

Video and audio codecs can be applied respectively to the video stream and/or the audio stream according to the CompressionType property.

AVI playback:

TVideoGrabber includes a player that allows to view captured AVI files at their nominal rate, slower or faster. It can be used separately to play any clip.

Open a clip with OpenPlayer, run it with RunPlayer, pause it with PausePlayer and close it with ClosePlayer.

Interactive versus programmatical use:

TVideoGrabber has been designed to be used interactively as well as programmatically.

By default, changing the TVideoGrabber settings while previewing automatically restart the preview if RestartPreviewOnParamChange is enabled, allowing to preview the changes in real time.

To programmatically preset several parameters in preview mode without restarting preview each time a parameter is set, simply disable RestartPreviewOnParamChange. Then, after all the parameters have been set, call StartPreview to restart the preview using the new parameters.

Another way is to stop the preview using StopPreview, set all the parameters and then restart the preview using StartPreview.

Note: no parameter changes are applied during AVI capture. You must stop the capture first, using StopCapture, and then restart the capture using StartCapture for the new settings to be effective.

devices-dependent parameters:

The following parameters are device-dependent. The allowed values for the current device are returned as a list of strings. The current value is selected by assigning the index of the string in the list to the corresponding index property.

Parameters whose values change from 1 platform to another:

VideoDevices list -> VideoDevice index
AudioDevices list -> AudioDevice index
VideoCompressors list -> VideoCompressor index
AudioCompressors list -> AudioCompressor index

Parameters whose values change according to the current video device:

VideoSizes list -> VideoSize index
VideoSubTypes list -> VideoSubType index

Note:
- these lists are strings that can be directly assigned to a comboBox.
E.g. ComboBox1.Items.Text := VideoGrabber1.VideoFormats;

- you can also assign these lists to a TstringList to get the number of available items:
E.g.:
var
TheList: TStringList;
ItemCount: integer;
begin
TheList := TStringList.Create;
TheList.Text := VideoGrabber1.VideoFormats;
ItemNumber := TheList.count;
TheList.Free;
end;

INSTALLATION

1. If a previous package of TVideoGrabber is already installed, remove it first:

- Components | Install Packages
- Click on "DelphiCity TVideoGrabber"
- Click "Remove"
- Click "Yes"
- Click "Ok".
- search for "TVidGrab.*" and "VidGrab*.*" files in your Borland directories and delete them, to be certain that old units will not remain in the search paths (causing later raw errors).

2. Install the current package:

- Unzip the archive in a folder of your choice (e.g. c:\vidgrab)

- According to your Delphi or C++Builder version,
copy all the Delphi?\*.* or CBuilder?\*.* archive files to the Borland\Delphi?\Imports or \Borland\CBuilder?\Imports directory,
- Run Delphi or C++Builder,

- Select Component | Install packages,

- Press the "Add" button,

- Locate the TVidGrab.bpl file in the Imports directory and select it,

- Select Open

- Select Ok

- Check the ActiveX tab in the right of the component palette. The TVideoGrabber object should have been added.

Note about zipped files:
when unzipping the package, the unzip tool must re-create the package sub-directory tree with several Delphi and C++Builder directories. If you are using WinZip, don't forget to enable the "use folder names" checkbox, otherwise files with same name will overwrite themselves.

Methods, functions, properties and events

procedures and functions

> CaptureFrameTo
> ClosePlayer
> FastForwardPlayer
> FastReversePlayer
> IsDialogAvailable
> PausePlayer
> OpenPlayer
> RebuildDeviceList
> RecompressFile
> RunPlayer
> SendDVCommand
> SetPlayerPosition
> ShowDialog
> ShutdownGraph
> StartCapture
> StopCapture
> StartPreview
> StopPreview

public properties

> AudioCompressors: string
> AudioCompressorsCount: integer
> AudioCompressorName (index: integer): string
> AudioDevices: string
> AudioDevicesCount: string
> AudioDeviceName (index: integer): string
> AudioFormats: string
> Busy: Boolean
> CaptureDuration: Double
> CurrentState: TCurrentState
> DVResolutions: string
> ImageRatio: Double
> IsAnalogVideoIn: Boolean
> PlayerClipDuration: Double
> PlayerClipFrameRate: Double
> TVTuner: IAMTVTuner
> VideoCompressors: string
> VideoCompressorsCount: integer
> VideoCompressorName (index: integer): string
> VideoDevices: string
> VideoDevicesCount: integer
> VideoDeviceName (index: integer): string
> VideoSizes: string
> VideoSubTypes: string
> VideoHeight: integer
> VideoWidth: integer

published properties

> AnalogVideoStandard: TAnalogVideoStandard
> AudioCompressor: integer
> AudioDevice: integer
> AudioFormat: TAudioFormat
> AutoFileName: TAutoFileName
> AutoFilePrefix: string
> AutoSearchNextAvailVideoDevice: Boolean
> AutoSize: boolean
> AutoStartPreview: Boolean
> AVI1IndexCompatibility: boolean
> BurstCount: Integer
> BurstInterval: Integer
> BurstMode: Boolean
> BusyCursor: TCursor
> CaptureAudio: Boolean
> CaptureFileExt: string
> CaptureFileName: string
> CompressionMode: TCompressionMode
> CompressionType: TCompressionType
> DVCaptureMode: TDVCaptureMode
> DVCaptureResolution: TDVResolution
> DVPreviewResolution: TDVResolution
> DVReduceFrameRate: Boolean
> FrameGrabberEnabled: Boolean
> FrameGrabberOnCaptureStream: Boolean
> FrameRate: Double
> JPEGPerformance: TJPEGPerformance
> JPEGProgressiveDisplay: boolean
> JPEGQuality: TJPEGQualityRange
> MaintainImageRatio: Boolean
> NormalCursor: TCursor
> PlayerAutoStart: Boolean
> PlayerFileName: String
> PlayerRate: Double
> PreallocCapFileEnabled: Boolean
> PreallocCapFileName: string
> PreallocCapFileSizeInMB: integer
> PreallocCapRecreate: Boolean
> RefreshPreviewOnParamChange: Boolean
> RenderAudio: Boolean
> StoragePath: string
> VCompKeyFrameRate: Integer
> VCompQuality: Double
> VideoCompressor: integer
> VideoDevice: integer
> VideoSize: integer
> VideoSubType: integer
> Visible: boolean

events

> OnCaptureCompleted
> OnCaptureProgress
> OnCaptureReadyToStart
> OnCaptureStarted
> OnChangeAudioDevice
> OnChangeVideoDevice
> OnComponentLoaded
> OnCopyPreallocDataCompleted
> OnCopyPreallocDataStarted
> OnCreatePreallocFileCompleted
> OnCreatePreallocFileStarted
> OnDeviceArrival
> OnDeviceLost
> OnDeviceRemoval
> OnDirectX8Required
> OnDiskFull
> OnErrorLog
> OnFrameCaptureCompleted
> OnFullScreenKeyPress
> OnNoVideoDevices
> OnPlayerCompleted
> OnPlayerEndOfStream
> OnPlayerFileNotFound
> OnPlayerStarted
> OnPreviewStarted
> OnRecompressCompleted
> OnRecompressStarted
> OnResizeVideo
> OnTimeCodeReader

enumerated types

> TAudioFormat
> TAutoFileName
> TCompressionMode
> TCurrentState
> TDialog
> TDVCaptureMode
> TDVResolution
> TFrameCaptureDest
> TInterleavingMode
> TMasterStream
> TVideoFormat

## procedures and functions

procedure CaptureFrameTo (Dest: TFrameCaptureDest; FileName: string);
Captures the current frame to a memory Bitmap, a BMP file or a JPEG file, according the the Dest parameter.

The capture is asynchronous and returned by the OnFrameCaptureCompleted event.

Dest = fc_TBitmap:
The frame capture will return only a TBitmap. In this case the FileName parameter is ignored.
Dest = fc_BmpFile:
The frame capture creates a BMP file. See the notes below.
Dest = fc_JpegFile:
same for BMP files above, but creates a JPEG file. See the notes below.

Notes about frame capture to BMP or JPEG files (Dest = fc_BmpFile or Dest = fc_JpegFile):
1. if FileName is left blank, a file name is automatically generated in the StoragePath directory according to the AutoFileName and AutoFilePrefix properties. The file name generated is returned for each frame captured by the OnFrameCaptureCompleted event.
2. the memory bitmap is always returned by OnFrameCaptureCompleted, even if the Dest parameter is fc_BmpFile or fc_JpegFile. The reason is that you can need to save the file as BMP or JPEG and display it, e.g. in a TImage. The bitmap returned avoids you to have to read the BMP or JPEG file to display the bitmap.

procedure ClosePlayer;
Closes the current clip, if opened.

procedure FastForwardPlayer (Percent: Integer);
Scans rapidly forward through the current clip. The new position is the clip's current position + Percent (percentage of the total length of the clip).

procedure FastReversePlayer (Percent: Integer);
Scans rapidly backward through the current clip. The new position is the clip's current position - Percent (percentage of the total length of the clip).

function IsDialogAvailable (Dialog: TDialog): Boolean;
Returns true if the TDialog dialog is currently available. See ShowDialog.

procedure PausePlayer;
Pauses the opened clip, if currently playing.

procedure OpenPlayer;
Opens the clip specified by the PlayerFileName property.

procedure RebuildDeviceList;
Scans the currently available video and audio devices, and updates the VideoDevices and AudioDevices lists.

function RecompressFile (SourceFile, DestFile: string): Boolean;
Recompresses an uncompressed clip, using the VideoCompressor and/or AudioCompressor settings.

procedure RunPlayer;
Plays a clip, opened by OpenPlayer, or restarts a clip paused by PausePlayer.

function SendDVCommand (DvCommand: TDvCommand): Boolean;
Sends the specified command to the DV camcorder. Returns true on success.

function SetPlayerPosition (Value: Double): Boolean;
Sets the current position of an opened clip (see OpenPlayer). The current position is expressed in seconds. Valid range between 0 and PlayerClipDuration.

procedure ShowDialog (Dialog: TDialog);
displays the TDialog dialog, if available. Use IsDialogAvailable to test if it is.
Warning: ShowDialog(dlg_Capture) usually allows to change only 1 parameter at the same time.

procedure ShutdownGraph;
Ends immediately the current graph (previewing, capturing or playing). The frame grabber is disabled. Using it should be avoided, it is better to cleanly stop the current graph with StopCapture, StopPreview or ClosePlayer.

procedure StartCapture;
Starts the AVI capture to the CaptureFileName file. If CaptureFileName is left blank, a filename is automatically generated according to the AutoFileName property. The file is created in the StoragePath directory.

procedure StopCapture;
Stops the capture started by StartCapture.

procedure StartPreview;
Starts or restarts the preview.
Use it to start the preview if AutoStartPreview is disabled to avoid automatically starting preview when the application starts, or to restart the preview when parameters have been set and RefreshPreviewOnParameterChange is disabled.

procedure StopPreview;
Stops the current preview.
The frame capture is not available when the preview is stopped. To disable the preview but keep the frame capture alive, simply set the Visible property to false.

## Public properties

property Audio Compressors: string;
List of the audio compressors available on the current platform.
This list can be directly assigned to a comboBox. E.g.: ComboBox1.Items.Text := VideoGrabber1.AudioCompressors.
Select the audio compressor by assigning its list index to the AudioCompressor property. E.g.: VideoGrabber1.AudioCompressor := ComboBox1.ItemIndex.

property AudioCompressorsCount: integer
Retrieves the number of audio compressors available on the current platform.

property AudioCompressorName (index: integer): string
Retrieves the name of the audio compressor whose range is index in the AudioCompressors list (range = 0..AudioCompressorsCount-1). See AudioCompressor.

property AudioDevices: string;
List of the audio input devices available on the current platform.
This list can be directly assigned to a comboBox (e.g. ComboBox1.Items.Text := VideoGrabber1.AudioDevices).
Select the device by assigning the list index to the AudioDevice property (e.g.: VideoGrabber1.AudioDevice := ComboBox1.ItemIndex).

property AudioDevicesCount: string
Retrieves the number of audio input devices available on the current platform.

property AudioDeviceName (index: integer): string
Retrieves the name of the audio input device whose range is index in the AudioDevices list (range = 0..AudioDevicesCount-1). See AudioDevice.

property AudioFormats: string;
List of the audio formats available.
This list can be directly assigned to a comboBox. E.g. ComboBox1.Items.Text := VideoGrabber1.AudioFormats.
Select the audio format by assigning its list index to the AudioFormat property. E.g.: VideoGrabber1.AudioFormat := TAudioFormat (ComboBox1.ItemIndex).

Note: the audio format is applied to DV only if type 2 capture with PCM audio compression is used.

property Busy: Boolean;
Returns true if TAVideoGrabber is in an intermediary state (e.g. when switching from preview mode to capture mode, when restarting after a parameter changes, etc...) and cannot execute commands or certain parameter changes immediately).

However, commands and certain parameter changes received by the component when it is in a Busy state are queued and executed as soon as the component becomes available. So, you can send commands without waiting for the component to be back from its busy state.

property CaptureDuration: Double;
Duration of the last captured file since the application started.

property CurrentState: TCurrentState;
Returns the state of TAVideoGrabber.
cs_Down: the component is stopped.
cs_Preview: the component is previewing, accepting frame captures.
cs_Capture: the component is capturing data, while previewing if PreviewCapture is enabled.
cs_Playback: the component is playing back a video.
cs_Compress: the component is recompressing a video (activated by RecompressFile, or by StopCapture when CompressionMode was set to vc_CompressAfterCapture).

property ImageRatio: Double;
Returns the ratio between the Width and Height of the video source.

property IsAnalogVideoIn: Boolean;
Returns true if the video input is an analog device.

property PlayerClipDuration: Double;
Returns the total length in seconds of a clip opened by OpenPlayer.

property PlayerClipFrameRate: Double;
Returns the frame rate of a clip opened by OpenPlayer.

property TVTuner: IAMTVTuner
Gives full control on the functions of the IAMAnalogVideoDecoder interface, the IAMTVTuner interface, derived from the IAMTuner interface.
Note: TVTuner is available if the TV card is WDM compliant.

property VideoCompressors: string;
List of the video compressors available on the current platform.
This list can be directly assigned to a comboBox. E.g.: ComboBox1.Items.Text := VideoGrabber1.VideoCompressors.
Select the video compressor by assigning its list index to the VideoCompressor property. E.g.: VideoGrabber1.VideoCompressor := ComboBox1.ItemIndex.

property VideoCompressorsCount: integer
Retrieves the number of video compressors available on the current platform.

property VideoCompressorName (index: integer): string
Retrieves the name of the video compressor whose range is index in the VideoCompressors list (range = 0..VideoCompressorsCount-1). See VideoCompressor.

property VideoDevices: string;
List of the video devices available on the current platform.
This list can be directly assigned to a comboBox. E.g.: ComboBox1.Items.Text := VideoGrabber1.VideoDevices.
Select the video device by assigning its list index to the VideoDevice property. E.g.: VideoGrabber1.VideoDevice := ComboBox1.ItemIndex.

property VideoDevicesCount: integer
Retrieves the number of video input devices available on the current platform.

property VideoDeviceName (index: integer): string
Retrieves the name of the video input device whose range is index in the VideoDevices list (range = 0..VideoDevicesCount-1). See VideoDevice.

property VideoSizes: string;
List of the video sizes supported by the current video device (does not apply to DV).
This list depends of the current video device and changes when another video device is selected.
This list can be directly assigned to a comboBox. E.g. ComboBox1.Items.Text := VideoGrabber1.VideoFormats.
Select the video size by assigning its list index to the VideoSize property. E.g.: VideoGrabber1.VideoFormat := ComboBox1.ItemIndex.

property VideoSubTypes: string;
List of the video sub types supported by the current video device. The video subtype is usually the FOURCC code or the RGBnnn type.
This list depends of the current video device and changes when another video device is selected.
This list can be directly assigned to a comboBox. E.g. ComboBox1.Items.Text := VideoGrabber1.VideoSubTypes.
Select the video sub type by assigning its list index to the VideoSubType property. E.g.: VideoGrabber1.VideoSubType := ComboBox1.ItemIndex.

property VideoHeight: integer;
Returns the height of the video source, in pixels.

property VideoWidth: integer;
Returns the width of the video source, in pixels.

## Published properties

property AnalogVideoStandard: TAnalogVideoStandard;
Sets or retrieves the video standard of analog TV or composite video devices.

property Audio Compressor: integer;
Sets or retrieves the index of the active audio compressor in the AudioCompressors list. Effective only if CompressionMode is set to cm_CompressOnTheFly or cm_CompressAfterCapture and CaptureAudio is enabled.

property AudioDevice: integer;
Sets or retrieves the index of the active audio device in the AudioDevices list.

property AudioFormat: TAudioFormat;
Sets or retrieves the current audio format. The TAudioFormat enumerated type matches the AudioFormats list.

Note: the audio format is applied to DV only if type 2 capture with PCM audio compression is used.

property AutoFileName: TAutoFileName;
fn_Sequential: the file name is based on a sequential number, starting from 000001.
fn_DateTime: the file name is based on a date/time format, like yymmdd_hhmmss_zzz (zzz = milliseconds).

Note about AVI capture file name:
you can choose to force the AVI file name created by the stream capture by setting the CaptureFileName property before calling StartCapture. If CaptureFileName is left blank, a file name is generated automatically and returned by the OnCaptureCompleted event.

Note about BMP or JPEG capture file name:
you can choose to force the file name of BMP and JPEG files created by the frame capture by specifying a file name when calling the CaptureFrameTo procedure. If the file name is left blank in CaptureFrameTo, a BMP or JPEG file name is generated automatically and returned by the OnFrameCaptureCompleted event.

property AutoFilePrefix: string
Sets or retrieves a prefix string placed at the beginning of a capture file name generated automatically. Especially used to distinguish different serials of files when AutoFileName is set to fn_Sequential (e.g. when several TVideoGrabber components are used in the same app and you want to generate separated serials of files for each component).

property AutoSize: boolean;
Enables or disables the automatic resizing of the video preview window, when the video source size changes.

property AutoStartPreview: Boolean;
Automatically starts the video preview when the component is loaded. If disabled, the preview must be started later by StartPreview.

property AutoSearchNextAvailVideoDevice: Boolean;
If enabled and the current VideoDevice is is use or disconnected, TVideoGrabber tries to locate and select the next available video device. If found, the VideoDevice property is changed to the new video device selected by TVideoGrabber.
This property allows to place several TVideoGrabber components on the same form and automatically start several video capture devices, no matter to the VideoDevice property. Each TVideoGrabber component automatically starts the next available video device it finds.
Note: it may be longer to start several devices when this property is enabled and all the TVideoGrabber.VideoDevice properties are left to their default value (0), because each TVideoGrabber component tries to start the 1st video device, then the 2nd, then the 3rd, etc...

property AVI1IndexCompatibility: Boolean;
Value specifying the AVI index format. True indicates either AVI 1.0 or AVI 2.0 index format; False indicates only AVI 2.0 index format. AVI 2.0 index format allows for increased AVI file size (greater than 1 GB), hierarchical indexing, incremental growth of files, and minimal disk seeks.

property BurstCount: Integer
Sets or retrieves the number of frames to capture when calling CaptureFrameTo.
Setting BurstCount to 0 and BurstInterval to 1 will grab ALL THE FRAMES when calling CaptureFrameTo.
This parameter is ignored when BurstMode is disabled.

property BurstInterval: integer
Sets or retrieves the number of frames to skip between 2 captured frames. Set this value to 1 if you do not want to skip frames (E.g. BurstInterval = 20 means that 1 frame is grabbed every 20 frames).
This parameter is ignored when BurstMode is disabled.

property BurstMode: Boolean
Enables or disables the capture of several frames by calling CaptureFrameTo.
If disabled, only 1 frame is grabbed when calling CaptureFrameTo.
If enabled, CaptureFrameTo starts grabbing frames according to the BurstCount and BurstInterval parameters.

property BusyCursor: TCursor
Sets or retrieves the cursor displayed while the component processes significant tasks (like recompressing or copying captured data, restarting preview or capture). The BusyCursor is displayed when the process starts, and then, the NormalCursor is displayed back when the process finishes. Set BusyCursor to crDefault to disable cursor changes. In this case NormalCursor is ignored.

property CaptureAudio: Boolean;
Enables or disables the audio capture channel. If false, only the Video stream is captured.

property CaptureFileExt: string
Default extension used to create AVI files when the file name is automatically created. The default value is "avi".

property CaptureFileName: string;
Sets or retrieves the full qualified path and name of the AVI capture file to create. If the file is overwritten if it exists when the capture starts. If CaptureFileName is left blank, a file name is generated automatically according to the AutoFileName property.

property CompressionMode: TCompressionMode;
Sets or retrieves the compression mode applied to the capture:

cm_NoCompression: no compression is applied to the avi file created,
cm_CompressOnTheFly: the VideoCompressor and/or AudioCompressor are applied WHILE capturing data,
cm_CompressAfterCapture: the VideoCompressor is applied on the captured file AFTER the capture ends.

Note: this is an enumerated type of 3 elements, so, an integer value from 0 to 2 can be assigned. E.g.: VideoGrabber1.CompressionMode := TCompressionMode (RadioGroup.ItemIndex).

property CompressionType: TCompressionType
Sets or retrieves the compression type applied to the capture:

ct_Video: only the video stream is compressed by the VideoCompressor codec,
ct_Audio: only the audio stream is compressed by the Audiocompressor codec,
ct_AudioVideo: both audio and video streams are compressed by the VideoCompressor and AudioCompressor codecs.

Note: this is an enumerated type of 3 elements, so, an integer value from 0 to 2 can be assigned. E.g.: VideoGrabber1.CompressionType := TCompressionType (RadioGroup.ItemIndex).

property DVCaptureMode: TDvCaptureMode;
DV cameras produce interleaved audio-video; each frame of video also contains the audio information.
dv_CaptureType1: Includes the native interleaved data as a single stream in the AVI file, with type ivas. This is known as a type-1 file.

dv_CaptureType2: Splits the DV data into separate audio and video streams, with types auds and vids. This is known as a type-2 file.

For video capture, where maximum throughput is crucial, it is better to save the data as type-1. This is because type-2 files carry redundant data. Te type-1 format is not compatible with Microsoft® Video for Windows.

Note: compression is never applied to Type1 video capture.

property DVCaptureResolution: TDVResolution;
Sets or retrieves the size of the digital video sample captured:

dvr_default: default DV device resolution,
dvr_Dc: 88 x 66 (NTSC), 88 x 72 (PAL)
dvr_Quarter: 180 x 120 (NTSC), 180 x 144 (PAL)
dvr_Half: 360 x 240 (NTSC), 360 x 288 (PAL)
dvr_Full: 720 x 480 (NTSC), 720 x 576 (PAL).

property DVPreviewResolution: TDVResolution;
Sets or retrieves the size of the digital video sample previewed. See above.

property DVReduceFrameRate: Boolean;
Enables or disables the reduction of the frame rate. If enabled, discards half of the frames in the video stream. For NTSC, the frame rate is reduced from 30 frames per second (fps) to 15 fps. For PAL, the frame rate is reduced from 25 fps to 12.5 fps.

property FrameGrabberEnabled: Boolean;
If true, the frame grabber is inserted in the capture graph, either on the capture stream or the preview stream according to FrameGrabberOnCaptureStream. Disable the frame grabber to minimize the number of dropped frames for a given frame rate, if any. If disabled, no more frames can be captured by CaptureFrameTo.
The default value is true.

property FrameGrabberOnCaptureStream: Boolean;
If true, TVideoGrabber tries to insert the frame grabber on the capture stream, otherwise it tries to insert it on the preview stream.
If the choosen stream fails to insert the frame grabber, TVideoGrabber automatically inserts it on the other stream.
The default value is false.
Note: the frame grabber must have been enabled by FrameGrabberEnabled.

property FrameRate: Double;
Sets or retrieves the frame rate in frames per second. Does not apply to DV (see DV resolutions above).

property JPEGPerformance: TJPEGPerformance = (jpBestQuality, jpBestSpeed);
Controls the trade-off between color quality and speed of decompression of
JPEG files created by CaptureFrameTo.

property JPEGProgressiveDisplay: boolean;
Use ProgressiveDisplay to turn on or off the incremental display of an image when reading in JPEG files created by CaptureFrameTo.

property JPEGQuality: TJPEGQualityRange = 1..100;
Use CompressionQuality to set the compression quality of a JPEG image created by CaptureFrameTo. Higher compression results in a poorer picture quality, but a smaller file size.

property MaintainImageRatio: Boolean;
Maintains the image ratio of the video within the display control.

property NormalCursor: TCursor
Sets or retrieves the cursor type that is restored after a process finishes that displayed BusyCursor. If BusyCursor is left to crDefault, NormalCursor is ignored. See the BusyCursor property.

property PlayerAutoStart: Boolean;
If enabled, clips starts automatically after calling OpenPlayer. If disabled, clips are opened and immediately displayed in a paused mode.

property PlayerFileName: string;
Sets or retrieves the file name of the clip to play. Then, call OpenPlayer.

property PlayerRate: Double
Sets or retrieves the value of the player rate, used when playing a captured file or a clip (call OpenPlayer, and then RunPlayer). The value is expressed as a ratio of the normal speed. 1.0 is normal playback speed, 0.5 is half speed, 2.0 is twice speed.

property PreallocCapFileEnabled: Boolean;
Enables the pre-allocation of a capture file. For best capture results, capture to a unfragmented, pre-allocated capture file that is larger than the size of the capture data.

property PreallocCapFileName: string;
Sets or retrieves the full qualified path and name of the pre-allocated file. If left blank, a generic filename is created in the StoragePath directory. Effective only if PreallocCapFileEnabled is true.

property PreallocCapFileSizeInMB: integer;
Size of the preallocated capture file in Mb. For best results, the size should be larger than the size of the capture data. Effective only if PreallocCapFileEnabled is true.

property PreallocCapRecreate: Boolean;
If true, the preallocated file is recreated each time a capture starts. Effective only if PreallocCapFileEnabled is true.

property RefreshPreviewOnParamChange: Boolean;
If true, the previewed video is restarted each time a parameter is set.
If false, the previewed video is not refreshed when new values are assigned to the TVideoGrabber's parameters. In this case use StartPreview to apply the new parameters (it is not necessary to call StopPreview to restart the preview with StartPreview).

property RenderAudio: Boolean;
Enables or disables the audio rendering. If the audio capture device is a microphone and RenderAudio is enabled, take care to keep the microphone away from the speakers, otherwise you will get loop back echoes.

property StoragePath: string;
Sets or retrieves the full qualified path where video captures and bmp snapshots will be stored. If left blank, the default storage path is the directory.

property VCompKeyFrameRate: Integer;
Sets or retrieves then desired video compressor's key-frame rate. If the value is negative, the filter will use the default key-frame rate. If the value is zero, only the first frame will be a key frame.

property VCompQuality: Double;
Specifies the video compressor's quality as a value between 0.0 and 1.0, where 1.0 indicates the best quality and 0.0 indicates the worst quality. If the value is negative, the filter will use the default quality.

property VideoCompressor: integer;
Sets or retrieves the index of the active video format in the VideoCompressors list. Effective only if CompressionMode is set to cm_CompressOnTheFly or cm_CompressAfterCapture.

property VideoDevice: integer;
Sets or retrieves the index of the active video device in the VideoDevices list.

property VideoSize: integer;
Sets or retrieves the index of the video size in the VideoSizes list. Does not apply to DV.

property VideoSubType: string;
Sets or retrieves the index of the video subtype in the VideoSubTypes list. The list Does not apply to DV.

property Visible: Boolean;
If enabled, the preview window (or player window) is visible. Is disabled, the preview is not visible, but capture can be started and frames can be grabbed if the graph has not been shut down by the ShutDownGraph procedure.

## Events

property OnCaptureCompleted (Sender: TObject; FileName: string; Succeeded: Boolean);
Occurs after a StopCapture call, when the process is fully completed (with or without success).
FileName returns the file name of the AVI file. Useful to know the file name automatically generated if CaptureFileName was left blank before calling StartCapture.

property OnCaptureProgress (FDroppedFrames, FDeliveredFrames: integer);
Occurs while previewing or capturing streams. Returns the number or delivered frames (and possibly dropped frames) since the last preview start or capture start.

property OnCaptureReadyToStart (Sender: TObject; var OkToStart: Boolean);
Occurs after calling StartCapture, when the capture is really ready to start writing data to disk. Use this event to accurately start capturing data, e.g. using a MessageDlg box like "start capture now?". At this point the capture can be cancelled by setting OkToStart = false.

property OnCaptureStarted (Sender: TObject);
Occurs when the capture starts writing captured data to the disk.

property OnChangeAudioDevice (Sender: TObject);
Occurs when a new device is selected (or disconnected).

property OnChangeVideoDevice (Sender: TObject);
Occurs when a new device is selected (or disconnected).

property OnComponentLoaded (Sender: TObject);
Occurs immediately after starting the application, when the component is fully loaded and ready to accept commands.

property OnCopyPreallocDataCompleted (Sender: TObject; Succeeded: Boolean);
Occurs when the valid data has been fully copied from the pre-allocated file to a new file. As a result, the new file can be much smaller than the preallocated file.

property OnCopyPreallocDataStarted (Sender: TObject);
Occurs when the valid data is about to be copied from the pre-allocated file.

property OnCreatePreallocFileCompleted (Sender: TObject; Succeeded: Boolean);
Occurs when the pre-allocated file is created.

property OnCreatePreallocFileStarted (Sender: TObject);
Occurs when the pre-allocated file is about to be created.

property OnDeviceArrival (Sender: TObject);
Occurs when a video or audio device is connected.

property OnDeviceLost (Sender: TObject);
Occurs when the video or audio device currently previewing or capturing is disconnected.

property OnDeviceRemoval (Sender: TObject);
Occurs when the current video or audio device is disconnected.

property OnDirectX8Required (Sender: TObject);
Occurs while the component is loading if DirectX8 is not installed on the current platform. DirectX8 or above is required by TVideoGrabber.

property OnDiskFull (Sender: TObject);
Occurs when no more disk space is available while capturing data or recompressing a file. The detection level is 25 Mb free.

property OnErrorLog (Sender: TObject; ErrorCode: Integer; ErrorMsg: String);
Returns error messages with their associated code.

property OnFrameCaptureCompleted (Sender: TObject; DestType: TFrameCaptureDest; FileName: string; Succeeeded: Boolean);
Occurs after a call to CaptureFrameTo when the frame is available as a memory bitmap, a BMP file or a JPEG file, according to the DestType value, initially specified in the CaptureFrameTo procedure call. If FileName was left blank when calling CaptureFrameTo, a file name is automatically generated and returned by this event.

property OnFullScreenKeyPress (Sender: TObject; var Key: Char);
Occurs when pressing a key while displaying in full screen mode. Allow to associate commands with keyboard keys (ESC is reserved to the exit from the full screen mode).

property OnNoVideoDevices (Sender: TObject);
Occurs if there is video device available when the component loads.

property OnPlayerCompleted (Sender: TObject; Succeeded: Boolean);
Occurs when a playback ends. Returns true on success.

property OnPlayerEndOfStream (Sender: TObject);
Occurs when end of the clip currently playing is reached.

property OnPlayerFileNotFound (Sender: TObject; FileName: string);
Occurs if the play back file invoked by StartPlayBack is not found.

property OnPlayerStarted (Sender: TObject);
Occurs when a file playback starts.

property OnPreviewStarted (Sender: TObject);
Occurs when the preview is active.

property OnRecompressCompleted (Sender: TObject; Succeeded: Boolean);
Occurs when a video file stream recompression ends. Returns true on success.

property OnRecompressStarted (Sender: TObject);
Occurs when a video file stream recompression starts.

property OnResizeVideo (Sender: TObject; FVideoWidth, FVideoHeight: integer);
Occurs when the size of the video source changes.

property OnTimeCodeReader (Sender: TObject; TrackNum: integer; hh, mm, ss, ff: integer);
Occurs when time code is read from devices like a camcorder.

## Enumerated Types

TAutoFileName = (fn_Sequential, fn_DateTime);
See the AutoFileName property.

TCompressionMode = (cm_NoCompression, cm_CompressOnTheFly, cm_CompressAfterCapture);
See the CompressionMode property.

TCompressionType = (ct_Video, ct_Audio, ct_AudioVideo);
See the CompressionType property.

TCurrentState = (cs_Down, cs_Preview, cs_Capture, cs_Playback, cs_Compress);
See the CurrentState property.

TDVCaptureMode = (dv_CaptureType1, dv_CaptureType2);
See the DvCaptureMode property.

TDialog = (
dlg_Capture,
dlg_Compressor,
dlg_StreamConfig,
dlg_ProcAmp,
dlg_VfwFormat,
dlg_vfwSource,
dlg_vfwDisplay,
dlg_vfwCompressor,
dlg_Crossbar,
dlg_TVTuner,
dlg_TVAudio,
dlg_Audio
);
See the ShowDialog procedure.

TDvCommand = (
dv_Play,
dv_Stop,
dv_Freeze,
dv_FF,
dv_Rew,
dv_Record,
dv_RecordFreeze,
dv_StepFwd,
dv_StepRev,
dv_PlayFastestFwd,
dv_PlaySlowestFwd,
dv_PlayFastestRev,
dv_PlaySlowestRev);
See the SendDVCommand function.

TDVResolution = (dvr_default, dvr_Dc, dvr_Quarter, dvr_Half, dvr_Full);
See the DVCaptureResolution and DVPreviewResolution properties.

TFrameCaptureDest = (fc_TBitmap, fc_BmpFile, fc_JpegFile);
See the CaptureFrameTo procedure.

TAnalogVideoStandard = (
AnalogVideo_None,
AnalogVideo_NTSC_M,
AnalogVideo_NTSC_M_J,
AnalogVideo_NTSC_433,
AnalogVideo_PAL_B,
AnalogVideo_PAL_D,
AnalogVideo_PAL_H,
AnalogVideo_PAL_I,
AnalogVideo_PAL_M,
AnalogVideo_PAL_N,
AnalogVideo_PAL_60,
AnalogVideo_SECAM_B,
AnalogVideo_SECAM_D,
AnalogVideo_SECAM_G,
AnalogVideo_SECAM_H,
AnalogVideo_SECAM_K,
AnalogVideo_SECAM_K1,
AnalogVideo_SECAM_L,
AnalogVideo_SECAM_L1,
AnalogVideo_PAL_N_COMBO);
See the AnalogVideoStandard property.

TAudioFormat = (
af_default,
af_8000_8b_1ch,
af_8000_8b_2ch,
af_8000_16b_1ch,
af_8000_16b_2ch,
af_11025_8b_1ch,
af_11025_8b_2ch,
af_11025_16b_1ch,
af_11025_16b_2ch,
af_12000_8b_1ch,
af_12000_8b_2ch,
af_12000_16b_1ch,
af_12000_16b_2ch,
af_16000_8b_1ch,
af_16000_8b_2ch,
af_16000_16b_1ch,
af_16000_16b_2ch,
af_22050_8b_1ch,
af_22050_8b_2ch,
af_22050_16b_1ch,
af_22050_16b_2ch,
af_24000_8b_1ch,
af_24000_8b_2ch,
af_24000_16b_1ch,
af_24000_16b_2ch,
af_32000_8b_1ch,
af_32000_8b_2ch,
af_32000_16b_1ch,
af_32000_16b_2ch,
af_44100_8b_1ch,
af_44100_8b_2ch,
af_44100_16b_1ch,
af_44100_16b_2ch,
af_48000_8b_1ch,
af_48000_8b_2ch,
af_48000_16b_1ch,
af_48000_16b_2ch);
See the AudioFormat and AudioFormats property.

Quick Start guide

. look at the SimpleDemo project included in the package. It illustrates well the basic features of TVideoGrabber.

. a bit more complex, the Demo project includes near all of the possibilities of TVideoGrabber.

DESIGN MODE:

The TVideoGrabber component does not display anything in design mode. The video is previewed only at runtime.

HOW TO SELECT VIDEO DEVICES, AUDIO DEVICES, COMPRESSORS:

The explanations below (about video devices) are the same for audio devices, video compressors and audio compressors.

- video input devices can be selected by assigning a number to the VideoDevice property (index),

- the video input devices list is available in the VideoDevices string property. This list can be directly assigned to a TListBox, TComboBox, TMemo, etc...
E.g. ComboBox1.Items.Text := VideoGrabber1.VideoDevices (see the SimpleDemo project).

- the number of video input devices is available through the VideoDevicesCount property,

- the name of an individual video input device is available through the VideoDeviceName (Index) property. Index is the position of the device in the VideoDevices list. The index range is 0 to VideoDevicesCount - 1.

- FAQ

Q: My project runs fine out of the IDE, but when I run it from the IDE, an exception error occurs a CPU-window screen appears that shows 80x86 assembly.

A: This is a know bug of Voxware audio codecs when running a debug build of an application that enumerate audio codecs.
To avoid this problem while debugging a project, rename the vct3216.acm file located in your system directory (winnt\system32 or windows\system32). The Voxware audio codecs will no longer appear in the audio compressors list, and you will be able to debug the application.
If the problem is not solved after renaming this file, try to do the same with the vct3216.dll and/or MSMS001.vwp files.

Q: My project crashes when closing the form.

A: according to the way you use forms, the FormClose and FormCloseQuery events of the TVideoGrabber's form may not be called when closing the project, well, TVideoGrabber hooks these events to intercept the "form close" request and cleanly stop and free the current graph.
To fix the problem, change the main form FormClose code as following (let's say that the main form is named MainForm and the TVideoGrabber form is named VidGrabForm):
procedure TMainForm.FormClose(Sender: TObject; var Action: TCloseAction);
begin
if MessageDlg('Quit project?' , mtConfirmation, [mbYes, mbNo], 0) = mrYes then begin
VidGrabForm.Close;
end
else begin
Action := caNone;
end;
end;

Q: I get an abnormal number of dropped frames when I start the video capture.

A: Take a look at your StoragePath property, especially if you run your app including TVideoGrabber from a network drive. The default storage path where TVideoGrabber writes its capture files is the app's start directory. If the app is launched from a network drive, the capture file may be located on this drive, slowering excessively the capture process.
In a general way, the StoragePath directory must be located on a fast disk drive.
When starting video capture, TVideoGrabber checks if the storage path is located on a network drive or a removable drive and returns a warning.

Q: I am trying to capture all the frames. I am using a timer to call CaptureFrameTo(fc_MemoryBitmap, '').
I tried to use the BustMode settings (BurstInterval = 1, BurstCount = 0 and BurstMode = true), but the onFrameCaptureCompleted is only fired once and no more.

A: To capture frames continuously, CaptureFrameTo must be call one time after setting the correct Bust... parameters. Proceed as following:

- set BurstInterval = 0 (to get all the frames),
- set BurstCount = 0 (means that you do not want to stop grabbing frames),
- set BurstMode = true (to activate it),
- call CaptureFrameTo only 1 time.

Starting from this point all the frames will be reported by the OnFrameCaptureCompleted event until you set BustMode to False or the graph is restarted (note that changing a parmeter can dynamically restart the graph if RefreshDisplayOnParamChange is enabled).

Sample code is included in the OnClick event of the "dont' stop grabbing" button in the "Frame capture" groupbox of the demo project.

Q: I get an error when opening mpeg clips. Nothing is displayed.

A: 2 possibilities:

1. the codec required by your clip is not installed on your platform. To check that, try to open the clip with the Windows Media Player.
- if the media player reports an error, try to find and install the required codec.
- if the media player downloads and install automatically the codec, and then, plays the clip, try again to open the clip with TActiveMovie.

2. errors when opening clips are often caused by bugs in third-party codecs. Try to open the clip in the Windows Media Player. If the clip don't work in the WMP as well, and you have additional(s) codec(s) installed, remove it(them) and try again.

Q: I am trying to install the demo version of TVideoGrabber for Delphi 5.0. The error message I get is : rtl60.bpl could not be found. It looks to me that I have a Delphi 6 version of the program.

A: this problem usually occurs when unzipping the package if the unzip tool does not recreate the Delphi and C++Builder directory structures contained in the package. In this case the different versions of the component overwrite themselves while unzipping.

If you are using WinZip, check that the "use folder names" checkbox is enabled before extracting the files.

Q: I loaded up the demo for TVideoGrabber in Delphi 6 Trial and tried to build it.
I am getting the following error: Access violation at address 009807e7 in module dcc60.dll read of address 000E9c6.

A: The trial version comes with a different DCU format than the real one. TVideoGrabber or other third-party components can't be used in the trial.

### License Agreement

Copyright

All DelphiCity Software components are copyrighted and shall remain the exclusive property of the author.

Agreement

By installing this software you agree with:
- You may not use the source code in this package to create competitive software product.
- You may not manipulate any binary files included or generated by Delphi/C++Builder using the package.
- You may not distribute source code or registered version to non registered people.

Registered versions license statement

This software and any accompanying documentation are protected by copyright law and by International Treaty provisions.
Any use of this software in violation of copyright law or the terms of this agreement will be prosecuted to the best of the author's ability.
You are hereby authorized to make archival copies of this software for the sole purpose of back-up and protecting your investment from loss.
Under no circumstances may you copy this software or documentation for the purposes of distribution to others. Under no conditions may you remove the copyright notices made part of the software or documentation.

Distribution Rights

You are granted a non-exclusive, royalty-free right to produce and distribute executable binary files (executables, DLLs, etc.) that are built with the registered version of the software unless specifically stated otherwise.

Restrictions

Without the express prior written consent of the author, you may not distribute any of the author's commercial source code, compiled units or documentation by any means whatsoever. You may not transfer, lease, lend, copy, modify, translate, sublicense, time-share, or electronically transmit or receive the software or documentation.

Upgrade

The upgrade version of the software constitutes a single product of the author's software that you upgraded. For example, the upgrade and the software that you upgraded cannot both be available for use by two different people at the same time, without written permission from the author.

Disclaimer

The Author cannot and does not warrant that any functions contained in the Software will meet your requirements, or that its operations will be error free. The entire risk as to the Software performance or quality, or both, is solely with the user and not the Author. You assume responsibility for the selection of the component to achieve your intended results, and for the installation, use, and results obtained from the Software.
The Author makes no warranty, either implied or expressed, including without limitation any warranty with respect to this Software documented here, its quality, performance, or fitness for a particular purpose. In no event shall the Author be liable to you for damages, whether direct or indirect, incidental, special, or consequential arising out the use of or any defect in the Software, even if the Author has been advised of the possibility of such damages, or for any claim by any other party.
All other warranties of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose, are expressly excluded.