Table of Contents

Class TeeBlock

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

Provides a media stream splitter that duplicates input data to multiple outputs without modification.

public class TeeBlock : MediaBlock, IMediaBlock, IDisposable, IMediaBlockInternals

Inheritance

Implements

Inherited Members

Extension Methods

Examples

// Example 1: Display video while recording
var tee = new TeeBlock(2, MediaBlockPadMediaType.Video);
var displayQueue = new QueueBlock();
var recordQueue = new QueueBlock();

pipeline.Connect(decoder.Output, tee.Input);
pipeline.Connect(tee.Outputs[0], displayQueue.Input);
pipeline.Connect(tee.Outputs[1], recordQueue.Input);
pipeline.Connect(displayQueue.Output, videoRenderer.Input);
pipeline.Connect(recordQueue.Output, encoder.Input);

// Example 2: Apply multiple effects
var tee = new TeeBlock(3, MediaBlockPadMediaType.Video);

pipeline.Connect(source.Output, tee.Input);
pipeline.Connect(tee.Outputs[0], blurEffect.Input);
pipeline.Connect(tee.Outputs[1], edgeDetection.Input);
pipeline.Connect(tee.Outputs[2], colorCorrection.Input);

// Example 3: Dynamic output addition
var tee = new TeeBlock(1, MediaBlockPadMediaType.Audio);
pipeline.Connect(audioSource.Output, tee.Input);

// Later, add a new output dynamically
var newOutput = tee.AddNewPadLive();
pipeline.Connect(newOutput, newAudioProcessor.Input);

Remarks

The VisioForge.Core.MediaBlocks.Special.TeeBlock (named after the Unix 'tee' command) acts as a 1-to-N splitter, taking a single input stream and replicating it to multiple output pads. This is essential for scenarios where the same media data needs to be processed or consumed by multiple downstream elements simultaneously.

Key characteristics:

  • Zero-copy operation - data is not duplicated in memory
  • Minimal performance overhead
  • Preserves all stream properties (format, timing, metadata)
  • Supports dynamic pad addition during pipeline operation
  • Each output operates independently

Common use cases:

  • Recording while displaying video
  • Applying multiple different effects to the same source
  • Sending streams to multiple network destinations
  • Creating preview and high-quality encoding paths
  • Implementing A/B testing for processing chains

Performance Note: While the tee itself has minimal overhead, connecting slow consumers can affect the entire pipeline. Consider using queue blocks after each tee output to decouple processing speeds.

Constructors

TeeBlock(int, MediaBlockPadMediaType)

Initializes a new instance of the VisioForge.Core.MediaBlocks.Special.TeeBlock class.

public TeeBlock(int numOfOutputs, MediaBlockPadMediaType mediaType)

Parameters

numOfOutputs int

The initial number of output pads to create.

mediaType MediaBlockPadMediaType

The type of media this tee will handle.

Remarks

Creates a tee block with the specified number of output pads. Additional outputs can be added later using VisioForge.Core.MediaBlocks.Special.TeeBlock.AddNewPadLive if needed.

The media type determines what kind of data can flow through the tee:

  • VisioForge.Core.MediaBlocks.MediaBlockPadMediaType.Video - For video streams
  • VisioForge.Core.MediaBlocks.MediaBlockPadMediaType.Audio - For audio streams
  • VisioForge.Core.MediaBlocks.MediaBlockPadMediaType.Auto - For any media type

While you must specify at least one output during construction, unused outputs don't consume resources until connected.

Exceptions

ArgumentException

Thrown when numOfOutputs is less than 1.

Properties

Input

Gets the input.

public override MediaBlockPad Input { get; }

Property Value

MediaBlockPad

Inputs

Gets the inputs.

public override MediaBlockPad[] Inputs { get; }

Property Value

MediaBlockPad[]

MediaType

Gets the media type that this tee block handles.

public MediaBlockPadMediaType MediaType { get; }

Property Value

MediaBlockPadMediaType

Remarks

All pads (input and outputs) of a tee block must have the same media type. This is set during construction and cannot be changed.

Output

Gets the output.

public override MediaBlockPad Output { get; }

Property Value

MediaBlockPad

Outputs

Gets the outputs.

public override MediaBlockPad[] Outputs { get; }

Property Value

MediaBlockPad[]

Type

Gets the type.

public override MediaBlockType Type { get; }

Property Value

MediaBlockType

Methods

AddNewPadLive()

Dynamically adds a new output pad to the tee while the pipeline is running.

public MediaBlockPad AddNewPadLive()

Returns

MediaBlockPad

The newly created VisioForge.Core.MediaBlocks.MediaBlockPad, or null if creation failed.

Examples

// Add a new output while streaming
var newOutput = tee.AddNewPadLive();
if (newOutput != null)
{
    var recorder = new FileRecorderBlock("output.mp4");
    pipeline.Connect(newOutput, recorder.Input);
}

Remarks

This method allows adding outputs to a tee block during active pipeline operation without interrupting the media flow. This is useful for:

  • Adding recording capabilities on demand
  • Connecting monitoring or analysis tools dynamically
  • Implementing dynamic routing scenarios

The new pad inherits the media type of the tee block and can be immediately connected to downstream elements.

Thread Safety: This method is thread-safe and can be called while the pipeline is in PLAYING state.

Build()

Builds and initializes the tee element within the pipeline.

public override bool Build()

Returns

bool

true if the element was successfully built and initialized; otherwise, false.

Remarks

This method performs the following operations:

  1. Creates the underlying GStreamer tee element
  2. Initializes it with the specified number of outputs
  3. Configures the input pad for receiving data
  4. Sets up all output pads for distribution

The method configures static pads for all outputs specified during construction. Additional dynamic pads can be added later if needed.

CleanUp()

Performs cleanup of the tee element and resources.

public void CleanUp()

Remarks

This method disposes of the underlying GStreamer tee element and resets the build state. All output connections are implicitly broken during cleanup.

After cleanup, the block cannot be used again and must be recreated if needed. This method is called automatically during disposal.

Dispose(bool)

Releases unmanaged and - optionally - managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

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

GetCore()

Gets the core GStreamer wrapper element.

public BaseElement GetCore()

Returns

BaseElement

The VisioForge.Core.GStreamer.Base.Tee wrapper that manages the underlying GStreamer tee element.

Remarks

This provides access to the wrapper class for advanced operations or direct manipulation of the tee element's properties.

GetElement()

Gets the underlying GStreamer element.

public Element GetElement()

Returns

Element

The native GStreamer tee element.

Remarks

Direct access to the GStreamer element should be used carefully. Most operations should go through the block's public API.

GetFreeOutputPad()

Gets the first unconnected output pad.

public MediaBlockPad GetFreeOutputPad()

Returns

MediaBlockPad

The first available output pad that is not connected to another block, or null if all outputs are connected.

Examples

// Dynamically connect available outputs
var freePad = tee.GetFreeOutputPad();
if (freePad != null)
{
    pipeline.Connect(freePad, newConsumer.Input);
}
else
{
    // All outputs used, add a new one
    var newPad = tee.AddNewPadLive();
    pipeline.Connect(newPad, newConsumer.Input);
}

Remarks

This method is useful for dynamically connecting outputs without tracking which pads are in use. It scans outputs in order and returns the first unconnected pad found.

If all outputs are connected, consider using VisioForge.Core.MediaBlocks.Special.TeeBlock.AddNewPadLive to create additional outputs during pipeline operation.

IsAvailable()

Determines whether the tee functionality is available in the current environment.

public static bool IsAvailable()

Returns

bool

true if the tee element is available; otherwise, false.

Remarks

The tee is a core GStreamer element and should be available in all standard installations. If this returns false, it indicates a serious problem with the GStreamer installation.

Always verify availability before creating instances, especially in environments with custom or minimal GStreamer installations.

IMediaBlockInternals.SetContext(MediaBlocksPipeline)

Sets the context.

void IMediaBlockInternals.SetContext(MediaBlocksPipeline pipeline)

Parameters

pipeline MediaBlocksPipeline

The pipeline.

See Also