frambe/README.md

# Frambe

<p align="center">
  <img src="public/img/icon.png" alt="Frambe" width="180">
</p>

A lightweight, self-contained Docker web application that connects to your [Immich](https://immich.app/) 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

```bash
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:

```bash
docker compose up -d
```

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

### 3. Run with Docker directly

```bash
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

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.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