Files

T

edde746 bcd6fe9906 feat(linux): HDR video on a native Wayland plane

Video on Linux went through a Flutter texture: 8-bit sRGB, which cannot carry
HDR at all, and which forced a whole-window Flutter recomposite for every video
frame. This moves it onto a wl_subsurface stacked below the Flutter surface, with
mpv rendering into an EGL window surface on it through the libmpv render API. The
subsurface is desynchronized, so video and UI now present independently.

With the plane in place HDR follows: the surface is described to the compositor
through wp_color_manager_v1 as the source's own curve and gamut - PQ or HLG,
BT.2020 - carrying whatever HDR10 static metadata the stream actually declares.
The description and the buffer it describes land on the same commit, staged and
validated before mpv is switched, so a PQ frame is never presented labelled sRGB.
A five-second watchdog bounds the one wait a compositor could otherwise leave
hanging. A session that cannot host the plane - X11, or a compositor without
wl_subcompositor - fails initialize with VIDEO_PLANE_UNSUPPORTED naming the
reason: the texture path is gone, and refusing by name beats degrading to
something the user cannot see. An SDR output, a missing capability or an 8-bit
config keep the plane and simply leave it undescribed.

The output's colour state is trusted only when it has been earned. Every landed
property step records itself as it lands; a reset or sequence that cannot
finish downgrades its result to unknown and marks the applied-output cache
untrusted until a clean apply earns it back. A plane whose output state cannot
be named is quarantined - hidden, its description withdrawn - and the
quarantine is recorded state: an unrelated visibility change cannot put a
mislabelled plane back on screen, and only a commit that resolves to a nameable
outcome lifts it. A rect collapsing to zero detaches the buffer exactly as
hiding does, a refused setVideoRect drops the Dart-side sent-rect cache so the
next layout pass retries for free, and a refused tone-mapping pick tells the
user instead of dying in a log.

NVIDIA's Wayland EGL (through at least 610.xx) offers no 10-bit unorm window
configs, so the plane takes half-float as the tier between 10-bit unorm and
8-bit, declares the whole surface opaque so the compositor never reads the
alpha those configs carry, and states GL_RGBA16F rather than a 10-bit lie.
Whether the output is in HDR is read from luminance headroom above its own
reference white rather than from the preferred transfer function, which current
KWin no longer answers PQ for; the margin is half a stop, because KWin reports
an undimmed maximum over a software-dimmed SDR white. Validated on an RTX 4090
(driver 610.57.04) under KWin 6.7.4 with locked-exposure photographs.

Who tone-maps is a user choice. The default is the compositor: photographed on a
400-nit HDR output against a PQ chart it keeps 400 -> 1000 nits monotonic and
separated where the player leg flattens them, because the player path drives
mpv's legacy vo_gpu, whose own standalone output scores the same. The gap is the
renderer, not the wiring.

The decision itself - what the source carries, what the output supports, what to
tell mpv and what to tell the compositor - lives in hdr_metadata.h, free of
Wayland and GTK so its luminance validation can be tested without a display
server. Sending an incoherent luminance set is a protocol error that disconnects
the client, so the rules are worth a unit test.

The deb, rpm and pacman packages now declare wayland-client, wayland-egl and EGL:
the plane links them directly and bundle-libs.sh deliberately never bundles them,
since they are coupled to the running compositor and GPU driver.

lib/dev/harness_main.dart is a second entrypoint for measuring this on hardware -
it drives one clip with scripted mpv properties and reports the colour state mpv
actually settled on. Nothing imports it, so it is tree-shaken out of the app.

Verified on a Steam Deck against an external 400-nit HDR display: the compositor
reports PQ / BT.2020, the connector carries HDR_OUTPUT_METADATA, and against mpv
vo=gpu-next on the same frame the shipped build sits 4.90 counts away overall -
closer to the reference HDR player than to its own SDR fallback.

2026-08-10 08:48:13 +02:00

9.8 KiB

Raw Blame History

Plezy

A modern client for Plex, Jellyfin, and Emby on desktop, mobile, and TV. Built with Flutter for native performance and a clean interface.

Website · Screenshots · Download · Contributing · License

Download

Platform	Download
macOS	DMG (x64, arm64)
Linux x64	.deb · .rpm · .pkg.tar.zst · portable tar.gz
Linux arm64	.deb · .rpm · .pkg.tar.zst · portable tar.gz

Package managers:

Nix - Community package by @mio-19 and @MiniHarinn

Homebrew (macOS):

brew tap edde746/plezy https://github.com/edde746/plezy
brew install --cask plezy

AUR (Arch Linux) - Community maintained by @jianglai:
```
yay -S plezy-bin
```
WinGet (Windows):
```
winget install edde746.Plezy
```

Features

Browse & Discover

Libraries, collections, and playlists — video and audio
Discover hub — Continue Watching, Next Up, trending, and recommendations
Cross-server search across every connected Plex, Jellyfin, and Emby server
Filtering, sorting, and alphabetical jump navigation
Folder browsing and folder playback — home-video libraries open in folder view
Resolution, HDR/Dolby Vision, and audio-format badges on cards and detail pages
Favorites and unwatched library filters¹
Extras — trailers, deleted scenes, behind-the-scenes

Explore & Requests

Explore tab — watchlist, trending, popular, and recommendation rows from Plex Discover², Trakt, MyAnimeList, AniList, Simkl, and Seerr³
Search any connected catalog source
Catalog titles matched back to your own libraries by external ID
Seerr — request movies and shows with per-season, 4K, and advanced destination options, and see request status inline
Watchlist sync — add and remove titles on Plex, Trakt, MyAnimeList, AniList, and Simkl from anywhere in the app

Playback

Wide codec support (HEVC, AV1, VP9, and more)
HDR and Dolby Vision⁴
Direct play, or transcode presets from 240p/320 kbps to 1080p/20 Mbps
Multi-version switching with per-version file details
Full ASS/SSA subtitles with customizable styling
Online subtitle search & download²
Audio & subtitle choices remembered per title, or follow the server's per-episode selections
Progress sync and resume
Auto-play next episode with skip intro / skip credits
Chapter navigation with thumbnail scrub previews
Playback speed from 0.25x to 8x, audio sync offset, sleep timer (fixed durations or end of video)
Video zoom 50-200% with pinch, presets, and hotkeys
Audio passthrough⁵, stereo downmix with center-channel boost, and loudness normalization
File Info sheet — every version, file, and stream the server reports
Ambient lighting and GLSL shader presets⁶
Picture-in-Picture⁷
Refresh-rate matching⁸
External player launch (VLC, MX Player, etc.) with progress sync back⁹

Music

Music libraries — artist, album, and track browsing with square artwork
Album and artist screens with play, shuffle, and Instant Mix
Gapless playback with a full play queue — reorder, remove, play next, add to queue
Now Playing with synced lyrics¹⁰, persistent mini-player, and sleep timer
Background playback with lock-screen, media-key, and notification controls¹¹
Offline playback of downloaded albums and tracks
Streaming quality presets — Original, 320, 192, or 128 kbps

Live TV & DVR

Live TV channel browsing, tuning, and favorites
EPG guide with What's On and per-show schedules
DVR recording rules, scheduled recordings, and a rememberable recording target library²
Multi-server Live TV support where available

Downloads & Offline

Download movies, shows, and music for offline playback¹²
Background queue with pause / resume
Sync rules for automatic downloads, with per-show "Include Specials"
Offline browsing with watch state sync-back on reconnect

Watch Together

Synchronized playback with friends
Real-time play / pause / seek sync

Integrations

Discord Rich Presence¹³
Trakt, MyAnimeList, AniList, and Simkl — ratings, watched sync, and real-time scrobbling¹⁴
Plezy Remote — control desktop and TV from mobile
Watch Next row and tvOS Top Shelf¹⁵

Platform & Customization

Desktop, mobile, and TV — full D-pad, keyboard, and gamepad support
Multiple servers at once — Plex, Jellyfin, and Emby side by side
Profiles with per-profile downloads, watch state, and settings; Plex Home switching with PIN
Jellyfin and Emby local-server discovery and multiple URLs per server; Quick Connect sign-in¹⁶
TV layout options — corner spotlight backdrop, full-card artwork, and Force TV mode on desktop
Customizable keyboard shortcuts¹³
Metadata and artwork editing
Settings import/export
Localized in English plus 21 translations

Building from Source

Prerequisites

Flutter SDK 3.44.0+
A Plex account, or a Jellyfin or Emby server with user credentials

Setup

git clone https://github.com/edde746/plezy.git
cd plezy
flutter pub get
scripts/codegen.sh
flutter run

Code Generation

After modifying model classes or other generated sources:

scripts/codegen.sh

After modifying translations:

dart run slang

Local Checks

scripts/ci_checks.sh

To install the same pre-commit checks locally:

scripts/setup_hooks.sh

End-to-end tests (Android emulator plus a Dockerized Jellyfin fixture):

python3 scripts/run_maestro.py basic

Contributing

See CONTRIBUTING.md for development workflow, formatting, tests, and translation guidelines.

License

Plezy is licensed under GPL-3.0.

Acknowledgments

Built with Flutter
Supports Plex Media Server, Jellyfin, and Emby
Playback powered by mpv, MPVKit, Android ExoPlayer, libass-android, and libmpv-android

Jellyfin and Emby only. ↩︎
Plex only. ↩︎
Requires connecting the service under Settings > Services. ↩︎
In-app HDR toggle on Windows, macOS, iOS, tvOS, and Linux — Linux needs a colour-managed Wayland compositor. Dolby Vision on Android and Apple TV. ↩︎
Desktop, Android TV, and Apple TV. ↩︎
Requires the mpv player backend — unavailable on iOS and tvOS, and Android defaults to ExoPlayer. ↩︎
Android, iOS, and macOS — not on Android TV or Apple TV. ↩︎
Windows, Android, and tvOS. ↩︎
Progress sync on Android. ↩︎
Where your server provides lyrics. ↩︎
tvOS pauses music when the app is backgrounded. ↩︎
Not available on tvOS. ↩︎
Desktop only. ↩︎
Real-time scrobbling on Trakt and Simkl; MyAnimeList and AniList update on completion. ↩︎
Android TV / Fire TV and tvOS. ↩︎
Jellyfin only. ↩︎

9.8 KiB Raw Blame History