Table of Contents

Class MediaInfoReaderX

Namespace
VisioForge.Core.MediaInfoReaderX
Assembly
VisioForge.Core.dll

Provides cross-platform media file analysis capabilities, extracting detailed metadata such as video resolution, frame rate, audio channels, codec information, and duration.

public class MediaInfoReaderX

Inheritance

Inherited Members

Remarks

This class serves as the primary entry point for reading media file information across different platforms. It automatically selects the appropriate underlying implementation:

  • iOS: Uses AVFoundation-based IOSMediaInfoReader for native performance.
  • Other platforms (Windows, macOS, Linux, Android): Uses GStreamer-based MediaInfoReaderCore.

The class supports both local files and remote URIs, providing synchronous and asynchronous methods for opening media sources. After successfully opening a file, access the VisioForge.Core.MediaInfoReaderX.MediaInfoReaderX.Info property to retrieve all discovered media information.

Constructors

MediaInfoReaderX(ContextX)

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

public MediaInfoReaderX(ContextX context = null)

Parameters

context ContextX

The context object providing logging, debugging, and platform-specific configuration. If null, a default context will be created internally.

Remarks

The context allows customization of logging behavior and provides platform-specific settings. When sharing a context across multiple SDK instances, logging output will be consolidated for easier debugging.

MediaInfoReaderX(MediaPlayerCoreX)

Initializes a new instance of the VisioForge.Core.MediaInfoReaderX.MediaInfoReaderX class using the context from an existing VisioForge.Core.MediaPlayerX.MediaPlayerCoreX instance.

public MediaInfoReaderX(MediaPlayerCoreX player)

Parameters

player MediaPlayerCoreX

The VisioForge.Core.MediaPlayerX.MediaPlayerCoreX instance from which to obtain the context. This allows the media info reader to share logging and configuration with the player.

Remarks

Use this constructor when you want the media info reader to use the same context as an existing media player instance. This ensures consistent logging output and shared platform-specific settings between components.

Exceptions

ArgumentNullException

Thrown when player is null.

Properties

DeepDiscovery

Gets or sets a value indicating whether deep discovery mode is enabled.

public bool DeepDiscovery { get; set; }

Property Value

bool

Remarks

When enabled, deep discovery mode uses GStreamer's uridecodebin element directly instead of the GstDiscoverer API. This approach can be more reliable for:

  • Files with non-standard or unusual container formats.
  • Media files that GstDiscoverer fails to analyze correctly.
  • Sources requiring custom decoding pipelines.

The trade-off is that deep discovery may be slower for standard media files where GstDiscoverer would work efficiently. Consider enabling this option only when the default discovery mode fails to extract complete information.

This property is not available on iOS platforms where AVFoundation is used instead.

Info

Gets the media file information discovered after opening a media source.

public MediaFileInfo Info { get; }

Property Value

MediaFileInfo

Methods

GetFileSnapshotRGB(Stream, TimeSpan?, ContextX, CancellationToken, TimeSpan?)

Captures a snapshot from a media stream and returns 24-bit RGB pixel data.

public static Tuple<byte[], int, int> GetFileSnapshotRGB(Stream stream, TimeSpan? position = null, ContextX context = null, CancellationToken cancellationToken = default, TimeSpan? timeout = null)

Parameters

stream Stream

Input stream containing a media file. The stream is copied to a temporary file before decoding. The current stream position is used (no rewinding is performed).

position TimeSpan?

Optional timestamp to seek to before capturing. If null, the first frame (0 seconds) is used.

context ContextX

Optional SDK context for logging. If null, a default context is created.

cancellationToken CancellationToken

Token used to cancel snapshot capture.

timeout TimeSpan?

Optional timeout for receiving a frame. If null, defaults to 10 seconds.

Returns

Tuple<byte[], int, int>

A tuple containing: (RGB byte array, width, height). The byte array is interleaved RGB (3 bytes per pixel), row-major order. The byte array can be null if no frame could be captured.

Remarks

This overload writes the stream to a temporary file on disk, then delegates to VisioForge.Core.MediaInfoReaderX.MediaInfoReaderX.GetFileSnapshotRGB(System.String,System.Nullable{System.TimeSpan},VisioForge.Core.GStreamer.ContextX,System.Threading.CancellationToken,System.Nullable{System.TimeSpan}).

Exceptions

ArgumentNullException

Thrown when stream is null.

GetFileSnapshotRGB(string, TimeSpan?, ContextX, CancellationToken, TimeSpan?)

Captures a snapshot from a media file and returns 24-bit RGB pixel data.

public static Tuple<byte[], int, int> GetFileSnapshotRGB(string filename, TimeSpan? position = null, ContextX context = null, CancellationToken cancellationToken = default, TimeSpan? timeout = null)

Parameters

filename string

Path to the media file to decode.

position TimeSpan?

Optional timestamp to seek to before capturing. If null, the first frame (0 seconds) is used.

context ContextX

Optional SDK context for logging. If null, a default context is created.

cancellationToken CancellationToken

Token used to cancel snapshot capture.

timeout TimeSpan?

Optional timeout for receiving a frame. If null, defaults to 10 seconds.

Returns

Tuple<byte[], int, int>

A tuple containing: (RGB byte array, width, height). The byte array is interleaved RGB (3 bytes per pixel), row-major order. The byte array can be null if no frame could be captured.

Remarks

The implementation builds a small GStreamer pipeline based on uridecodebin and performs an accurate seek where possible. Some formats/containers may return the nearest decodable frame rather than an exact timestamp.

Exceptions

ArgumentException

Thrown when filename is null or empty.

GetFileSnapshotSKBitmap(string, TimeSpan?, ContextX, CancellationToken, TimeSpan?)

Captures a snapshot from a media file and returns it as an SkiaSharp.SKBitmap.

public static SKBitmap GetFileSnapshotSKBitmap(string filename, TimeSpan? position = null, ContextX context = null, CancellationToken cancellationToken = default, TimeSpan? timeout = null)

Parameters

filename string

Path to the media file to decode.

position TimeSpan?

Optional timestamp to seek to before capturing.

context ContextX

Optional SDK context for logging.

cancellationToken CancellationToken

Token used to cancel snapshot capture.

timeout TimeSpan?

Optional timeout for receiving a frame.

Returns

SKBitmap

An SkiaSharp.SKBitmap containing the captured frame, or null if a frame could not be captured.

Exceptions

ArgumentException

Thrown when filename is null or empty.

GetFileSnapshotSKBitmap(Stream, TimeSpan?, ContextX, CancellationToken, TimeSpan?)

Captures a snapshot from a media stream and returns it as an SkiaSharp.SKBitmap.

public static SKBitmap GetFileSnapshotSKBitmap(Stream stream, TimeSpan? position = null, ContextX context = null, CancellationToken cancellationToken = default, TimeSpan? timeout = null)

Parameters

stream Stream

Input stream containing a media file.

position TimeSpan?

Optional timestamp to seek to before capturing.

context ContextX

Optional SDK context for logging.

cancellationToken CancellationToken

Token used to cancel snapshot capture.

timeout TimeSpan?

Optional timeout for receiving a frame.

Returns

SKBitmap

An SkiaSharp.SKBitmap containing the captured frame, or null if a frame could not be captured.

Exceptions

ArgumentNullException

Thrown when stream is null.

Open(string)

Opens the specified file synchronously for media information extraction.

public bool Open(string filename)

Parameters

filename string

The absolute or relative path to the media file to analyze. The path will be automatically converted to a file URI internally.

Returns

bool

true if the file was successfully opened and analyzed; false if the filename is null or empty, or if the file could not be opened.

Remarks

This method blocks the calling thread until the media file analysis is complete. For UI applications or scenarios where responsiveness is important, prefer the asynchronous VisioForge.Core.MediaInfoReaderX.MediaInfoReaderX.OpenAsync(System.String) method instead.

After successful completion, access the VisioForge.Core.MediaInfoReaderX.MediaInfoReaderX.Info property to retrieve the discovered media information.

OpenAsync(Uri)

Opens the specified URI asynchronously for media information extraction.

public Task<bool> OpenAsync(Uri uri)

Parameters

uri Uri

The URI of the media file to analyze. Supports both local file URIs (file://) and remote URIs (http://, https://, rtsp://, etc.).

Returns

Task<bool>

A task that represents the asynchronous open operation. The task result is true if the media file was successfully opened and analyzed; otherwise, false.

Remarks

After successful completion, access the VisioForge.Core.MediaInfoReaderX.MediaInfoReaderX.Info property to retrieve the discovered media information including video streams, audio streams, duration, and metadata.

OpenAsync(string)

Opens the specified file asynchronously for media information extraction.

public Task<bool> OpenAsync(string filename)

Parameters

filename string

The absolute or relative path to the media file to analyze. The path will be automatically converted to a file URI internally.

Returns

Task<bool>

A task that represents the asynchronous open operation. The task result is true if the media file was successfully opened and analyzed; false if the filename is null or empty, or if the file could not be opened.

Remarks

This is the most common method for opening local media files. After successful completion, access the VisioForge.Core.MediaInfoReaderX.MediaInfoReaderX.Info property to retrieve the discovered media information. For remote sources, use the VisioForge.Core.MediaInfoReaderX.MediaInfoReaderX.OpenAsync(System.Uri) overload.

See Also

ContextX