diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md
index 3da67118..f603317e 100644
--- a/docs/maui/views/MediaElement.md
+++ b/docs/maui/views/MediaElement.md
@@ -13,6 +13,7 @@ ms.date: 02/15/2024
- The web, using a URI (HTTP or HTTPS).
- A resource embedded in the platform application, using the `embed://` URI scheme.
- Files that come from the app's local filesystem, using the `filesystem://` URI scheme.
+- Any valid source via a `Stream`.
`MediaElement` can use the platform playback controls, which are referred to as transport controls. However, they are disabled by default and can be replaced with your own transport controls. The following screenshots show `MediaElement` playing a video with the platform transport controls:
@@ -222,7 +223,7 @@ Local media can be played from the following sources:
- Files that come from the app's local filesystem, using the `filesystem://` URI scheme.
> [!NOTE]
-> The shorthand `embed://` and `filesystem://` only work from XAML. In code, please use `MediaSource.FromResource()` and `MediaSource.FromFile()` respectively. Using these methods, you can omit the the `embed://` and `filesystem://` prefixes. The rest of the path should be the same.
+> The shorthand `embed://` and `filesystem://` only work when `Source` is set from a string in XAML. In code, please use `MediaSource.FromResource()` and `MediaSource.FromFile()` respectively. Using these methods, you can omit the `embed://` and `filesystem://` prefixes. The rest of the path should be the same. Stream-backed sources don't have an equivalent URI-style XAML shorthand. To use a stream source with XAML, bind `Source` to a `MediaSource` instance created in code.
### Play media embedded in the app package
@@ -239,13 +240,52 @@ An example of how to use this syntax in XAML can be seen below.
ShouldShowPlaybackControls="True" />
```
+### Play media from a Stream
+
+You can play media from a `Stream`, which enables scenarios where end-to-end capture and playback remains in memory.
+
+Consider for example capturing a video using [`MediaPicker`](/dotnet/maui/platform-integration/device-media/picker):
+
+```csharp
+var videoResult = await MediaPicker.Default.CaptureVideoAsync(new MediaPickerOptions
+{
+ Title = "Capture Video"
+});
+
+if (videoResult is null)
+{
+ return;
+}
+```
+
+`videoResult` is a `FileResult`, and its stream can be read by a `MediaElement`.
+
+
+```xaml
+
+```
+
+Copying it to a new stream lets you reset the position to 0 so the `MediaElement` can read it correctly. Keep that stream alive for the duration of playback, and dispose it when it's no longer needed.
+
+```csharp
+await using var stream = await videoResult.OpenReadAsync();
+var memoryStream = new MemoryStream();
+await stream.CopyToAsync(memoryStream);
+memoryStream.Position = 0;
+
+MyMediaElement.Source = MediaSource.FromStream(memoryStream);
+```
+
+This may be particularly useful for scenarios with security requirements that don't allow saving data outside the app's sandboxed environment.
+
## 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 four static methods:
- `FromFile`, returns a `FileMediaSource` instance from a `string` argument.
- `FromUri`, returns a `UriMediaSource` instance from a `Uri` argument.
- `FromResource`, returns a `ResourceMediaSource` instance from a `string` argument.
+- `FromStream`, returns a `StreamMediaSource` instance from a `Stream` argument.
In addition, the `MediaSource` class also has implicit operators that return `MediaSource` instances from `string` and `Uri` arguments.
@@ -257,6 +297,7 @@ 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`.
- `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`.
+- `StreamMediaSource`, which is used to specify a stream that is read incrementally from memory, a file, or a remote source.
> [!NOTE]
> When a `FileMediaSource` object is created in XAML, a type converter is invoked to return a `FileMediaSource` instance from a `string`.
@@ -374,7 +415,7 @@ Media playback controls implemented by each platform include a volume bar. This
A custom volume bar can be implemented using a [`Slider`](xref:Microsoft.Maui.Controls.Slider), as shown in the following example:
```xaml
-
+
-
+
```
In this example, the [`Slider`](xref:Microsoft.Maui.Controls.Slider) data binds its `Value` property to the `Volume` property of the `MediaElement`. This is possible because the `Volume` property uses a `TwoWay` binding. Therefore, changing the `Value` property will result in the `Volume` property changing.