A native Apple TV app for browsing your self-hosted Immich photo library with a beautiful, TV-optimized interface.
Tip
If you see "Data couldnt read because its missing", update Immich and try again: mensadilabs#67
- 🖼️ Photo Grid View: Browse all your photos in a responsive grid layout with infinite scrolling
- 👥 People Recognition: View and browse photos by people detected in your library
- 📁 Album Support: View and navigate through your Immich albums
- 🏷️ Tag Support with animated thubnails: Browse photos by tags (optional, configurable)
- 🎬 Slideshow Mode: Full-screen slideshow with optional clock overlay
- 👤 Multi-User Support: Multiple user accounts with easy switching
- 📊 EXIF Data: View detailed photo metadata including camera settings and location
- 🔒 Privacy First: Self-hosted solution with secure credential storage, no data sent to third parties
Untitled720p.mov
- Apple TV (4th generation or later)
- tvOS 15.0+
- Immich server running and accessible
- Network connectivity between Apple TV and Immich server
- Launch the app - You'll be prompted to sign in to your Immich server
- Enter server details - Server URL (e.g.,
https://your-immich-server.com), email, and password - Browse your photos - Navigate using the Apple TV remote or Siri Remote
Immich Gallery/
├── Models/
│ └── ImmichModels.swift # Data models for Immich API responses
├── Services/
│ ├── AuthenticationService.swift # User authentication and session management
│ ├── NetworkService.swift # Core HTTP networking layer
│ ├── AssetService.swift # Photo/video asset management
│ ├── AlbumService.swift # Album data handling
│ ├── PeopleService.swift # People recognition integration
│ ├── TagService.swift # Tag-based photo organization
│ └── ThumbnailCache.swift # Efficient image caching system
├── Views/
│ ├── AssetGridView.swift # Main photo grid interface
│ ├── FullScreenImageView.swift # Full-screen photo viewer
│ ├── SlideshowView.swift # Slideshow functionality
│ └── Settings/ # Configuration interfaces
├── Extensions/
│ └── DateFormatter+Extensions.swift
└── ContentView.swift # Main app coordinator
- SwiftUI: Modern declarative UI framework
- Async/Await: Modern Swift concurrency for network operations
- URLSession: HTTP networking with custom authentication
- UserDefaults: Secure credential storage with encryption
- Core Image: Image processing and thumbnail generation
- AVKit: Video playback support
- Immich REST API: Full integration with Immich server endpoints
- Authentication: Bearer token-based authentication with automatic refresh
- Caching Strategy: Multi-layer caching for thumbnails and metadata
- Error Handling: Comprehensive error boundaries and retry mechanisms
- Lazy Loading: Photos loaded on-demand as user scrolls
- Thumbnail Caching: Persistent cache with configurable size limits
- Memory Management: Efficient image loading with automatic cleanup
- Background Processing: Non-blocking API calls for smooth UI
- Credential Encryption: Secure storage of server credentials
- HTTPS Support: Encrypted communication with Immich server
- Token Validation: Automatic token refresh and validation
- No Telemetry: No data collection or external service communication
- Default Tab: Customizable startup tab (Photos, Albums, People, Tags)
- Slideshow Settings: Configurable timing and overlay options
- Cache Management: User-controlled cache size and cleanup
- Multi-User: Support for multiple Immich accounts
- Clone the repository
- Open
Immich Gallery.xcodeprojin Xcode - Select Apple TV target device
- Build and run
This project uses only system frameworks and has no external dependencies.
- Verify server URL includes protocol (
http://orhttps://) - Ensure Immich server is accessible from Apple TV network
- Check firewall settings and port configuration
- Monitor cache usage in Settings > Cache Management
- Clear cached data if storage is full
- Ensure stable network connection for optimal loading
