Merge pull request #637 from AvaloniaUI/fixes/mediaplayer-tweaks

Accelerate MediaPlayer tweaks

Author: maxkatz6

accelerate/components/media-player/mediaplayer.md

@@ -31,11 +31,11 @@ the `MediaPlayerControl`.
 
 ### 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 | MediaPlayerState | Gets or sets playback behavior when media is loaded.               |
+| 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
 
@@ -71,7 +71,7 @@ the `MediaPlayerControl`.
 | MediaPaused            | Occurs when media playback has been paused.           |
 | MediaStopped           | Occurs when media playback has been stopped.          |
 | MediaPlaybackCompleted | Occurs when media playback has completed.             |
-| OnErrorOccurred        | Occurs when an error is encountered.                  |
+| ErrorOccurred        | Occurs when an error is encountered.                  |
 | PropertyChanged        | Standard INotifyPropertyChanged event.                |
 
 ## Methods
@@ -118,7 +118,7 @@ await player.InitializeAsync();
 
 // Configure
 player.Volume = 0.8;
-player.LoadedBehavior = MediaPlayerState.AutoPlay;
+player.LoadedBehavior = MediaPlayerLoadedBehavior.Manual;
 
 // Load and play media
 player.Source = new UriSource("https://example.com/audio.mp3");
@@ -135,7 +135,7 @@ player.MediaStarted += (s, e) => Console.WriteLine("Playback started");
 player.MediaPlaybackCompleted += (s, e) => Console.WriteLine("Playback completed");
 
 // Error handling
-player.OnErrorOccurred += (s, e) => {
+player.ErrorOccurred += (s, e) => {
     Console.WriteLine($"Error: {e.ErrorMessage}");
 };
 ```
@@ -153,23 +153,18 @@ await player.UnInitialize();
 
 The MediaPlayer uses an event-based approach to error handling:
 
-- When an error occurs, the player transitions to MediaPlayerState.Error
-- The `OnErrorOccurred` event is raised with detailed error information
+- 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
 
 ```csharp
 // Subscribe to error events
-player.OnErrorOccurred += (sender, args) => async {
+player.ErrorOccurred += (sender, args) =>
+{
     // Handle the error appropriately here with your custom logic.
     // ...
     Console.WriteLine($"Error: {args.ErrorMessage}");
-
-    // Optionally reset the player
-    await player.ReleaseAsync();
-    
-    // Set this to true to avoid unhandled exception crash.
-    args.Handled = true;
 };
 
 // Try to play media
@@ -195,8 +190,7 @@ catch (Exception ex) {
     - Call `UnInitialize()` when completely done with `MediaPlayer`.
 
 2. **Error Handling**:
-    - Subscribe to the `OnErrorOccurred` event to handle playback errors.
-    - Use `ReleaseAsync()` to reset the player after an error.
+    - Subscribe to the `ErrorOccurred` event to handle playback errors.
 
 3. **Resource Management**:
     - Properly clean up to avoid resource leaks.

accelerate/components/media-player/mediaplayercontrol.md

@@ -71,44 +71,44 @@ interface for media playback.
 
 | Event           | Description                                                  |
 |-----------------|--------------------------------------------------------------|
-| OnErrorOccurred | Occurs when an error is encountered during media operations. |
+| ErrorOccurred | Occurs when an error is encountered during media operations. |
 
 ## Usage Examples
 
 ### Basic Usage
 
 ```xaml
-<MediaPlayerControl Name="mediaPlayer" Source="{Binding MediaSource}" 
-                          Volume="0.8"
-                          LoadedBehavior="AutoPlay" />
+<MediaPlayerControl Name="mediaPlayerControl" Source="{Binding MediaSource}" 
+                    Volume="0.8"
+                    LoadedBehavior="AutoPlay" />
 ```
 
 ### Binding to Commands
 
 ```xaml
-<Button Command="{Binding #mediaPlayer.PlayPauseCommand}" 
+<Button Command="{Binding #mediaPlayerControl.PlayPauseCommand}" 
         Content="Play/Pause" />
 
-<Button Command="{Binding #mediaPlayer.StopCommand}" 
+<Button Command="{Binding #mediaPlayerControl.StopCommand}" 
         Content="Stop" />
 ```
 
 ### Error Handling
 
 ```csharp
-mediaPlayer.OnErrorOccurred += (sender, args) =>
+mediaPlayerControl.ErrorOccurred += (sender, args) =>
 {
     Console.WriteLine($"Media error: {args.Message}");
     args.Handled = true; // Prevents the exception from being thrown.
 };
 ```
 
-**Note**: This callback gives you the opportunity to reset the state of the `MediaPlayer` gracefully.
+**Note**: This callback gives you the opportunity to reset the state of the `MediaPlayerControl` gracefully.
+
 
 ## Template Parts and Customization
 
-The default control template for `MediaPlayerControl` in `Avalonia.Media.Themes.Fluent`
-includes several key parts:
+The default control template for `MediaPlayerControl` includes several key parts:
 
 - **PART_MediaPlayerPresenter**: Displays the video content
 - **MediaControlOverlay**: Contains the playback controls
@@ -117,49 +117,50 @@ includes several key parts:
 The most basic configuration of the `MediaPlayerControl` can be like this:
 
 ```xml
-<!-- Put this in a ResourceDictionary referenced by your app. 
-     This by default replaces the -->
+<!-- In a ResourceDictionary referenced by your app. -->
 <ControlTheme x:Key="{x:Type MediaPlayerControl}" TargetType="MediaPlayerControl">
+  <Setter Property="Template">
     <ControlTemplate>
-        <!-- This border is for decoration and for setting a default background for the control 
-             When there's no media. -->
-        <Border Background="Gray" ClipToBounds="True" CornerRadius="4">
-            <Panel>
-                <!-- This is used to have a dark background against the MediaPlayerPresenter when there's a 
-                     video to be displayed. -->
-                <Border IsVisible="{TemplateBinding HasVideo}">
-                    <Border Background="Black" IsVisible="{TemplateBinding IsMediaActive}"/>
-                </Border>
-
-                <!-- This ViewBox is responsible on how the MediaPlayerPresenter is stretched to fit
-                     the bounding area of the control. -->
-                <Viewbox>
-                    <!-- The control in which the internal MediaPlayer draws the video -->
-                    <MediaPlayerPresenter Name="PART_MediaPlayerPresenter"/>
-                </Viewbox>
-
-                <!-- Example of the overlay playback controls. 
-                     Use the built-in Commands to easily control the playback. -->
-                <DockPanel LastChildFill="True" MaxHeight="64" VerticalAlignment="Bottom">
-                    <ProgressBar DockPanel.Dock="Bottom"
-                                 IsIndeterminate="True"
-                                 IsVisible="{TemplateBinding IsBuffering}"/>
-                    <StackPanel Orientation="Horizontal"
-                                HorizontalAlignment="Center"
-                                Spacing="10"
-                                Margin="5"
-                                TextElement.FontSize="24">
-                        <Button Content="&#x23EF;"
-                                Padding="5,-5,5,0"
-                                Command="{TemplateBinding PlayPauseCommand}"/>
-                        <Button Content="&#x23F9;"
-                                Padding="5,-5,5,0"
-                                Command="{TemplateBinding StopCommand}"/>
-                    </StackPanel>
-                </DockPanel>
-            </Panel>
-        </Border>
+      <!-- This border is for decoration and for setting a default background for the control 
+         When there's no media. -->
+      <Border Background="Gray" ClipToBounds="True" CornerRadius="4">
+        <Panel>
+          <!-- This is used to have a dark background against the MediaPlayerPresenter when there's a 
+                 video to be displayed. -->
+          <Border IsVisible="{TemplateBinding HasVideo}">
+            <Border Background="Black" IsVisible="{TemplateBinding IsMediaActive}"/>
+          </Border>
+
+          <!-- This ViewBox is responsible on how the MediaPlayerPresenter is stretched to fit
+                 the bounding area of the control. -->
+          <Viewbox>
+            <!-- The control in which the internal MediaPlayer draws the video -->
+            <MediaPlayerPresenter Name="PART_MediaPlayerPresenter"/>
+          </Viewbox>
+
+          <!-- Example of the overlay playback controls. 
+                 Use the built-in Commands to easily control the playback. -->
+          <DockPanel LastChildFill="True" MaxHeight="64" VerticalAlignment="Bottom">
+            <ProgressBar DockPanel.Dock="Bottom"
+                         IsIndeterminate="True"
+                         IsVisible="{TemplateBinding IsBuffering}"/>
+            <StackPanel Orientation="Horizontal"
+                        HorizontalAlignment="Center"
+                        Spacing="10"
+                        Margin="5"
+                        TextElement.FontSize="24">
+              <Button Content="&#x23EF;"
+                      Padding="5,-5,5,0"
+                      Command="{TemplateBinding PlayPauseCommand}"/>
+              <Button Content="&#x23F9;"
+                      Padding="5,-5,5,0"
+                      Command="{TemplateBinding StopCommand}"/>
+            </StackPanel>
+          </DockPanel>
+        </Panel>
+      </Border>
     </ControlTemplate>
+  </Setter>
 </ControlTheme>
 ```
 
@@ -195,7 +196,7 @@ flowchart LR
     class Init,Setup,Cleanup phase
 ```
 
-Here's a more comprehensive graph of `MediaPlayerControl`'s interactions with `MediaPlayer` over the course of its
+Here's a more comprehensive graph of `MediaPlayerControl`'s interactions with its internal `MediaPlayer` over the course of its
 lifetime:
 
 ```mermaid
@@ -247,11 +248,11 @@ flowchart LR
 ## Best Practices
 
 1. **Error Handling**:
-    - Always subscribe to the `OnErrorOccurred` event to handle errors gracefully.
-    - Set the `Handled` property to true on the `OnErrorOccurred` event handler if you've managed the error.
+    - Always subscribe to the `ErrorOccurred` event to handle errors gracefully.
+    - Set the `Handled` property to true on the `ErrorOccurred` event handler if you've managed the error.
 
 2. **Resource Management**:
-    - The control manages the `MediaPlayer` lifecycle automatically.
+    - The control manages the `MediaPlayerControl` lifecycle automatically.
 
 3. **UI Integration**:
     - Use the built-in commands for integrating with custom buttons/controls.
@@ -260,4 +261,4 @@ flowchart LR
 ## Related Components
 
 - [MediaPlayer](mediaplayer.md)
-- [MediaSource](mediasource.md)
+- [MediaSource](mediasource.md)

accelerate/components/media-player/quickstart.md

@@ -20,11 +20,10 @@ Accelerate MediaControls package.
 
 ## Installation
 
-Add the Avalonia Accelerate MediaControls packages to your project:
+Add the Avalonia Accelerate MediaPlayer package to your project:
 
 ```bash
-dotnet add package Avalonia.Media
-dotnet add package Avalonia.Media.Theme.Fluent
+dotnet add package Avalonia.Controls.MediaPlayer
 ```
 
 Add the default theme to your App.axaml:
@@ -134,11 +133,11 @@ public async void OpenFile_Click(object sender, RoutedEventArgs e)
 
 ```csharp
 // Play/pause
-await mediaPlayer.Player.PlayAsync();
-await mediaPlayer.Player.PauseAsync();
+await mediaPlayer.PlayAsync();
+await mediaPlayer.PauseAsync();
 
 // Stop
-await mediaPlayer.Player.StopAsync();
+await mediaPlayer.StopAsync();
 
 // Seek to position
 mediaPlayer.Position = TimeSpan.FromSeconds(30);
@@ -147,7 +146,7 @@ mediaPlayer.Position = TimeSpan.FromSeconds(30);
 mediaPlayer.Volume = 0.75;
 
 // Mute/unmute
-mediaPlayer.Player.IsMuted = true;
+mediaPlayer.IsMuted = true;
 ```
 
 ### Media Information
@@ -169,7 +168,7 @@ TimeSpan position = mediaPlayer.Position;
 ### Error Handling
 
 ```csharp
-mediaPlayer.OnErrorOccurred += (sender, args) =>
+mediaPlayer.ErrorOccurred += (sender, args) =>
 {
     Console.WriteLine($"Media error: {args.Message}");
     args.Handled = true; // Prevents the exception from being thrown.
@@ -242,7 +241,7 @@ Common issues and solutions:
 
 5. **Player in error state**
     - Call `Player.ReleaseAsync()` to reset from the error state
-    - Handle the `OnErrorOccurred` event for any error messages and reset accordingly.
+    - Handle the `ErrorOccurred` event for any error messages and reset accordingly.
 
 For more detailed information on the components: