SakuraWallpaper

A lightweight video and image wallpaper application for macOS. Current version: v1.0.1

Chinese Documentation

Project Status

SakuraWallpaper is complete and fully usable in its current form.

Future updates will focus on necessary fixes, compatibility upkeep, and polishing what already exists. New features will no longer be added for the sake of accumulation. The project will continue to follow a lightweight standard: keep it focused, keep it clean, keep it useful.

Sakura first.

Features

• Set videos (MP4, MOV, GIF) or images (PNG, JPG, HEIC, WebP) as desktop wallpaper
• System Desktop Sync: Images are applied directly as the system desktop picture; videos sync the currently playing frame to the system desktop on wallpaper changes and lock/screen saver start
• Rotation Mode: Select a folder to automatically cycle through wallpapers
• Per-Screen Independent Rotation: Each display can keep its own folder path, playlist, interval, and shuffle state
• Synchronized Linking: Link screens together to mathematically guarantee their rotation timers switch wallpapers at the exact same millisecond
• Dual-Preview Mode: Live playback of the current wallpaper directly within the settings window, alongside an interactive thumbnail grid for folder contents
• Mission Control Resilience: Wallpapers seamlessly span across all virtual spaces and instantly recover during monitor reattachments
• Low Battery Auto Pause: Automatically pauses wallpaper playback when battery level is at or below 20% and not charging
• Multi-display support with robust monitor detection
• Video wallpaper with automatic loop playback
• Recent wallpapers history for quick switching (Supports folders)
• Launch at login support
• Manual Pause/Resume control
• Bilingual interface (English / Chinese)

Screenshots

Supported Formats

Video

• MP4, MOV, M4V
• GIF (animated)

Image

• PNG, JPG, JPEG
• HEIC
• WebP, BMP, TIFF

Installation

Download

Download the latest SakuraWallpaper.dmg from Releases and drag SakuraWallpaper to Applications folder. OR

brew install --cask yueseqaz/tap/sakura-wallpaper

Build from Source

git clone https://github.com/yueseqaz/SakuraWallpaper.git
cd SakuraWallpaper
./build.sh
open build/SakuraWallpaper.app

Requirements: macOS 12.0+, Xcode Command Line Tools

MCP — AI Agent Control

SakuraWallpaper ships with an MCP (Model Context Protocol) server that lets AI agents (Claude Desktop, Cursor, Codex) control your wallpapers directly. The binary is bundled inside the app — no separate download or build required.

Connect to Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "sakura-wallpaper": {
      "command": "/Applications/SakuraWallpaper.app/Contents/Resources/sakura-mcp"
    }
  }
}

Restart Claude Desktop, then say things like:

• "Set my wallpaper to a minimal mountain landscape image"
• "Pause all wallpapers"
• "Switch my external monitor to the next wallpaper"
• "Set my laptop screen to rotate wallpapers from ~/Pictures/Nature every 10 minutes with shuffle on"

Note: If you installed SakuraWallpaper elsewhere, adjust the path accordingly.

AI Self-Install Prompt

If your AI agent doesn't have a pre-configured connection, paste this prompt — it will find and start the MCP server on its own:

You are setting up SakuraWallpaper MCP server. Find and start the binary:

1. Run: ls /Applications/SakuraWallpaper.app/Contents/Resources/sakura-mcp
2. If found, start it as a subprocess over stdio. This is an MCP server with
   9 JSON-RPC tools.
3. If not found, run: cd /path/to/SakuraWallpaper && swift build --product sakura-mcp
   then start .build/debug/sakura-mcp
4. Tool list: list_screens, get_status, set_wallpaper, set_folder,
   stop_wallpaper, pause_resume, next_wallpaper, get_settings, update_settings
5. Once connected, I can ask you to control my wallpapers — set images/videos,
   manage folders, pause/resume, adjust rotation settings, etc.

How MCP Coordinates with the App

The MCP server is designed to behave like a safe remote control instead of a second competing wallpaper app:

Situation	Behavior
SakuraWallpaper app is already running	MCP forwards wallpaper commands to the running app, so the app remains the single wallpaper controller
SakuraWallpaper app is not running	MCP starts its own lightweight wallpaper engine and can control wallpapers independently
A standalone MCP process is already controlling wallpapers	A second standalone MCP process refuses wallpaper-control requests instead of creating another wallpaper engine
MCP is only forwarding to the app	The MCP process exits normally after the stdio session ends
MCP is running standalone	The MCP process stays alive after stdin closes so wallpaper windows remain visible

This prevents flickering caused by multiple wallpaper engines fighting over the same desktop while still allowing AI agents to work when the main app is closed.

Available MCP Tools

Tool	Description
list_screens	List all connected displays
get_status	Current wallpaper status per screen
set_wallpaper	Set a single image/video file on one or all screens
set_folder	Set a folder for rotational wallpapers
stop_wallpaper	Stop wallpaper on one or all screens
pause_resume	Pause or resume playback
next_wallpaper	Skip to the next wallpaper
get_settings	Read current configuration
update_settings	Change rotation interval, shuffle, fit mode, etc.

Usage

1. Drag a wallpaper file/folder into the preview area, or click the preview area to choose in Finder
2. Use the Interval stepper to set how often the wallpaper changes (in Rotation Mode)
3. Enable Shuffle for randomized order
4. Toggle Battery Saver to optimize energy usage while working in other apps or when the screen is off
5. Use the screen dropdown to switch displays (prioritizes built-in displays first)
6. Enable Link Screens to synchronize the current display's configuration and rotation timing with other linked screens
7. Click Stop Wallpaper to clear the current screen's wallpaper
8. Select a New Screen Policy to determine how newly connected monitors should behave (e.g., Inherit Sync Group)
9. Right-click the status bar icon for quick controls

System Desktop Sync Behavior

• Image wallpapers are pushed to the system desktop immediately
• Video wallpapers snapshot the current playback frame when the wallpaper changes
• Locking the screen or starting the screen saver triggers another sync using the current on-screen content

Battery Saver Behavior

• When enabled, wallpapers auto-pause only if battery is <=20% and the Mac is not charging
• This auto-pause is different from manual pause in the menu

Status Bar Menu

• Open SakuraWallpaper - Open main window
• Status: Live/Manually Paused/Low Battery Auto Paused/None - Real-time informational readout
• Pause - Submenu with All Screens and per-screen pause/resume actions
• Battery Saver - Enable low-battery auto pause (<=20% and not charging)
• Next Wallpaper - Includes All Screens plus per-screen next actions (shortcut n applies to all screens)
• Clear Wallpaper - Reset and remove current selection
• Recent - Quick switch to previous wallpapers or folders
• Language - Switch between English and Chinese
• Clear History - Clear wallpaper history

Fix "App is Damaged" Error

If you see "SakuraWallpaper is damaged and can't be opened", run this command in Terminal:

xattr -cr /Applications/SakuraWallpaper.app

This removes the quarantine attribute that macOS applies to apps downloaded from the internet.

System Requirements

• macOS 12.0 Monterey or later
• Supports multiple displays

Project Structure

SakuraWallpaper/
├── AppDelegate.swift          # App lifecycle and status bar
├── MainWindowController.swift # Main window UI
├── WallpaperManager.swift     # Wallpaper playback engine
├── ScreenPlayer.swift         # Individual screen player
├── SettingsManager.swift      # User preferences storage
├── Localization.swift         # Localization helper
├── MediaType.swift            # File type detection
├── ThumbnailItem.swift        # Collection view item for previews
├── AboutWindowController.swift # About window
├── main.swift                 # Entry point
├── build.sh                   # Build script
├── AppIcon.icns               # App icon
├── Sources/sakura-mcp/        # MCP server (AI agent control)
│   ├── main.swift             #   Entry point
│   ├── MCPServer.swift        #   JSON-RPC stdio transport
│   ├── ToolRegistry.swift     #   Tool dispatch
│   ├── IPCSync.swift          #   GUI sync via notifications
│   └── Tools/                 #   9 MCP tools
├── Resources/
│   ├── en.lproj/              # English strings
│   └── zh-Hans.lproj/         # Chinese strings
├── README.md                  # English documentation
├── README_CN.md               # Chinese documentation
├── LICENSE                    # MIT License
└── .gitignore                 # Git ignore rules

Contributing

Thoughtful fixes, compatibility updates, and quality improvements are welcome. Changes that keep SakuraWallpaper stable, lightweight, and pleasant to use are the best fit for the project.

License

MIT License - see LICENSE for details.

Acknowledgments

Made with care by sakura.

May there be endless progress.