Skip to content

chore: update MediaElement docs to include custom http headers feature #639

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Kaaybi wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

chore: update MediaElement docs to include custom http headers feature #639

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
493e3c0
chore: update MediaElement docs to include custom http headers feature
Kaaybi Mar 20, 2026
43391ee
chore: adjust MediaElement docs according to custom http headers PR r…
Kaaybi Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions docs/maui/views/MediaElement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,38 @@ 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`.

### Play remote media with custom HTTP headers

A `MediaElement` can send custom HTTP headers when loading remote media. This is useful for authenticated streams that require an `Authorization` header or other custom headers.

```csharp
mediaElement.Source = new UriMediaSource
{
Uri = new Uri("https://example.com/stream.m3u8"),
HttpHeaders = new Dictionary<string, string>
{
["Authorization"] = "Bearer my-token"
}
};
Comment on lines +161 to +168
Copy link
Copy Markdown
Contributor

@TheCodeTraveler TheCodeTraveler Apr 2, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @Kaaybi!

To ensure we call OnSourceChanged() each time a new header is added to the dictionary, I updated UriSource.Headers to be a public readonly-property and to use an ObservableDictionary under the hood that fires an event any time its content changes.

(I.e. public event EventHandler? ContentsChanged now fires any time something is added to or removed from UriSource.Headers, and we call OnSourceChanged() when it does.)

This means that we can no longer pass in a Dictionary to UriMediaSource.HttpHeaders.

Long story short, we just need to update the docs here to use the Add method instead of passing in a Dictionary:

Suggested change
mediaElement.Source = new UriMediaSource
{
Uri = new Uri("https://example.com/stream.m3u8"),
HttpHeaders = new Dictionary<string, string>
{
["Authorization"] = "Bearer my-token"
}
};
mediaElement.Source = new UriMediaSource
{
Uri = new Uri("https://example.com/stream.m3u8")
};
mediaElement.Source.Headers.Add("Authorization", "Bearer my-token");

```

Or using the `MediaSource.FromUri` overload:

```csharp
var headers = new Dictionary<string, string>
{
["Authorization"] = "Bearer my-token"
};
mediaElement.Source = MediaSource.FromUri(
new Uri("https://example.com/stream.m3u8"), headers);
```

> [!NOTE]
> HTTP headers are applied to all HTTP requests made for the media source, including manifest and segment downloads for adaptive streams (HLS/DASH). This feature is supported on Android, iOS, macOS, and Windows. Tizen does not support custom HTTP headers.

> [!IMPORTANT]
> On iOS and macOS, custom HTTP headers are set via the `AVURLAssetHTTPHeaderFieldsKey` option, which requires iOS 16.0+ / macOS 13.0+. On earlier versions, custom headers will not be applied.

### 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.
Expand Down Expand Up @@ -241,10 +273,11 @@ An example of how to use this syntax in XAML can be seen below.

## Understand MediaSource types

A `MediaElement` can play media by setting its `Source` property to a remote or local media file. The `Source` property is of type `MediaSource`, and this class defines three static methods:
A `MediaElement` can play media by setting its `Source` property to a remote or local media file. The `Source` property is of type `MediaSource`, and this class defines the following static methods:

- `FromFile`, returns a `FileMediaSource` instance from a `string` argument.
- `FromUri`, returns a `UriMediaSource` instance from a `Uri` argument.
- `FromUri(Uri, IDictionary<string, string>)`, returns a `UriMediaSource` instance from a `Uri` argument with custom HTTP headers applied to all requests.
- `FromResource`, returns a `ResourceMediaSource` instance from a `string` argument.
Comment on lines 278 to 281
Copy link

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MediaSource static-method list mixes a bare method name (FromUri) with a full signature for the overload (FromUri(Uri, IDictionary<string, string>)). To keep the docs consistent/clear, consider listing both overloads with signatures (e.g., FromUri(Uri) and FromUri(Uri, IDictionary<string,string>)), or list only method names and note that FromUri has an overload accepting headers.

Suggested change
- `FromFile`, returns a `FileMediaSource` instance from a `string` argument.
- `FromUri`, returns a `UriMediaSource` instance from a `Uri` argument.
- `FromUri(Uri, IDictionary<string, string>)`, returns a `UriMediaSource` instance from a `Uri` argument with custom HTTP headers applied to all requests.
- `FromResource`, returns a `ResourceMediaSource` instance from a `string` argument.
- `FromFile(string)`, returns a `FileMediaSource` instance from a `string` argument.
- `FromUri(Uri)`, returns a `UriMediaSource` instance from a `Uri` argument.
- `FromUri(Uri, IDictionary<string, string>)`, returns a `UriMediaSource` instance from a `Uri` argument with custom HTTP headers applied to all requests.
- `FromResource(string)`, returns a `ResourceMediaSource` instance from a `string` argument.

Copilot uses AI. Check for mistakes.

In addition, the `MediaSource` class also has implicit operators that return `MediaSource` instances from `string` and `Uri` arguments.
Expand All @@ -255,7 +288,7 @@ In addition, the `MediaSource` class also has implicit operators that return `Me
The `MediaSource` class also has these derived classes:

- `FileMediaSource`, which is used to specify a local media file from a `string`. This class has a `Path` property that can be set to a `string`. In addition, this class has implicit operators to convert a `string` to a `FileMediaSource` object, and a `FileMediaSource` object to a `string`.
- `UriMediaSource`, which is used to specify a remote media file from a URI. This class has a `Uri` property that can be set to a `Uri`.
- `UriMediaSource`, which is used to specify a remote media file from a URI. This class has a `Uri` property that can be set to a `Uri`. It also has an `HttpHeaders` property of type `IDictionary<string, string>` that allows setting custom HTTP headers (e.g. `Authorization`) sent with all HTTP requests for this media source, including manifest and segment downloads.
- `ResourceMediaSource`, which is used to specify an embedded file that is provided through the app's resource files. This class has a `Path` property that can be set to a `string`.

> [!NOTE]
Expand Down
Loading