Recording methods and properties

Recording overview.

Description

Video and audio capture devices
- if AudioRecording is disabled, only the VideoDevice video source (chosen in the VideoDevices list) will be recording to the file.
- if AudioRecording is enabled, the current VideoDevice and the current AudioDevice (chosen in the AudioDevices list) will be captured.
- if the audio and video capture devices are different and the audio of the video clip recorded is not in sync with the video, enable AudioSyncAdjustmentEnabled and adjust the number of audio samples to delay with AudioSyncAdjustment.

Video format

The video format is determined by the extenstion of the RecordingFileName
E.g. to record a MP4 video set .mp4 as extension, to record a Matroska video set .mkv as extention.

If the file name is generated automatically, specify the video format with the RecordingMethod, e.g.

RecordingMethod = rm_MP4 will record a ".mp4" video clip.

RECORDING BY USING THE DATASTEAD ENCODER (recommended)

See Recording through the Datastead Encoder

RECORDING BY USING THIRD-PARTY CODECS

- select the third-party codec by its name, e.g.:

- set VideoCompressor = VideoCompressorIndex ("x264vfw - H.264/MPEG-4 AVC codec")
- set CompressionMode = cm_CompressOnTheFly

Starting the recording immediately

- once the settings above applied, invoke StartRecording()

Starting the recording preview but not writing immediately to the file

- once the settings above applied:

- set HoldRecording = true

- invoke StartRecording()

this starts the video preview and recording but does not write yet to the file.

- later, to begin writing to the file, invoke ResumeRecording()

Stopping writing to the current file and starting writing to a new file while the recording is running

Invoke RecordToNewFileNow

Stopping the recording

- invoke Stop()

Delayed start/stop
The RecordingTimer property lets you start, stop or restart preriodically the recording after an interval of time:
RecordingTimer = rt_Disabled : normal start/stop
RecordingTimer = rt_RecordToNewFile : a new recording file is generated each RecordingTimerInterval seconds
RecordingTimer = rt_StopRecording : the recording will stop after RecordingTimerInterval seconds
RecordingTimer = rt_StartRecording : the recording starts in preview mode only, the real recording will begin after RecordingTimerInterval seconds

Creating a new video clip on the fly
While the recording is running, invoke RecordToNewFileNow (NewFileName, true) and a new video clip will be created.
- either pass the new file name to be created, either pass an empty string to let TVideoGrabber generate the new file name automatically, according to the AutoFileName settings.

To create small video clips having the same duration:
- set RecordingTimerInterval to the desired period (expressed in seconds)
- set RecordingTimer = rt_RecordToNewFileNow

Note that this feature is not compatible with:
- the recompression after recording (be sure that you use CompressionMode = cm_NoCompression or cm_CompressOnTheFly),
- the use of a preallocated recording file (be sure that PreallocCapfileEnabled = false)

Specifying a maximum file size

To limit the recording file size, specify a RecordingFileSizeMaxInMB value > 0.
During the recording, each time the size specified is exceeded, a new file is generated on the fly, according to the auto file name settings.

Holding the beginning of the recording for an accurate recording start time
By default, when invoking StartRecording the recording starts immediately, but building the recording graph requires a few seconds, so the moment when the recording starts after invoking StartRecording is never accurate.
To avoid this problem, enable the HoldRecording property before invoking StartRecording.

When HoldRecording is enabled, the recording graph is built, and then the OnRecordingReadyToStart event occurs.
When this event occurs, you can invoke ResumeRecording to really start the recording, or StopRecording to cancel it.
E.g.:
...
procedure TForm1.Button1Click (Sender: TObject);
begin
VideoGrabber1.HoldRecording := True;
VideoGrabber1.StartRecording;
end;
...
procedure TForm1.VideoGrabberRecordingReadyToStart(Sender: TObject);
begin
if ConditionToStartRecording then begin
VideoGrabber.ResumeRecording;
end
else begin
VideoGrabber.StopRecording;
end;
end;

Recording file name
The recording file name can be chosen by assigning the RecordingFileName property before invoking StartRecording.
If RecordingFileName is left blank, a file name is generated automatically according to the AutoFileName, AutoFileNameDateTimeFormat, AutoFileNameMinDigits, AutoFilePrefix and CaptureFileExt properties.

By example if you customize the file name as follows:
VideoGrabber.AutoFileName = fn_DateTime;
VideoGrabber.AutoFileNameDateTimeFormat = "dd-mm-yy_hh-mm-ss"
VideoGrabber.AutoFilePrefix = "file_"
the recording file name will be file_13-02-13_15-27-45.avi

As soon as recording begins, this file name can be retrieved with Last_Recording_FileName.
When the recording ends, this file name is returned by the OnRecordingCompleted event.

Current file size of the video clip beeing recorded

The RecordingKBytesWrittenToDisk reports the current (growing) file size in KB while the recording is running.
Invoke this function periodically (e.g. every 10 seconds) to retrieve on the fly the current file size of the video clip being recorded.
When the recording ends, invoke RecordingKBytesWrittenToDisk from the OnRecordingCompleted event to get the final file size of the recorded clip.

You can find the corresponding sample code in the OnFrameProgress event of the MainDemo project.

Pausing / resuming the AVI recording
See AVI pause/resume during recording

Events
- if HoldRecording is enabled, when invoking StartRecording the OnRecordingReadyToStart event occurs, and then you can invoke ResumeRecording to really start to record.
- when the recording really begins, the OnRecordingStarted event occurs,
- when the recording ends, the OnRecordingCompleted event occurs.

Frame capture
It is possible to capture frames during recording when the frame grabber is enabled. See the Frame Capture chapter.

Frame overlay
It is possible to perform graphics or text overlay during recording when the frame grabber is enabled. See the Frame Capture chapter.

Quality of the video window during Recording
If the quality of the preview is not critical during recording, we recommend to set VideoRenderer = vr_RecordingPriority before invoking StartRecording to assign the resources prioritarily to the recording.

As the CPU load is critical during recording, in certain cases, preventing the video frames to be stretched to the video window size may save CPU, especially if the video frame is resized to a size larger than the original size of the video frame.
To prevent the video frames to be resized:
- if you want the control to be resized automatically, set AdjustPixelAspectRatio = false and Display_AutoSize = true
- if you want to specify yourself the size of the control, set AdjustPixelAspectRatio = false and Display_AutoSize = false and Display_AspectRatio = ar_NoResize

Back-timed recording (preroll)
It is possible to start recording with a preroll a few seconds before an event occurs.
E.g. when motion detection is used, this allows to capture the full video sequence by starting just before the motion detection event occurs.
See the Back-timed recording (preroll) chapter.

CPU and disk requirements
In order to minimize dropped frames, capturing to AVI in real time requires high CPU and disk availability, therefore:
- prefer fast disks / fast CPU platforms,
- prefer Windows 2000 / Windows XP platforms rather than Win98 or WinME platforms,
- prefer NTFS partitions rather than FAT32 partitions.
If several video clips are recorded at the same time and lot of dropped frames occur, we recommend to use SCSI disks for better disk performances.

Dropped frames
As video capture is synchrone, when the time required to record a given video frame becomes longer than the time between 2 video frames, frames are dropped.
An excessive amount of dropped frames cause jerky AVI playback and bad audio/video synchronization.
When dropped frames problems occur, act on the following points:
- check that StoragePath saves to a fast disk (avoid networked drives),
- disable the frame grabber on the AVI stream (set FrameGrabber = fg_PreviewStream), or disable it totally (set FrameGrabber = fg_Disabled)
- reduce the video size,
- reduce the frame rate (FrameRate property or DVReduceFrameRate for DV sources).