docs: add comprehensive README with features, setup, config, and architecture

2026-05-19 14:29:49 +10:00
parent 3b5ec44403
commit 8ad9f94304
1 changed files with 116 additions and 2 deletions
@@ -1,3 +1,117 @@
-# immich-frame
+# 🖼️ ImmichFrame

-A lightweight Docker web app that connects to Immich API and displays photos as a digital photo frame — perfect for old tablets and spare screens
+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
+- **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
+- **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
+
+## 🚀 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/immich-frame.git
+cd immich-frame
+```
+
+Edit `docker-compose.yml` and set your `IMMICH_URL` and `IMMICH_API_KEY`, then:
+
+```bash
+docker compose up -d
+```
+
+Open `http://your-server:3000` in a browser on your tablet/screen.
+
+### 3. Run with Docker directly
+
+```bash
+docker build -t immich-frame .
+docker run -d \
+  --name immich-frame \
+  -p 3000:3000 \
+  -e IMMICH_URL=http://your-immich-server:2283 \
+  -e IMMICH_API_KEY=your-api-key \
+  --restart unless-stopped \
+  immich-frame
+```
+
+## ⚙️ 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 |
+| `ALBUM_ID` | *(empty)* | Auto-start with specific album |
+| `SHOW_FAVORITES_ONLY` | `false` | Auto-start with favorites |
+| `PORT` | `3000` | 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
+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   │  ImmichFrame │   API   │    Immich     │
+│  (Tablet)    │◄───────►│   (Node.js)  │◄───────►│   Server     │
+└──────────────┘  :3000  └──────────────┘  :2283  └──────────────┘
+```
+
+The Node.js backend acts as a secure proxy — your Immich API key never reaches the browser.
+
+## 📋 Version History
+
+- **1.0.0** — Initial release: album browser, slideshow with crossfade, clock/date/EXIF overlays, touch & keyboard controls, Docker deployment
+
+## 📄 License
+
+MIT