OpenMaui.Controls.Linux.MediaElement 10.0.101.1

OpenMaui Linux Platform

A comprehensive Linux platform implementation for .NET MAUI using SkiaSharp rendering.

Developed by MarketAlly Pte Ltd Lead Architect: David H. Friedel Jr.

Overview

This project brings .NET MAUI to Linux desktops with native X11/Wayland support, hardware-accelerated Skia rendering, and full platform service integration.

Key Features

• Full Control Library: 50+ controls including Button, Label, Entry, Shapes, CarouselView, RefreshView, SwipeView, and more
• Native Integration: First-class X11 and native Wayland support (xdg-shell, wp_viewporter, fractional-scale-v1, zxdg_decoration_manager_v1, zwp_primary_selection_v1) — programmatically selectable or auto-detected
• Accessibility: AT-SPI2 screen reader support and high contrast mode
• Platform Services: Native wl_data_device_manager clipboard and drag-and-drop (no wl-clipboard subprocess required), zwp_primary_selection_v1 middle-click paste, file picker, notifications, global hotkeys, CUPS printing, system tray icons via StatusNotifierItem
• Input Methods: IBus / XIM on X11 + native zwp_text_input_v3 on Wayland with full delete_surrounding_text round-trip for compositor-integrated IMEs (GNOME Pinyin/Hangul/Anthy, native Fcitx5)
• High DPI: Automatic scale factor detection for GNOME, KDE, and X11; fractional scale handled via Wayland viewporter for pixel-exact rendering at non-integer scales (1.25x, 1.5x, 1.75x)
• Theming: AppThemeBinding live propagation across the entire view tree — CollectionView items, pushed pages, Shell content, and flyout regions all flip on theme toggle
• Window decorations: Server-side decorations (KDE/Sway) or client-side titlebar drawn in Skia with full drag/resize/close/maximize/minimize (GNOME/Mutter)
• MediaElement: Opt-in OpenMaui.Controls.Linux.MediaElement package backs CommunityToolkit.Maui.MediaElement with GStreamer (playbin + appsink → Skia). MediaHardwareAcceleration.Prefer boosts VA-API / NVDEC / V4L2 / MediaSDK decoder ranks when those plugins are installed
• Maps: Opt-in OpenMaui.Controls.Linux.Maps package backs Microsoft.Maui.Controls.Maps with OpenStreetMap raster tiles in Skia — pan/zoom, pin & polyline overlays, persistent XDG tile cache. Plus a standalone SkiaMap view for code-first map UI

Quick Start

Installation

# Install the templates
dotnet new install OpenMaui.Linux.Templates

# Create a new project (choose one):
dotnet new openmaui-linux -n MyApp           # Code-based UI
dotnet new openmaui-linux-xaml -n MyApp      # XAML-based UI (recommended)

cd MyApp
dotnet run

Manual Installation

dotnet add package OpenMaui.Controls.Linux

Optional: MediaElement (video / audio playback)

CommunityToolkit.Maui.MediaElement on Linux requires the opt-in sibling package that adds the GStreamer-backed handler:

dotnet add package CommunityToolkit.Maui.MediaElement
dotnet add package OpenMaui.Controls.Linux.MediaElement

Then in your MauiProgram.cs:

builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement(isAndroidForegroundServiceEnabled: false)
    .UseLinux()
    .UseLinuxMediaElement();   // Linux backend; no-op on Windows/Android/iOS/macCatalyst

System dependencies (GStreamer + plugin sets):

# Fedora
sudo dnf install gstreamer1-plugins-good gstreamer1-plugins-bad-free \
                 gstreamer1-plugins-ugly-free gstreamer1-libav gstreamer1-vaapi

# Ubuntu/Debian
sudo apt install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
                 gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-vaapi

gstreamer1-vaapi enables hardware-accelerated decode on Intel/AMD GPUs; substitute the nvdec plugin for NVIDIA. Software decode works without either.

To explicitly bias playbin toward the hardware decoders when they are installed:

using Microsoft.Maui.Platform.Linux.MediaElement.Services;

builder.UseLinuxMediaElement(MediaHardwareAcceleration.Prefer);

Auto keeps the default behavior, Prefer bumps HW decoder factory ranks above SW, and Disable demotes them.

Optional: Maps (OpenStreetMap)

Microsoft.Maui.Controls.Maps on Linux uses the opt-in sibling package that adds an OSM raster-tile renderer:

dotnet add package Microsoft.Maui.Controls.Maps
dotnet add package OpenMaui.Controls.Linux.Maps

Then in your MauiProgram.cs:

builder
    .UseMauiApp<App>()
    .UseMauiMaps()
    .UseLinux()
    .UseLinuxMaps();   // Linux backend; no-op on Windows/Android/iOS/macCatalyst

Tiles are fetched on first view and cached under $XDG_CACHE_HOME/openmaui/osm-tiles.

Map.MapType selects the layer style:

• Street — OpenStreetMap standard raster (© OpenStreetMap contributors).
• Satellite — Esri "World Imagery" (keyless aerial basemap).
• Hybrid — the satellite base with an Esri transparent labels/boundaries overlay.

The active layer's attribution is drawn in the on-map overlay. The Esri layers are keyless but governed by Esri's terms of use, not the OSM tile policy — confirm those terms for production use, or redirect the sources at your own imagery.

Each layer is a TileSource with a settable URL template (the {z}/{x}/{y} placeholder position sets the axis order — OSM uses {z}/{x}/{y}, ArcGIS uses {z}/{y}/{x}). To use a self-hosted or commercial tile server, redirect a layer at startup:

using Microsoft.Maui.Platform.Linux.Maps.Services;

MapTileLayers.Street.UrlTemplate = "https://my-tiles.example.com/{z}/{x}/{y}.png";
// (OsmTileService.Default.UrlTemplate still works as a shortcut for the Street layer.)

For code-first map UI without Microsoft.Maui.Controls.Maps, the package also exposes a standalone SkiaMap view that subclasses SkiaView:

using Microsoft.Maui.Platform.Linux.Maps.Views;

var map = new SkiaMap { CenterLatitude = 35.68, CenterLongitude = 139.65, ZoomLevel = 11 };
map.Pins.Add(new MapPin { Latitude = 35.68, Longitude = 139.65, Label = "Tokyo" });

OSM's tile usage policy requires displaying attribution; SkiaMap renders the credit overlay automatically (toggle with ShowAttribution).

XAML Support

OpenMaui fully supports standard .NET MAUI XAML syntax. Use the familiar XAML workflow:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MyApp.MainPage">
    <VerticalStackLayout>
        <Label Text="Hello, OpenMaui!" FontSize="32" />
        <Button Text="Click me" Clicked="OnButtonClicked" />
        <Entry Placeholder="Enter text..." />
        <Slider Minimum="0" Maximum="100" />
    </VerticalStackLayout>
</ContentPage>

// MauiProgram.cs
var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseLinux();  // Enable Linux with XAML support (auto-detects X11/Wayland)

Backend Selection (X11 / Wayland)

Pick exactly one — calls are no-ops on Windows/Android/iOS so they're safe in cross-platform MauiProgram.cs:

builder
    .UseMauiApp<App>()
    .UseLinux();      // auto-detect from session (default)
    // .UseX11();     // force X11/XWayland — most stable, recommended for WebView-heavy apps
    // .UseWayland(); // prefer native Wayland; auto-falls back to X11 if Wayland unavailable

Native Wayland uses xdg-shell + wp_viewporter for fractional-scale rendering and ssd via zxdg_decoration_manager_v1. The X11 path remains the default fallback and is fully supported. Environment overrides (MAUI_PREFER_X11=1, GDK_BACKEND=x11) still work and take effect before the builder runs.

Supported Controls

Platform Services

Accessibility

• AT-SPI2: Screen reader support for ORCA and other assistive technologies
• High Contrast: Automatic detection and color palette support
• Keyboard Navigation: Full keyboard accessibility

Requirements

• .NET 10.0 SDK or later
• Linux (kernel 5.4+)
• X11 or Wayland
• SkiaSharp native libraries

System Dependencies

Ubuntu/Debian:

sudo apt-get install libx11-dev libxrandr-dev libxcursor-dev libxi-dev libgl1-mesa-dev libfontconfig1-dev

Fedora:

sudo dnf install libX11-devel libXrandr-devel libXcursor-devel libXi-devel mesa-libGL-devel fontconfig-devel

Documentation

• Getting Started Guide
• FAQ - Visual Studio Integration
• API Reference
• Contributing Guide

Sample Applications

Full sample applications are available in the maui-linux-samples repository:

Distribution

Package your OpenMaui app as a portable AppImage with a single command:

dotnet tool install --global OpenMaui.AppImage
dotnet appimage

Auto-detects your executable and icon, generates a .desktop file, and produces a self-contained AppImage that runs on most Linux distributions. See the OpenMaui.AppImage repository for details.

Quick Example

// MauiProgram.cs
using Microsoft.Maui.Hosting;
using Microsoft.Maui.Platform.Linux.Hosting;

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseLinux();   // or .UseX11() / .UseWayland() to force a backend

var app = builder.Build();
LinuxApplication.Run(app, args);

Building from Source

# Primary repository
git clone https://github.com/open-maui/maui-linux.git

# Or from GitHub mirror
git clone https://github.com/open-maui/maui-linux.git

cd maui-linux
dotnet build
dotnet test

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Note: Please submit issues and pull requests on GitHub.

Architecture

┌─────────────────────────────────────────────────┐
│                  .NET MAUI                       │
│              (Virtual Views)                     │
├─────────────────────────────────────────────────┤
│                  Handlers                        │
│         (Platform Abstraction)                   │
├─────────────────────────────────────────────────┤
│              Skia Views                          │
│        (SkiaButton, SkiaLabel, etc.)            │
├─────────────────────────────────────────────────┤
│           SkiaSharp Rendering                    │
│         (Hardware Accelerated)                   │
├─────────────────────────────────────────────────┤
│              X11 / Wayland                       │
│          (Display Server)                        │
└─────────────────────────────────────────────────┘

Styling and Data Binding

OpenMaui supports the full MAUI styling and data binding infrastructure:

XAML Styles

<ContentPage.Resources>
    <ResourceDictionary>
        <Color x:Key="PrimaryColor">#5C6BC0</Color>
        <Style TargetType="Button">
            <Setter Property="BackgroundColor" Value="{StaticResource PrimaryColor}" />
            <Setter Property="TextColor" Value="White" />
        </Style>
    </ResourceDictionary>
</ContentPage.Resources>

Data Binding

<Label Text="{Binding Title}" />
<Entry Text="{Binding Username, Mode=TwoWay}" />
<Button Command="{Binding SaveCommand}" IsEnabled="{Binding CanSave}" />

Visual State Manager

All interactive controls support VSM states: Normal, PointerOver, Pressed, Focused, Disabled.

<Button Text="Hover Me">
    <VisualStateManager.VisualStateGroups>
        <VisualStateGroup x:Name="CommonStates">
            <VisualState x:Name="Normal">
                <VisualState.Setters>
                    <Setter Property="BackgroundColor" Value="#2196F3"/>
                </VisualState.Setters>
            </VisualState>
            <VisualState x:Name="PointerOver">
                <VisualState.Setters>
                    <Setter Property="BackgroundColor" Value="#42A5F5"/>
                </VisualState.Setters>
            </VisualState>
        </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
</Button>

Roadmap

• Core control library (50+ controls)

• Platform services integration

• Accessibility (AT-SPI2)

• Input method support (IBus/XIM)

• High DPI support

• Drag and drop

• Global hotkeys

• BindableProperty for all controls

• Visual State Manager integration

• XAML styles and StaticResource

• Data binding (OneWay, TwoWay, IValueConverter)

• App icon support (MauiIcon build targets, .desktop integration)

• Dark mode for all picker popups

• DPI-aware popup rendering with edge detection

• MAUI Shapes (Ellipse, Line, Rectangle, Polygon, Polyline, Path)

• Native Wayland backend (xdg-shell, wp_viewporter, fractional-scale-v1, decoration-manager)

• Programmatic backend selection (UseX11() / UseWayland())

• AppThemeBinding live propagation through Shell, NavigationPage, and CollectionView item trees

• GTK4 interop layer (Gtk4InteropService with GTK3 fallback)

• Client-side decorations for GNOME-Wayland sessions (10.0.60.10)

• Native wl_data_device_manager clipboard — zero subprocess overhead, works without wl-clipboard (10.0.60.11)

• zwp_text_input_v3 IME for native Wayland (Fcitx5 / GNOME Pinyin) (10.0.60.12)

• MediaElement / video support via GStreamer — opt-in OpenMaui.Controls.Linux.MediaElement sibling package (10.0.60.13)

• MAUI 10.0.70 alignment — default-template CS1508 fix, Wayland-shim deployment fix, Essentials registration fix for MAUI 10's split SetDefault/SetCurrent naming (10.0.70.1)

• IInputContext.DeleteSurrounding — zwp_text_input_v3.delete_surrounding_text round-trips into SkiaEntry / SkiaEditor with full UTF-8 byte → UTF-16 char conversion (10.0.70.2)

• Primary-selection clipboard — zwp_primary_selection_v1 binding + PrimarySelectionService, SkiaEntry / SkiaEditor push on drag-end and paste on middle-click (10.0.70.2)

• Native wl_data_device_manager drag-and-drop — first functional Linux DnD path, file-drop URI decoding, source-side start_drag (10.0.70.2)

• Hardware video acceleration tuning — MediaHardwareAcceleration.Prefer boosts VA-API / NVDEC / V4L2 / MediaSDK decoder ranks (10.0.70.2)

• System tray icons — TrayIcon over libappindicator3 / libayatana-appindicator3 (StatusNotifierItem on the session bus) (10.0.70.2)

• CUPS printing — PrintService enumerates printers, submits files, renders Skia pages to PDF via SKDocument and prints (10.0.70.2)

• Maps integration (OpenStreetMap) — opt-in OpenMaui.Controls.Linux.Maps sibling package backs Microsoft.Maui.Controls.Maps with OSM raster tiles, pin / polyline overlays, persistent XDG tile cache (10.0.70.2)

• Stability / correctness hardening from deep code review — Wayland listener-delegate rooting (crash-class), DnD protocol fixes with default-accept drops, self-paste deadlock fixes, first working X11 XDND drop path (INCR-capable), Maps tile-cache race + MoveToRegion zoom + VisibleRegion write-back + OSM tile-policy compliance + HiDPI tiles, tray binding/lifetime fixes, off-UI-thread printing, reversible HW-decode ranking (10.0.70.4)

• Full X11 XDND drag-and-drop — outgoing drags via backend-agnostic DragDropService.TryStartDrag (Wayland-first, XDND source fallback) (10.0.70.4)

• MAUI DragGestureRecognizer / DropGestureRecognizer wired to the native drag paths — DragStarting starts real drags; drops route to recognizer views with AllowDrop/AcceptedOperation feedback (10.0.70.4)

• set_surrounding_text for text-input-v3 — focused entry text + caret + anchor pushed to the IME (also feeds IBus); completes the Wayland IME loop (10.0.70.4)

• Map polygon / circle overlays — IFilledMapElement / ICircleMapElement routed end-to-end with Mercator-correct circle radii (10.0.70.4)

• GTK print dialog — PrintService.ShowPrintDialogAsync (GtkPrintUnixDialog: printer, copies, ranges, duplex, PPD options → CUPS-ready) (10.0.70.4)

• Tray icon XEmbed fallback — freedesktop System Tray Protocol backend for desktops without an SNI host; left-click Activated works here (10.0.70.4)

• MAUI 10.0.90 alignment — bumped Controls/Graphics/Graphics.Skia/Controls.Maps 10.0.70 → 10.0.90 (10.0.90.1)

• Drag payload types — DragPayload (text/files/image) drives TryStartDrag; per-payload MIMEs, outgoing X11 INCR, DataPackage file/image extraction (10.0.90.1)

• Maps satellite / hybrid layers — SkiaMap.LayerType + MAUI Map.MapType; TileSource abstraction with keyless OSM/Esri defaults, layer-stacking hybrid, layer-keyed cache (10.0.90.1)

• Tmds.DBus migration — Fcitx5 transport off the dbus-monitor subprocess to typed Tmds.DBus proxies (10.0.90.1)

• Live Visual Tree — Diagnostics/VisualTreeInspector: tree snapshot, highlight overlay, click-to-pick, text dump; opt-in Ctrl+Shift+D (10.0.90.1)

• Hot Reload — dotnet watch C#/XAML edits re-render the current page (Shell-rooted apps); see docs/HOT_RELOAD.md (10.0.90.1)

• MAUI 10.0.101 alignment + SkiaSharp 3 → 4 migration — ~400 call sites to the SKFont API; SkiaFontFactory (Subpixel + LinearMetrics) fixes HiDPI glyph gaps; label measurement is wrap-aware and glyph-independent (10.0.101.1)

• Multi-window support — Application.OpenWindow/CloseWindow, per-window render/input/focus, X11 + Wayland parity, MAUI IWindow lifecycle, last-window-close exits (10.0.101.1)

• Non-Shell-root XAML Hot Reload — raw ContentPage/NavigationPage roots rebuild and re-swap under dotnet watch (10.0.101.1)

• Async drag image sourcing — StreamImageSource payloads resolve in-flight with format sniffing and bounded honest-fail (10.0.101.1)

Up next

• Multi-window round-out — per-window WindowHandler (live title/page updates), DnD onto secondary windows, window positioning
• Hardware video decode zero-copy — explicit pipeline construction for direct compositor-surface playback (Prefer mode already covers decoder selection)

License

Copyright (c) 2025-2026 MarketAlly Pte Ltd. Licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• MarketAlly Pte Ltd - Project development and maintenance
• SkiaSharp - 2D graphics library
• .NET MAUI - Cross-platform UI framework
• The .NET community
• A very special thank you to the Anthropic team for delivering on the promise I hold most dear — that an individual with enough energy and persistence can still make a difference