Repository navigation
Media Mode
Super + Z turns the desktop into a full-screen now-playing surface: album art behind everything, synced lyrics, a queue, transport controls and audio visualizers, re-coloured from whatever is playing. It follows any MPRIS player — and it can also be the player, with local music files, a queue you can sort, fades between tracks and an immersive layout that can fill the screen with the cover.
The wallpaper-side options (blurred art, animated background, the music-video backdrop) are also summarised on the Wallpaper System page; this page is the full tour.
- Play something, then press Super + Z. With Toggle per monitor on (the default) it opens on the monitor you are on.
- Open Settings → Background → Media Mode Background and switch on Immersive design for the new layout.
- In the immersive view, open Player options → Source → Local music to play files from your own disk; Files and Folder open the local music explorer.
- Exit Fullscreen Media Mode (or Super + Z again) closes it; local music keeps playing. To stop it too, use the power button (classic layout) or Player options → Library → Stop local music service (immersive).
- Classic — the original layout: cover art, controls, a player switcher across the top, a seek bar and a volume slider, with side panels for lyrics and the queue (Show side panels (Lyrics & Queue)).
-
Immersive (
Config.options.background.mediaMode.immersive, off by default) — a header naming the player (or Local music), the cover in the middle, transport controls underneath (Shuffle, Previous track, Play / Pause, Next track, Repeat), an Audio output picker and a Player options sheet. Two side panels, Lyrics and Up next, can be shown or hidden together with one button.
In the immersive layout the cover has two states — Show the whole cover and Fill the screen with the cover — toggled from a fullscreen button on the art. The classic layout has the equivalent Expand player card (Fullscreen).
The sheet groups everything you would otherwise open Settings for:
| Group | What's there |
|---|---|
| Source | Each running app player by name, or Local music (switching pauses the other) |
| Lyrics | The lyrics provider, decrease / increase lyrics size, reload lyrics, and nudge the lyrics offset by ±250 ms |
| Library | Files and Folder (add music to the local player), Cancel import, Stop local music service |
| Display | Match shell colors to album art, Music video background (app players only), Reload artwork |
Media Mode ships its own player for files on disk. A small helper (scripts/media/local_player.py) owns an mpv process and exposes it over MPRIS as org.mpris.MediaPlayer2.ii_local, so the rest of the shell — the bar's media widget, the Dynamic Island, the dashboard — sees it like any other player. The helper lives for the whole shell session, not for the Media Mode window: closing Media Mode on one monitor neither stops the audio nor starts a second player on another.
-
Local Music Explorer — Browse local disks, folders and music tracks: shortcuts for Music, Home, Downloads, mounted disks under
/mntand the root, a toggle for hidden folders, and a filter that shows only audio files (or everything). From a folder: Play entire folder or Add folder to queue; from a track: Play this track or Add track to queue. -
Up next — the queue panel: Clear upcoming tracks, Add music to queue, Add folder to queue, Center on current track, Expand queue, and Sort queue by Title, Artist, Date modified, Date created or Duration, ascending or descending. The sort is remembered in
states.json. - Stop — the classic layout's power button (Close Media Mode and stop local music service) or Stop local music service in the immersive Player options ends the helper too; the ordinary close leaves the music playing.
The library scanner (scripts/media/library_index.py, run in the shell's Python environment) reads tags, picks up embedded or folder cover art and lyric files (.lrc and friends) beside the tracks, and accepts .m3u/.m3u8 playlists. Requires mpv.
Enable track crossfade in the Media Mode settings fades each local-music track in over its first seconds and out over its last (Config.options.background.mediaMode.crossfade.enable, off by default; Crossfade duration (seconds), durationSec, 1–15, default 3). It applies to the local player only.
Synced lyrics with horizontal or vertical highlight styles, a millisecond offset (also nudgeable from the sheet), animated lines, a skeleton while they load and an empty state when a track has none. Font size is adjustable from the Player options sheet.
Sources: Auto tries LRCLib (synced, then plain), then YouTube Music, then Genius; any one of them can be pinned instead (Config.options.lyricsService.lyricsProvider). Local tracks use a lyric file found beside them. When nothing is found you can Paste .lrc with [mm:ss.xx] timestamps; pasted lyrics are saved per track in ~/.local/state/quickshell/user/custom-lyrics.json.
Turn it on from Player options → Display → Music video background (classic: the music-video button): the shell searches YouTube for the current track's video (search suffix musicVideo.searchSuffix, default official music video), fetches it with yt-dlp up to the chosen resolution and plays it behind the overlay with mpvpaper, dimmed for readability and colour-sampled every few hundred milliseconds so the shell's accent follows the video. It never starts on its own and switches off when Media Mode closes. Requires mpvpaper and yt-dlp.
Settings → Background → Media Mode Background — Immersive design, synchronized lyrics panel, top player switcher bar, audio visualizers (Waves / Bars / Radial), seek bar, volume slider, background animation and its speed, background album art opacity and shape, Change shell color to match album art, text highlight style, Toggle per monitor, crossfade, and the music-video options (maximum resolution, Dim background overlay and its opacity, colour sampling interval).
Everything persists under Config.options.background.mediaMode; the queue sort, the cover state and the local player's volume live in Persistent.states.background.mediaMode.
| Piece | Role |
|---|---|
modules/ii/background/MediaMode.qml |
The classic full-screen instance: background, visualizers, controls, the close and power buttons |
MediaModeImmersive.qml, MediaModeImmersiveArtwork.qml, MediaModeImmersiveGlass.qml, MediaModeImmersiveOptions.qml, MediaModeImmersiveButton.qml, MediaModeSidePanels.qml, MediaModePanelLayout.js
|
The immersive layout and its Player options sheet |
MediaModeQueue.qml, MediaModeFileBrowser.qml
|
Up next and the Local Music Explorer |
MediaModeLyrics*.qml, MediaModeLyricsProviderRow.qml
|
Lyrics rendering, skeletons, fallbacks and providers |
services/LocalMediaService.qml, services/LocalMediaSelection.qml
|
Shell-lifetime proxy for the local player helper and its import/scan state |
scripts/media/local_player.py, scripts/media/library_index.py
|
The mpv/MPRIS helper and the library scanner |
services/MusicVideoService.qml, services/VideoColorSampler.qml
|
Music-video fetching and live colour sampling |