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
• Admin Dashboard — Real-time WebSocket-based control panel for all connected frames
• Admin Authentication — Optional username/password login to protect the admin dashboard
• REST API with Token Auth — Control frames from Home Assistant, scripts, or external tools
• 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:3000 \
  -e IMMICH_URL=http://your-immich-server:2283 \
  -e IMMICH_API_KEY=your-api-key \
  --restart unless-stopped \
  frambe

🔑 Authentication

Admin Dashboard Login

Protect the admin dashboard with a username and password:

environment:
  - ADMIN_USERNAME=admin
  - ADMIN_PASSWORD=your-secure-password

When ADMIN_PASSWORD is set, accessing /admin requires signing in. When not set, the dashboard is open (useful for trusted local networks).

API Token for External Access

Enable token-authenticated REST API access for Home Assistant, scripts, or other external tools:

environment:
  - FRAMBE_API_TOKEN=your-secret-token-here

🔌 REST API

When FRAMBE_API_TOKEN is configured, the following endpoints are available:

List Connected Frames

GET /api/clients
Authorization: Bearer your-secret-token-here

Returns all connected frame clients with their status, IP, name, and config.

Send Command to a Frame

POST /api/clients/:id/command
Authorization: Bearer your-secret-token-here
Content-Type: application/json

{
  "action": "next",
  "payload": {}
}

Available actions: start, stop, next, prev, sleep, wake, refresh, setSource, setConfig

Home Assistant Example

rest_command:
  frambe_next_photo:
    url: "http://frambe-server:3030/api/clients/{{ client_id }}/command"
    method: POST
    headers:
      Authorization: "Bearer your-secret-token-here"
      Content-Type: "application/json"
    payload: '{"action": "next"}'

Authentication can also be provided via x-api-token header or ?token= query parameter.

🔗 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)
ADMIN_USERNAME	admin	Admin dashboard login username
ADMIN_PASSWORD	(empty)	Admin dashboard password (leave empty to disable auth)
FRAMBE_API_TOKEN	(empty)	API token for REST endpoint access (leave empty for open access)
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

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

📋 Version History

• 1.4.0 — Admin login (username/password), API token auth for external access (Home Assistant), REST endpoints (GET /api/clients, POST /api/clients/:id/command)
• 1.3.0 — Admin dashboard with real-time WebSocket frame management, video support, person/face support
• 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