Avalonia Controls Media

Avalonia Media Controls

Overview

Media controls display images, vector graphics, and embedded web or video content. Image sources use avares:// URIs for app assets. Vector content (PathIcon, DrawingImage) scales without pixelation.

---

Image

Displays raster (PNG, JPEG, BMP, WebP) or vector images.

| Property | Type | Notes | |---|---|---| | Source | IImage | Bitmap, DrawingImage, bound IImage | | Stretch | Stretch | None, Fill, Uniform (default), UniformToFill | | Width / Height | double | Explicit size; required if parent gives infinite space | | RenderOptions.BitmapInterpolationMode | BitmapInterpolationMode | Default, LowQuality, MediumQuality, HighQuality, None |

Stretch modes:

| Value | Behavior | |---|---| | None | Original pixel size | | Fill | Stretches to fill, distorts aspect ratio | | Uniform | Letterboxed to fit, preserves aspect ratio | | UniformToFill | Fills area, may clip, preserves aspect ratio |

Loading from app assets (AXAML):

Loading in code:

using Avalonia.Platform;
using Avalonia.Media.Imaging;

// From app assets
var uri = new Uri("avares://MyApp/Assets/logo.png");
var bitmap = new Bitmap(AssetLoader.Open(uri));
myImage.Source = bitmap;

// From file system
var bitmap = new Bitmap("/home/user/photo.png");
myImage.Source = bitmap;

// From stream
using var stream = File.OpenRead(path);
var bitmap = new Bitmap(stream);

Binding to ViewModel:

// In ViewModel
private Bitmap? _photo;
public Bitmap? Photo
{
    get => _photo;
    set => SetProperty(ref _photo, value);
}

// Load async
public async Task LoadPhotoAsync(string path)
{
    await using var stream = File.OpenRead(path);
    Photo = await Task.Run(() => new Bitmap(stream));
}

Dispose Bitmaps when no longer needed to release native memory:

_photo?.Dispose();

---

DrawingImage

Vector image source built from geometry. Use for scalable icons embedded as image sources.

| Class | Use | |---|---| | DrawingGroup | Combines multiple drawings | | GeometryDrawing | Fills/strokes a geometry path | | ImageDrawing | Embeds a bitmap in a drawing |

> Prefer PathIcon for simple icons. Use DrawingImage when you need composite layered vector drawings or need to embed as Image.Source.

---

PathIcon

SVG-path-based scalable icon. Preferred for UI icons. Color controlled by Foreground.

| Property | Type | Notes | |---|---|---| | Data | Geometry | SVG path string | | Foreground | IBrush | Icon color (inherits from parent) | | Width / Height | double | Display size |

Dynamic path from ViewModel:

// In ViewModel
public string IconPathData => IsPlaying
    ? "M6 19h4V5H6v14zm8-14v14h4V5h-4z"   // pause icon
    : "M8 5v14l11-7z";                       // play icon

---

MediaPlayerControl (LibVLCSharp)

Avalonia does not include built-in video playback. Use LibVLCSharp.Avalonia.

NuGet packages:

LibVLCSharp
LibVLCSharp.Avalonia
VideoLAN.LibVLC.Windows  (or .Mac / .Linux)

Namespace: xmlns:vlc="using:LibVLCSharp.Avalonia"

using LibVLCSharp.Shared;

public class MediaViewModel : ObservableObject, IDisposable
{
    private readonly LibVLC _libVlc;
    public MediaPlayer MediaPlayer { get; }

    public MediaViewModel()
    {
        Core.Initialize(); // required before first use
        _libVlc = new LibVLC();
        MediaPlayer = new MediaPlayer(_libVlc);
    }

    public void Play(string url)
    {
        var media = new Media(_libVlc, url, FromType.FromLocation);
        MediaPlayer.Play(media);
    }

    public void Dispose()
    {
        MediaPlayer.Dispose();
        _libVlc.Dispose();
    }
}

---

WebView / NativeWebView

Embeds a native browser engine. Requires Avalonia.WebView NuGet package.

Supported engines:

• Windows: WebView2 (requires WebView2 Runtime)
• macOS: WKWebView
• Linux: WebKitGtk

NuGet:

Avalonia.WebView
Avalonia.WebView.Desktop   (for desktop platforms)

Registration in Program.cs:

AppBuilder.Configure()
    .UsePlatformDetect()
    .UseAvaloniaNative()
    .UseSkia()
    .UseWebView()           // add this
    .StartWithClassicDesktopLifetime(args);

AXAML usage:

xmlns:wv="using:Avalonia.WebView"

Code-behind:

// Navigate programmatically
Browser.Url = new Uri("https://example.com");

// Load local HTML
Browser.Url = new Uri("data:text/html,Hello from Avalonia");

// Load local file
Browser.Url = new Uri("file:///home/user/page.html");

// Handle navigation events
private void OnNavigationCompleted(object? sender, WebViewNavigationCompletedEventArgs e)
{
    if (!e.IsSuccess)
        Console.WriteLine($"Navigation failed: {e.WebErrorStatus}");
}

Execute JavaScript:

var result = await Browser.ExecuteScriptAsync("document.title");

---

Community Media Libraries

| Library | NuGet / Source | Purpose | |---|---|---| | LibVLCSharp.Avalonia | LibVLCSharp.Avalonia | Full VLC media engine — video, audio, streams | | AvaloniaGif | AvaloniaGif | Animated GIF playback control | | FFME.Avalonia | GitHub: WangsYi/ffme.avalonia | FFmpeg-based MediaElement | | Mpv.Avalonia | GitHub: saverinonrails/Mpv.Avalonia | MPV + OpenGL media control | | MediaPlayerUI.NET | MediaPlayerUI.NET | Reusable media player UI shell | | Avalonia Accelerate | avaloniaui.net/accelerate | Premium WebView + MediaPlayer from the Avalonia team | | CefGlue | Xilium.CefGlue.Avalonia | Chromium Embedded Framework WebView | | OutSystems WebView | GitHub: OutSystems/WebView | Full-featured Avalonia WebView | | MuPDFCore | MuPDFCore | PDF/XPS/ePub rendering via MuPDF | | Markdown.Avalonia | Markdown.Avalonia | Markdown renderer control | | LiveMarkdown.Avalonia | GitHub: DearVa/LiveMarkdown.Avalonia | High-performance real-time markdown |

LibVLCSharp Full Example

// NuGet: LibVLCSharp.Avalonia + VideoLAN.LibVLC.Windows (or .Linux, .Mac)
using LibVLCSharp.Shared;
using LibVLCSharp.Avalonia;

var libVlc = new LibVLC();
var mediaPlayer = new MediaPlayer(libVlc);

// In XAML:
// 

mediaPlayer.Play(new Media(libVlc, new Uri("https://example.com/stream.mp4")));

Common Mistakes

| Mistake | Fix | |---|---| | avares:// URI not finding asset | Check exact casing — case-sensitive on Linux. Verify Build Action = AvaloniaResource in project | | Image renders blank with no explicit size | Parent may give infinite space (e.g., StackPanel). Set Width/Height or MaxWidth/MaxHeight | | Image leaking memory | Bitmap is IDisposable — call .Dispose() when image is replaced or view is closed | | PathIcon color not changing | Use Foreground property, not Fill. Fill has no effect on PathIcon | | PathIcon appears clipped | The Data geometry may have values outside [0,0,width,height]. Set Width/Height to match geometry bounds | | WebView blank on Windows | WebView2 Runtime not installed. Distribute or check for runtime in installer | | WebView crashes on non-desktop | Only works on IClassicDesktopStyleApplicationLifetime; guard before instantiation | | LibVLCSharp video not showing | Must call Core.Initialize() before any LibVLC operation; missing platform NuGet package | | DrawingImage GeometryDrawing invisible | Check that Brush is set — unfilled geometry with no stroke is invisible |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: linuxdevel
• Source: linuxdevel/Avalonia-skills
• License: MIT

Install and usage instructions live in the source repository linked above.