Skip to content

Add support for videos as background images#701

Open
OneTrickSupport wants to merge 1 commit into
gnachman:masterfrom
OneTrickSupport:video-backgrounds
Open

Add support for videos as background images#701
OneTrickSupport wants to merge 1 commit into
gnachman:masterfrom
OneTrickSupport:video-backgrounds

Conversation

@OneTrickSupport

Copy link
Copy Markdown

Summary

Adds support for using short videos (mp4/mov) as terminal background images, addressing the long-standing request for animated backgrounds (GitLab issue #7920).

  • The Settings > Profiles > Window file picker accepts videos alongside images, validates that the file is playable, previews the first frame, and shows a permanently-silenceable notice about the energy cost of high-resolution / high-frame-rate files.
  • Videos play muted in a seamless loop (AVPlayerLooper) and respect blend, transparency, and all four scaling modes (Tile falls back to Fill).
  • Works with both renderers:
    • GPU renderer: iTermBackgroundImageRenderer wraps each frame's pixel buffer as a BGRA Metal texture via CVMetalTextureCache (zero-copy). The update cadence treats a playing video like an inline animated GIF so frames draw at display rate.
    • Legacy renderer: an AVPlayerLayer in iTermImageView plays the video; playback position carries over seamlessly when the renderer switches because both paths share one player.
  • iTermImageWrapper owns a single shared muted AVQueuePlayer + AVPlayerItemVideoOutput per video and loads a poster frame for image-only consumers (blending, tiling, snapshots). Consumers hold playback interests, so decoding pauses when nothing is visible and split panes showing the same video share a single decoder.

Test plan

Manually verified on macOS 26 (Apple Silicon), Xcode 26.6:

  • Picking mp4/mov via the picker; picker still accepts images and folders; corrupt-file warning still works
  • Playback under the GPU renderer (confirmed active) and under the legacy renderer (transparency enabled)
  • Split panes: shared decoder, synchronized playback; per-pane and whole-window background modes
  • Blend slider and all scaling modes live-update
  • Playback pauses when the window is hidden/miniaturized
  • Removing the video restores normal behavior

Known limitations

  • Drag-and-drop of a video onto the settings image well is not supported (picker only) since NSImageView filters non-image drags
  • The Metal path samples raw BGRA without color-space conversion, so colors can differ very slightly from the legacy path
  • The non-monochrome manual drawing path (e.g. minimum contrast) shows the static poster frame

🤖 Generated with Claude Code

Background images can now be mp4 or mov files.
The Settings file picker accepts videos,
validates that they are playable, previews the
first frame, and shows a silenceable notice
about the energy cost of high-resolution,
high-frame-rate files.

iTermImageWrapper carries the video URL, loads a
poster frame for image-only consumers, and owns
one shared muted looping AVQueuePlayer per video
with an AVPlayerItemVideoOutput. Consumers hold
playback interests so decoding pauses when
nothing is visible and panes showing the same
video share a single decoder.

With the GPU renderer, iTermBackgroundImageRenderer
wraps each frame's pixel buffer as a BGRA Metal
texture via CVMetalTextureCache, and the update
cadence treats a playing video like an inline
animated GIF so frames draw at display rate.
Without it, an AVPlayerLayer in iTermImageView
plays the video; blend, transparency, and all
scaling modes apply in both paths, and playback
position carries over when switching renderers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant