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

Open your Immich web interface
Click your profile picture → Account Settings → API Keys
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:3000 \
  -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`	`3000`	Internal server port (Docker maps externally via compose)

🎮 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

Open the frame URL in your tablet's browser (use a ?album= or ?person= URL for zero-touch)
Add to Home Screen for a full-screen app experience
Enable kiosk mode or guided access to lock to the app
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.1 — Fix port mapping (3030:3000 external:internal), fix URL param auto-launch not starting slideshow
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

5.8 KiB Raw Permalink Blame History