{"id":50996371,"url":"https://github.com/ariksasmita/wallpaperapp","last_synced_at":"2026-06-20T10:01:04.798Z","repository":{"id":361742321,"uuid":"1255628363","full_name":"ariksasmita/WallpaperApp","owner":"ariksasmita","description":"A simple macOS app that displays a full-screen image behind all other windows. Perfect for managed Macs where you can't change the desktop wallpaper.","archived":false,"fork":false,"pushed_at":"2026-06-01T03:51:31.000Z","size":50,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T05:08:26.381Z","etag":null,"topics":["background-app","macos","multi-monitor","swift","wallpaper"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ariksasmita.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T03:04:46.000Z","updated_at":"2026-06-01T03:51:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ariksasmita/WallpaperApp","commit_stats":null,"previous_names":["ariksasmita/wallpaperapp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ariksasmita/WallpaperApp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ariksasmita%2FWallpaperApp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ariksasmita%2FWallpaperApp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ariksasmita%2FWallpaperApp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ariksasmita%2FWallpaperApp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ariksasmita","download_url":"https://codeload.github.com/ariksasmita/WallpaperApp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ariksasmita%2FWallpaperApp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34565244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["background-app","macos","multi-monitor","swift","wallpaper"],"created_at":"2026-06-20T10:01:02.437Z","updated_at":"2026-06-20T10:01:04.789Z","avatar_url":"https://github.com/ariksasmita.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WallpaperApp\n\n\u003cimg src=\"image-frame.svg\" width=\"100\" height=\"100\" alt=\"WallpaperApp Icon\"\u003e\n\n\u003e **A simple macOS app that displays a full-screen image behind all other windows.**\n\u003e\n\u003e Perfect for managed Macs where you can't change the desktop wallpaper.\n\n## 📖 About\n\n**WallpaperApp** was born out of frustration with managed MacBooks that lock down the desktop wallpaper setting. This lightweight background app creates a full-screen window that sits behind all other applications, effectively \"faking\" a custom wallpaper.\n\n### Why WallpaperApp?\n\n- 🏢 **Corporate Macs** often restrict wallpaper changes via MDM\n- 🎨 **Personalization** shouldn't be limited by IT policy\n- 🔒 **Privacy** - runs locally, no cloud, no tracking\n- 💡 **Simple** - just build, add your image, and run\n\n### How It Works\n\nInstead of changing the actual desktop wallpaper (which is often locked), WallpaperApp:\n\n1. Creates a borderless full-screen window on **each connected monitor**\n2. Sets the window level **below all other apps** but **above the desktop**\n3. Displays your chosen image with **fill scaling** (covers entire screen)\n4. Stays out of your way - **clicks pass through** to other apps\n5. Lives in the **menu bar** (🖼️) for easy quitting\n\n### Tech Stack\n\n- **Language:** Swift\n- **Framework:** Cocoa (AppKit)\n- **Build:** Native Swift compiler\n- **Icon:** Custom SVG → .icns conversion\n\n## 🎯 Features\n\n- ✅ Full-screen wallpaper behind all other apps\n- ✅ Multi-monitor support (shows on all connected screens)\n- ✅ Fill scaling (wallpaper fills screen completely)\n- ✅ Clicks pass through (doesn't interfere with other apps)\n- ✅ Menu bar icon for easy quitting\n- ✅ No dock icon (runs as background app)\n- ✅ Supports PNG, JPEG, JPG formats\n\n## 🚀 Quick Start\n\n1. **Build the app:**\n   ```bash\n   ./build.sh\n   ```\n\n2. **Add your wallpaper:**\n   ```bash\n   cp /path/to/your/wallpaper.jpg ~/Pictures/wallpaper.jpg\n   ```\n\n3. **Run it:**\n   ```bash\n   open ~/Applications/WallpaperApp.app\n   ```\n\n## 📦 Building\n\nThe build script:\n- Compiles the Swift code\n- Creates the app bundle\n- Adds the custom icon\n- Signs the app for macOS\n- Installs to `~/Applications/WallpaperApp.app`\n\n```bash\n./build.sh\n```\n\n## 🖼️ Adding Your Wallpaper\n\nPlace your image in `~/Pictures/` with one of these names:\n\n- `wallpaper.jpg` (recommended for photos)\n- `wallpaper.jpeg`\n- `wallpaper.png`\n\nThe app searches in order and uses the first one found.\n\n## 🎮 Usage\n\n### Running\n\n```bash\nopen ~/Applications/WallpaperApp.app\n```\n\n### Menu Bar Options\n\nClick the **🖼️ icon** in your menu bar to access:\n\n- **Select Wallpaper Image...** (⌘+O) - Open file picker to choose and auto-optimize a new wallpaper\n- **Add to login items** / **✓ Login at startup** - Toggle auto-start on login\n- **Quit WallpaperApp** (⌘+Q) - Close the app\n\n### Selecting Wallpaper via Menu\n\nThe easiest way to set your wallpaper:\n\n1. Click **🖼️** → **Select Wallpaper Image...**\n2. Choose any image (JPG, PNG, etc.)\n3. The app will:\n   - Detect your screen resolution\n   - Optimize the image to match\n   - Save it to `~/Pictures/wallpaper.png`\n   - Create a backup of your old wallpaper\n   - Automatically reload the wallpaper\n\n### Quitting\n\n- Click the **🖼️ icon** → \"Quit WallpaperApp\"\n- Or via Terminal: `pkill WallpaperApp`\n\n### After selecting a new wallpaper\n\nQuit and restart the app:\n\n```bash\npkill WallpaperApp \u0026\u0026 open ~/Applications/WallpaperApp.app\n```\n\n## 🎨 Tips\n\n- Use a high-resolution image that matches your screen resolution\n- The image scales to fill (may crop if aspect ratios differ)\n- Each monitor gets its own window with the same wallpaper\n- If no image is found, shows a black screen\n\n### Image Optimization for Lower Memory Usage\n\n**Memory usage depends on your image resolution!**\n\n- **Optimized image** (matches screen): ~110-180 MB\n- **Large image** (2x screen): ~340 MB\n- **Very large image** (4K+): 500+ MB\n\nTo optimize your wallpaper:\n\n```bash\n# Automatic optimization (included in repo)\n./optimize-wallpaper.sh ~/Pictures/wallpaper.jpg\n\n# Or manually with sips (built-in macOS tool)\nsips -z 1920 1080 ~/Pictures/wallpaper.jpg --out ~/Pictures/wallpaper_optimized.jpg\n```\n\n## 💻 Resource Usage\n\n**With optimized image (recommended):**\n- **Memory:** ~110-180 MB (~0.5% of 24GB RAM)\n- **CPU:** 0.0% when idle\n\n**With large image:**\n- **Memory:** ~340 MB (~1.4% of 24GB RAM)\n- **CPU:** 0.0% when idle\n\nThe app uses direct CALayer rendering and ImageIO for efficient image loading with on-the-fly downsampling.\n\n## 🔄 Auto-Start on Login\n\nTo automatically start on login:\n\n1. **System Settings** → **General** → **Login Items**\n2. Click **+** button\n3. Navigate to `~/Applications/WallpaperApp.app`\n4. Add it\n\nYour custom wallpaper will appear every time you log in! 🎨\n\n## 🛠️ Development\n\n### Requirements\n\n- macOS 10.15+\n- Xcode Command Line Tools (for Swift compiler)\n\n### Project Structure\n\n```\nWallpaperApp/\n├── WallpaperApp.swift    # Main app code\n├── Info.plist            # App configuration\n├── WallpaperApp.icns     # App icon\n├── image-frame.svg       # Icon source\n├── build.sh              # Build script\n├── .gitignore\n└── README.md\n```\n\n### Icon Customization\n\nTo change the app icon:\n\n1. Replace `image-frame.svg` with your own SVG\n2. Run the build script\n3. The icon will be automatically converted and applied\n\n## 📝 License\n\nMIT License - feel free to use and modify!\n\n## 🙏 Acknowledgments\n\n- Icon: [image-frame](https://www.svgrepo.com/svg/532476/image-frame) from SVG Repo\n\n---\n\nMade with ❤️ for managed Macs everywhere\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fariksasmita%2Fwallpaperapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fariksasmita%2Fwallpaperapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fariksasmita%2Fwallpaperapp/lists"}