Class SimplePlayerCoreX
- Namespace
- VisioForge.Core.SimplePlayerX
- Assembly
- VisioForge.Core.dll
Provides GStreamer bus message handling for SimplePlayerX, managing PlayBin3 pipeline events and state changes. This partial class handles asynchronous communication from the GStreamer pipeline including video overlay setup, stream collection parsing, error propagation, end-of-stream notifications, and state transition monitoring. Essential for maintaining player state and providing event notifications in the simplified player implementation. Implements the IDisposable. Implements the IAsyncDisposable.
public class SimplePlayerCoreX : IDisposable, IAsyncDisposable, INotifyPropertyChangedInheritance
Implements
Inherited Members
Constructors
SimplePlayerCoreX(IVideoView)
Initializes a new instance of the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX class.
public SimplePlayerCoreX(IVideoView videoView)Parameters
videoViewIVideoView-
The video view control that will render video output. Can be null for audio-only playback.
Remarks
This constructor initializes the VisioForgeX SDK context and associates the player with a video view control. The video view must implement VisioForge.Core.Types.IVideoView interface and provide platform-specific video rendering capabilities. If videoView is null, video rendering is disabled and only audio playback is supported.
Properties
Audio_Mute
Gets or sets a value indicating whether audio output is muted.
public bool Audio_Mute { get; set; }Property Value
Remarks
Muting preserves the current VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Audio_Volume setting. When unmuted, audio resumes at the previous volume level. This property can be changed during playback and takes effect immediately. Muting is implemented at the GStreamer PlayBin3 element level, not at the system audio level.
Audio_Streams
Gets a collection of available audio streams in the current media.
public ObservableCollection<AudioStreamInfo> Audio_Streams { get; }Property Value
Remarks
This collection is populated after media playback starts and the GStreamer pipeline has parsed the stream information. Each VisioForge.Core.Types.MediaInfo.AudioStreamInfo contains metadata such as language, codec, channels, and stream identifier. The collection is empty when no media is loaded or before stream information becomes available. Use methods in Streams.cs to select a specific audio stream for playback. Subscribe to VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnStreamsInfoAvailable to be notified when stream information is ready.
Audio_Streams_MixAll
Gets or sets a value indicating whether to mix all audio streams together during playback.
public bool Audio_Streams_MixAll { get; set; }Property Value
Remarks
When enabled, an 'adder' element is configured as the audio-stream-combiner for the PlayBin3 element. This allows simultaneous playback of multiple audio streams from multi-language or multi-track content. The adder element mixes the audio samples from all streams into a single output stream. This property must be set before calling VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Start(VisioForge.Core.Types.X.Sources.UniversalSourceSettings) or VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.StartAsync(VisioForge.Core.Types.X.Sources.UniversalSourceSettings) to take effect.
Audio_Volume
Gets or sets the audio volume level for playback.
public double Audio_Volume { get; set; }Property Value
Remarks
The volume can be adjusted during playback. Changes take effect immediately. This property controls the GStreamer PlayBin3 element's volume property. The actual output volume also depends on the system volume settings and audio output device capabilities.
Debug_Dir
Gets or sets the directory path where debug files and logs will be saved.
public string Debug_Dir { get; set; }Property Value
Remarks
When VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Debug_Mode is enabled, this directory will contain:
- Log files with detailed player operations
- GStreamer pipeline graph DOT files for visualization Debug files are named with timestamps to prevent overwrites. Changing this property during runtime reconfigures the logger.
Debug_DisableMessageDialogs
Gets or sets a value indicating whether to suppress error message dialogs on Windows platforms when no error handler is attached.
public bool Debug_DisableMessageDialogs { get; set; }Property Value
Remarks
On Windows platforms, when VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnError event has no handlers attached, the player will display error message dialogs unless this property is set to true. This property only affects Windows builds (NET_WINDOWS). When set to true, errors are only logged and no UI dialogs are shown.
Debug_Mode
Gets or sets a value indicating whether detailed debug logging is enabled.
public bool Debug_Mode { get; set; }Property Value
Remarks
When enabled, debug mode:
- Sets Serilog minimum log level to Debug (instead of Error)
- Creates detailed log files in the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Debug_Dir directory
- Enables pipeline graph export via VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Debug_SavePipeline(System.String) method
- Logs include timestamps, thread information, and detailed event data Debug mode should be disabled in production to minimize performance impact and log file size. Changing this property during runtime reconfigures the logger.
Debug_Telemetry
Gets or sets a value indicating whether telemetry data collection is enabled for debugging purposes.
public bool Debug_Telemetry { get; set; }Property Value
Remarks
When enabled and running under a debugger, telemetry includes: - Exception stack traces and breadcrumbs - Environment PATH variables - Application version information - Custom tags for debugging context
Only anonymous data is collected and sent to Sentry. Telemetry is only active when IsAttached is true. This feature requires a valid Sentry DSN to be configured. Changing this property during runtime reconfigures the logger.
SDK_BuildDate
Gets the build date of the VisioForge SDK.
public static DateTime SDK_BuildDate { get; }Property Value
Remarks
This property provides version tracking and diagnostic information. The build date is extracted from the assembly's build timestamp.
SDK_Version
Gets the version number of the VisioForge SDK.
public static Version SDK_Version { get; }Property Value
Remarks
This property provides version tracking and compatibility checking. The version is extracted from the assembly's version attribute. Use this to verify SDK compatibility and for support diagnostics.
State
Gets the current playback state of the player.
public PlaybackState State { get; }Property Value
Remarks
This property reflects the player's current operational state:
- VisioForge.Core.Types.PlaybackState.Free: Player is not playing (initial state or after stop)
- VisioForge.Core.Types.PlaybackState.Play: Player is actively playing media
- VisioForge.Core.Types.PlaybackState.Pause: Playback is paused The property implements INotifyPropertyChanged to support data binding in UI frameworks. State changes are managed internally by playback control methods and GStreamer state changes.
Subtitle_Streams
Gets a collection of available subtitle streams in the current media.
public ObservableCollection<SubtitleStreamInfo> Subtitle_Streams { get; }Property Value
Remarks
This collection is populated after media playback starts and the GStreamer pipeline has parsed the stream information. Each VisioForge.Core.Types.MediaInfo.SubtitleStreamInfo contains metadata such as language, format, and stream identifier. The collection is empty when no media is loaded, before stream information becomes available, or if the media has no subtitle streams. Subscribe to VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnStreamsInfoAvailable to be notified when stream information is ready.
Video_Streams
Gets a collection of available video streams in the current media.
public ObservableCollection<VideoStreamInfo> Video_Streams { get; }Property Value
Remarks
This collection is populated after media playback starts and the GStreamer pipeline has parsed the stream information. Each VisioForge.Core.Types.MediaInfo.VideoStreamInfo contains metadata such as resolution, codec, and stream identifier. The collection is empty when no media is loaded or before stream information becomes available. Subscribe to VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnStreamsInfoAvailable to be notified when stream information is ready.
Methods
Audio_Stream_Select(AudioStreamInfo)
Selects and activates a specific audio stream for playback.
public bool Audio_Stream_Select(AudioStreamInfo stream)Parameters
streamAudioStreamInfo-
The VisioForge.Core.Types.MediaInfo.AudioStreamInfo object representing the audio stream to activate.
Returns
- bool
-
true if the stream selection was successful; false if the pipeline is not initialized or the stream selection event failed.
Remarks
This method sends a select-streams event to the GStreamer pipeline to switch the active audio stream. The stream parameter should be obtained from the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Audio_Streams collection.
Stream selection can be performed during playback without stopping. The change may not be instantaneous depending on buffering and codec switching time. If the current video stream exists, it is preserved during audio stream switching.
Common use cases: - Switching between different language tracks in multi-language content - Selecting between stereo and surround sound audio tracks - Choosing commentary or descriptive audio tracks
Audio_Streams_Current()
Gets the index of the currently playing audio stream.
public int Audio_Streams_Current()Returns
- int
-
The zero-based index of the currently active audio stream, or 0 if the playbin is not initialized.
Remarks
This method queries the current audio stream index from the GStreamer PlayBin3 element. If the pipeline is not initialized, an error is logged and 0 is returned. Use this method to determine which audio stream from the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Audio_Streams collection is currently active.
Debug_SavePipeline(string)
Saves the current GStreamer pipeline graph to a DOT file for debugging purposes. The file is saved in the debug directory if configured.
public void Debug_SavePipeline(string name)Parameters
namestring-
The name of the DOT file to create (without extension).
Dispose(bool)
Releases unmanaged and - optionally - managed resources used by the player.
protected virtual void Dispose(bool disposing)Parameters
disposingbool-
trueto release both managed and unmanaged resources;falseto release only unmanaged resources.
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.
public ValueTask DisposeAsync()Returns
- ValueTask
-
A task that represents the asynchronous dispose operation.
Duration()
Gets the total duration of the currently playing media synchronously.
public TimeSpan Duration()Returns
- TimeSpan
-
The total media duration as a TimeSpan, or Zero if no media is loaded or duration query fails.
Remarks
This method queries the GStreamer pipeline for the media duration in nanoseconds and converts it to milliseconds. Duration may be unavailable or inaccurate for:
- Live streams (returns zero or maximum value)
- Files with incomplete or missing index information
- Certain streaming protocols that don't provide duration metadata If the duration query fails, an error is raised via VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnError event.
DurationAsync()
Gets the total duration of the currently playing media asynchronously.
public Task<TimeSpan> DurationAsync()Returns
- Task<TimeSpan>
-
A task that represents the asynchronous operation. The task result contains the media duration, or Zero if duration cannot be determined.
Remarks
Duration may not be available for live streams or certain streaming protocols. The duration is queried from the GStreamer pipeline and may not be accurate for files with variable bitrate or incomplete index.
~SimplePlayerCoreX()
Finalizes an instance of the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX class. Ensures resources are released if Dispose was not called explicitly.
protected ~SimplePlayerCoreX()GetContext()
Gets the execution context containing logging configuration and GStreamer environment settings.
public ContextX GetContext()Returns
- ContextX
-
The VisioForge.Core.GStreamer.ContextX instance that manages logging and GStreamer initialization for this player.
Remarks
The context provides access to:
- Serilog logger instance
- Debug, Info, Warning, and Error logging methods
- GStreamer initialization state
- Thread-safe logging operations Use this context when you need lower-level access to the player's execution environment.
GetLogger()
Gets the current Serilog logger instance associated with this player for structured logging operations.
public ILogger GetLogger()Returns
- ILogger
-
The Serilog.ILogger instance configured with the player's debug settings.
Remarks
The returned logger is configured based on the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Debug_Mode and VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Debug_Telemetry settings. Use this logger to write custom log entries that integrate with the player's logging infrastructure. Log entries are written to both debug output and file (when debug mode is enabled). The logger is automatically reconfigured when debug settings change.
OnPropertyChanged(string)
Raises the PropertyChanged event for data binding support.
protected virtual void OnPropertyChanged(string propertyName = null)Parameters
propertyNamestring-
The name of the property that changed. Automatically populated by CallerMemberName.
Pause()
Pauses media playback synchronously.
public bool Pause()Returns
- bool
-
true if the pipeline was successfully paused; false if no media is loaded or the state change failed.
Remarks
This method transitions the GStreamer pipeline to Paused state, suspending audio and video output while maintaining current position. The player state is updated to VisioForge.Core.Types.PlaybackState.Pause before the pipeline state change. If the state change fails, an error is raised via VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnError event and the method returns false.
PauseAsync()
Pauses media playback asynchronously.
public Task PauseAsync()Returns
- Task
-
A task that represents the asynchronous pause operation.
Remarks
When paused, the player maintains its current position and can be resumed with VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.ResumeAsync or VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Resume. Audio and video output are suspended, but buffered data is retained. The player state transitions to VisioForge.Core.Types.PlaybackState.Pause.
Position_Get()
Gets the current playback position synchronously.
public TimeSpan Position_Get()Returns
- TimeSpan
-
The current playback position as a TimeSpan, or Zero if no media is loaded or position query fails.
Remarks
This method queries the GStreamer pipeline for the current time position. The position is converted from nanoseconds (GStreamer's internal time unit) to milliseconds. Position accuracy depends on the media format and seeking capabilities of the source.
Position_GetAsync()
Gets the current playback position asynchronously.
public Task<TimeSpan> Position_GetAsync()Returns
- Task<TimeSpan>
-
A task that represents the asynchronous operation. The task result contains the current playback position, or Zero if position cannot be determined.
Remarks
The position represents the elapsed time from the start of the media. Position updates continuously during playback and can be used for displaying time information or progress bars. For live streams, the returned position may represent buffered data position rather than actual broadcast time.
Position_Set(TimeSpan, bool)
Seeks to a specific position in the media synchronously.
public void Position_Set(TimeSpan position, bool seekToKeyframe = false)Parameters
positionTimeSpan-
The target playback position to seek to.
seekToKeyframebool-
True to seek to the nearest keyframe (faster but less accurate); false for frame-accurate seeking.
Remarks
This method performs a seek operation with flush semantics, clearing buffered data before seeking. When seekToKeyframe is true, the Gst.SeekFlags.KeyUnit flag is added to snap to the nearest keyframe.
Keyframe seeking is recommended for: - Quick navigation in large files - Live stream rewind operations - Preview thumbnails generation Frame-accurate seeking is recommended for: - Precise editing operations - Subtitle synchronization - Frame-by-frame analysis
If the seek operation fails, an error is raised via VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnError event.
Position_SetAsync(TimeSpan, bool)
Seeks to a specific position in the media asynchronously.
public Task Position_SetAsync(TimeSpan position, bool seekToKeyframe = false)Parameters
positionTimeSpan-
The target playback position to seek to.
seekToKeyframebool-
True to seek to the nearest keyframe (faster but less accurate); false for frame-accurate seeking.
Returns
- Task
-
A task that represents the asynchronous seek operation.
Remarks
Seeking to a keyframe is faster but may result in a position slightly different from the requested position. Frame-accurate seeking is slower but positions more precisely at the requested time. Not all media formats support accurate seeking. Errors during seeking are reported via the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnError event.
Resume()
Resumes paused media playback synchronously.
public bool Resume()Returns
- bool
-
true if the pipeline was successfully resumed; false if no media is loaded or the state change failed.
Remarks
This method transitions the GStreamer pipeline from Paused state back to Playing state. The player state is updated to VisioForge.Core.Types.PlaybackState.Play before the pipeline state change. If the state change fails, an error is raised via VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnError event and the method returns false. Playback continues from the position where it was paused.
ResumeAsync()
Resumes paused media playback asynchronously.
public Task ResumeAsync()Returns
- Task
-
A task that represents the asynchronous resume operation.
Remarks
This method resumes playback from the position where it was paused. It should only be called when the player is in VisioForge.Core.Types.PlaybackState.Pause state. After resuming, the player state transitions to VisioForge.Core.Types.PlaybackState.Play.
Start(UniversalSourceSettings)
Starts media playback synchronously with the specified settings.
public bool Start(UniversalSourceSettings settings)Parameters
settingsUniversalSourceSettings-
The universal source settings containing media URI and playback configuration.
Returns
- bool
-
true if the GStreamer pipeline was created and started successfully; false if pipeline initialization or state change failed.
Remarks
This method performs the following operations: - Creates a new PlayBin3 element instance - Configures the media URI from settings - Optionally configures audio stream mixing if VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Audio_Streams_MixAll is enabled - Attaches bus message handlers for error and state change notifications - Invokes video view initialization - Transitions the pipeline to Playing state
This is a synchronous operation that blocks until the pipeline state change completes. For non-blocking operation, use VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.StartAsync(VisioForge.Core.Types.X.Sources.UniversalSourceSettings) instead.
StartAsync(UniversalSourceSettings)
Starts media playback asynchronously with the specified settings.
public Task<bool> StartAsync(UniversalSourceSettings settings)Parameters
settingsUniversalSourceSettings-
The universal source settings containing media URI and playback configuration.
Returns
- Task<bool>
-
A task that represents the asynchronous operation. The task result contains true if playback started successfully; otherwise, false.
Remarks
This method creates a GStreamer PlayBin3 pipeline, configures it with the specified settings, and starts playback on a background thread. The PlayBin3 element automatically handles format detection, codec selection, and stream management. Use this method when you need to start playback without blocking the calling thread. Subscribe to VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.OnError event to handle playback errors.
Stop()
Stops media playback synchronously and releases GStreamer resources.
public bool Stop()Returns
- bool
-
Always returns true. This method does not fail if resources are already released.
Remarks
This method performs the following operations:
- Sets the async flag to false
- Transitions the GStreamer pipeline to Null state (if active)
- Disposes the PlayBin3 element and releases resources
- Sets the player state to VisioForge.Core.Types.PlaybackState.Free This is a synchronous operation that blocks until cleanup completes. For non-blocking operation, use VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.StopAsync instead.
StopAsync()
Stops media playback asynchronously and releases GStreamer resources.
public Task<bool> StopAsync()Returns
- Task<bool>
-
A task that represents the asynchronous operation. The task result contains true if playback was stopped successfully; false if the player was already in Free state.
Remarks
This method transitions the GStreamer pipeline to Null state, disposes the PlayBin3 element, and sets the player state to Free. If the player is already stopped (VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.State is VisioForge.Core.Types.PlaybackState.Free), the method returns immediately. Use this method when you need to stop playback without blocking the calling thread.
Video_Stream_Select(VideoStreamInfo)
Selects and activates a specific video stream for playback.
public bool Video_Stream_Select(VideoStreamInfo stream)Parameters
streamVideoStreamInfo-
The VisioForge.Core.Types.MediaInfo.VideoStreamInfo object representing the video stream to activate.
Returns
- bool
-
true if the stream selection was successful; false if the pipeline is not initialized or the stream selection event failed.
Remarks
This method sends a select-streams event to the GStreamer pipeline to switch the active video stream. The stream parameter should be obtained from the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Video_Streams collection.
Stream selection can be performed during playback without stopping. The change may not be instantaneous depending on buffering and codec switching time. Video switching may cause a brief display disruption while the new stream is decoded and rendered.
Common use cases: - Switching between different camera angles in multi-angle content - Selecting between different quality/resolution video tracks - Choosing between main video and picture-in-picture streams
OnError
Event raised when an error occurs during media playback or player operations.
public event EventHandler<ErrorsEventArgs> OnErrorEvent Type
Remarks
This event provides error information through VisioForge.Core.Types.Events.ErrorsEventArgs, including error level and message. Errors can originate from:
- GStreamer pipeline errors (media format issues, missing codecs, I/O errors)
- Playback operations (seek failures, state change failures)
- Serilog logger errors (when error event propagation is enabled) If no event handler is attached on Windows platforms and VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Debug_DisableMessageDialogs is false, error messages will be displayed in dialogs.
OnStop
Event raised when media playback stops, either explicitly via VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Stop or due to end-of-stream.
public event EventHandler<StopEventArgs> OnStopEvent Type
Remarks
This event is triggered when:
- VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Stop or VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.StopAsync is called
- Media playback reaches the end of the stream (EOS)
- An unrecoverable error causes playback to halt After this event, the player enters the VisioForge.Core.Types.PlaybackState.Free state and can be started again with new media.
OnStreamsInfoAvailable
Event raised when media stream information becomes available after playback starts.
public event EventHandler<EventArgs> OnStreamsInfoAvailableEvent Type
Remarks
This event is triggered after the GStreamer pipeline has parsed the media file and extracted stream metadata. At this point, the VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Video_Streams, VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Audio_Streams, and VisioForge.Core.SimplePlayerX.SimplePlayerCoreX.Subtitle_Streams collections are populated with available streams. Subscribe to this event to perform stream selection, display stream information in UI, or configure stream-specific settings. The event is raised during the initial playback start, not on resume or seek operations.
PropertyChanged
Property changed event.
public event PropertyChangedEventHandler PropertyChanged