Table of Contents

Class LiveVideoCompositor

Namespace
VisioForge.Core.LiveVideoCompositor
Assembly
VisioForge.Core.dll

Resource disposal and cleanup functionality for the Live Video Compositor. This partial class implements proper disposal patterns for releasing unmanaged resources, cleaning up MediaBlocks pipelines, and ensuring proper shutdown of composition operations. Provides both synchronous and asynchronous disposal methods for different cleanup scenarios. Implements the IDisposable.

public class LiveVideoCompositor : IDisposable, IAsyncDisposable

Inheritance

Implements

Inherited Members

Examples

// Create compositor with specific settings
var settings = new LiveVideoCompositorSettings
{
    VideoWidth = 1920,
    VideoHeight = 1080,
    VideoFrameRate = new VideoFrameRate(30, 1),
    MixerType = LVCMixerType.OpenGL,
    MaxVideoInputsCount = 4,
    MaxVideoOutputsCount = 2
};

using var compositor = new LiveVideoCompositor(settings);

// Add video inputs
var input1 = new LVCVideoAudioInput("Camera 1", captureSettings);
await compositor.Input_AddAsync(input1);

// Add output
var output = new LVCVideoAudioOutput("RTMP Stream", rtmpSettings);
await compositor.Output_AddAsync(output);

// Start composition
await compositor.StartAsync();

Remarks

Disposal operations include:

  • Proper shutdown of MediaBlocks pipelines
  • Cleanup of video and audio mixers
  • Disposal of overlay managers and effects processors
  • Release of all input and output resources
  • Cleanup of tee blocks and bridge connections Both synchronous and asynchronous disposal patterns are supported for different use cases.

Constructors

LiveVideoCompositor(LiveVideoCompositorSettings)

Initializes a new instance of the VisioForge.Core.LiveVideoCompositor.LiveVideoCompositor class.

public LiveVideoCompositor(LiveVideoCompositorSettings settings)

Parameters

settings LiveVideoCompositorSettings

The settings.

Properties

Background

Gets or sets the background type for the video mixer (transparent, black, white, etc.).

public VideoMixerBackground Background { get; set; }

Property Value

VideoMixerBackground

Settings

Gets the configuration settings used to initialize this compositor instance.

public LiveVideoCompositorSettings Settings { get; }

Property Value

LiveVideoCompositorSettings

Video_Overlay_Enabled

Gets or sets a value indicating whether video overlay rendering is enabled globally.

public bool Video_Overlay_Enabled { get; set; }

Property Value

bool

Remarks

When disabled, no overlays will be rendered on any channel regardless of individual overlay settings. Default value is true.

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.

Remarks

This method follows the standard IDisposable pattern. When disposing is true, both managed and unmanaged resources are released. When disposing is false (called from finalizer), only unmanaged resources are released.

Dispose()

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

public void Dispose()

Remarks

This method should be called when the Live Video Compositor is no longer needed. It releases all resources including MediaBlocks pipelines, mixers, effects, and overlays. After disposal, the object cannot be used and should be discarded.

DisposeAsync()

Asynchronously disposes of the Live Video Compositor and all its resources.

public ValueTask DisposeAsync()

Returns

ValueTask

A ValueTask representing the asynchronous disposal operation.

Remarks

This method provides asynchronous disposal support for scenarios where pipeline shutdown may involve asynchronous operations. It ensures proper cleanup of all MediaBlocks components without blocking the calling thread. Prefer this method over synchronous Dispose() when possible.

DurationAsync()

Gets the current playback position of the main pipeline.

public Task<TimeSpan> DurationAsync()

Returns

Task<TimeSpan>

A task that represents the asynchronous operation. The task result contains the current position.

~LiveVideoCompositor()

Finalizes an instance of the VisioForge.Core.LiveVideoCompositor.LiveVideoCompositor class.

protected ~LiveVideoCompositor()

Remarks

The finalizer ensures that unmanaged resources are released even if Dispose was not called. This is a safety mechanism and should not be relied upon for proper cleanup. Always call Dispose() or use a using statement for deterministic cleanup.

GetAudioMixer()

Gets the audio mixer block if it's an AudioMixerBlock type (not a switcher).

public AudioMixerBlock GetAudioMixer()

Returns

AudioMixerBlock

The audio mixer block, or null if using switcher mode.

GetContext()

Gets the context object for logging and error handling.

public ContextX GetContext()

Returns

ContextX

The context object used by this compositor instance.

GetPipeline()

Gets the main MediaBlocks pipeline that manages the mixing and effects processing.

public MediaBlocksPipeline GetPipeline()

Returns

MediaBlocksPipeline

The main pipeline instance.

GetVideoMixer()

Gets the video mixer block if it's a VideoMixerBlock type (not a switcher).

public VideoMixerBlock GetVideoMixer()

Returns

VideoMixerBlock

The video mixer block, or null if using switcher mode or another mixer type.

Input_AddAsync(LVCVideoInput)

Adds a video-only input source to the compositor.

public Task<bool> Input_AddAsync(LVCVideoInput input)

Parameters

input LVCVideoInput

The video input configuration to add.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if added successfully, false if max inputs reached.

Input_AddAsync(LVCAudioInput)

Adds an audio-only input source to the compositor.

public Task<bool> Input_AddAsync(LVCAudioInput input)

Parameters

input LVCAudioInput

The audio input configuration to add.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if added successfully, false if max inputs reached.

Input_AddAsync(LVCVideoAudioInput, bool)

Adds a combined video and audio input source to the compositor.

public Task<bool> Input_AddAsync(LVCVideoAudioInput input, bool start = false)

Parameters

input LVCVideoAudioInput

The video/audio input configuration to add.

start bool

If true, starts the input immediately after adding (overrides AutoStart property).

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if added successfully, false if max inputs reached.

Input_AddAsync(LVCFileVideoAudioInput, bool)

Adds a file-based video and audio input source to the compositor.

public Task<bool> Input_AddAsync(LVCFileVideoAudioInput input, bool start = false)

Parameters

input LVCFileVideoAudioInput

The file video/audio input configuration to add.

start bool

If true, starts the input immediately after adding (overrides AutoStart property).

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if added successfully, false if max inputs reached.

Input_FileVideoAudio_Get(int)

Gets a file video/audio input by its index.

public LVCFileVideoAudioInput Input_FileVideoAudio_Get(int index)

Parameters

index int

The zero-based index of the input.

Returns

LVCFileVideoAudioInput

The file video/audio input at the specified index, or null if index is invalid or input is not a file video/audio type.

Input_Get(int)

Gets an input source by its index, regardless of type.

public LVCInput Input_Get(int index)

Parameters

index int

The zero-based index of the input.

Returns

LVCInput

The input at the specified index, or null if index is invalid.

Input_RemoveAsync(string)

Removes an input source from the compositor by its name.

public Task<bool> Input_RemoveAsync(string name)

Parameters

name string

The unique name of the input to remove.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if removed successfully, false if not found.

Input_RemoveAtAsync(int)

Removes an input source from the compositor by its index.

public Task<bool> Input_RemoveAtAsync(int index)

Parameters

index int

The zero-based index of the input to remove.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if removed successfully, false if index is invalid.

Input_VideoAudio_Get(int)

Gets a video/audio input by its index.

public LVCVideoAudioInput Input_VideoAudio_Get(int index)

Parameters

index int

The zero-based index of the input.

Returns

LVCVideoAudioInput

The video/audio input at the specified index, or null if index is invalid or input is not a video/audio type.

Input_VideoStream_Get(int)

Gets the video mixer stream configuration for a specific input by index.

public VideoMixerStream Input_VideoStream_Get(int index)

Parameters

index int

The zero-based index of the video input.

Returns

VideoMixerStream

The video mixer stream configuration, or null if index is invalid or mixer is not available.

Input_VideoStream_Update(int, VideoMixerStream)

Updates the video mixer stream configuration for a specific input.

public void Input_VideoStream_Update(int index, VideoMixerStream stream)

Parameters

index int

The zero-based index of the video input (not used as stream contains its own ID).

stream VideoMixerStream

The updated stream configuration including position, size, and other properties.

Output_AddAsync(LVCVideoOutput, bool)

Adds a video-only output destination to the compositor.

public Task<bool> Output_AddAsync(LVCVideoOutput output, bool start = false)

Parameters

output LVCVideoOutput

The video output configuration to add.

start bool

If true, starts the output immediately when the pipeline is running.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if added successfully, false if max outputs reached.

Output_AddAsync(LVCAudioOutput, bool)

Adds an audio-only output destination to the compositor.

public Task<bool> Output_AddAsync(LVCAudioOutput output, bool start = false)

Parameters

output LVCAudioOutput

The audio output configuration to add.

start bool

If true, starts the output immediately when the pipeline is running.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if added successfully, false if max outputs reached.

Output_AddAsync(LVCVideoAudioOutput, bool)

Adds a combined video and audio output destination to the compositor.

public Task<bool> Output_AddAsync(LVCVideoAudioOutput output, bool start = false)

Parameters

output LVCVideoAudioOutput

The video/audio output configuration to add.

start bool

If true, starts the output immediately when the pipeline is running.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if added successfully, false if max outputs reached.

Output_Audio_Get(int)

Gets an audio output by its index.

public LVCAudioOutput Output_Audio_Get(int index)

Parameters

index int

The zero-based index of the output.

Returns

LVCAudioOutput

The audio output at the specified index, or null if index is invalid or output is not an audio type.

Output_Get(int)

Gets an output destination by its index, regardless of type.

public LVCOutput Output_Get(int index)

Parameters

index int

The zero-based index of the output.

Returns

LVCOutput

The output at the specified index, or null if index is invalid.

Output_Get(string)

Gets an output destination by its unique name.

public LVCOutput Output_Get(string name)

Parameters

name string

The unique name of the output.

Returns

LVCOutput

The output with the specified name, or null if not found.

Output_RemoveAsync(string)

Removes an output destination from the compositor by its name.

public Task<bool> Output_RemoveAsync(string name)

Parameters

name string

The unique name of the output to remove.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if removed successfully, false if not found.

Output_RemoveAtAsync(int)

Removes an output destination from the compositor by its index.

public Task<bool> Output_RemoveAtAsync(int index)

Parameters

index int

The zero-based index of the output to remove.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if removed successfully, false if index is invalid.

Output_VideoAudio_Get(int)

Gets a video/audio output by its index.

public LVCVideoAudioOutput Output_VideoAudio_Get(int index)

Parameters

index int

The zero-based index of the output.

Returns

LVCVideoAudioOutput

The video/audio output at the specified index, or null if index is invalid or output is not a video/audio type.

Output_Video_Get(int)

Gets a video output by its index.

public LVCVideoOutput Output_Video_Get(int index)

Parameters

index int

The zero-based index of the output.

Returns

LVCVideoOutput

The video output at the specified index, or null if index is invalid or output is not a video type.

SetLicenseKey(string, string, string)

Sets the license key and user information for Live Video Compositor activation.

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

Parameters

licenseKey string

The VisioForge license key for this component.

userName string

The registered user name associated with the license.

email string

The email address associated with the license.

Remarks

This method must be called before starting composition operations to enable full functionality. The license key is validated against the provided user credentials. Invalid or missing license may result in limited functionality or watermarked output.

StartAsync()

Starts the compositor, including all input pipelines, the main pipeline, and auto-start outputs.

public Task<bool> StartAsync()

Returns

Task<bool>

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

StopAsync()

Stops the compositor, including all input pipelines, the main pipeline, and all outputs.

public Task StopAsync()

Returns

Task

A task that represents the asynchronous stop operation.

Switch(int)

Switches to a specific input when using switcher mode (applies to both video and audio).

public void Switch(int index)

Parameters

index int

The zero-based index of the input to switch to.

Video_Effects_AddOrUpdateAsync(IBaseVideoEffect, int)

Adds a new video effect or updates an existing effect on the specified channel.

public Task Video_Effects_AddOrUpdateAsync(IBaseVideoEffect effect, int channel = 0)

Parameters

effect IBaseVideoEffect

The video effect to add or update. Must implement IBaseVideoEffect interface.

channel int

The video channel index to apply the effect to. Default is 0.

Returns

Task

A Task representing the asynchronous operation.

Remarks

If an effect with the same name already exists, it will be updated with the new parameters. Effects are applied in the order they are added to the channel.

Video_Effects_Clear(int)

Removes all video effects from the specified channel.

public void Video_Effects_Clear(int channel = 0)

Parameters

channel int

The video channel index to clear effects from. Default is 0.

Remarks

This operation immediately removes all effects without pausing the pipeline. Use with caution during active composition as it may cause visual discontinuity.

Video_Effects_Get(string, int)

Retrieves a video effect by name from the specified channel.

public IBaseVideoEffect Video_Effects_Get(string effectName, int channel = 0)

Parameters

effectName string

The unique name identifier of the effect to retrieve.

channel int

The video channel index to search for the effect. Default is 0.

Returns

IBaseVideoEffect

The video effect instance if found; otherwise, null.

Remarks

Effect names are case-sensitive and must match exactly.

Video_Effects_RemoveAsync(IBaseVideoEffect, int)

Removes a video effect instance from the specified channel.

public Task Video_Effects_RemoveAsync(IBaseVideoEffect effect, int channel = 0)

Parameters

effect IBaseVideoEffect

The video effect instance to remove.

channel int

The video channel index to remove the effect from. Default is 0.

Returns

Task

A Task representing the asynchronous operation.

Remarks

The pipeline is temporarily paused during effect removal to ensure thread safety. If the effect is not found on the channel, the method returns without error.

Video_Effects_RemoveAsync(string, int)

Removes a video effect by name from the specified channel.

public Task Video_Effects_RemoveAsync(string name, int channel = 0)

Parameters

name string

The unique name identifier of the effect to remove.

channel int

The video channel index to remove the effect from. Default is 0.

Returns

Task

A Task representing the asynchronous operation.

Remarks

The pipeline is temporarily paused during effect removal to ensure thread safety. If no effect with the given name exists, the method returns without error.

Video_Overlay_Add(IOverlayManagerElement, int)

Adds a new overlay element to the specified video channel.

public void Video_Overlay_Add(IOverlayManagerElement overlay, int channel = 0)

Parameters

overlay IOverlayManagerElement

The overlay element to add. Must implement IOverlayManagerElement interface.

channel int

The video channel index to add the overlay to. Default is 0.

Remarks

Overlays are rendered in the order they are added, with later overlays appearing on top. Supported overlay types include text, images, graphics, and custom visual elements.

Video_Overlay_Clear(int)

Removes all overlay elements from the specified video channel.

public void Video_Overlay_Clear(int channel = 0)

Parameters

channel int

The video channel index to clear overlays from. Default is 0.

Remarks

This operation immediately removes all overlays from the channel. Use with caution during active composition as it may cause visual discontinuity.

Video_Overlay_Count(int)

Gets the total number of overlays in the specified video channel.

public int Video_Overlay_Count(int channel = 0)

Parameters

channel int

The video channel index to count overlays from. Default is 0.

Returns

int

The number of overlay elements in the channel.

Video_Overlay_Get(int, int)

Gets the overlay element at the specified index from the video channel.

public IOverlayManagerElement Video_Overlay_Get(int index, int channel = 0)

Parameters

index int

The zero-based index of the overlay to retrieve.

channel int

The video channel index to get the overlay from. Default is 0.

Returns

IOverlayManagerElement

The overlay element at the specified index.

Exceptions

ArgumentOutOfRangeException

Thrown when index is out of range.

Video_Overlay_Remove(IOverlayManagerElement, int)

Removes an overlay element from the specified video channel.

public void Video_Overlay_Remove(IOverlayManagerElement overlay, int channel = 0)

Parameters

overlay IOverlayManagerElement

The overlay element instance to remove.

channel int

The video channel index to remove the overlay from. Default is 0.

Remarks

If the overlay is not found on the channel, the method returns without error.

Video_Overlay_RemoveAt(int, int)

Removes an overlay element at the specified index from the video channel.

public void Video_Overlay_RemoveAt(int index, int channel = 0)

Parameters

index int

The zero-based index of the overlay to remove.

channel int

The video channel index to remove the overlay from. Default is 0.

Remarks

Throws an exception if the index is out of range for the channel's overlay collection.

Video_Overlay_Update(IOverlayManagerElement, int)

Updates an existing overlay element by removing and re-adding it to the specified channel.

public void Video_Overlay_Update(IOverlayManagerElement overlay, int channel = 0)

Parameters

overlay IOverlayManagerElement

The overlay element with updated properties.

channel int

The video channel index containing the overlay. Default is 0.

Remarks

This method removes the existing overlay and adds it back with updated properties. The overlay's position in the rendering order is preserved.

OnError

Occurs when an error happens in any of the pipelines or during operations.

public event EventHandler<ErrorsEventArgs> OnError

Event Type

EventHandler<ErrorsEventArgs>

See Also