INSTALLATION

OVERVIEW OF THE MAJOR  METHODS, PROPERTIES AND EVENTS, BY CATEGORY

Preview
AVI capture
Frame capture
Auto-generated file names
DV (Digital Video)
Video device
Audio device
Playback
Drawing over frames
Third-party filters
Transparency
Miscellaneous

HOW DOES IT WORK

Frame capture
Video format
Avoiding dropped frames
Writing text over frames
Drawing shapes over frames
Audio/video compression
Interactive vs. programmatically use
Device-dependent parameters
Component dynamically created at runtime
Player
Third-party filters
Transparency
ProVideo multi-ports capture card SDK

 

METHODS AND FUNCTIONS

PUBLIC PROPERTIES

PUBLISHED PROPERTIES

EVENTS

event OnCaptureCompleted
event OnCaptureReadyToStart
event OnCaptureStarted
event OnChangeAudioDevice
event OnChangeVideoDevice
event OnColorKeyChange
event OnComponentLoaded
event OnCopyPreallocDataCompleted
event OnCopyPreallocDataStarted
event OnCreatePreallocFileCompleted
event OnCreatePreallocFileStarted
event OnDeviceArrival
event OnDeviceLost
event OnDeviceRemoval
event OnDiskFull
event OnDrawOverFrame
event OnErrorLog
event OnFrameCaptureCompleted
event OnFrameProgress
event OnFullScreenKeyPress
event OnNoVideoDevices
event OnPlayerEndOfStream
event OnPlayerFileNotFound
event OnPlayerStarted
event OnPreviewStarted
event OnRecompressCompleted
event OnRecompressStarted
event OnResizeVideo

TV TUNER functions

ANALOG VIDEO DECODER functions

Structures returned by events

TFrameData
TFrameInfo

Enumerated Types

TAudioFormat
TAutoFileName
TCompressionMode
TCurrentState
TDialog
TFrameCaptureDest
TVideoQuality

 

Gobal variables

CleanTVideoGrabberRegistryOnExit: boolean;
CodecsDisabledFromIDE: boolean;
RegKeyId: string;
RegistryUpdateErrorMsg: string;
VfwDriversEnabled: boolean;

 

INSTALLATION

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

- Components | Install Packages
- Click on "DataStead 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 Borland's search paths.

2.  Install the current package:

- Unzip the archive in a folder of your choice (e.g. c:\vidgrab). Be sure to unzip the full directory structure (with WinZip check "folders names" ).

- according to your version of Delphi/C++Builder, copy all the Delphi\*.* or CBuilder\*.* files to your \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 C++Builder:
Go to Project | Options | Packages and uncheck "Build with runtime packages", or keep it checked but remove "TVidGrab" at the end of the package list, otherwise you will get a "TVidGrab.bpi file not found at build time.

OVERVIEW OF THE MAJOR METHODS, PROPERTIES AND EVENTS, BY CATEGORY

Notes:
- most of the preview properties are used during the AVI capture
- the Frame Capture methods and properties can be used during Preview as well as AVI capture

Preview

General

procedure StartPreview;
procedure StopPreview;
property AutoStartPreview; boolean;

property Visible: boolean;

property RefreshPreviewOnParamChange: boolean;

property OnFrameProgress (Sender: TObject; FrameInfo: TFrameInfo);
property OnPreviewStarted (Sender: TObject);

Overlay

property OverlayEnabled: boolean;
property IsOverlayAvailable: boolean; (device dependant)

Window Size

property VideoHeight: longint;
property VideoWidth: longint;

property PreviewZoomSize: longint;

property AutoSize: boolean;
property MaintainImageRatio: boolean;

property FullScreenPreview: boolean;
property OnFullScreenKeyPress (Sender: TObject; var Key: Char);

property OnResizeVideo (Sender: TObject; FVideoWidth, FVideoHeight: longint);

property ImageRatio: double;

 

AVI Capture

General

procedure StartCapture;
procedure StopCapture;

property CaptureAudio: boolean;

property OnCaptureCompleted (Sender: TObject; FileName: string; Succeeded: boolean);
property OnFrameProgress (Sender: TObject; FrameInfo: TFrameInfo);
property OnDiskFull (Sender: TObject);

property FrameBuffers: longint;

AVI file name

property Last_AVICapture_FileName: string;
property StoragePath: string;

property AutoFileName: TAutoFileName;
property AutoFilePrefix: string;

property CaptureFileExt: string;
property CaptureFileName: string;

AVI compression

property CompressionMode: TCompressionMode;
property CompressionType: TCompressionType;

property VideoCompressor: longint;
property VideoCompressors: string;
property VideoCompressorsCount: longint;

property AudioCompressor: longint;
property AudioCompressors: string;
property AudioCompressorsCount: longint;

procedure ShowDialog (dlg_Compressor);

property OnRecompressCompleted (Sender: TObject; Succeeded: boolean);
property OnRecompressStarted (Sender: TObject);

Preallocated huge file

property PreallocCapFileEnabled: boolean;
property PreallocCapFileName: string;
property PreallocCapFileSizeInMB: longint;
property PreallocCapFileRecreate: boolean;

property OnCopyPreallocDataCompleted (Sender: TObject; Succeeded: boolean);
property OnCopyPreallocDataStarted (Sender: TObject);
property OnCreatePreallocFileCompleted (Sender: TObject; Succeeded: boolean);
property OnCreatePreallocFileStarted (Sender: TObject);

 

Frame Capture

Auto-generated  file names  (AVI capture and frame capture)

General

property AutoFileName: TAutoFileName;
property AutoFilePrefix: string;

 

DV (Digital Video)

General

function  SendVCRCommand  

property IsDigitalVideoIn: boolean;
property DVRgb219: boolean;
property DVReduceFrameRate: boolean;
property DVNativeInterleavedToAVI: boolean;

property DVUseExternalAudio: boolean ;

Time code

property IsTimeCodeReaderAvailable: boolean;
property OnFrameProgress (Sender: TObject; FrameInfo: TFrameInfo); (time code returned within the FrameInfo record. See OnFrameProgress.

Video device

TVideoGrabber keeps and restores the current values for each device if StoreDeviceSettingsInRegistry is enabled.

The video device settings and properties noted by an asterisk (*) are device-dependant. So, the values change when the video device change. The best location to retrieve the new values for the current video device is from the OnChangeVideoDevice event. 

General

property VideoDevice: longint;
property VideoDevices: string;
property VideoDevicesCount: longint;

* property FrameRate: double;
property CurrentFrameRate: double;

procedure ShowDialog (dlg_Device);
procedure ShowDialog (dlg_StreamConfig);

property StoreDeviceSettingsInRegistry: boolean;

event OnChangeVideoDevice (Sender: TObject);
event OnNoVideoDevices (Sender: TObject);
event OnDeviceArrival (Sender: TObject);
event OnDeviceLost (Sender: TObject);
event OnDeviceRemoval (Sender: TObject);

Crossbar (Tuner, S-Video, Composite, etc...)

procedure ShowDialog (dlg_VideoCrossbar);

* property VideoCrossbarInput: longint;
* property VideoCrossbarInputs: string;
* property VideoCrossbarInputsCount: longint;
* property IsVideoCrossbarAvailable: boolean;

Frame size (320x240, 640x480, etc...)

* property VideoSize: longint;
* property VideoSizes: string;

Media subtypes (YUV2, I420, RGB24, RGB555, etc...)

* property VideoSubType: longint;
* property VideoSubTypes: string;

Analog video standard (NTSC, PAL, etc...)

* property AnalogVideoStandard: longint;
* property AnalogVideoStandards: string;
* property IsAnalogVideoDecoderAvailable: boolean;

TV

procedure ShowDialog (dlg_TVTuner);
function TVPutChannel ...
* function TVGetChannel ...
* property IsTVTunerAvailable: boolean;

Audio device

General

event OnChangeAudioDevice

property AudioDevice: longint;
property AudioDevices: string;
property AudioDevicesCount: longint;

property RenderAudio: boolean;
property CaptureAudio: boolean;

property AudioFormat: TAudioFormat;
property AudioVolume: longint;

Audio input

property AudioInputs: string;
property AudioInputsCount: longint;
property AudioInput: integer;
property AudioInputLevel: longint;

 

PLAYER

Drawing over frames

Transparency

Third-party filters

Miscellaneous

event  OnErrorLog (Sender: TObject; ErrorCode: longint; ErrorMsg: string);
property IsDirectX8OrHigherInstalled: boolean;

HOW DOES IT WORK

Video preview

- the preview is started by StartPreview and stopped by StopPreview. 

The preview is done by default in a window derived from a TPanel. The borders can be disabled by setting BorderStyle to BsNone, and by setting BevelInner and BevelOuter to bvNone.

It is possible to attach/detach the video window with  AttachVideoWindow and DetachVideoWindow.

The preview can be switched to full screen mode by enabling  FullScreenPreview. 

- during the preview, each frame is reported by the OnFrameProgress event.

To start the preview automatically at run time, enable the AutoStartPreview property or call StartPreview from the OnComponentLoaded event.

Video capture

- the AVI capture is started by StartCapture and stopped by StopCapture.

- during the AVI capture, each frame is reported by the OnFrameProgress event.

You are notified of the end of the AVI capture by the OnCaptureCompleted event.

Frame capture:

The frame capture is enabled by FrameGrabberEnabled.

Whatever you are in preview mode, AVI capture mode or playback mode, TVideoGrabber can capture frames one by one (snapshot mode) using CaptureFrameTo, or automatically using BurstMode, BurstType, BurstCount and BurstInterval. 

The MainDemo project shows how to capture frames one by one or in burst mode. The QuickStartDemo project included in the package shows how to capture continuously all the frames, returns them as TBitmap and display them in a contiguous TImage component.

In all cases the frames captured are returned 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.
In "one shot mode", it  is passed as "Dest" parameter when calling CaptureFrameTo,
In burst mode, it is passed as "BurstType" property.

For BMP or JPEG files:
- in one shot mode using CaptureFrameTo, you can pass the file name to assign to the captured frame,
- in burst mode  the file name is generated automatically according to the StoragePath, AutoFileName and AutoFilePrefix properties. 

To be able to capture frames without previewing the video, simply disable the Visible property, because stopping the preview stream using StopPreview will stop the frame grabber as well.

Note: the component can be used without Form and without Parent. Look at the NonVisible demo project included in the package.

- be careful not to save the AVI to a slow drive (mapped network drive, etc...).

Writing text over frames

To write text over frames:

- set the TextOnFrameString property with the text string to write. Some variables names are accepted. See TextOnFrameString for more information,
Look also at the MainDemo project to get sample code.

- choose the font size and color using the TextOnFrameFont property,

- if you want the text to be transparent, enable the TextOnFrameTransparent property, otherwise set the TextOnFrameBkColor with a background color,

- choose the alignment of the text using the TextOnFrameAlign property. See TextOnFrameAlign for more information,

- position the text over the frame using TextOnFrame_Left, TextOnFrame_Right and TextOnFrame_Top properties. 
If you want the text to be aligned to  the right and/or bottom of the video, use the VideoWidth and VideoHeight properties.

- enable the TextOnFrameEnabled property to get the text displayed over frames.

Drawing shapes over frames

TVideoGrabber is able do draw geometrical shapes over frames (rectangle, square, circle, ...). If both text and shape are drawn on the same area, the text is written over the shape.

To avoid defining redundant properties, TVideoGrabber uses an external TShape VCL component to define the shape properties. 

So, you have to create this TShape component, define its properties and assign it to the TVideoGrabber's ShapeOnFrame property. The TShape component can be took on the component palette and placed on a form, or dynamically created at runtime.

TShape component placed on a form at design time:

- put a TShape component anywhere on your  form (this component will not be visible at runtime).

- assign the TShape component to the ShapeOnFrame property,

- define the shape properties of the component (color, background, aspect...). You can also define the Width and Height, but DO NOT DEFINE the Left and Top properties. Let it at the place where you put it on the form.

- at runtime, define the Left and Top properties, and if necessary the Width and Height. 
These 4 properties are used by TVideoGrabber to position and size the shape over the video.

- to draw the shape over the frame enable the ShapeOnFrameEnabled property.

TShape component dynamically created at runtime:

Here is some sample code that draws a stripped circle over frames:

procedure TForm1.Button1Click(Sender: TObject);
var
   VideoShape: TShape;
begin
   VideoShape := TShape.Create (Self);
   VideoShape.Left := 10;
   VideoShape.Top := 10;
   VideoShape.Width := 140;
   VideoShape.Height := 100;
   VideoShape.Brush.Color := clAqua;
   VideoShape.Brush.Style := bsBDiagonal;
   VideoShape.Pen.Style := psClear;
   VideoShape.Shape := stCircle;
   VideoGrabber1.ShapeOnFrame := VideoShape;
   VideoGrabber1.ShapeOnFrameEnabled := CheckBox11.Checked;
end;

audio/video compression:

The codecs returned by TVideoGrabber are those available on the current platform. 

TVideoGrabber automatically saves and retrieves the current settings of each codec. The current states are saved in the RegKeyId registry key string that you can change to the key name of your choice.

For the best capture quality, we recommend to use the Microsoft's MPEG-4 codec. The DivX codec gives similar results, but it is not free for commercial use.

The Microsoft's MPEG-4 codec, is available from  http://www.microsoft.com -> Downloads | Download Center | Windows Media Player Codecs.
DivX codec is available for download at http://www.divx.com/download/index.php. 

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. 

If you do not use video compression, the capture will require a high disk availability because the data flow is very important. In this case prefer NTFS partitions and avoid having other software requiring disk access (e.g. disk backup) during the AVI capture, otherwise you could get dropped frames.

Note: some third-party codecs (like Voxware audio codecs) have internal bugs that cause Delphi to pause on unwanted breakpoints when running a project from the IDE (no problem out of the IDE). Although it is just necessary to press F9 several times to go on, if you are worried by these unwanted breakpoints, you can temporarily disable the codecs from the IDE using the global variable CodecsDisabledFromIDE.

Interactive versus programmatically 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 RefreshPreviewOnParamChange is enabled, allowing to preview the changes in real time. However, this behavior does not apply to the AVI capture.

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

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

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.

Device-dependent parameters:

The following parameters are device-dependent. For this reason, and to avoid having to handle the complexity of saving them, TVideoGrabber is able to save them automatically for each video device separately if StoreDeviceSettingsInRegistry is enabled.

The device dependent parameters are changed by TVideoGrabber each time another device is selected by assigning the VideoDevice property. When the new parameters have been reloaded by TVideoGrabber, the OnChangeVideoDevice event occurs. Use this event to refresh your settings if necessary (look at the MainDemo project for sample code).

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 a platform to the other:

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

Parameters whose values change from a device to the other:

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

Note: 
- these lists are strings that can be directly assigned to list-based components. E.G.:
ComboBox1.Items.Text := VideoGrabber1.VideoSizes;

- these lists can be assigned to lists to get the number of available items. E.g.:

var
    TheList: TStringList;
   ItemCount: integer;
begin
   TheList := TStringList.Create;
   TheList.Text := VideoGrabber1.VideoSizes;
   ItemNumber := TheList.count;
   TheList.Free;
end;

Component dynamically created at runtime

To create the component:

- call the create method of the component,
- set its Parent property,
- set all the required properties and events,
- call the DynamicallyCreated method

To destroy the component:

- call its Free method.

See the NonVisible project demo and the DynamicallyCreated method for sample code.

PLAYER:

The TVideoGrabber's embedded player allows to playback AVI or MPEG clips  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.

Third-party filters:

Transparency:

ProVideo multi-ports capture card SDK:

function CaptureFrameTo (Dest: TFrameCaptureDest;
Captures the current frame to a memory Bitmap, a BMP file or a JPEG file, according to the Dest parameter.
The captured frame is returned by the OnFrameCaptureCompleted event. 

To capture a frame to a TBitmap:
    - call CaptureFrameTo (fc_TBitmap);
    - the frame is returned by the OnFrameCaptureCompleted event. 

procedure ClosePlayer;
Closes the current clip, if opened.

procedure DynamicallyCreated;
If you dynamically create the component at runtime, call this procedure after all the parameters have been set. E.g.:

if not assigned (VGrab) then begin
   VGrab := TVideoGrabber.Create (Self);
   VGrab.Parent := Self;
   VGrab.Visible := False;
   VGrab.OnChangeVideoDevice := ChangeVideoDevice;
   VGrab.OnFrameCaptureCompleted := OnFrameCaptureCompleted;
   VGrab.VideoDevice := 0;

   VGrab.DynamicallyCreated;
end;

DataRate: retrieves the output data rate.
KeyFrameRate: The key-frame rate is the number of frames per key frame. For example, if the rate is 15, then a key frame occurs every 15 frames.
PFramesPerKeyFrame: P frames are used only in MPEG compression. E.g. let's say a key frame occurs once every 10 frames, and there are three P frames per key frame. The P frames will be spaced evenly between the key frames. The remaining six frames are bi-directional (B) frames.
WindowSize: retrieves the number of frames over which the compressor will maintain the average data rate. E.g. if a data rate of 100K/sec and a frame rate of 10 frames per second, if the window size is 1, then every frame will be 10K or less. If the window size is 5, then every five consecutive frames will average 10K per frame, but individual frames may exceed this size.
Quality: The quality is expressed 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. 

CanCrunch: the compressor can compress video to a specified data rate (see DataRate above).
CanKeyFrame: the compressor supports the KeyFrame property above.
CanBFrame: the compressor supports the PFramesPerKeyFrame property above.
CanWindow: the compressor supports WindowSize property above. 
CanQuality: the compressor supports Quality property above. 

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

procedure PauseCapture;
Pauses the AVI capture started by StartCapture. The AVI capture can be resumed by ResumeCapture.
Note: this feature is not available if capturing both audio and video. 

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