# Odorou A macOS desktop-pet app that displays animated GIFs and WebP images as transparent floating windows on your screen. Pets live on top of (or behind) your other windows, snap to screen edges, and persist across relaunches. --- ## Features - **Import** GIFs and WebP via file picker, drag & drop onto the library window, or direct URL download - **Animated playback** with pause/resume, preserving frame timing - **Transparent borderless windows** — pets float over all apps with no chrome - **Drag freely** — snap to any screen edge with automatic rotation (head always faces inward) - **Per-pet controls** via right-click menu: - Resize ±5% (`sizeRatio` 5 %–50 % of the shortest screen dimension) - Opacity ±10 % (10 %–100 %) - Move to a specific monitor (multi-display) - **Global controls** in the menu bar: - Pause / resume all animations - Lock / unlock pet positions - Wallpaper mode (send pets behind all windows) - Remove individual pets or all at once - **Background removal** — one-click tool strips solid-color backgrounds from GIFs using corner color sampling and per-frame pixel comparison - **Library management**: rename (double-click name), search, delete - **Preset export / import** — save and restore the full pet layout as a JSON file - **Launch at login** via `SMAppService` - **Local notifications** when a new pet is added - **First-launch onboarding** overlay (dismissed once, stored in `@AppStorage`) --- ## Architecture ``` OdorouApp (SwiftUI App + MenuBarExtra) ├── AppDelegate NSApplicationDelegate — activation policy, window lifecycle ├── ContentView Main library window (NavigationSplitView) │ ├── Sidebar Active pets list + global size slider │ ├── LibraryGrid GIFLibraryCard grid (filterable) │ └── Toolbar Edge picker, URL import, settings popover │ ├── GIFLibraryManager @Observable singleton — library CRUD + file persistence ├── GIFLibraryCard Card view — thumbnail, hover overlay (wand/trash), inline rename ├── GIFPlayerView NSViewRepresentable wrapping NSImageView for GIF/WebP playback │ ├── PetWindowManager @Observable singleton — pet lifecycle, global controls, persistence ├── PetWindowController NSWindowController per pet — owns the transparent NSPanel │ ├── DraggableHostingView NSHostingView — drag, snap, hit-test, cursor, menus │ └── PetOverlayView SwiftUI view rendered inside each pet window │ ├── BackgroundRemover Removes solid backgrounds from GIFs (CoreGraphics + simd) └── Models GIFEntry, ActivePet, GlobalSettings, ScreenEdge ``` --- ## Key Files | File | Responsibility | |---|---| | `OdorouApp.swift` | App entry point, `MenuBarExtra`, `AppDelegate` | | `ContentView.swift` | Library window UI, URL import, onboarding overlay | | `GIFLibraryManager.swift` | Import, delete, rename GIFs; JSON persistence | | `GIFPlayerView.swift` | `NSImageView` wrapper that animates GIF/WebP frames | | `PetWindowManager.swift` | Create/remove/update pet windows; global state | | `PetWindowController.swift` | `NSPanel` + `DraggableHostingView` per pet | | `PetOverlayView.swift` | Renders `GIFPlayerView` with `rotationEffect` inside each pet panel | | `BackgroundRemover.swift` | Frame-by-frame alpha keying based on corner color sampling | | `Models.swift` | `GIFEntry`, `ActivePet`, `GlobalSettings`, `ScreenEdge` | --- ## Data Persistence All data lives under `~/Library/Application Support/Odorou/`: | Path | Content | |---|---| | `gifs/` | Imported GIF / WebP files (renamed to `.`) | | `library.json` | `[GIFEntry]` — id, filename, display name, date added | | `active_pets.json` | `[ActivePet]` — position, size ratio, rotation, opacity, screen index | | `settings.json` | `GlobalSettings` — isPaused, isLocked, isWallpaperMode | `@AppStorage("hasSeenOnboarding")` in `UserDefaults` controls first-launch onboarding. --- ## Pet Window Internals Each pet is a **square** `NSPanel` sized to `sizeRatio × min(screenWidth, screenHeight)`: ``` NSPanel (PetPanel) └── DraggableHostingView : NSHostingView └── PetOverlayView (SwiftUI) └── GIFPlayerView .rotationEffect(.degrees(rotation)) .frame(maxWidth: .infinity, maxHeight: .infinity) ``` **Why square windows?** SwiftUI's `.rotationEffect` is cosmetic — it rotates rendering but not layout bounds. A square window ensures the GIF can be displayed at any rotation angle (0°, 90°, 180°, 270°) without clipping, with `NSImageView.scaleProportionallyUpOrDown` inscribing the image correctly. **Rotation convention (SwiftUI CW, Y-down):** | Edge | Degrees | Head direction | |---|---|---| | Bottom | 0° | Up (12pm) | | Top | 180° | Down (6pm) | | Left | 90° | Right (3pm) | | Right | 270° | Left (9pm) | **Hit testing** uses `displayedImageRect` — the aspect-ratio-correct image bounds inside the square window, with dimensions transposed for 90°/270° rotations — so clicks in the transparent letterbox/pillarbox areas pass through to windows below. --- ## Snap to Edge On `mouseUp`, `snapToEdgeIfNeeded()` fires if any window edge is within 80 pt of the screen's `visibleFrame`. The closest edge wins; the window is repositioned flush and the pet rotates to face inward. Both axes are clamped so the pet stays fully on screen. --- ## Background Removal `BackgroundRemover.removeBackground(from:tolerance:)`: 1. Samples the four corners of frame 0 to determine background color (as `SIMD3`) 2. If all corners agree within a threshold, uses the average; otherwise uses the top-left corner 3. For each frame, pixels within `tolerance` Euclidean distance of the background color are set fully transparent (`alpha = 0`) 4. Writes the result to a temp file then atomically replaces the source via `FileManager.replaceItemAt` Default `tolerance` is `0.20`, which works well for solid anime-style backgrounds. --- ## Entitlements | Entitlement | Reason | |---|---| | `com.apple.security.app-sandbox` | App is sandboxed | | `com.apple.security.network.client` | URL import (download GIFs from arbitrary URLs) | | `com.apple.security.files.user-selected.read-only` | File importer (`fileImporter` modifier) | --- ## Requirements - macOS 15+ (uses `@Observable`, `ContentUnavailableView`, `MenuBarExtra`) - Xcode 16+ - Swift 5.10+ --- ## Build & Run Open `Odorou.xcodeproj` in Xcode and press **⌘R**. No external dependencies — all frameworks are system-provided. The app runs as a **menu bar accessory** (no Dock icon at startup). Click the menu bar icon to show the library window.