Add support for local files and package resources to MediaElement

[ne0rrmatrix]

• Feature/Proposal
  [Proposal] Add support for local files and package resources to MediaElement #2151

Description of Change

Add support for file and resource file types to MediaElement.MetadataArtworkSource. This will allow developers to set artwork using MediaSource class.

Linked Issues

• Fixes Add support to Metadata for local files and resources in Media Element #1989

PR Checklist

• Has a linked Issue, and the Issue has been approved(bug) or Championed (feature/proposal)
• Has tests (if omitted, state reason in description)
• Has samples (if omitted, state reason in description)
• Rebased on top of main at time of PR
• Changes adhere to coding standard
• Documentation created or updated: https://github.com/MicrosoftDocs/CommunityToolkit/pulls

Additional information

Summary

Add support for local files and package resources as a source for MediaElement.MetadataArtworkUrl. This will add the missing support for all types of files on all device for artwork images.

Motivation

Allow developer more options to add images from more locations to use as artwork for player.

Detailed Design

API Design:

/// <summary>
	/// Backing store for the <see cref="MetadataArtworkUrl"/> property.
	/// </summary>
	public static readonly BindableProperty MetadataArtworkUrlProperty = BindableProperty.Create(nameof(MetadataArtworkSource), typeof(MediaSource), typeof(MediaElement));

/// Gets or sets the Artwork Image Url of the media.
	/// This is a bindable property.
	/// </summary>
	[TypeConverter(typeof(MediaSourceConverter))]
	public MetadataArtworkSource? MetadataArtworkSource
	{
		get => (MediaSource)GetValue(MetadataArtworkUrlProperty);
		set => SetValue(MetadataArtworkUrlProperty, value);
	}

Usage Syntax

XAML:

 <toolkit:MediaElement
     x:Name="MediaElement"
     ShouldAutoPlay="True"
     Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
     MetadataArtworkSource="ebedded://robot.jpg"
     MetadataTitle="Big Buck Bunny"
     MetadataArtist="Blender Foundation"/>

Code Behind:

MediaElement.MetadataArtworkSource = MediaSource.FromResource("robot.jpg");  

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 6 comments.

[Copilot]

There is code duplication between the SetPoster method (lines 539-560) and the GetTrack method (lines 505-516). Both implement version-specific logic for handling AVAsset.TracksWithMediaType obsolescence in iOS 18+/MacCatalyst 18+. However, the SetPoster implementation correctly uses the new Tracks API (line 548), while GetTrack simply returns null for newer OS versions. Either the GetTrack method should be fixed to match SetPoster's implementation, or SetPoster should call GetTrack instead of duplicating the logic.

[Copilot]

Using System.Diagnostics.Trace.WriteLine for debug logging violates the codebase's logging convention. According to the project's coding standards, Trace.WriteLine() should be used instead of Debug.WriteLine(), but more importantly, this file should use structured logging via the ILogger instance that exists in other platform managers. The Windows and Android implementations consistently use Logger.LogWarning() and Logger.LogInformation() for similar scenarios. This inconsistency makes debugging harder and prevents proper log filtering and categorization.

[Copilot]

The SetPoster method can throw exceptions when loading images (UIImage.LoadFromData or UIImage.FromFile might fail), and it's called from PlatformUpdateSource without a try-catch block at line 276. If image loading fails, the entire source update operation could fail. Consider wrapping the SetPoster call in a try-catch block to ensure that media playback isn't prevented by artwork loading failures.

Suggested change

	await SetPoster();
	try
	{
	await SetPoster();
	}
	catch (Exception ex)
	{
	Logger.LogError(ex, "Failed to set poster artwork.");
	}

[Copilot]

Using System.Diagnostics.Trace.WriteLine for debug logging violates the codebase's logging convention. According to the project's coding standards, Trace.WriteLine() should be used instead of Debug.WriteLine(), but more importantly, this file should use structured logging via the ILogger instance that exists in other platform managers. The Windows and Android implementations consistently use Logger.LogWarning() and Logger.LogInformation() for similar scenarios. This inconsistency makes debugging harder and prevents proper log filtering and categorization.