MediaPlayer class

The MediaPlayer class provides the core functionality for media playback in Avalonia applications. It handles media loading, playback control, and platform-specific backend management, serving as the engine behind MediaPlayerControl.

info

This control is available as part of Avalonia Pro or higher.

Using MediaPlayer without MediaPlayerControl

When using MediaPlayer without MediaPlayerControl, you must call InitializeAsync() first and ensure the source is set only after the control is loaded:

private MediaPlayer _player = new MediaPlayer();

protected override async void OnLoaded(RoutedEventArgs e)
{
    base.OnLoaded(e);

    await _player.InitializeAsync();

    _player.Volume = 0.8;
    _player.LoadedBehavior = MediaPlayerState.AutoPlay;

    _player.Source = new UriSource("file:///C:/Videos/sample.mp4");
    await _player.PrepareAsync();
    await _player.PlayAsync();
}

Properties

Media source properties

Property	Type	Description
Source	MediaSource	Gets or sets the media source to be played (UriSource or StreamSource).

Playback properties

Property	Type	Description
Position	TimeSpan	Gets or sets the current playback position.
Duration	TimeSpan?	Gets the total duration of the media. Null for non-seekable media.
LoadedBehavior	MediaPlayerLoadedBehavior	Gets or sets playback behavior when media is loaded.

State properties

Property	Type	Description
IsSeekable	bool	Gets whether the current media supports seeking.
IsBuffering	bool	Gets whether the media is currently buffering.
BufferProgress	double?	Gets buffer progress (0.0-1.0). Null if not available.
HasVideo	bool	Gets whether the current media contains video content.
LastErrorMessage	string	Gets the most recent error message in error state.

Audio properties

Property	Type	Description
Volume	double	Gets or sets the playback volume (0.0-1.0).
IsMuted	bool	Gets or sets whether audio is muted.

Advanced properties

Property	Type	Description
Statistics	MediaStatistics	Gets playback statistics information if available.
ForceVlcBackend	bool (static)	Forces the use of VLC backend (debugging only).

Events

Event	Description
NaturalSizeChanged	Occurs when the natural size of the video changes.
MediaPrepared	Occurs when the media has been prepared and is ready.
MediaStarted	Occurs when media playback has started.
MediaPaused	Occurs when media playback has been paused.
MediaStopped	Occurs when media playback has been stopped.
MediaPlaybackCompleted	Occurs when media playback has completed.
ErrorOccurred	Occurs when an error is encountered.
PropertyChanged	Standard INotifyPropertyChanged event.

Methods

Method	Return Type	Description
InitializeAsync()	Task	Initializes the media player and its backend.
PrepareAsync()	Task	Prepares the media for playback.
PlayAsync()	Task	Starts or resumes media playback.
PauseAsync()	Task	Pauses media playback.
StopAsync()	Task	Stops media playback.
ReleaseAsync()	Task	Releases resources for the current media.
UnInitialize()	Task	Releases all resources used by the player.

Backend architecture

The MediaPlayer uses a pluggable backend architecture to support different platforms:

The backend selection is automatic based on the platform:

Usage examples

Basic playback

caution

MediaPlayer is not ready to accept a media source until the Avalonia UI has fully loaded. Always set the Source property after the Loaded event has fired. See Initialization Timing for details.

private MediaPlayer _player = new MediaPlayer();

protected override async void OnLoaded(RoutedEventArgs e)
{
    base.OnLoaded(e);

    await _player.InitializeAsync();

    _player.Volume = 0.8;
    _player.LoadedBehavior = MediaPlayerLoadedBehavior.Manual;

    _player.Source = new UriSource("file:///C:/Videos/sample.mp4");
    await _player.PrepareAsync();
    await _player.PlayAsync();
}

Using a custom visual

You can attach a custom visual target:

<Window xmlns="https://github.com/avaloniaui"
        Width="800" Height="450">

    <Grid RowDefinitions="*, Auto">
        <Viewbox VerticalAlignment="Stretch" HorizontalAlignment="Stretch">
            <MediaPlayerPresenter Name="presenter" />
        </Viewbox>
    </Grid>

</Window>

private MediaPlayer _player = new MediaPlayer();

protected async override void OnLoaded(EventArgs e)
{
    base.OnLoaded(e);

    await _player.InitializeAsync();

    _player.UpdateTargetVisual(presenter);
    _player.NaturalSizeChanged += Player_NaturalSizeChanged;
}

private void Player_NaturalSizeChanged(object? sender, NaturalSizeChangedEventArgs e)
{
    UpdatePlayerSize(e.NewSize ?? default);
}

private void UpdatePlayerSize(Size size)
{
    var elemVisual = ElementComposition.GetElementChildVisual(presenter);
    var compositor = elemVisual?.Compositor;

    if (compositor is null || elemVisual is null)
    {
        return;
    }

    elemVisual.Size = new Vector(size.Width, size.Height);
    (presenter as MediaPlayerPresenter)?.SetNaturalSize(size);
    presenter.InvalidateMeasure();
}

MediaPlayerPresenter is provided for convenience, but you can use any custom visual. Ensure that you update the visual with the size provided by the MediaPlayer instance.

Event handling

// Setup event handlers
player.MediaPrepared += (s, e) => Console.WriteLine("Ready to play");
player.MediaStarted += (s, e) => Console.WriteLine("Playback started");
player.MediaPlaybackCompleted += (s, e) => Console.WriteLine("Playback completed");

// Error handling
player.ErrorOccurred += (s, e) => {
    Console.WriteLine($"Error: {e.ErrorMessage}");
};

Resource cleanup

// Clean up when done
await player.StopAsync();
await player.ReleaseAsync();
await player.UnInitialize();

Error handling

The MediaPlayer uses an event-based approach to error handling:

• When an error occurs, the player transitions to an Error state internally
• The ErrorOccurred event is raised with detailed error information
• Most methods check for the Error state and will not proceed
• Call ReleaseAsync() to reset the error state

// Subscribe to error events
player.ErrorOccurred += (sender, args) =>
{
    // Handle the error appropriately here with your custom logic.
    // Reset with ReleaseAsync() elsewhere if you need to playback again.
    // ...
    Console.WriteLine($"Error: {args.Message}");
};

// Try to play media
try {
    await player.PlayAsync();
}
catch (Exception ex) {
    // Fallback exception handling if needed
    if (player.LastErrorMessage != null) {
        Console.WriteLine($"Error: {player.LastErrorMessage}");
        
        // Optionally reset the player
        await player.ReleaseAsync();
    }
}

Best practices

1. Initialization Timing:

   • Never set Source in a constructor. The player is not ready until the UI has loaded.
   • Set Source in an OnLoaded override or use Dispatcher.UIThread.Post to defer the call.
   • See Initialization Timing for full guidance.

2. Initialization and Cleanup:

   • Always call InitializeAsync() before using MediaPlayer.
   • Call ReleaseAsync() between loading different media sources.
   • Call UnInitialize() when completely done with MediaPlayer.

3. Error Handling:

   • Subscribe to the ErrorOccurred event to handle playback errors.

4. Resource Management:

   • Properly clean up to avoid resource leaks.
   • Consider reusing a single MediaPlayer instance for multiple media items that are to be played sequentially.

5. Platform Considerations:

   • Test media playback on all target platforms.

See also

• MediaPlayer control
• MediaSource class
• Implementing MediaPlayer
• Installing Avalonia Pro
• Troubleshooting