Table of Contents

Class FrameSource

Namespace
VisioForge.Core.VideoFingerPrinting
Assembly
VisioForge.Core.dll

Provides video frame extraction and processing capabilities for video fingerprinting operations.

public class FrameSource : IDisposable, IAsyncDisposable

Inheritance

Implements

Inherited Members

Remarks

The VisioForge.Core.VideoFingerPrinting.FrameSource class creates a media processing pipeline that extracts video frames from various sources and applies optional transformations such as cropping and resizing. It uses the MediaBlocks pipeline architecture to process video streams and deliver individual frames through events. This class is designed to work with the video fingerprinting system to provide preprocessed frames for fingerprint generation.

Properties

Crop

Gets or sets the area to crop from video frames.

public Rect Crop { get; set; }

Property Value

Rect

Remarks

Cropping is useful for removing black bars, watermarks, or other static elements that could interfere with fingerprint matching. The crop is applied before resizing.

CustomResolution

Gets or sets the custom resolution for video frame output.

public Size CustomResolution { get; set; }

Property Value

Size

Remarks

Resizing is performed after cropping. Smaller resolutions can improve fingerprinting performance and reduce memory usage while maintaining sufficient detail for matching.

Pipeline

Gets the media blocks pipeline used for video processing.

public MediaBlocksPipeline Pipeline { get; }

Property Value

MediaBlocksPipeline

Remarks

The pipeline is created by every VisioForge.Core.VideoFingerPrinting.FrameSource.PlayAsync(VisioForge.Core.Types.X.Sources.UniversalSourceSettings) call and disposed when that session ends - on the next PlayAsync call, on a failed start, and when the FrameSource is disposed. It is therefore valid only for the current session and must not be cached across PlayAsync calls. It coordinates all media blocks in the processing chain.

StartPosition

Gets or sets the start position within the video.

public TimeSpan StartPosition { get; set; }

Property Value

TimeSpan

Remarks

Use this property to skip unwanted content at the beginning of the video, such as introductions or advertisements.

StopPosition

Gets or sets the stop position within the video.

public TimeSpan StopPosition { get; set; }

Property Value

TimeSpan

Remarks

Use this property to exclude content at the end of the video, such as credits or advertisements. Processing will stop when this position is reached.

Methods

Dispose(bool)

Releases unmanaged and - optionally - managed resources.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Remarks

A synchronous Dispose cannot wait for a VisioForge.Core.VideoFingerPrinting.FrameSource.PlayAsync(VisioForge.Core.Types.X.Sources.UniversalSourceSettings) that is already running - waiting on it from a UI or pipeline-callback thread is exactly the deadlock this class must not have. It therefore marks the instance disposed and, when a session transition is in flight, leaves the teardown to that call, so Dispose can return before the session is fully gone. Use VisioForge.Core.VideoFingerPrinting.FrameSource.DisposeAsync when the caller needs the teardown to have completed on return.

DisposeAsync()

Asynchronously releases the current session and marks the instance disposed.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

Remarks

The deterministic teardown: it waits for any VisioForge.Core.VideoFingerPrinting.FrameSource.PlayAsync(VisioForge.Core.Types.X.Sources.UniversalSourceSettings) or VisioForge.Core.VideoFingerPrinting.FrameSource.StopAsync already in flight, so on return nothing of the session is left running. Do not call it - nor VisioForge.Core.VideoFingerPrinting.FrameSource.PlayAsync(VisioForge.Core.Types.X.Sources.UniversalSourceSettings) or VisioForge.Core.VideoFingerPrinting.FrameSource.StopAsync - and then block on the returned task from an VisioForge.Core.VideoFingerPrinting.FrameSource.OnError or VisioForge.Core.VideoFingerPrinting.FrameSource.OnStop handler of the same instance: the session gate is not re-entrant.

~FrameSource()

Finalizes an instance of the VisioForge.Core.VideoFingerPrinting.FrameSource class.

protected ~FrameSource()

PlayAsync(UniversalSourceSettings)

Starts asynchronous video playback and frame extraction.

public Task<bool> PlayAsync(UniversalSourceSettings sourceSettings)

Parameters

sourceSettings UniversalSourceSettings

The settings defining the video source, including file path and format options.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if playback started successfully; otherwise, false.

Remarks

This method constructs a media processing pipeline with the following components:

  1. Universal source for reading the video file
  2. Optional crop block if Crop property is set
  3. Optional resize block if CustomResolution property is set
  4. Sample grabber for extracting individual frames
  5. Null renderer as the pipeline sink
The pipeline begins processing immediately after successful initialization. Video frames are delivered through the VisioForge.Core.VideoFingerPrinting.FrameSource.OnVideoFrame event.

Exceptions

ObjectDisposedException

Thrown when the FrameSource has been disposed.

StopAsync()

Stops the current session and releases its pipeline and blocks.

public Task StopAsync()

Returns

Task

A task that represents the asynchronous stop operation.

Remarks

Safe to call when nothing is playing - the call is a no-op in that case. The VisioForge.Core.VideoFingerPrinting.FrameSource can be reused afterwards by calling VisioForge.Core.VideoFingerPrinting.FrameSource.PlayAsync(VisioForge.Core.Types.X.Sources.UniversalSourceSettings) again.

OnError

Occurs when an error happens during video processing.

public event EventHandler<ErrorsEventArgs> OnError

Event Type

EventHandler<ErrorsEventArgs>

Remarks

This event provides detailed error information including error codes and descriptions. Common errors include file access issues, codec problems, or memory allocation failures.

OnStop

Occurs when video playback is stopped.

public event EventHandler<StopEventArgs> OnStop

Event Type

EventHandler<StopEventArgs>

Remarks

This event is raised when the pipeline stops, either due to reaching the end of the video, encountering an error, or being manually stopped. The event args indicate the reason for stopping.

OnVideoFrame

Occurs when a new video frame is available for processing.

public event EventHandler<VideoFrameXBufferEventArgs> OnVideoFrame

Event Type

EventHandler<VideoFrameXBufferEventArgs>

Remarks

This event is raised for each video frame extracted from the source. The frame data is provided in RGB format and includes timing information. Subscribers should process frames quickly to avoid blocking the pipeline.

See Also