Engine VlcPlayer

Engine: VlcPlayer

Sucrose.Live.VlcPlayer is Sucrose's libVLC-based media engine. It hosts libVLC through LibVLCSharp (the WPF VideoView control) and renders Gif and Video wallpapers. Like MpvPlayer, it bundles its own native media library — libVLC — per architecture, so it plays a wide range of formats without any system codecs. It is a second self-contained alternative to MpvPlayer for video and an additional option for GIF. VlcPlayer is not the default for any type (Gif and Video still default to MpvPlayer); you opt into it from Settings → Wallpaper. This page covers the technology, supported types, the bundled binary, playback control, customization, GIF handling, and its limitations.

Table of contents

• At a glance
• Technology
• Supported wallpaper types
• Bundled native binary (no runtime check)
• Playback control
• Hardware acceleration and Stay Awake
• Customization panel
• GIF handling
• Strengths and limitations
• See also

At a glance

Property	Value
Assembly	Sucrose.Live.VlcPlayer.exe
Tech	libVLC (native) via LibVLCSharp.WPF (VideoView)
Supported types	Gif, Video
Default for	(none — MpvPlayer is the default Gif/Video engine)
Preprocessor symbols	ENGINE, LIVE_VLCPLAYER
Enum member	EngineType.VlcPlayerLive (index 7)
Runtime requirement	None — native libVLC bundled per architecture; no OS-version check, no download prompt
Native dependency	Bundled libVLC (VideoLAN.LibVLC.Windows), one architecture per build
Interactivity	No (pure media playback; mouse/keyboard input disabled)
Audio/system-data injection	No
Properties panel	PropertiesType.VlcPlayer

Technology

VlcPlayer embeds libVLC through LibVLCSharp's WPF VideoView, which hosts a MediaPlayer backed by a single LibVLC instance. Frames are rendered natively by libVLC rather than through WPF's media stack or a browser, so it has the broad codec coverage of the VLC engine without relying on any system codecs.

The LibVLC instance is created with a fixed set of options — no-lua, no-osd, no-spu, no-stats, no-drop-late-frames, no-snapshot-preview, no-sub-autodetect-file, no-metadata-network-access — plus a screensaver flag driven by the Stay Awake setting (disable-screensaver / no-disable-screensaver). The player runs Fullscreen with mouse and keyboard input disabled.

The native libVLC binaries come from the VideoLAN.LibVLC.Windows NuGet package; at startup the engine calls Core.Initialize() and looks for the libVLC libraries under %AppData%\Sucrose\Cache\VlcPlayer\.

Supported wallpaper types

VlcPlayer renders Gif (SSDEWT.Gif) and Video (SSDEWT.Video) only. App.Configure()'s switch has exactly those two cases (showing the View.Gif or View.Video window); Url, Web, YouTube, and Application fall through to the default → Close() branch and nothing displays. See Type Gif and Type Video.

The source is resolved from Info.Source like the other engines: a local file inside the wallpaper folder, or an http/https URL.

Bundled native binary (no runtime check)

Unlike MpvPlayer (which performs a Windows 10 1607 / IsRedstone1 OS check) and the browser engines (which prompt to download the WebView2 or VC++ runtime), VlcPlayer performs no engine-specific OS or runtime check and shows no auto-download prompt. It bundles libVLC, so no user install is required.

The VideoLAN.LibVLC.Windows package ships native libVLC for x86, x64, and ARM64. By default it copies every architecture to the output, so the build keeps only the architecture it targets — mirroring how MpvPlayer ships a single libmpv-{arch}.dll — via the VlcWindowsX86Enabled / VlcWindowsX64Enabled / VlcWindowsArm64Enabled switches in the engine .csproj. The bundled libVLC binaries are the bulk of the engine's on-disk footprint.

Playback control

A 1-second GeneralTimer tick drives playback maintenance (Helper/Gif.cs, Helper/Video.cs):

• Loop — SetLoop(GetLoop()); on the EndReached event the media is replayed when WallpaperLoop is on.
• Volume (Video only) — SetVolume(GetVolume()) each tick, on libVLC's 0–100 scale. GIF media is silent, so the GIF view has no volume control.
• Stretch — SetStretch maps the WPF Stretch mode (None / Fill / Uniform / UniformToFill) to libVLC scale / aspect-ratio / crop settings.
• Pause / Resume — honors Backgroundog's PausePerformance: it pauses the MediaPlayer under a performance rule and resumes when the rule clears. See Performance Rules.

Mouse and keyboard input are disabled (EnableMouseInput = false, EnableKeyInput = false), so VlcPlayer is a non-interactive renderer. On window close the MediaPlayer is disposed.

Hardware acceleration and Stay Awake

• HardwareAcceleration (Settings → Wallpaper) sets EnableHardwareDecoding on the libVLC MediaPlayer. With it off, the color/image filters in the customization panel are skipped — libVLC video-adjust post-processing requires hardware decoding in this engine, and applying it with decoding disabled would crash.
• Stay Awake is wired two ways: the LibVLC instance is created with disable-screensaver / no-disable-screensaver, and the cross-engine "Stay Awake" loop (SetThreadExecutionState every 30 s) also runs. See Settings Wallpaper.

Customization panel

When you Customize a VlcPlayer Gif/Video wallpaper, the Property service renders the PropertiesType.VlcPlayer panel (the base64 VlcProperties JSON). The implemented controls are:

Control	Effect	Notes
saturation	Color saturation	slider −100..100 (mapped to libVLC 0.0–3.0)
hue	Hue shift	slider −100..100 (mapped to −180..180)
brightness	Brightness	slider −100..100 (mapped to 0.0–2.0)
contrast	Contrast	slider −100..100 (mapped to 0.0–2.0)
gamma	Gamma correction	currently non-functional (a known libVLC video-adjust issue, flagged in the code)
speed	Playback rate	applied via MediaPlayer.SetRate
mute	Mute audio	toggle

The four color filters (saturation, hue, brightness, contrast) and gamma are applied through libVLC's video-adjust and only take effect when Hardware Acceleration is ON — with it off they are silently skipped to avoid a post-processing crash. Speed and mute work regardless.

This is a subset of the MpvPlayer panel, which additionally exposes video-zoom, sharpen, scale-blur, and a subtitle (sid) toggle. Changes are applied live by the engine's property watcher. See Customizing Wallpaper and Property Service.

GIF handling

libVLC's native image demuxer would open an animated GIF as a single still frame (freezing it on the first frame), so for GIF wallpapers VlcPlayer:

• forces the FFmpeg/avformat demuxer (:demux=avformat) so every frame is decoded; and
• forces software decoding (:avcodec-hw=none), because GIF is a software-only codec and hardware decoding offers nothing and can produce corrupt frames.

As a result GIF playback is CPU-bound, and because VLC 3.x does not loop gaplessly, looping GIFs (and short clips) can show a brief stutter at the loop boundary. For the smoothest local-GIF playback prefer the default MpvPlayer, or the pure-WPF Vexana / Xavier engines. See Type Gif.

Strengths and limitations

Strengths

• Self-contained like MpvPlayer — bundles libVLC, needs no system codecs and no runtime download.
• No OS-version requirement and no dependency prompt.
• A second robust video engine and an extra GIF option, with live color, speed, and mute controls.

Limitations

• Renders only Gif and Video — no interactivity, no audio-reactive / system-status injection.
• The color filters require Hardware Acceleration to be on, and the gamma control is currently non-functional.
• GIF is software-decoded and not gapless — it can stutter at loop points; MpvPlayer / Vexana / Xavier are smoother for GIF.
• The bundled libVLC adds to the engine's on-disk size (one architecture per build).

See also

• Engines Overview
• Engine Comparison
• Engine MpvPlayer
• Engine Nebula
• Type Video
• Type Gif
• Customizing Wallpaper
• Runtime Dependencies