🖼️ ImmichFrame

A lightweight, self-contained Docker web application that connects to your Immich server and displays photos in a beautiful full-screen slideshow — perfect for turning old tablets, spare screens, and Raspberry Pis into digital photo frames.

✨ Features

• Immich API Integration — Connects securely via API key (kept server-side)
• Album Browser — Select any album, random photos, or favorites only
• Smooth Crossfade — Double-buffered image transitions with configurable duration
• Background Blur — Blurred backdrop fills the space behind non-covering images
• Clock & Date Overlay — Always know the time at a glance
• EXIF Info — Shows photo location, date, and camera info
• Progress Bar — Subtle indicator of time until next photo
• Touch Controls — Tap left/right edges to navigate, centre to toggle overlay
• Keyboard Controls — Arrow keys, Space, F (fullscreen), I (info), Esc (exit)
• Screen Wake Lock — Prevents screen sleep on supported devices
• Auto-Start — Configure an album ID or favorites-only to skip the setup screen
• Responsive — Works on any screen size from phone to TV
• Older Device Friendly — Vanilla HTML/CSS/JS, no heavy frameworks
• Docker Containerised — Single container, minimal footprint

🚀 Quick Start

1. Get your Immich API Key

1. Open your Immich web interface
2. Click your profile picture → Account Settings → API Keys
3. Create a new key with asset.read and album.read permissions

2. Run with Docker Compose

git clone https://gitea.hideawaygaming.com.au/jessikitty/immich-frame.git
cd immich-frame

Edit docker-compose.yml and set your IMMICH_URL and IMMICH_API_KEY, then:

docker compose up -d

Open http://your-server:3000 in a browser on your tablet/screen.

3. Run with Docker directly

docker build -t immich-frame .
docker run -d \
  --name immich-frame \
  -p 3000:3000 \
  -e IMMICH_URL=http://your-immich-server:2283 \
  -e IMMICH_API_KEY=your-api-key \
  --restart unless-stopped \
  immich-frame

⚙️ Configuration

All settings are via environment variables:

Variable	Default	Description
IMMICH_URL	(required)	Your Immich server URL
IMMICH_API_KEY	(required)	Immich API key
SLIDESHOW_INTERVAL	30	Seconds between photos
TRANSITION_DURATION	2	Crossfade duration in seconds
IMAGE_FIT	contain	contain or cover
SHUFFLE	true	Randomise photo order
BACKGROUND_BLUR	true	Show blurred backdrop
SHOW_CLOCK	true	Display clock overlay
SHOW_DATE	true	Display date overlay
SHOW_EXIF	true	Display photo metadata
SHOW_PROGRESS	true	Display progress bar
ALBUM_ID	(empty)	Auto-start with specific album
SHOW_FAVORITES_ONLY	false	Auto-start with favorites
PORT	3000	Server port

🎮 Controls

Touch / Mouse

• Left 20% of screen — Previous photo
• Centre 60% — Toggle overlay (clock, info, close button)
• Right 20% — Next photo

Keyboard

• ← / → — Previous / Next photo
• Space — Next photo
• F — Toggle fullscreen
• I — Toggle info overlay
• Esc — Exit to album selection

📱 Tablet Setup Tips

1. Open the frame URL in your tablet's browser
2. Add to Home Screen for a full-screen app experience
3. Enable kiosk mode or guided access to lock to the app
4. Disable screen timeout in your device settings

🏗️ Architecture

┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│   Browser    │  HTTP   │  ImmichFrame │   API   │    Immich     │
│  (Tablet)    │◄───────►│   (Node.js)  │◄───────►│   Server     │
└──────────────┘  :3000  └──────────────┘  :2283  └──────────────┘

The Node.js backend acts as a secure proxy — your Immich API key never reaches the browser.

📋 Version History

• 1.0.0 — Initial release: album browser, slideshow with crossfade, clock/date/EXIF overlays, touch & keyboard controls, Docker deployment

📄 License

MIT