Frambe

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
• Person / Face Support — Display photos of a specific person via Immich's face recognition
• URL-Based Zero-Touch Launch — Skip the setup screen entirely with query parameters
• Auto-Refresh — Periodically checks for new photos added to the source album/person
• 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
• 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/frambe.git
cd frambe

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

docker compose up -d

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

3. Run with Docker directly

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

🔗 Zero-Touch URL Parameters

Skip the setup screen entirely by passing query parameters. This is ideal for dedicated frames — just bookmark the URL on each tablet:

URL	What it shows
http://server:3030/?album=ALBUM_UUID	Photos from a specific album
http://server:3030/?person=PERSON_UUID	Photos of a specific person (face recognition)
http://server:3030/?favorites	Favorite photos only
http://server:3030/?random	Random photos from the library

You can find album and person UUIDs in Immich's web interface URL bar when viewing an album or person.

⚙️ 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
REFRESH_INTERVAL	300	Seconds between source refresh checks (new photos)
ALBUM_ID	(empty)	Auto-start with specific album (env-based)
SHOW_FAVORITES_ONLY	false	Auto-start with favorites (env-based)
PORT	3030	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 (use a ?album= or ?person= URL for zero-touch)
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   │    Frambe    │   API   │    Immich     │
│  (Tablet)    │◄───────►│   (Node.js)  │◄───────►│   Server     │
└──────────────┘  :3030  └──────────────┘  :2283  └──────────────┘

The Node.js backend acts as a secure proxy — your Immich API key never reaches the browser. The frontend periodically polls the backend for new photos so albums stay up to date without restarting.

📋 Version History

• 1.2.0 — URL params (?album=, ?person=, ?favorites, ?random), person/face support, periodic auto-refresh, app icon, default port changed to 3030
• 1.1.0 — Rebrand to Frambe
• 1.0.0 — Initial release: album browser, slideshow with crossfade, clock/date/EXIF overlays, touch & keyboard controls, Docker deployment

📄 License

MIT