skip to content
MusesΜοῦσαιdocs

basics / 01 of 15

Introduction

phonto plays a video as your desktop wallpaper, on Wayland compositors and on macOS, and leaves the decoding to the GPU.

What phonto is

phonto puts a looping video behind your windows. Give it a file, a stream URL or a YouTube link, and it plays that on every display, or a different video on each, until you stop it.

A video wallpaper sounds like a good way to spend a battery, and decoded on the CPU it would be. phonto keeps the work on the GPU. On Linux, GStreamer decodes the video, through VA-API when your driver has it, and hands phonto each frame as a GL texture. phonto draws it through EGL onto a layer-shell surface, the kind of Wayland surface that bars and lock screens use. On macOS, VideoToolbox decodes and CoreAnimation draws the frames into a borderless window at desktop level, under the icons.

What it isn’t

  • A wallpaper manager. There’s no picker, tray icon or daemon to talk to. phonto plays what you started it with. To change the wallpaper, stop phonto and start it again with something else.
  • For still images. phonto plays video. For a picture, swaybg or hyprpaper does the job with less.
  • For GNOME or X11. On Linux, phonto needs a compositor with wlr-layer-shell, such as Hyprland, Sway, niri, river or KDE Plasma. GNOME doesn’t have it.
  • Audible. Sound is never played. Linux drops the audio track and macOS mutes the player.

Timeline

  1. 2026

      • phonto dump saves a frame of a video as an image.

    2. v0.5.0

      • YouTube links play, looked up through yt-dlp.
      • Stream URLs play, over HTTP, HLS, RTSP and RTMP, and open again when they end.
      • HEVC videos in MP4 files play on Linux.

    3. v0.4.0

      • The wallpaper plays on every display, including displays plugged in later.
      • A different video on each display, with --display, --display-rand and [[display]].
      • [[alias]] gives a display one name on Linux and macOS.
      • phonto displays lists the display IDs.
      • Paths can start with ~/.

    4. v0.3.2

      • GLSL shaders on Linux, with --shader.
      • On Linux, the wallpaper follows a display’s change of resolution.

      • A Nix flake, and a package on the AUR.
      • File names with quotes or ! in them play instead of breaking the GStreamer pipeline.

    6. v0.3.1

      • --layer, for playing behind lock screens on Wayland.
      • Pausing on battery works on Linux.
      • A Homebrew tap.
      • ~/.cache/phonto/current names the video playing.

    7. v0.3.0

      • Pausing on battery on macOS, with --pause-on-battery and --pause-below.
      • Lock screen videos on macOS, with phonto install-live-lockscreen.

      • --scale, with fill, fit, stretch and center.

    9. v0.2.1

      • phonto writes a commented config file on its first run.

    10. v0.2.0

      • macOS, through AVFoundation.
      • --rand picks from folders listed in config.toml.

    11. v0.1.0

      • GStreamer replaces FFmpeg for decoding.
      • A command line: phonto <path>.
      • The first release binaries.

      • The first video wallpaper, decoded with FFmpeg.

      • A plain white background, drawn through EGL.

      • The first commit: a connection to the Wayland compositor.

Where to go next