Engine MpvPlayer

Engine: MpvPlayer

Sucrose.Live.MpvPlayer is Sucrose's native media engine. It hosts libmpv through the Sucrose.Mpv.NET library (a Mpv.NET fork) and is the default engine for both Gif and Video wallpapers. Because it ships its own libmpv binary per platform, it plays a very wide range of formats without any system codecs, making it the most format-robust playback option. This page covers the technology, supported types, runtime requirement, bundled binary, mpv configuration (including the user override), hardware acceleration, playback control, the customization panel, and the Mpv.NET surface.

Table of contents

• At a glance
• Technology
• Supported wallpaper types
• Runtime requirement and bundled binary
• mpv configuration
• Hardware acceleration and Stay Awake
• Playback control and surface fix
• Customization panel
• Mpv.NET public surface
• Strengths and limitations
• See also

At a glance

Property	Value
Assembly	Sucrose.Live.MpvPlayer.exe
Tech	libmpv (native) via Sucrose.Mpv.NET
Supported types	Gif, Video
Default for	Gif, Video
Preprocessor symbols	ENGINE, LIVE_MPVPLAYER
Runtime requirement	Windows 10 1607 (Redstone 1) or newer
Native dependency	Bundled libmpv-{arch}.dll (no external install)
Interactivity	No (pure media playback)
Audio/system-data injection	No
Properties panel	PropertiesType.MpvPlayer

Technology

MpvPlayer embeds libmpv in a Win32 child window. Sucrose.Mpv.NET drives libmpv through the player host's window handle (PlayerHost.Handle), so frames are rendered natively rather than through WPF or a browser. This gives near-native performance and the broadest codec coverage of any Sucrose engine.

Supported wallpaper types

MpvPlayer renders Gif (SSDEWT.Gif) and Video (SSDEWT.Video) only. Its Configure() switch has exactly those two cases; Url, Web, YouTube, and Application fall through to the default → Close() branch and nothing displays. Notably, MpvPlayer does not serve the YouTube type even though libmpv with youtube-dl could — YouTube is routed only to the browser engines (WebView/CefSharp) by design.

See Type Gif and Type Video.

Runtime requirement and bundled binary

OS check. The pre-launch Check calls IsRedstone1(), which requires Windows 10 Anniversary Update (version 1607 / Redstone 1) or newer. On older Windows the engine shows a warning box and closes.

Bundled native binary. MpvPlayer ships its own libmpv, so there is no external install:

Platform	File	Approx. size
x86	libmpv-x86.dll	~95 MB
x64	libmpv-x64.dll	~117 MB
ARM64	libmpv-ARM64.dll	~79 MB

These live in src/Live/Sucrose.Live.MpvPlayer/Requirements/ and are copied to the output Always, per platform. They are the bulk of the MpvPlayer engine's on-disk size.

mpv configuration

The mpv config is built by Sucrose.Shared.Engine.MpvPlayer/Helper/Config.cs and written into %AppData%\<App>\Cache\MpvPlayer\. Two files exist:

File	Role
MpvPlayerConfig	The default, Sucrose-generated mpv.conf-style config
uMpvPlayerConfig	A user override; if present it takes priority over the default

To customize libmpv directly, drop a uMpvPlayerConfig file into that cache folder. The default config lines come from Sucrose.Shared.Engine/Manage/Internal.cs (MpvConfig):

Category	Lines
Audio	volume-min=0, volume-max=100, audio-buffer=0.1, audio-channels=stereo, audio-pass-through=yes, audio-samplerate=48000
Video	vo=gpu, hwdec=no (overwritten by Hardware Acceleration), v-sync=no, deband=yes, fullscreen=yes, hwdec-codecs=all, interpolation=no, framedrop=decoder, profile=low-latency, stop-screensaver=no (overwritten by Stay Awake), gpu-shader-cache=yes
Windows	unregister=yes, media-controls=no
Performance	cache=yes, keep-open=no, gpu-context=d3d11, demuxer-max-bytes=64M, video-sync=display-desync, demuxer-seekable-cache=yes

Hardware acceleration and Stay Awake

Two Wallpaper-page toggles rewrite specific mpv config lines:

Setting	ON	OFF
HardwareAcceleration	hwdec=auto-safe	hwdec=no
StayAwake	stop-screensaver=always	stop-screensaver=no

In addition, the cross-engine "Stay Awake" loop (Helper/Awakening.cs) runs a 30-second timer that calls SetThreadExecutionState; when ON it sets ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_DISPLAY_REQUIRED to prevent sleep and the screensaver. MpvPlayer additionally rewrites its own stop-screensaver config line. See Choosing Engines and Settings Wallpaper.

Playback control and surface fix

Helper/Video.cs provides the playback control surface:

• Pause / Play (=Resume) / Stop.
• SetLoop — reloads the source at end when looping.
• SetVolume — direct 0–100 value (libmpv's own scale).
• SetSpeed — playback rate.
• SetStretch — maps WPF Stretch to the mpv properties panscan / keepaspect / video-unscaled (for example, UniformToFill → panscan 1.0).

The surface fix (Helper/Surface.cs) calls MoveWindow on the mpv child window whenever the size changes, so the native surface always covers the client rectangle.

Customization panel

When you click Customize on an MpvPlayer wallpaper, the Property service renders the PropertiesType.MpvPlayer panel, defined by the base64 MpvProperties JSON. The exposed controls are:

Control	Range / Notes
video-zoom	-5 .. 5
saturation	—
hue	—
sharpen	—
brightness	—
contrast	—
scale-blur	—
gamma	—
speed	0.25 – 2.5
mute	Toggle
sid (caption/subtitle)	Toggle

Changes are applied live (the engine's property watcher re-applies on each edit). See Customizing Wallpaper and Property Service.

Mpv.NET public surface

For reference, the Sucrose.Mpv.NET player exposes (Player/IMpvPlayer.cs):

• Properties: AutoPlay, IsMediaLoaded, IsPlaying, Loop, LoopPlaylist, Duration, Position, Remaining, Mute, Volume, Speed, YouTubeDlVideoQuality, KeepOpen.
• Methods: Load, LoadPlaylist, SeekAsync, Resume, Pause, Stop, RestartAsync, AddAudio, Playlist*, EnableYouTubeDl, NextFrame, PreviousFrame.
• Events: MediaLoaded, MediaFinished, MediaError, PositionChanged, and others.

(Although EnableYouTubeDl exists, the MpvPlayer engine does not use the YouTube path — YouTube is browser-only by routing.)

Strengths and limitations

Strengths

• Most format-robust playback in Sucrose; needs no system codecs because libmpv is bundled.
• Native rendering with low overhead and a low-latency profile by default.
• Default engine for both Gif and Video, so no configuration needed for the common cases.
• Direct mpv tuning via the uMpvPlayerConfig override.

Limitations

• Renders only Gif and Video — no interactivity, no web content, no audio-reactive/system-data injection.
• Requires Windows 10 1607 or newer.
• The bundled libmpv DLLs are large (~79–117 MB), the bulk of the engine's footprint.

See also

• Engines Overview
• Engine Comparison
• Engine Nebula
• Type Video
• Type Gif
• Customizing Wallpaper
• System Requirements