Odorou/README.md
remaster 6f244ef4a7 Versión Alfa — Odorou desktop pet app
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-13 18:39:16 -06:00

6.6 KiB
Raw Blame History

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<AnyView> — 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 <UUID>.<ext>)
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<AnyView>
    └── 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<Float>)
  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.