Dynamic Wallpaper Cycling for macOS
A fast, elegant, and memory-efficient macOS application that automatically cycles through your favorite wallpapers with intelligent multi-monitor support, built with SwiftUI.
- Recursive folder scanning - Automatically finds images in subfolders
- Multiple format support - JPEG, PNG, HEIC, BMP, TIFF, GIF, WebP
- Intelligent caching - Memory-efficient image preloading and management
- Real-time monitoring - Automatically detects new images added to folders
- Independent wallpapers - Different images on each monitor
- Synchronized mode - Same wallpaper across all displays
- Per-screen controls - Manual wallpaper selection for individual monitors
- Dynamic detection - Automatically adapts to monitor configuration changes
- Memory efficient - Intelligent caching with configurable limits (50MB default)
- Background processing - Non-blocking file operations
- Smart preloading - Loads next wallpaper in advance for seamless transitions
- Aggressive optimization - Memory pressure monitoring and cleanup
- Customizable intervals - From 10 seconds to 24 hours
- Shuffle mode - Random wallpaper selection
- Manual navigation - Previous/next controls
- Sorting options - Name, date, size, random
- Scaling modes - Fill, fit, stretch, center, tile
- Native menu bar controls - Start/stop, navigate, browse
- Real-time status - Current image, countdown timer, memory usage
- Quick actions - Folder selection, gallery browser, settings
- System integration - Launch at startup, dock hiding options
- macOS 11.0+ (Big Sur or later)
- Apple Silicon or Intel Mac
- File system permissions for selected wallpaper folders
git clone https://github.com/yourusername/wallpier.git
cd wallpier
open wallpier.xcodeprojBuild and run using Xcode 14.0+
Download the latest release from Releases
- Launch Wallpier and grant necessary permissions
- Select a folder containing your wallpaper images
- Configure settings - Set interval, enable shuffle, choose scaling
- Start cycling and enjoy automatic wallpaper changes
- Same wallpaper: Check "Use same wallpaper on all monitors"
- Different wallpapers: Uncheck the option for independent images per screen
- Manual selection: Use "Browse Wallpapers" → click monitor previews
- Green icon = Running, Red icon = Error, Gray icon = Stopped
- Click for menu with start/stop, navigation, and settings
- Inline controls for quick previous/start/stop/next actions
- Models:
WallpaperSettings,ImageFile,CycleConfiguration - ViewModels:
WallpaperViewModel,SettingsViewModel - Views: SwiftUI interface with native macOS controls
- WallpaperService - System integration for setting wallpapers
- ImageScannerService - Recursive folder scanning and file discovery
- ImageCacheService - Memory-efficient image caching and preloading
- FileMonitorService - Real-time folder change detection
- SystemService - macOS system integration and permissions
- Async/await for all file operations
- Combine framework for reactive state management
- Background queues for non-blocking processing
- Smart memory management with automatic cleanup
// Interval range
10 seconds - 24 hours
// Supported formats
.jpg, .jpeg, .png, .heic, .bmp, .tiff, .gif, .webp
// Scaling modes
Fill, Fit, Stretch, Center, Tile- Cache size: Configurable memory limit (default: 50MB)
- Preload distance: Number of images to preload (default: 1)
- Memory pressure: Automatic cleanup at 300MB app usage
- Image optimization: Auto-downsample to 2MP for previews
- Independent cycling: Different images per screen
- Synchronized mode: Same wallpaper across displays
- Per-screen scaling: Individual scaling modes per monitor
# Clone repository
git clone https://github.com/yourusername/wallpier.git
cd wallpier
# Open in Xcode
open wallpier.xcodeproj
# Build for release
xcodebuild -project wallpier.xcodeproj -scheme wallpier -configuration Release build# Run tests
xcodebuild test -project wallpier.xcodeproj -scheme wallpier -destination 'platform=macOS'- Swift 5.7+ modern syntax
- SwiftUI for interface, AppKit for system integration
- Async/await for concurrent operations
- Comprehensive error handling
- Startup time: < 2 seconds
- Memory usage: < 100MB steady state
- Folder scan: < 1000ms for 500 images
- Wallpaper change: < 500ms average
- Cache hit rate: > 70% target efficiency
Wallpier respects your privacy:
- Local operation only - No network activity
- User-selected folders only - Access only to chosen directories
- Sandboxed application - macOS security compliance
- No data collection - All processing happens locally
Wallpaper not changing
- Check folder permissions
- Verify image file formats
- Ensure cycling is active (green menu bar icon)
High memory usage
- Reduce cache size in advanced settings
- Use smaller image files
- Enable memory pressure monitoring
Multi-monitor issues
- Check "Use same wallpaper" setting
- Verify monitor detection in settings
- Restart app after monitor changes
- Menu bar shows real-time memory usage
- Performance statistics in advanced view
- Detailed logging available in settings
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with SwiftUI and Combine
- Uses NSWorkspace for wallpaper integration
- Performance monitoring via mach_task_basic_info
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Wiki: Project Wiki
Made with ❤️ for macOS users who love beautiful wallpapers