From 5b9f275c82796f0214dc440369d22b9bccdb7b9f Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Mon, 26 Jan 2026 04:09:53 -0800 Subject: [PATCH 01/13] Update MediaElement documentation to include foreground service requirements for Android --- docs/maui/get-started.md | 4 +++- docs/maui/views/MediaElement.md | 27 +++++++++++++++++++++++++-- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/maui/get-started.md b/docs/maui/get-started.md index e45014fc..e1afed08 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 fail to do this, 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..808a2550 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); ``` 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,29 @@ 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` + +Add the following permissions to the `AndroidManifest.xml` file located in the `Platforms/Android` folder of your project. + +```xml + + + + + + + + + + + + + + +``` + +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/AndroidManifest.xml) + ### [Mac Catalyst](#tab/mac) Edit the `Info.plist` for `MacCatalyst` and add the following keys. From b6a9ff7ba73668f1f1ba12dd3cce69f0313b1c87 Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Mon, 26 Jan 2026 04:14:25 -0800 Subject: [PATCH 02/13] Fix minor error --- docs/maui/views/MediaElement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 808a2550..3872246e 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -49,7 +49,7 @@ 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. 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`. +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(); From 4401ea3365ca1d6e606112c3ee708cb32c1a391d Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Mon, 26 Jan 2026 04:42:26 -0800 Subject: [PATCH 03/13] Update MediaElement documentation to include background playback permissions and rich media notifications --- docs/maui/views/MediaElement.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 3872246e..2d6f7c1d 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -82,7 +82,7 @@ For a full example of this method included in an application please refer to the #### 2. Add required permissions to `AndroidManifest.xml` -Add the following permissions to the `AndroidManifest.xml` file located in the `Platforms/Android` folder of your project. +If you are using background playback and want rich media notifications you will need to add the following permissions to the `AndroidManifest.xml` file located in the `Platforms/Android` folder of your project. ```xml @@ -172,6 +172,12 @@ 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 audio playback by setting the `enableForegroundService` parameter to `true` when calling the `UseMauiCommunityToolkitMediaElement` method in *MauiProgram.cs*. +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. + ### Using Metadata A `MediaElement` can use metadata for `MediaElement.MetadataTitle`, `MediaElement.MetadataArtist` and `MediaElement.MetadataArtworkUrl`. You can set From 7aaf986f34f4dfb897bd5a9307d344b19929a496 Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Mon, 26 Jan 2026 04:44:02 -0800 Subject: [PATCH 04/13] Clarify documentation for enabling background video playback in MediaElement --- docs/maui/views/MediaElement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 2d6f7c1d..9b99cb27 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -174,7 +174,7 @@ Platform provided media playback controls are enabled by default, and can be dis ### 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 audio playback by setting the `enableForegroundService` parameter to `true` when calling the `UseMauiCommunityToolkitMediaElement` method in *MauiProgram.cs*. +1. Enable background video playback by setting the `enableForegroundService` parameter to `true` when calling the `UseMauiCommunityToolkitMediaElement` method in *MauiProgram.cs*. 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. From 781942a3d7533bbc9079cf0f605e34e0ab5c52bd Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Mon, 26 Jan 2026 04:46:47 -0800 Subject: [PATCH 05/13] Add documentation for enabling foreground service in MediaElement on Android --- docs/maui/views/MediaElement.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 9b99cb27..4591dd33 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -178,6 +178,12 @@ A `MediaElement` can show rich media notifications on Android, iOS, Mac Catalyst 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. +### 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. + +You must also add the required permissions to the `AndroidManifest.xml` file as described in the [Platform specific initialization](#platform-specific-initialization) section. +The purpose of the foreground service is to keep the media playback active when the application is in the background. The foreground service also enables rich media notifications. + ### Using Metadata A `MediaElement` can use metadata for `MediaElement.MetadataTitle`, `MediaElement.MetadataArtist` and `MediaElement.MetadataArtworkUrl`. You can set From 1c4b6d096f3db5be09a94d551c6f68d8347a89b6 Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Mon, 26 Jan 2026 04:47:50 -0800 Subject: [PATCH 06/13] Update MediaElement documentation to clarify metadata setup for rich media notifications --- docs/maui/views/MediaElement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 4591dd33..a6059cfb 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -176,7 +176,7 @@ Platform provided media playback controls are enabled by default, and can be dis 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*. 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. +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. From 1384646bc000715cd1351ba0a01959874728305b Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Mon, 26 Jan 2026 04:53:35 -0800 Subject: [PATCH 07/13] Clarify instructions for enabling rich media notifications in MediaElement documentation --- docs/maui/views/MediaElement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index a6059cfb..d98f31b5 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -174,7 +174,7 @@ Platform provided media playback controls are enabled by default, and can be dis ### 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*. +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 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. From b42d6e105cd552f51aa8b814a79e2d4fec5df19e Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Wed, 28 Jan 2026 08:11:18 -0800 Subject: [PATCH 08/13] Update docs/maui/views/MediaElement.md Co-authored-by: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> --- docs/maui/views/MediaElement.md | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index d98f31b5..c2830623 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -81,28 +81,6 @@ 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` - -If you are using background playback and want rich media notifications you will need to add the following permissions to the `AndroidManifest.xml` file located in the `Platforms/Android` folder of your project. - -```xml - - - - - - - - - - - - - - -``` - -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/AndroidManifest.xml) - ### [Mac Catalyst](#tab/mac) Edit the `Info.plist` for `MacCatalyst` and add the following keys. From 089347475e8c8528c4d968376abad6635ca0dfad Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Wed, 28 Jan 2026 08:11:26 -0800 Subject: [PATCH 09/13] Update docs/maui/views/MediaElement.md Co-authored-by: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> --- docs/maui/views/MediaElement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index c2830623..77fa3cce 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -55,7 +55,7 @@ In order to use the `MediaElement` correctly the `UseMauiCommunityToolkitMediaEl var builder = MauiApp.CreateBuilder(); builder .UseMauiApp() - .UseMauiCommunityToolkitMediaElement(enableForegroundService: true); + .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. From eb423275f6fd40271a2f5f652387531118aee71b Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Wed, 28 Jan 2026 08:11:34 -0800 Subject: [PATCH 10/13] Update docs/maui/views/MediaElement.md Co-authored-by: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> --- docs/maui/views/MediaElement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 77fa3cce..628a0795 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -152,7 +152,7 @@ Platform provided media playback controls are enabled by default, and can be dis ### 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 for more information. +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. From 420add9aa39a60cf49b0e2bb35fe83058026639d Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Wed, 28 Jan 2026 08:11:42 -0800 Subject: [PATCH 11/13] Update docs/maui/views/MediaElement.md Co-authored-by: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> --- docs/maui/views/MediaElement.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 628a0795..15b86887 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -159,7 +159,8 @@ A `MediaElement` can show rich media notifications on Android, iOS, Mac Catalyst ### 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. -You must also add the required permissions to the `AndroidManifest.xml` file as described in the [Platform specific initialization](#platform-specific-initialization) 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. The purpose of the foreground service is to keep the media playback active when the application is in the background. The foreground service also enables rich media notifications. ### Using Metadata From b099bb4c8c1170ee3411387c158d5265ae2cb778 Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Wed, 28 Jan 2026 08:11:49 -0800 Subject: [PATCH 12/13] Update docs/maui/get-started.md Co-authored-by: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> --- docs/maui/get-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/get-started.md b/docs/maui/get-started.md index e1afed08..fbf6619d 100644 --- a/docs/maui/get-started.md +++ b/docs/maui/get-started.md @@ -139,7 +139,7 @@ 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 fail to do this, an exception will be thrown when the application is run on Android. +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(); From 7aeed1b8204162166a4e86fc00ee7791c4aa7f92 Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Wed, 28 Jan 2026 15:12:50 -0800 Subject: [PATCH 13/13] Fix duplication --- docs/maui/views/MediaElement.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 15b86887..ddba17d2 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -159,10 +159,6 @@ A `MediaElement` can show rich media notifications on Android, iOS, Mac Catalyst ### 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. -### 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. -The purpose of the foreground service is to keep the media playback active when the application is in the background. The foreground service also enables rich media notifications. - ### Using Metadata A `MediaElement` can use metadata for `MediaElement.MetadataTitle`, `MediaElement.MetadataArtist` and `MediaElement.MetadataArtworkUrl`. You can set