Table of Contents

Class MediaBlocksPipeline

Namespace
VisioForge.Core.MediaBlocks
Assembly
VisioForge.Core.dll

MediaBlocks pipeline bus message handling implementation. This partial class contains all message bus processing, event handling, and pipeline state management. Handles video overlay setup, stream collection detection, specialized block messaging, and pipeline lifecycle events.

public class MediaBlocksPipeline : IMediaBlocksPipeline, IDisposable, IAsyncDisposable, INotifyPropertyChanged

Inheritance

Implements

Inherited Members

Remarks

The MediaBlocksPipeline serves as the container and coordinator for media blocks. Key responsibilities include:

  • Managing the collection of media blocks and their connections
  • Building and initializing the media pipeline infrastructure
  • Controlling pipeline state (Free, Playing, Paused)
  • Processing bus messages and translating them to .NET events
  • Handling errors and providing diagnostic information
  • Managing resource cleanup and disposal

This is the foundation class for the MediaBlocks SDK, which represents the most flexible and powerful approach to media processing in the VisioForge Media Framework.

Constructors

MediaBlocksPipeline(string, ContextX)

Initializes a new instance of the VisioForge.Core.MediaBlocks.MediaBlocksPipeline class with optional name and logging context. This constructor creates a new pipeline instance ready to accept media blocks and build processing workflows.

public MediaBlocksPipeline(string name = null, ContextX context = null)

Parameters

name string

Optional pipeline name for identification in logs and debugging. If not provided, a random name will be auto-generated.

context ContextX

Optional logging context for centralized logging. If not provided, a new context will be created automatically.

Remarks

The constructor performs essential initialization:

  • Loads the multimedia framework libraries and initializes the system
  • Sets up logging infrastructure (Serilog)
  • Configures local library redistribution paths (Windows only)
  • Creates the internal media pipeline object
  • Sets up error handling callbacks

After construction, add media blocks using AddBlock() and connect them before calling Build() and Start().

Properties

Debug_Dir

Gets or sets the directory path where debug files (logs, pipeline graphs) will be saved. Changing this property reconfigures the logger to write to the new directory.

public string Debug_Dir { get; set; }

Property Value

string

Remarks

Debug files include:

  • Log files with detailed pipeline operations
  • DOT graph files showing pipeline structure
  • Error diagnostics and telemetry data

Ensure the application has write permissions to the specified directory.

Debug_DisableMessageDialogs

Gets or sets a value indicating whether error message dialogs are suppressed when OnError event is not handled. When true, errors are logged but no UI dialogs are shown, useful for headless or service applications.

public bool Debug_DisableMessageDialogs { get; set; }

Property Value

bool

Remarks

Set this to true in scenarios where UI dialogs are inappropriate:

  • Background services
  • Console applications
  • Automated testing
  • Applications with custom error handling UI

Always handle the OnError event for production applications rather than relying on default dialogs.

Debug_Mode

Gets or sets a value indicating whether debug mode is enabled for detailed logging and diagnostics. When enabled, the pipeline generates comprehensive log files and saves pipeline graph visualizations.

public bool Debug_Mode { get; set; }

Property Value

bool

Remarks

Debug mode features:

  • Detailed log files with all operations and state changes
  • Pipeline graph DOT files for visualization
  • More verbose console output
  • Performance may be slightly reduced due to additional logging

Recommended for development and troubleshooting. Disable in production for optimal performance.

Debug_Telemetry

Gets or sets a value indicating whether anonymous error telemetry is sent to VisioForge during Visual Studio debugging sessions. This helps improve SDK quality by reporting errors encountered during development. No personal data is transmitted.

public bool Debug_Telemetry { get; set; }

Property Value

bool

Remarks

Telemetry information includes:

  • Exception messages and stack traces
  • Pipeline configuration (anonymized)
  • SDK version and platform information
  • Media element usage patterns

Telemetry is only active when debugging in Visual Studio and is automatically disabled in production builds. No personal information, file paths, or media content is transmitted.

Loop

Gets or sets a value indicating whether playback automatically restarts from the beginning when the end is reached. Enables continuous looping playback for presentations, kiosks, or background video displays.

public bool Loop { get; set; }

Property Value

bool

Remarks

When enabled, the OnLoop event is fired each time the media restarts. The OnStop event will not be fired during loop restarts, only when Stop() is called explicitly. Loop mode works with seekable sources (files) but not with live streams.

Name

Gets or sets the name of this pipeline instance for identification in logs and debugging output. Provides a human-readable identifier to distinguish between multiple pipeline instances.

public string Name { get; set; }

Property Value

string

PauseOnStop

Gets or sets a value indicating whether the pipeline seeks to the beginning and pauses when playback completes. When enabled, reaching the end of media results in a paused state at the start position instead of stopping.

public bool PauseOnStop { get; set; }

Property Value

bool

Remarks

This property affects End-of-Stream (EOS) behavior:

  • When true: Pipeline seeks to start and enters paused state (ready to play again)
  • When false: Pipeline stops and enters Free state (requires full restart)

Useful for video preview scenarios where quick replay is desired without full pipeline restart overhead.

SDK_BuildDate

Gets the SDK build date indicating when this version of the MediaBlocks framework was compiled. Useful for version verification and support inquiries.

public static DateTime SDK_BuildDate { get; }

Property Value

DateTime

SDK_Version

Gets the semantic version number of the MediaBlocks SDK indicating feature set and compatibility level. Use this for version checks and compatibility verification in your application.

public static Version SDK_Version { get; }

Property Value

Version

StartPosition

Gets or sets the time position where playback should begin for seekable media sources. When set before starting, the pipeline will automatically seek to this position after initialization.

public TimeSpan? StartPosition { get; set; }

Property Value

TimeSpan?

Remarks

This property only affects seekable sources like media files. It has no effect on live sources. The actual seek operation occurs during the pipeline state transition to Paused. For precise seeking, consider using seekToKeyframe parameter based on your accuracy requirements.

State

Gets the current playback state of the pipeline (Free, Play, Pause, etc.). This property reflects the real-time status of media processing operations.

public PlaybackState State { get; }

Property Value

PlaybackState

StopPosition

Gets or sets the time position where playback should stop for seekable media sources. When set along with StartPosition, defines a segment of media to play or process.

public TimeSpan? StopPosition { get; set; }

Property Value

TimeSpan?

Remarks

This property enables segment playback by defining the end boundary. Both StartPosition and StopPosition must be set to create a valid segment. The pipeline will automatically stop or loop (if Loop is enabled) when reaching this position. Useful for previewing specific portions of media or processing media segments.

Methods

AddBlock(IMediaBlock)

Adds a media processing block to the pipeline. The block will be included in the pipeline's processing chain and can be connected to other blocks. This method is thread-safe and can only be called when the pipeline is in the Free state.

public bool AddBlock(IMediaBlock block)

Parameters

block IMediaBlock

The media block to add to the pipeline. Cannot be null.

Returns

bool

true if the block was successfully added; false if the operation failed (e.g., null block, pipeline not in Free state, or block already exists).

Examples

var sourceBlock = new UniversalSourceBlock(sourceSettings);
bool success = pipeline.AddBlock(sourceBlock);
if (success)
{
    Console.WriteLine("Block added successfully");
}

Remarks

Special blocks like barcode detectors, face detection, and VU meters are automatically tracked separately for event handling. The pipeline must be in Free state to add blocks. Attempting to add the same block twice will result in a warning but return true.

Build()

Builds and prepares the media pipeline for execution. This method configures the internal pipeline structure, initializes logging and telemetry, and prepares all added media blocks for connection and playback.

public bool Build()

Returns

bool

true if the pipeline was successfully built; false if the build process failed.

Examples

// Add blocks to pipeline
pipeline.AddBlock(sourceBlock);
pipeline.AddBlock(encoderBlock);

// Build the pipeline
if (pipeline.Build())
{
    await pipeline.StartAsync();
}

Remarks

This method should be called after adding all required media blocks but before starting playback. It performs essential initialization including Sentry telemetry configuration for error reporting. The pipeline must be successfully built before calling Start() or other playback methods.

ClearBlocks()

Removes all media blocks from the pipeline. This method clears both regular media blocks and special blocks (detectors, analyzers). The pipeline must be in the Free state to perform this operation.

public void ClearBlocks()

Examples

// Stop the pipeline first
await pipeline.StopAsync();

// Clear all blocks
pipeline.ClearBlocks();

// Add new blocks for different processing
pipeline.AddBlock(newSourceBlock);

Remarks

This method is thread-safe and will only execute if the pipeline state is Free. Both the main media blocks collection and special blocks collection are cleared. Use this method to reset the pipeline before adding a new set of blocks.

Close()

Closes the pipeline and releases all resources including media elements and bus connections. This method transitions the pipeline to a stopped state and performs cleanup operations.

public void Close()

Remarks

This method:

  • Disconnects bus message handlers to prevent memory leaks
  • Marks the pipeline context as closed
  • Clears internal data structures
  • Transitions the pipeline state to Free

Consider using Dispose() or DisposeAsync() instead for complete resource cleanup.

Connect(MediaBlockPad, MediaBlockPad)

Connects two media blocks by linking an output pad to an input pad. This method establishes a data flow connection between blocks, automatically adding blocks to the pipeline if needed. The connection enables media data to flow from the output block to the input block during processing.

public bool Connect(MediaBlockPad output, MediaBlockPad input)

Parameters

output MediaBlockPad

The source pad that will provide media data.

input MediaBlockPad

The destination pad that will receive media data.

Returns

bool

true if the connection was successfully established; false if the operation failed due to null pads, null blocks, or connection errors.

Connect(MediaBlock, MediaBlock)

Connects two media blocks using their default output and input pads. This is a convenience method that automatically uses the primary output pad of the source block and the primary input pad of the destination block to establish the connection.

public bool Connect(MediaBlock output, MediaBlock input)

Parameters

output MediaBlock

The source media block that will provide data from its default output pad.

input MediaBlock

The destination media block that will receive data on its default input pad.

Returns

bool

true if the blocks were successfully connected; false if the operation failed due to null blocks or connection errors.

Connect(MediaBlockPad[][])

Connects multiple media block pad pairs in a batch operation. This method allows connecting several output pads to input pads in a single call, useful for establishing multiple connections efficiently in complex pipelines.

public bool Connect(MediaBlockPad[][] pairs)

Parameters

pairs MediaBlockPad[][]

An array of pad pair arrays, where each inner array contains exactly 2 elements: [output_pad, input_pad].

Returns

bool

true if all connections were successful; false if any connection failed.

Exceptions

Exception

Thrown when any pad pair array does not contain exactly 2 elements.

ConnectLive(MediaBlockPad, MediaBlockPad)

Dynamically connects two media block pads while the pipeline is already running (live connection). This method enables runtime modification of the pipeline by establishing new connections between blocks without stopping playback. Useful for dynamic routing scenarios like switching between video sources.

public bool ConnectLive(MediaBlockPad output, MediaBlockPad input)

Parameters

output MediaBlockPad

The source pad that will provide media data.

input MediaBlockPad

The destination pad that will receive media data.

Returns

bool

true if the live connection was successfully established; false if the operation failed.

Remarks

Live connections allow for dynamic pipeline reconfiguration without interrupting playback. This is more complex than pre-built connections and may cause brief disruptions in data flow. Both pads must be in a compatible state for live linking to succeed.

CreateEditingPipeline(string, ContextX)

Creates a specialized MediaBlocksPipeline configured for non-linear video editing workflows. This factory method initializes a pipeline with timeline editing engine support for timeline-based editing.

public static MediaBlocksPipeline CreateEditingPipeline(string name = null, ContextX context = null)

Parameters

name string

Optional pipeline name for identification in logs and debugging.

context ContextX

Optional logging context for centralized logging.

Returns

MediaBlocksPipeline

A new MediaBlocksPipeline instance configured with editing capabilities.

Remarks

The editing pipeline uses the timeline editing engine which provides:

  • Timeline-based editing with multiple layers
  • Non-linear editing capabilities
  • Transition and effect support
  • Project management

This is distinct from the standard playback/recording pipeline and is intended for video editing applications.

Debug_GetPipeline()

Gets the current media pipeline structure as a DOT format string for programmatic analysis or visualization. This method returns the raw DOT graph data without writing to a file.

public string Debug_GetPipeline()

Returns

string

DOT format string representing the complete pipeline structure with all elements, pads, and connections, or empty string if the pipeline is not available or DOT generation fails.

Remarks

The returned DOT string includes:

  • All media elements with their properties
  • Pad connections and caps
  • Element states
  • Data flow directions

Use this method when you need to:

  • Programmatically analyze pipeline structure
  • Send pipeline graphs over network
  • Store graphs in databases
  • Generate custom visualizations

The DOT format can be processed by Graphviz or other graph visualization libraries.

Debug_SavePipeline(string)

Saves the current media pipeline structure to a DOT file for visualization and debugging. The DOT file can be rendered into a graph image using Graphviz tools to visualize the complete pipeline structure.

public void Debug_SavePipeline(string name)

Parameters

name string

The base filename for the DOT file (without extension). The .dot extension will be added automatically. The file will be saved to the Debug_Dir directory.

Remarks

Pipeline graphs show:

  • All media elements in the pipeline
  • Pad connections between elements
  • Element properties and states
  • Caps (capabilities) negotiated between elements

To view the graph:

  1. Install Graphviz (https://graphviz.org/)
  2. Run: dot -Tpng graph.dot -o graph.png
  3. Open the resulting PNG file

This is invaluable for debugging pad linking issues, caps negotiation problems, and understanding pipeline structure.

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()

DisposeAsync()

Disposes the asynchronous.

public ValueTask DisposeAsync()

Returns

ValueTask

System.Threading.Tasks.ValueTask.

Duration()

Gets the total duration of the media content in the pipeline. This method queries the pipeline for the total duration of the media being processed. Duration is only available for seekable sources like files; live sources will return TimeSpan.Zero.

public TimeSpan Duration()

Returns

TimeSpan

A TimeSpan representing the total duration of the media, or Zero if duration cannot be determined.

Examples

var duration = pipeline.Duration();
if (duration > TimeSpan.Zero)
{
    Console.WriteLine($"Media duration: {duration:hh\\:mm\\:ss}");
}
else
{
    Console.WriteLine("Duration not available (live source)");
}

Remarks

Duration information is only available for seekable sources such as media files. Live sources (cameras, network streams) typically return TimeSpan.Zero as they have no defined end. The pipeline must be in a playing or paused state for duration queries to be reliable. This method performs a duration query internally.

DurationAsync()

Asynchronously queries the total duration of the media content in the pipeline without blocking the calling thread. This is the recommended method for duration queries from UI threads.

public Task<TimeSpan> DurationAsync()

Returns

Task<TimeSpan>

A Task that completes with a TimeSpan representing the total duration, or TimeSpan.Zero if unavailable.

~MediaBlocksPipeline()

Finalizes an instance of the VisioForge.Core.MediaBlocks.MediaBlocksPipeline class.

protected ~MediaBlocksPipeline()

ForceGPUDecodersUsage(bool)

Forces the pipeline to prioritize GPU hardware decoders over software decoders. This method adjusts decoder element rankings to prefer hardware-accelerated decoding for better performance. Note: Hardware decoder availability varies by platform and installed drivers.

public static void ForceGPUDecodersUsage(bool value = true)

Parameters

value bool

True to force GPU decoders to high priority; false to restore default rankings.

GetBlock(string)

Retrieves a media block from the pipeline by its name. The search is case-insensitive and returns the first block with a matching name. This method is thread-safe and can be called at any time.

public IMediaBlock GetBlock(string name)

Parameters

name string

The name of the block to retrieve. Cannot be null or empty.

Returns

IMediaBlock

The VisioForge.Core.MediaBlocks.IMediaBlock with the specified name, or null if no block is found or the name is invalid.

Examples

var sourceBlock = pipeline.GetBlock("VideoSource");
if (sourceBlock != null)
{
    // Use the retrieved block
    Console.WriteLine($"Found block: {sourceBlock.Name}");
}

Remarks

Block names are assigned when creating media blocks and should be unique within a pipeline for best results. This method performs a case-insensitive string comparison to find the matching block.

GetBlock(MediaBlockType)

Retrieves the first media block from the pipeline that matches the specified block type. This method is useful for finding blocks by their functional type when the exact name is unknown. This method is thread-safe and can be called at any time.

public IMediaBlock GetBlock(MediaBlockType type_)

Parameters

type_ MediaBlockType

The VisioForge.Core.MediaBlocks.MediaBlockType to search for (e.g., VideoRenderer, AudioEncoder, etc.).

Returns

IMediaBlock

The first VisioForge.Core.MediaBlocks.IMediaBlock of the specified type, or null if no matching block is found.

Examples

var videoRenderer = pipeline.GetBlock(MediaBlockType.VideoRenderer);
if (videoRenderer is VideoRendererBlock renderer)
{
    // Configure the video renderer
    renderer.SetOutputSize(1920, 1080);
}

Remarks

If multiple blocks of the same type exist in the pipeline, this method returns the first one found. For pipelines with multiple blocks of the same type, consider using GetBlock(string name) with specific names.

GetContext()

Gets the logging context that provides centralized logging services for this pipeline instance. The context manages the Serilog logger and provides structured logging methods for all pipeline operations.

public ContextX GetContext()

Returns

ContextX

The ContextX instance containing the configured logger and logging infrastructure.

Remarks

The logging context provides:

  • Structured logging with Serilog
  • Log level filtering (Debug, Info, Warning, Error)
  • File output when debug mode is enabled
  • Observable logging for event processing

Blocks and pipeline components use this context for consistent logging throughout the framework.

GetHardwareDecoders(string[])

Retrieves a list of available hardware decoders filtered by the specified criteria. This method queries the media framework registry for hardware-accelerated decoder elements that match the given filters.

public static Tuple<string, string>[] GetHardwareDecoders(string[] filters)

Parameters

filters string[]

Array of filter strings to match against decoder names (e.g., "H264", "H265", "VP9").

Returns

Tuple<string, string>[]

Array of tuples containing decoder element names and their descriptions for matching hardware decoders.

GetPipelineContext()

Gets the internal pipeline context containing low-level media pipeline infrastructure and shared resources. This method provides access to the underlying pipeline implementation for advanced scenarios that require direct interaction with media components.

public BlockPipelineContext GetPipelineContext()

Returns

BlockPipelineContext

The BlockPipelineContext instance containing the media pipeline, callbacks, and pipeline-wide state.

Remarks

The pipeline context includes:

  • The media pipeline instance
  • Pipeline-wide callbacks and error handlers
  • Shared resources accessible by all media blocks
  • Pipeline state information

This is intended for advanced scenarios. Most applications should use the higher-level MediaBlocksPipeline API.

GetSoftwareH264Decoders()

Gets the list of available software-based H.264 decoders. Returns the standard FFmpeg-based H.264 decoder that provides reliable software decoding capabilities.

public static Tuple<string, string>[] GetSoftwareH264Decoders()

Returns

Tuple<string, string>[]

Array of tuples containing H.264 software decoder element names and descriptions.

GetSoftwareH265Decoders()

Gets the list of available software-based H.265/HEVC decoders. Returns the standard FFmpeg-based H.265 decoder that provides reliable software decoding capabilities.

public static Tuple<string, string>[] GetSoftwareH265Decoders()

Returns

Tuple<string, string>[]

Array of tuples containing H.265 software decoder element names and descriptions.

GetVRVideoControl()

Gets the VR (Virtual Reality) video control interface for 360-degree or stereoscopic video playback. This method searches for VR-capable components in the pipeline and returns the control interface if available.

public IVRVideoControl GetVRVideoControl()

Returns

IVRVideoControl

An IVRVideoControl interface for controlling VR video features (projection mode, viewing angle, etc.), or null if no VR-capable component is found in the pipeline.

Remarks

The method searches for VR support in the following order:

  1. The video view component
  2. Media blocks implementing IVRVideoControl
  3. Video renderer blocks with VR-capable video views

VR video control enables features like equirectangular projection, viewing angle adjustment, and stereoscopic modes.

NextFrame()

Advances video playback by one frame in frame-by-frame stepping mode. This method pauses the pipeline and then steps forward by exactly one video frame, useful for precise video analysis, editing, or frame extraction scenarios.

public bool NextFrame()

Returns

bool

true if the frame step was successful; false if the operation failed or video renderer is unavailable.

Remarks

Frame stepping requires a video renderer to be present in the pipeline. The pipeline will be automatically paused before stepping to the next frame. Frame stepping precision depends on the video codec and whether frames are keyframes or predictive frames.

OnPropertyChanged(string)

Raises the PropertyChanged event for the specified property. This method is called automatically when properties are modified to notify listeners of changes.

protected virtual void OnPropertyChanged(string propertyName = null)

Parameters

propertyName string

The name of the property that changed. This is automatically populated by the CallerMemberName attribute.

Pause()

Pauses the media pipeline playback. This method transitions the pipeline from playing state to paused state, maintaining the current position. Playback can be resumed later using Resume() or ResumeAsync() methods.

public bool Pause()

Returns

bool

true if the pipeline was successfully paused; false if the operation failed or the pipeline is not available.

Examples

if (pipeline.Pause())
{
    Console.WriteLine("Pipeline paused successfully");
    // Later resume playback
    pipeline.Resume();
}

Remarks

This method immediately changes the pipeline state to Pause and pauses the media pipeline. The method will return false if the pipeline is null or not properly initialized. Use PauseAsync() for asynchronous pause operations.

PauseAsync()

Asynchronously pauses the media pipeline playback without blocking the calling thread. This is the recommended method for pausing from UI threads to maintain responsiveness.

public Task PauseAsync()

Returns

Task

A Task that represents the asynchronous pause operation.

Position_Get()

Gets the current playback position in the media timeline. This method queries the pipeline for the current position during playback or recording. Position information is only meaningful for seekable sources like media files.

public TimeSpan Position_Get()

Returns

TimeSpan

A TimeSpan representing the current position, or Zero if position cannot be determined or pipeline is not available.

Remarks

Position queries work best with seekable sources like local files. Live sources and non-seekable network streams may return zero or invalid positions. For UI progress bars or time displays, consider calling this method periodically (e.g., every 100-500ms) rather than on every frame.

Position_GetAsync()

Asynchronously queries the current playback position in the media timeline without blocking the calling thread. This is the recommended method for position queries from UI threads.

public Task<TimeSpan> Position_GetAsync()

Returns

Task<TimeSpan>

A Task that completes with a TimeSpan representing the current position, or TimeSpan.Zero if unavailable.

Position_Set(TimeSpan, bool)

Sets the playback position in the media timeline (seeking operation). This method performs a seek operation to jump to a specific time position in the media. Seeking is only supported for seekable sources like media files, not live streams.

public void Position_Set(TimeSpan position, bool seekToKeyframe = false)

Parameters

position TimeSpan

The target position to seek to in the media timeline.

seekToKeyframe bool

If set to true, seeks to the nearest keyframe for faster seeking but potentially less precise positioning. If false, seeks to the exact position which may be slower but more accurate.

Position_SetAsync(TimeSpan, bool)

Asynchronously sets the playback position (seeking) without blocking the calling thread. This is the recommended method for seeking from UI threads to maintain responsiveness.

public Task Position_SetAsync(TimeSpan position, bool seekToKeyframe = false)

Parameters

position TimeSpan

The target position to seek to in the media timeline.

seekToKeyframe bool

If true, seeks to the nearest keyframe for faster seeking but potentially less precise positioning. If false, seeks to the exact position which may be slower but more accurate.

Returns

Task

A Task representing the asynchronous seek operation.

Position_SetRange(TimeSpan, TimeSpan, bool)

Sets the playback range by seeking to a specific start and stop position in the media. This method performs a segment seek operation to limit playback to the specified time range.

public void Position_SetRange(TimeSpan startPosition, TimeSpan stopPosition, bool seekToKeyframe = false)

Parameters

startPosition TimeSpan

The position where playback should begin.

stopPosition TimeSpan

The position where playback should end.

seekToKeyframe bool

If true, seeks to the nearest keyframe for more accurate positioning; if false, seeks to exact position.

Position_SetRangeAsync(TimeSpan, TimeSpan, bool)

Asynchronously sets the playback range by seeking to a specific start and stop position in the media. This method performs a segment seek operation to limit playback to the specified time range without blocking the calling thread.

public Task Position_SetRangeAsync(TimeSpan startPosition, TimeSpan stopPosition, bool seekToKeyframe = false)

Parameters

startPosition TimeSpan

The position where playback should begin.

stopPosition TimeSpan

The position where playback should end.

seekToKeyframe bool

If true, seeks to the nearest keyframe for more accurate positioning; if false, seeks to exact position.

Returns

Task

A Task representing the asynchronous seek operation.

Rate_Get()

Gets the current playback rate (speed) of the media pipeline. The rate determines how fast the media plays relative to normal speed (1.0 = normal, 2.0 = double speed, 0.5 = half speed).

public double Rate_Get()

Returns

double

A Double value representing the current playback rate, where 1.0 is normal speed.

Rate_GetAsync()

Asynchronously gets the current playback rate (speed) without blocking the calling thread.

public Task<double> Rate_GetAsync()

Returns

Task<double>

A Task that completes with a double value representing the playback rate (1.0 = normal speed).

Rate_Set(double)

Sets the playback rate (speed) of the media pipeline. This method changes how fast the media plays back relative to normal speed. Rate changes require a video renderer to be present in the pipeline.

public bool Rate_Set(double rate)

Parameters

rate double

The playback rate where 1.0 is normal speed, values greater than 1.0 are faster, and values less than 1.0 are slower. Negative values enable reverse playback if supported.

Returns

bool

true if the rate was successfully changed; false if the operation failed due to missing video renderer or other errors.

Rate_SetAsync(double)

Asynchronously sets the playback rate (speed) without blocking the calling thread. This is the recommended method for rate changes from UI threads to maintain responsiveness.

public Task<bool> Rate_SetAsync(double rate)

Parameters

rate double

The playback rate where 1.0 is normal speed, values greater than 1.0 are faster, and values less than 1.0 are slower. Negative values enable reverse playback if supported by the media format.

Returns

Task<bool>

A Task that completes with true if the rate change was successful, false otherwise.

Resume()

Resumes media pipeline playback from a paused state. This method transitions the pipeline from paused state back to playing state, continuing from the current position without seeking.

public bool Resume()

Returns

bool

true if the pipeline was successfully resumed; false if the operation failed or the pipeline is not available.

Examples

// Pause the pipeline
pipeline.Pause();

// Later resume from the same position
if (pipeline.Resume())
{
    Console.WriteLine("Playback resumed successfully");
}

Remarks

This method immediately changes the pipeline state to Play and resumes the media pipeline. The method will return false if the pipeline is null or not properly initialized. Use ResumeAsync() for asynchronous resume operations that return a Task.

ResumeAsync()

Asynchronously resumes media pipeline playback from a paused state without blocking the calling thread. This is the recommended method for resuming from UI threads to maintain responsiveness.

public Task<bool> ResumeAsync()

Returns

Task<bool>

A Task that completes with a boolean value: true if resume was successful, false otherwise.

SendEOS()

Sends an End-of-Stream (EOS) event to the pipeline for graceful playback termination. This method allows the pipeline to finish processing any remaining data before stopping, ensuring proper file closure and resource cleanup. This is the recommended way to stop recording or playback.

public void SendEOS()

Examples

// Gracefully stop recording to ensure file integrity
pipeline.SendEOS();

// Wait for the pipeline to finish processing
await pipeline.WaitForStateChangeAsync(PlaybackState.Stop);

Remarks

The EOS event propagates through the entire pipeline, allowing each element to flush remaining data. This is particularly important for file outputs to ensure proper file structure and prevent corruption. After sending EOS, the pipeline will transition to the stopped state once all data is processed. Use this method instead of Stop() when you need to ensure all data is properly written.

SetCustomErrorHandler(IMediaBlocksPipelineCustomErrorHandler)

Sets a custom error handler to process pipeline errors before the default error handling logic. The custom handler receives priority and can choose to suppress default error processing.

public void SetCustomErrorHandler(IMediaBlocksPipelineCustomErrorHandler errorHandler)

Parameters

errorHandler IMediaBlocksPipelineCustomErrorHandler

The custom error handler implementation, or null to remove custom handling and restore default behavior.

Remarks

Custom error handlers enable application-specific error processing such as:

  • Custom error recovery strategies
  • Specialized error logging or reporting
  • Suppressing specific error types
  • Translating media framework errors to application-specific error codes

The handler's ErrorHandler method receives the message bus, message, and pipeline, allowing low-level inspection of the error. Return true to suppress default handling, false to allow it.

SetLicenseKey(string, string, string)

Activates the SDK with the provided license credentials to remove trial limitations. This method must be called with valid license information obtained from VisioForge to unlock the full functionality of the SDK and remove any trial restrictions or nag screens.

public void SetLicenseKey(string licenseKey, string username, string email)

Parameters

licenseKey string

The license key string provided by VisioForge after purchase.

username string

The username associated with the license purchase (currently not used but required for future compatibility).

email string

The email address associated with the license purchase (currently not used but required for future compatibility).

Examples

pipeline.SetLicenseKey("your_license_key_here", "username", "email@example.com");

Start(bool)

Starts this instance.

public bool Start(bool onlyPreload = false)

Parameters

onlyPreload bool

if set to true only preload and set to Pause.

Returns

bool

true if successfull, false otherwise.

StartAsync(bool)

Starts the media pipeline asynchronously for playback or recording. This method builds the media pipeline, connects all media blocks, and transitions to the playing state. Optionally, the pipeline can be preloaded to a paused state for faster subsequent playback.

public Task<bool> StartAsync(bool onlyPreload = false)

Parameters

onlyPreload bool

If set to true, the pipeline will be built and preloaded but remain in paused state instead of playing. This allows for faster playback startup later.

Returns

Task<bool>

A Task<TResult> that represents the asynchronous start operation. The task result is true if the pipeline started successfully; otherwise, false.

Examples

// Standard playback start
bool started = await pipeline.StartAsync();
if (started)
{
    Console.WriteLine("Pipeline started successfully");
}

// Preload for faster subsequent playback
bool preloaded = await pipeline.StartAsync(onlyPreload: true);
if (preloaded)
{
    // Later start actual playback quickly
    await pipeline.ResumeAsync();
}

Remarks

This method handles the complete pipeline initialization process:

  • Validates pipeline state and prevents multiple simultaneous start operations
  • Builds the internal media pipeline from added media blocks
  • Connects all block inputs and outputs according to their media types
  • Configures bus message handling for events and errors
  • Transitions the pipeline to playing state (or paused if onlyPreload is true)

If the pipeline is already in paused state, this method will resume playback instead of rebuilding. The method is thread-safe and prevents concurrent start operations.

Stop(bool)

Stops the media pipeline and halts all processing operations. This method brings the pipeline to a complete stop and transitions to the Free state. Source blocks are stopped first, followed by pipeline state transition and resource cleanup.

public bool Stop(bool force = false)

Parameters

force bool

If set to true, forces immediate pipeline shutdown without waiting for graceful EOS processing. For file outputs, this may cause incomplete frames or file corruption. Use graceful shutdown (false) for production recording scenarios.

Returns

bool

true if the pipeline was successfully stopped; false if the operation failed or stop was already in progress.

StopAsync(bool)

Asynchronously stops the media pipeline and halts all processing operations without blocking the calling thread. This is the recommended method for stopping from UI threads to maintain responsiveness.

public Task<bool> StopAsync(bool force = false)

Parameters

force bool

If set to true, forces immediate pipeline shutdown without waiting for graceful EOS (End-of-Stream) processing. For file outputs, this may cause incomplete frames or file corruption. Use graceful shutdown (false) for production recording scenarios to ensure proper file finalization.

Returns

Task<bool>

A Task that completes with a boolean value: true if stop was successful, false if already stopped.

ToString()

Returns a String that represents this instance.

public override string ToString()

Returns

string

A String that represents this instance.

WaitForStop()

Synchronously waits for the pipeline to reach the stopped (Free) state, blocking the calling thread. This method polls the pipeline state and returns when playback has fully stopped.

public void WaitForStop()

Remarks

This method blocks the calling thread while waiting for the pipeline to stop. It polls the State property every 50 milliseconds until PlaybackState.Free is reached. For UI applications, consider using WaitForStopAsync() instead to avoid blocking the UI thread.

WaitForStopAsync()

Asynchronously waits for the pipeline to reach the stopped (Free) state without blocking the calling thread. This method polls the pipeline state and completes when playback has fully stopped.

public Task WaitForStopAsync()

Returns

Task

A Task that completes when the pipeline transitions to the Free state.

Remarks

This method is useful for coordinating pipeline shutdown with other application logic. It polls the State property every 50 milliseconds until PlaybackState.Free is reached. For applications that need to perform cleanup after the pipeline stops, await this method before proceeding with cleanup operations.

OnBusStreamCollection

Event raised when stream collection information becomes available from the pipeline bus. Provides detailed information about all video, audio, and subtitle streams in the media content.

public event EventHandler<Tuple<VideoStreamInfo[], AudioStreamInfo[], SubtitleStreamInfo[]>> OnBusStreamCollection

Event Type

EventHandler<Tuple<VideoStreamInfo[], AudioStreamInfo[], SubtitleStreamInfo[]>>

OnError

Event raised when an error occurs during pipeline operation. Provides detailed error information including severity level and descriptive message.

public event EventHandler<ErrorsEventArgs> OnError

Event Type

EventHandler<ErrorsEventArgs>

OnLoop

Event raised when the pipeline completes processing and automatically restarts due to the Loop property being enabled. This allows for continuous playback of media content.

public event EventHandler<EventArgs> OnLoop

Event Type

EventHandler<EventArgs>

OnPause

Event raised when the pipeline is paused, temporarily suspending media processing. The pipeline can be resumed from the current position without losing state.

public event EventHandler<EventArgs> OnPause

Event Type

EventHandler<EventArgs>

OnReady

Event raised when the pipeline has completed initialization and is ready for operation. This indicates that all blocks have been configured and the pipeline is prepared to start.

public event EventHandler<EventArgs> OnReady

Event Type

EventHandler<EventArgs>

OnResume

Event raised when the pipeline resumes processing after being paused. Media processing continues from the position where it was paused.

public event EventHandler<EventArgs> OnResume

Event Type

EventHandler<EventArgs>

OnStart

Event raised when the pipeline successfully starts media processing. This indicates that all blocks are initialized and data flow has begun.

public event EventHandler<EventArgs> OnStart

Event Type

EventHandler<EventArgs>

OnStop

Event raised when the pipeline stops media processing, either normally or due to an error. Provides information about the final position and reason for stopping.

public event EventHandler<StopEventArgs> OnStop

Event Type

EventHandler<StopEventArgs>

PropertyChanged

Event raised when any pipeline property value changes. Supports data binding and property change notifications in UI frameworks.

public event PropertyChangedEventHandler PropertyChanged

Event Type

PropertyChangedEventHandler

See Also