Type YouTube
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, speed). 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.
- What it is
- Accepted URLs
- Engines for YouTube
- How to apply a YouTube wallpaper
- Playback controls
- Customization
- Caveats
- Tips
- See also
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).
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.
| 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.
- Open the Portal → Library.
- Use the Create dialog, choose the YouTube type, and paste a valid video/playlist URL.
- Right-click the card → Use.
- (Optional) Switch the engine first in Settings → Wallpaper.
Because YouTube wallpapers run in a browser engine through the built-in wrapper, they support Sucrose's standard JavaScript playback functions:
| Function | Effect |
|---|---|
SucrosePlay() |
Start/resume playback |
SucrosePause() |
Pause playback |
SucrosePlayPause() |
Toggle play/pause |
SucroseLoopMode(state) |
Loop the video/playlist |
SucroseShuffleMode(state) |
Shuffle the playlist |
SucroseStretchMode(mode) |
Fit mode (None/Fill/Uniform/UniformToFill) |
SucroseSpeedRate(rate) |
Playback speed (playbackRate) |
SucroseVolumeLevel(level) |
Volume |
These map to the global wallpaper settings (loop, shuffle, stretch, volume) so the standard Portal controls drive the embedded player. The YouTube wrapper additionally supports a caption toggle. See Create Property Listener & Filters.
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.
- 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
SucroseAudioDataor 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.
- Pick videos/playlists that loop well and have minimal on-screen text/logos.
- A playlist plus
SucroseShuffleModegives 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).
- 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