From 6c26688244c3a0ed3d23e7927a730da96541d237 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Tue, 19 May 2026 16:16:27 +1000 Subject: [PATCH] =?UTF-8?q?docs:=20update=20README=20with=20v1.2.0=20featu?= =?UTF-8?q?res=20=E2=80=94=20URL=20params,=20person=20support,=20refresh,?= =?UTF-8?q?=20icon,=20port=203030?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index eb3283c..2d05891 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,8 @@ -# 🖼️ Frambe +# Frambe + +

+ Frambe +

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. @@ -6,6 +10,9 @@ A lightweight, self-contained Docker web application that connects to your [Immi - **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 @@ -14,7 +21,6 @@ A lightweight, self-contained Docker web application that connects to your [Immi - **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 @@ -30,8 +36,8 @@ A lightweight, self-contained Docker web application that connects to your [Immi ### 2. Run with Docker Compose ```bash -git clone https://gitea.hideawaygaming.com.au/jessikitty/immich-frame.git -cd immich-frame +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: @@ -40,7 +46,7 @@ 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. +Open `http://your-server:3030` in a browser on your tablet/screen. ### 3. Run with Docker directly @@ -48,13 +54,26 @@ Open `http://your-server:3000` in a browser on your tablet/screen. docker build -t frambe . docker run -d \ --name frambe \ - -p 3000:3000 \ + -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: @@ -72,9 +91,10 @@ All settings are via environment variables: | `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 | +| `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 @@ -92,7 +112,7 @@ All settings are via environment variables: ## 📱 Tablet Setup Tips -1. Open the frame URL in your tablet's browser +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 @@ -103,13 +123,14 @@ All settings are via environment variables: ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Browser │ HTTP │ Frambe │ API │ Immich │ │ (Tablet) │◄───────►│ (Node.js) │◄───────►│ Server │ -└──────────────┘ :3000 └──────────────┘ :2283 └──────────────┘ +└──────────────┘ :3030 └──────────────┘ :2283 └──────────────┘ ``` -The Node.js backend acts as a secure proxy — your Immich API key never reaches the browser. +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