Immich-Integration für das Foto-Widget
1. Kontext & Ziel
Gladys wird bald ein Foto-Widget für das Dashboard (box.type = 'photo') haben, das
eine Diashow aus einer manuell eingegebenen Liste von URLs ({ url, caption }) anzeigt. Die Bilder werden
über einen Proxy-Server (GET /api/v1/dashboard/photo/proxy?url=) abgerufen, um remote
zugänglich zu bleiben (Gladys Plus).
Ziel: Dem Benutzer ermöglichen, diese Diashow automatisch von einem Immich-Server
(selbstgehostetes Fotomanagement) zu speisen.
Der Benutzer verbindet sein Immich einmal und wählt dann eine dynamische Quelle (ein Album,
oder seine Erinnerungen „an diesem Tag“); das Widget zeigt die entsprechenden Fotos an und
aktualisiert sich selbstständig.
Umfang v1
- Quellen: Album nach Wahl + Erinnerungen „an diesem Tag“
- Bildqualität: Vorschau (~1440px)
- Architektur: vollständiger Immich-Service (Konfigurationsseite + authentifizierter Proxy)
2. Die Immich-API — was sie ermöglicht
2.1 Authentifizierung
- Alle Anfragen enthalten den Header
x-api-key: <key>. - Der Schlüssel wird in Immich generiert: Account Settings → API Keys. Minimale benötigte
Berechtigungen:album.read,asset.read,memory.read. - Basis-URL = Adresse des Immich-Servers, z. B.
http://192.168.1.20:2283. Alle unten genannten
Pfade sind mit/apipräfixiert.
Strukturierender Punkt: Der aktuelle Proxy von Gladys (
dashboard.getPhoto.js) macht ein GET ohne
Header → er kann nicht mit Immich kommunizieren. Es wird also ein dedizierter Immich-Proxy
benötigt, derx-api-keyinjiziert und auf die konfigurierte Basis-URL verweist.
2.2 Auswahl welcher Fotos angezeigt werden sollen (die Quellen)
| Quelle | Endpunkt | Nützliche Antwort |
|---|---|---|
| Liste der Alben | GET /api/albums |
[{ id, albumName, assetCount, albumThumbnailAssetId, shared }] — dient zur Befüllung des Album-Auswahlmenüs |
| Inhalt eines Albums | GET /api/albums/{id} |
{ albumName, assets: [{ id, type, originalFileName, fileCreatedAt, exifInfo }] } |
| Erinnerungen „an diesem Tag“ | GET /api/memories |
[{ id, type:"on_this_day", memoryAt, data:{ year }, assets:[{ id, ... }] }] — eine Gruppe pro Jahr, das am gleichen Datum stattfand |
2.3 Abrufen der Bilddatei eines Assets
Jedes Foto ist durch eine UUID asset.id identifiziert. Drei Varianten:
| Variante | Endpunkt | Verwendung |
|---|---|---|
Vorschau (~1440px)  v1 |
GET /api/assets/{id}/thumbnail?size=preview |
Guter Kompromiss aus Qualität und Größe für eine Diashow |
| Miniaturansicht | GET /api/assets/{id}/thumbnail?size=thumbnail |
Kleine Miniaturansicht (Zeitleiste) |
| Original | GET /api/assets/{id}/original |
Maximale Qualität, potenziell große Dateien (>5 MB) |
Antwort = binärer Bildstrom image/*. Der Immich-Proxy konvertiert ihn in das bereits vom
Widget erwartete Format: "<contentType>;base64,<data>".
2.4 Asset-Felder, die für die Bildunterschrift genutzt werden können
originalFileName, fileCreatedAt / localDateTime, und exifInfo (description, city,
dateTimeOriginal). Ermöglicht die automatische Generierung einer Bildunterschrift (z. B. „Rom — 12. August 2019“).
3. Erwartetes funktionales Verhalten
3.1 Verbindung der Integration (einmalig)
- Neue Karte Immich in der Liste der Integrationen.
- Konfigurationsseite, die Server-URL + API-Schlüssel anfordert.
- Button „Verbindung testen“ → ruft
GET /api/albumsauf, um URL + Schlüssel zu validieren, und
zeigt eine klare Fehlermeldung an, falls fehlgeschlagen (URL nicht erreichbar, 401 ungültiger Schlüssel).
3.2 Konfiguration des Widgets (durch den Benutzer, beim Bearbeiten des Dashboards)
Das Foto-Widget erhält eine Auswahl der Quellenart:
- Manuelle URLs — aktuelles Verhalten, unverändert (volle Rückwärtskompatibilität).
- Immich — Album — ein Dropdown-Menü listet die Alben (über
GET /api/albums) auf; der
Benutzer wählt eines aus. - Immich — Erinnerungen — zeigt die Fotos an, die von
GET /api/memorieszurückgegeben werden
(„vor X Jahren, an diesem Tag“).
Bestehende Optionen bleiben erhalten und sind auf alle Modi anwendbar: Einrahmen (cover/contain),
Intervall des Durchlaufens, Anzeige/Ausblenden der Bildunterschriften, Titel des Widgets.
Für die Immich-Modi kann die Bildunterschrift automatisch generiert werden aus den Metadaten des Assets (Datum + Ort) statt manuell eingegeben.
3.3 Anzeige (Laufzeit)
- Beim Öffnen löst das Widget die Immich-Quelle in Liste von Assets (Album oder Erinnerungen) auf,
und zeigt dann jedes Bild als Vorschau über den authentifizierten Immich-Proxy an. - Diashow: Automatisches Durchlaufen gemäß dem Intervall, Vorwärts-/Rückwärtsnavigation und
Indikatoren (bereits inPhotoBox.jsxvorhanden). - Bildcache im Speicher + Vorladen des nächsten Bildes (bereits vorhanden), unverändert.
- Aktualisierung der Liste: Die Liste der Assets (insbesondere „Erinnerungen“, die sich täglich ändern) wird
periodisch / beim Einbetten des Widgets erneut abgefragt, zu entscheiden.
3.4 Grenzfälle & funktionale Entscheidungen zur Validierung
- Leeres Album / leere Erinnerungen des Tages → expliziter Leerzustand (Nachricht), kein Fehler.
- Videos in einem Album (
asset.type = VIDEO) → gefiltert (nurIMAGEbeibehalten) oder
Anzeige ihres Posters? → zu entscheiden (Vorschlag: Videos in v1 ignorieren). - Große Alben → Begrenzung der Anzahl der geladenen Assets (z. B. Obergrenze + eventuelle
zufällige Reihenfolge), um Tausende von Einträgen zu vermeiden? → zu entscheiden. - Anzeigereihenfolge: Chronologisch (nach
fileCreatedAt), umgekehrt oder zufällig?
→ zu entscheiden (Vorschlag: zuerst die neuesten). - 5-MB-Grenze des Proxys: Die Vorschau bleibt deutlich unter der Grenze, daher beibehalten. Nur
überprüfen, wenn wir später den Modus „Original“ oder Video hinzufügen.
4. API-Quellen (Referenz)
- Immich-API-Dokumentation: API | Immich · Endpunkte: Immich - API Documentation
- Alben:
getAllAlbums,getAlbumInfo· Erinnerungen:searchMemories(GET /api/memories) - Bild:
viewAsset/GET /api/assets/{id}/thumbnail?size=preview - Zufällig (Referenz):
POST /api/search/random· Metadaten:POST /api/search/metadata
5. Offene Fragen vor der Implementierung
- Videos in Alben: Ignorieren oder ein Poster anzeigen? (Vorschlag: Ignorieren in v1)
- Anzeigereihenfolge: Umgekehrt chronologisch, chronologisch oder zufällig?
- Obergrenze der Anzahl der Fotos pro Quelle (Performance)?
- Bildunterschrift: Automatisch generiert (Datum + Ort) standardmäßig oder keine Bildunterschrift für Immich?
