diff --git a/docs/maui/get-started.md b/docs/maui/get-started.md index e45014fc..fbf6619d 100644 --- a/docs/maui/get-started.md +++ b/docs/maui/get-started.md @@ -138,12 +138,14 @@ using CommunityToolkit.Maui; ``` In order to use the `MediaElement` correctly the `UseMauiCommunityToolkitMediaElement` method must be called on the `MauiAppBuilder` class when bootstrapping an application the *MauiProgram.cs* file. The following example shows how to perform this. +You must specify whether to enable the foreground service on Android by setting the `enableForegroundService` parameter to true or false. +If you require Rich Media Notifications or background playback, and `enableForegroundService` is `false`, an exception will be thrown when the application is run on Android. ```csharp var builder = MauiApp.CreateBuilder(); builder .UseMauiApp() - .UseMauiCommunityToolkitMediaElement() + .UseMauiCommunityToolkitMediaElement(enableForegroundService: true); ``` To use the features of the toolkit please refer to the documentation pages for each specific feature. diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index dfdb0330..ddba17d2 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -49,13 +49,13 @@ First the using statement needs to be added to the top of your *MauiProgram.cs* using CommunityToolkit.Maui.MediaElement; ``` -In order to use the `MediaElement` correctly the `UseMauiCommunityToolkitMediaElement` method must be called on the `MauiAppBuilder` class when bootstrapping an application the *MauiProgram.cs* file. The following example shows how to perform this. +In order to use the `MediaElement` correctly the `UseMauiCommunityToolkitMediaElement` method must be called on the `MauiAppBuilder` class when bootstrapping an application the *MauiProgram.cs* file. The following example shows how to perform this. If you fail to set `enableForeGroundService` to `true` on Android, background playback will not work. If you do not need background playback, you can set this to `false`. If you fail to call this method, an exception will be thrown when trying to use the `MediaElement`. ```csharp var builder = MauiApp.CreateBuilder(); builder .UseMauiApp() - .UseMauiCommunityToolkitMediaElement() + .UseMauiCommunityToolkitMediaElement(enableForegroundService: true); // Set to `false` if Rich Notifications and background playback is not required ``` For more information on how to do this, please refer to the [Get Started](../get-started.md?tabs=CommunityToolkitMauiMediaElement#adding-the-nuget-packages) page. @@ -80,6 +80,7 @@ public class MainActivity : MauiAppCompatActivity For a full example of this method included in an application please refer to the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Platforms/Android/MainActivity.cs) +#### 2. Add required permissions to `AndroidManifest.xml` ### [Mac Catalyst](#tab/mac) Edit the `Info.plist` for `MacCatalyst` and add the following keys. @@ -149,6 +150,15 @@ By default, the media that is defined by the `Source` property doesn't immediate Platform provided media playback controls are enabled by default, and can be disabled by setting the `ShouldShowPlaybackControls` property to `false`. +### Use Rich Media Notifications +A `MediaElement` can show rich media notifications on Android, iOS, Mac Catalyst, and Windows when media is playing in the background. To enable rich media notifications, the following steps are required: +1. Enable background video playback by setting the `enableForegroundService` parameter to `true` when calling the `UseMauiCommunityToolkitMediaElement` method in *MauiProgram.cs*. Refer to the **Initializing the package** section above for more information. +2. Platform specific setup as described in the [Platform specific initialization](#platform-specific-initialization) section. +3. Set the `MetadataTitle`, `MetadataArtist`, and `MetadataArtworkUrl` properties to provide metadata for the media that is playing as described in the [Using Metadata](#using-metadata) section. + +### Foreground service on Android +To enable background playback on Android, you must set the `enableForegroundService` parameter to `true` when calling the `UseMauiCommunityToolkitMediaElement` method in *MauiProgram.cs*. If you fail to do this, an exception will be thrown when the application is run on Android. + ### Using Metadata A `MediaElement` can use metadata for `MediaElement.MetadataTitle`, `MediaElement.MetadataArtist` and `MediaElement.MetadataArtworkUrl`. You can set