Table of Contents

Class ClosedCaptionsTextEventArgs

Namespace
VisioForge.Core.Types.Events
Assembly
VisioForge.Core.dll

Provides data for closed captions text events, containing decoded caption text and timing information.

public class ClosedCaptionsTextEventArgs : EventArgs

Inheritance

Inherited Members

Examples

// Event handler for displaying closed caption text
void OnClosedCaptionsText(object sender, ClosedCaptionsTextEventArgs e)
{
    Console.WriteLine($"Caption: {e.Text}");
    Console.WriteLine($"Display from {e.StartTime} to {e.StopTime}");

    // Display the caption in UI
    captionLabel.Text = e.Text;

    // Schedule removal of caption at stop time
    var duration = e.StopTime - e.StartTime;
    Task.Delay(duration).ContinueWith(_ => 
    {
        Dispatcher.Invoke(() => captionLabel.Text = string.Empty);
    });
}

// Subscribe to the event
mediaPlayer.ClosedCaptionsText += OnClosedCaptionsText;

Remarks

This event args class is used when closed caption data has been decoded into readable text. Unlike VisioForge.Core.Types.Events.ClosedCaptionsBufferEventArgs which provides raw caption data, this class provides the actual text content ready for display.

Closed captions include not only dialogue but also: - Sound effects (e.g., "[door slams]", "[music playing]") - Speaker identification (e.g., "NARRATOR:", "JOHN:") - Musical notes (♪) for songs - Other audio cues important for understanding the content

The timing information ensures captions are synchronized with the audio/video content, appearing and disappearing at the appropriate times.

Constructors

ClosedCaptionsTextEventArgs(string, TimeSpan, TimeSpan)

Initializes a new instance of the VisioForge.Core.Types.Events.ClosedCaptionsTextEventArgs class with decoded caption text and timing.

public ClosedCaptionsTextEventArgs(string text, TimeSpan startTime, TimeSpan stopTime)

Parameters

text string

The decoded closed caption text to be displayed. Can be null or empty for clearing captions.

startTime TimeSpan

The media timeline position when this caption should start displaying.

stopTime TimeSpan

The media timeline position when this caption should stop displaying. Must be greater than or equal to startTime.

Examples

// Create a closed caption text event
string captionText = "[Door opens]\nJOHN: Hello, everyone!";
TimeSpan start = TimeSpan.FromSeconds(10.5);
TimeSpan stop = TimeSpan.FromSeconds(13.0);

var args = new ClosedCaptionsTextEventArgs(captionText, start, stop);
ClosedCaptionsText?.Invoke(this, args);

// Example of clearing captions
var clearArgs = new ClosedCaptionsTextEventArgs(
    string.Empty, 
    TimeSpan.FromSeconds(13.0), 
    TimeSpan.FromSeconds(13.1));
ClosedCaptionsText?.Invoke(this, clearArgs);

Remarks

This constructor is typically called by closed caption decoders after processing raw caption data into displayable text. The timing information ensures proper synchronization with the media content.

Empty or null text is valid and may be used to clear the caption display area.

Exceptions

ArgumentException

Thrown when stopTime is less than startTime.

Properties

StartTime

Gets the start time when this caption text should begin displaying.

public TimeSpan StartTime { get; }

Property Value

TimeSpan

Remarks

This timestamp is synchronized with the media playback position. When the media reaches this time position, the caption should be displayed to the viewer.

For real-time captioning (like live TV), this may be very close to the current playback time. For pre-recorded content, captions are typically prepared with precise timing.

StopTime

Gets the stop time when this caption text should be removed from display.

public TimeSpan StopTime { get; }

Property Value

TimeSpan

Remarks

The duration between VisioForge.Core.Types.Events.ClosedCaptionsTextEventArgs.StartTime and VisioForge.Core.Types.Events.ClosedCaptionsTextEventArgs.StopTime determines how long the caption remains visible. This duration varies based on: - The length of the text - The pace of dialogue - Reading speed considerations - Caption style (pop-on, paint-on, or roll-up)

Typical display durations range from 1-7 seconds, with most captions displayed for 2-4 seconds.

Text

Gets the decoded closed caption text content.

public string Text { get; }

Property Value

string

Remarks

The text may contain special formatting or markup depending on the caption source: - Line breaks for multi-line captions - Speaker identifications in uppercase - Sound effects in square brackets [sound effect] - Musical notes (♪) for songs or background music

The text encoding is typically UTF-8 or UTF-16, supporting international characters and special symbols used in closed captions.