Type YouTube

YouTube Wallpapers

A YouTube wallpaper (type value 4, YouTube) plays a YouTube video — or an entire playlist — live on your desktop. You paste a YouTube or YouTube Music URL and Sucrose embeds it via the YouTube IFrame player, complete with JavaScript playback controls (play/pause, loop, shuffle). It is ideal for music videos, ambient loops, lo-fi playlists, and relaxing scenes you don't want to download. This page covers what a YouTube wallpaper is, its engines, the URLs it accepts, playback controls, and its caveats.

Contents

• What it is
• Accepted URLs
• Engines for YouTube
• How to apply a YouTube wallpaper
• Playback controls
• Customization
• Caveats
• Tips
• See also

What it is

In the manifest, a YouTube wallpaper has "Type": 4 and a Source that is the YouTube video or playlist URL. Sucrose renders it through a built-in YouTubeContent.html wrapper that uses the official YouTube IFrame API, so the video is streamed (nothing is downloaded into the folder).

Accepted URLs

When you create a YouTube wallpaper, the URL is validated against Sucrose's YouTube helpers, which recognize video and playlist links from both YouTube and YouTube Music. The wrapper extracts the video id from ?v= and the playlist id from ?list=. In practice you can paste:

• A standard video URL (https://www.youtube.com/watch?v=...)
• A YouTube Music URL
• A playlist URL (...&list=...)

If the link doesn't pass validation, the Create dialog rejects it.

Engines for YouTube

Engine	Tech	Notes
CefSharp (default)	Chromium Embedded Framework (offscreen)	Default for YouTube. Requires the VC++ Redistributable (≥ 14.40.33816.0).
WebView	Microsoft Edge WebView2 (Chromium)	Requires the WebView2 runtime (≥ 131.0.2903.70).

Note that even though libmpv can technically fetch YouTube via youtube-dl, Sucrose routes the YouTube type to the browser engines only — MpvPlayer does not serve YouTube. Change the engine in Settings → Wallpaper (the YouTubePlayer selector). See Choosing Engines.

How to apply a YouTube wallpaper

1. Open the Portal → Library.
2. Use the Create dialog, choose the YouTube type, and paste a valid video/playlist URL.
3. Right-click the card → Use.
4. (Optional) Switch the engine first in Settings → Wallpaper.

Playback controls

Because YouTube wallpapers run in a browser engine through the built-in wrapper, they expose YouTube-IFrame-specific JavaScript playback functions:

Function	Effect
playVideo()	Start/resume playback
pauseVideo()	Pause playback
playFirst()	Play only if not already playing
setLoop(state)	Loop the video/playlist
setShuffle(state)	Shuffle the playlist
setVolume(level)	Set volume
toggleFullScreen()	Force the embedded player full-screen
checkVideoEnded() / checkPlayingStatus()	Report player state back to the engine

These are driven by the engine via Sucrose.Shared.Engine.{CefSharp,WebView}.Helper.YouTube, mapping the global loop/shuffle/volume settings to the embedded YouTube IFrame player. Playback speed, mute, and captions are not standalone functions for YouTube — they are applied through the property/filter channel (SucrosePropertyListener) via the playbackRate, muted, and caption cases. See Create Property Listener & Filters.

Customization

YouTube wallpapers use the browser engine's filter panel: scale (zoom), saturate, hue-rotate, brightness, contrast, blur, grayscale, sepia, invert, mirror, animation effect, playbackRate, muted, and caption. Changes re-apply live. See Customizing Wallpaper.

Caveats

• Requires a network connection — the video streams from YouTube; offline means no playback.
• No Sucrose live data — like the Url type, YouTube wallpapers do not receive SucroseAudioData or the system-status callbacks (those are exclusive to the local Web type).
• Subject to YouTube — ads, region restrictions, age gates, "video unavailable", and YouTube layout changes can affect playback.
• Heavier than a local video — it runs Chromium and streams over the network; consider a local Video wallpaper for the lowest overhead.

Tips

• Pick videos/playlists that loop well and have minimal on-screen text/logos.
• A playlist plus SucroseShuffleMode gives endless variety without re-applying.
• Mute the wallpaper (Customize) if you only want the visuals.
• If a particular video won't embed, try the other engine (CefSharp ↔ WebView).

See also

• Wallpaper Types — all six types and the engine mapping
• Type-Url — any external website as a wallpaper
• Type-Video — a downloaded, offline-friendly alternative
• Engine-CefSharp and Engine-WebView — the browser engines
• Create Property Listener & Filters — playback wrappers and filters