AsciinemaRecorder

Namespace: Hex1b

Assembly: Hex1b.dll

Records terminal sessions in asciicast v2 format (Asciinema).

public sealed class AsciinemaRecorder : IHex1bTerminalWorkloadFilter, IAsyncDisposable, IDisposable

Inheritance

Object → AsciinemaRecorder

Implements

• IHex1bTerminalWorkloadFilter
• IAsyncDisposable
• IDisposable

Constructors

AsciinemaRecorder()

Creates a new Asciinema recorder in idle mode (not recording).

public AsciinemaRecorder()

AsciinemaRecorder(string, AsciinemaRecorderOptions?)

Creates a new Asciinema recorder that writes to the specified file. Recording starts immediately when the session starts.

Parameters:

• filePath (String): Path to the output file (typically with .cast extension).
• options (AsciinemaRecorderOptions): Recording options. If null, defaults are used.

public AsciinemaRecorder(string filePath, AsciinemaRecorderOptions? options = null)

Properties

FilePath

Gets the file path being written to, or null if not recording.

Returns: String

public string? FilePath { get; }

IsRecording

Gets whether the recorder is currently recording.

Returns: Boolean

public bool IsRecording { get; }

Options

Gets the recording options.

Returns: AsciinemaRecorderOptions

public AsciinemaRecorderOptions Options { get; }

PendingEventCount

Gets the number of events pending flush.

Returns: Int32

public int PendingEventCount { get; }

Methods

AddMarker(string, TimeSpan?)

Adds a marker event at the current time.

Parameters:

• label (String): Optional label for the marker.
• elapsed (Nullable<TimeSpan>): Time elapsed since session start.

public void AddMarker(string label = "", TimeSpan? elapsed = null)

ClearPending()

Clears all pending events (events already flushed to disk remain).

public void ClearPending()

Dispose()

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

public void Dispose()

DisposeAsync()

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

Returns: ValueTask

A task that represents the asynchronous dispose operation.

public ValueTask DisposeAsync()

FlushAsync(CancellationToken)

Flushes any pending events to the file.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: Task

public Task FlushAsync(CancellationToken ct = default)

StartRecording(string, AsciinemaRecorderOptions?)

Starts recording to the specified file.

Parameters:

• filePath (String): Path to the output file (typically with .cast extension).
• options (AsciinemaRecorderOptions): Recording options. If null, defaults are used.

public void StartRecording(string filePath, AsciinemaRecorderOptions? options = null)

StopRecordingAsync(CancellationToken)

Stops recording and finalizes the current file.

Parameters:

• ct (CancellationToken):

Returns: Task<String>

The path to the finalized recording file, or null if not recording.

public Task<string?> StopRecordingAsync(CancellationToken ct = default)

WriteInitialStateAsync(string, CancellationToken)

Writes synthesized initial state as the first output event.

Parameters:

• ansiContent (String): ANSI content representing the current terminal state.
• ct (CancellationToken): Cancellation token.

Returns: Task

public Task WriteInitialStateAsync(string ansiContent, CancellationToken ct = default)

Remarks

This filter captures terminal output and optionally input, producing files compatible with the Asciinema player and ecosystem.

The asciicast v2 format is newline-delimited JSON: First line: Header with metadata (version, dimensions, timestamp)Subsequent lines: Events as [time, type, data] tuples

var options = new Hex1bTerminalOptions { ... };
var recorder = options.AddAsciinemaRecorder("demo.cast", new AsciinemaRecorderOptions { Title = "Demo" });
var terminal = new Hex1bTerminal(options);
// ... run application ...
// Recording is automatically saved on dispose, or call FlushAsync() to flush buffered events