nashsu/VideoWallpaper

About

Native macOS dynamic wallpaper menubar app created automatically in 7m 9s by OpenCode using Claude Haiku 4.5. Using swift. Select any mp4 video file and set as dynamic wallpaper.

This project is only a test of opencode and claude Haiku 4.5's ability. for the moment no further development plans for additional functions.

For MacOS dynamic wallpaper, you can select https://wallspace.app/ or other functional apps.

Video Wallpaper - macOS Dynamic Wallpaper App

A lightweight macOS menu bar application that allows you to set MP4 video files as your desktop wallpaper with seamless looping.

Features

• Video Wallpaper Support: Set any MP4, MOV, MKV, or WebM video file as your desktop wallpaper
• Seamless Looping: Videos loop endlessly with AVPlayerLooper for smooth transitions
• Menu Bar Control: Minimal menu bar interface for easy access
• Play/Pause Controls: Quickly pause and resume wallpaper playback from the menu bar
• Preferences Window: Select and manage your wallpaper video files
• File Persistence: Remembers your selected video across app restarts
• macOS Native Integration: Works with macOS's native windowing system

Requirements

• macOS 12.0 or later
• Swift 5.0 or later
• Xcode 15.0 or later (for building)

Architecture

Core Components

VideoPlayerController (VideoPlayerController.swift)

• Manages AVPlayer instance and playback
• Handles video file loading and validation
• Provides play/pause/stop controls
• Uses AVQueuePlayer for seamless looping via AVPlayerLooper

DesktopWindowManager (DesktopWindowManager.swift)

• Creates and manages the desktop overlay window
• Positions video at desktop level using CGWindowLevel
• Ensures window stays behind all user windows
• Handles window lifecycle and visibility

WallpaperManager (WallpaperManager.swift)

• Manages user preferences (video file path, auto-start setting)
• Persists settings to UserDefaults
• Validates video file formats and availability

AppDelegate (VideoWallpaperApp.swift)

• Application entry point and lifecycle management
• Sets activation policy to .accessory (menu bar only)
• Manages status bar item and popover
• Coordinates between UI and video playback components

UI Components

MenuBarView (MenuBarView.swift)

• Popover menu displayed from menu bar icon
• Shows current video file name
• Play/pause/stop controls
• Quick access to preferences and quit

PreferencesView (PreferencesView.swift)

• Full preferences window
• Video file selection via file picker
• Settings toggles (auto-start on login)
• File validation and error messaging

Building from Source

cd VideoWallpaper
open VideoWallpaper.xcodeproj

Or build from command line:

cd VideoWallpaper
xcodebuild -scheme VideoWallpaper -configuration Release

Usage

1. Launch the App: Open VideoWallpaper.app from Applications
2. Select a Video: Click the menu bar icon → Click "Preferences" → Select your MP4 video file
3. Enable Wallpaper: Click "Apply" - the video will appear as your desktop background
4. Control Playback: Use the menu bar icon to pause/play/stop
5. Settings: Toggle "Launch at Login" to auto-start the app

Supported Video Formats

• MP4 (.mp4)
• MOV (.mov)
• Matroska (.mkv)
• WebM (.webm)

How It Works

Desktop Overlay Technique

Instead of using the official macOS wallpaper API (which doesn't support videos), this app creates a transparent window positioned at the desktop level:

1. Creates an NSWindow with .borderless style
2. Sets window level to kCGDesktopWindowLevel + 1 (behind all user windows)
3. Disables mouse interaction via ignoresMouseEvents = true
4. Embeds AVPlayerLayer for video rendering
5. Uses AVPlayerLooper for seamless loop playback

Video Playback

• Player Type: AVQueuePlayer (for looping support)
• Looping: AVPlayerLooper creates seamless infinite loops
• Audio: Always muted (for unobtrusive background playback)
• Rendering: Metal-accelerated via AVPlayer layer composition

Performance

• CPU Usage: Typically 5-15% depending on video resolution
• Memory: ~100-200 MB including video buffer
• Battery: Minimal impact when properly coded (video rendering uses GPU)

Optimization Tips

1. Use H.265 codec for better compression
2. Match video resolution to your display
3. Use 24-30 fps frame rate (not 60 fps)
4. Keep video file under 500 MB for smooth loading

Limitations

• Single Display: Current version supports single display (multi-monitor support can be added)
• Video-Only Wallpapers: Cannot set images as dynamic wallpapers (use static wallpaper API for that)
• Loop Points: Video must have clean start/end frames for smooth looping
• Full-Screen Apps: Video appears behind all windows (including full-screen apps)

Future Enhancements

• Multi-monitor support with per-display video selection
• Brightness and opacity adjustments
• Video file thumbnail preview
• Playback speed control
• Custom loop point selection
• Transition effects between video scenes
• Keyboard shortcuts for quick control

License

MIT License - Feel free to use and modify

Contributing

Contributions welcome! Please submit pull requests or issues for bugs and feature requests.

Troubleshooting

Video doesn't appear:

• Ensure the video file is not corrupted
• Try a different video format (MP4 recommended)
• Check that file permissions allow reading

App crashes on startup:

• Delete saved preferences: defaults delete com.videowallpaper.app
• Rebuild the app from Xcode

High CPU usage:

• Try a lower resolution video
• Use H.265 codec instead of H.264
• Reduce frame rate to 24 fps

Contact

For issues, questions, or suggestions, please open an issue on GitHub.