From 90baa6130f3b1fc0014d64e6ad2b1654bd4769b4 Mon Sep 17 00:00:00 2001 From: Erik Thiele Date: Sat, 29 Aug 2026 19:52:58 +0200 Subject: [PATCH] docs: Zeitsteuerung in README und Hilfeseite dokumentieren README: - Feature-Liste und Routen-Tabelle ergaenzt (POST /admin//update-playlist-item/) - Neuer Abschnitt "Playlist-Eintraege" mit dem Dict-Format fuer URL- und Datei-Eintraege sowie dem schedule-Objekt: Felder, Beispiele und die Verhaltensregeln (nur Uhrzeit bei daily/weekly, days nur bei weekly, Fenster ueber Mitternacht gehoert zum Starttag, unlesbare Angaben blenden nicht aus, Aktiv-Zustand fliesst in den Playlist-Hash ein) - Helper-Liste aktualisiert: playlist_item_enabled() gibt es nicht mehr, dafuer is_item_active(), _schedule_time(), _window_start_date(), _in_validity_range() und der Filter schedule_text() Hilfeseite (/admin/help): - Neuer Abschnitt "Zeitsteuerung" mit Modus-Tabelle, Beispielen und den Punkten, ueber die man sonst stolpert - Playlist-Abschnitt: Edit-Button gilt jetzt fuer alle Eintragstypen, "Zeit"-Badge erklaert - Priority-Abschnitt: Zeitsteuerung steht dort ebenfalls zur Verfuegung Co-Authored-By: Claude Opus 5 --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++-- templates/help.html | 57 +++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 83fd164..fd333d5 100755 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ Browserbasiertes Digital-Signage-System für interne Info-Screens. - **Admin Dashboard**: `/admin/dashboard` – Statistiken (Sites, Screens, User, Admins, Superuser) mit Sparkline-Charts + Trendanzeige, Aktivitätsverlauf - **Aktivitätsverlauf**: Alle Erstell-/Lösch-/Änderungsaktionen sowie Login/Logout werden in `history.json` protokolliert und im Dashboard angezeigt - Tab-basierte Admin-UI pro Screen: Playlist, Einstellungen, Aktionen, Digital Voice Agent, Medien, Info (Tabler Tabs) +- **Zeitsteuerung**: Pro Playlist-Eintrag (URL *und* Datei, auch in der Priority-Playlist) ein Zeitfenster festlegen – einmalig (Datum + Uhrzeit), täglich oder wöchentlich (Uhrzeit + optionaler Gültigkeitszeitraum, wöchentlich zusätzlich mit Wochentagen). Fenster über Mitternacht werden unterstützt. Ein "Zeit"-Badge in der Playlist-Zeile zeigt die Einstellung im Tooltip - **Query-Parameter-Passthrough**: Per Player-URL übergebene Query-Parameter (z. B. `/player/stuttgart/lobby?customer=acme`) können pro Playlist-URL im Edit-Modal aktiviert werden – standardmäßig aus. Link-Icon in der Playlist-Zeile zeigt Status (an/aus) an. - Priority-Seite ebenfalls mit Tabs: Playlist und Medien - Dark Mode (localStorage-persistiert) @@ -194,6 +195,7 @@ Server läuft auf `http://localhost:5005` (gunicorn mit 4 Workern, non-root User | `POST /admin//add-url/` | URL zur Playlist hinzufügen | | `POST /admin//delete//` | Datei löschen | | `POST /admin//playlist/` | Playlist-Reihenfolge speichern (JSON) | +| `POST /admin//update-playlist-item/` | Einzelnen Playlist-Eintrag ändern: URL, Zoom, Passthrough, Zeitsteuerung (JSON) | | `POST /admin//delete-screen/` | Screen + Medien löschen | | `GET /admin//add-screen?name=` | Neuen Screen anlegen | | `GET /add-site?name=` | Neuen Standort anlegen | @@ -404,7 +406,7 @@ OPENAI_API_KEY=sk-... | Feld | Typ | Beschreibung | |------|-----|-------------| -| `playlist` | Array | Playlist-Einträge (Strings oder Dicts mit `url`/`zoom`) | +| `playlist` | Array | Playlist-Einträge (Strings oder Dicts, siehe [Playlist-Einträge](#playlist-eintraege)) | | `interval` | int | Anzeige-Intervall in Sekunden | | `show_images` | bool | Bilder anzeigen | | `show_videos` | bool | Videos anzeigen | @@ -422,6 +424,64 @@ OPENAI_API_KEY=sk-... | `voice_agent_target` | string | `"overlay"` (iframe) oder `"redirect"` | | `voice_agent_position` | string | Position des Buttons: `top-left`, `top-center`, `top-right`, `middle-left`, `middle-center`, `middle-right`, `bottom-left`, `bottom-center`, `bottom-right` | + +## Playlist-Einträge + +Ein Eintrag ist entweder ein String (Dateiname oder URL, Altbestand) oder ein Dict: + +```jsonc +// URL-Eintrag +{ + "url": "https://example.com", + "zoom": 1.0, // Zoom-Faktor im Player + "enabled": true, // Checkbox in der Playlist + "passthrough_params": false, // Query-Parameter der Player-URL durchreichen + "schedule": { ... } // optional, siehe unten +} + +// Datei-Eintrag +{ + "name": "bild.jpg", + "enabled": true, + "schedule": { ... } // optional +} +``` + +### Zeitsteuerung (`schedule`) + +Optional pro Eintrag. Ohne `schedule` läuft der Eintrag immer (sofern `enabled`). + +| Feld | Typ | Beschreibung | +|------|-----|-------------| +| `mode` | string | `"once"`, `"daily"` oder `"weekly"` | +| `start` / `end` | string | Bei `once` voller Zeitstempel (`"2026-09-10T08:00"`), bei `daily`/`weekly` nur die Uhrzeit (`"08:00"`) | +| `days` | Array | Nur bei `weekly`: Wochentage als Strings, `"0"` = Montag … `"6"` = Sonntag | +| `valid_from` | string | Optional, nur bei `daily`/`weekly`: Datum (`"2026-09-10"`), ab dem das Fenster gilt – inklusiv | +| `valid_until` | string | Optional, nur bei `daily`/`weekly`: Datum, bis zu dem das Fenster gilt – inklusiv | + +```jsonc +// Täglich 08:00–12:00, nur vom 10.09. bis 20.09.2026 +{ "mode": "daily", "start": "08:00", "end": "12:00", + "valid_from": "2026-09-10", "valid_until": "2026-09-20" } + +// Mo/Mi/Fr von 09:00 bis 17:00, unbefristet +{ "mode": "weekly", "start": "09:00", "end": "17:00", "days": ["0", "2", "4"] } + +// Einmalig, durchgehend über mehrere Tage +{ "mode": "once", "start": "2026-09-10T08:00", "end": "2026-09-20T12:00" } +``` + +**Verhaltensregeln:** + +- Bei `daily` und `weekly` zählt **nur die Uhrzeit** von `start`/`end`. Ein Gültigkeitszeitraum wird über `valid_from`/`valid_until` gesetzt, nicht über den Datumsanteil. +- Bei `daily` sind **alle Wochentage** gemeint; `days` wird in diesem Modus nicht ausgewertet. +- Ist `start` > `end`, läuft das Fenster **über Mitternacht** (z. B. `22:00`–`02:00`). Ein solches Fenster gehört zum Wochentag bzw. Gültigkeitstag seines **Starts**: „Mi 22:00–02:00" läuft Mittwochabend bis Donnerstagfrüh. +- Unlesbare oder unvollständige Zeitangaben blenden den Eintrag **nicht** aus – ein Konfigurationsfehler soll nicht dazu führen, dass stillschweigend nichts mehr läuft. +- `_schedule_time()` liest neben `"08:00"` auch volle ISO-Zeitstempel, damit Einträge aus älteren Versionen unverändert weiterlaufen. +- Der Aktiv-Zustand fliesst in `/playlist///hash` ein, damit der Player beim Öffnen und Schliessen eines Zeitfensters von selbst neu lädt. + +--- + ## Helper-Funktionen (`app.py`) - `load_config()` / `save_config()` – JSON lesen/schreiben @@ -430,7 +490,11 @@ OPENAI_API_KEY=sk-... - `is_url(item)` – prüft ob Item eine URL ist - `normalize_url(item)` – normalisiert URL-Item zu `{"url", "zoom"}` - `playlist_item_name(item)` – Name aus String oder Dict extrahieren -- `playlist_item_enabled(item)` – Enabled-Status prüfen +- `is_item_active(item)` – prüft `enabled` **und** die Zeitsteuerung +- `_schedule_time(value)` – Uhrzeit aus `"HH:MM"` oder vollem ISO-Zeitstempel lesen +- `_window_start_date(now, start, end)` – Kalendertag, an dem das laufende Zeitfenster begann (`None` = ausserhalb) +- `_in_validity_range(schedule, day)` – optionalen Gültigkeitszeitraum prüfen +- `schedule_text(schedule)` – Jinja-Filter: Klartext einer Zeitsteuerung für Tooltips - `load_priority_files()` – Priority-Playlist + Dateien laden - `prio_redirect(site)` – Redirect-Pfad zur Priority-Seite - `get_background_url(site)` – URL zum benutzerdefinierten Hintergrundbild oder `None` diff --git a/templates/help.html b/templates/help.html index 09d8081..bcd8652 100644 --- a/templates/help.html +++ b/templates/help.html @@ -51,6 +51,7 @@ Standort Screen Playlist + Zeitsteuerung Priority Action Button Voice Agent @@ -105,12 +106,67 @@
  • Sortieren: Per Drag & Drop die Reihenfolge der Playlist-Einträge ändern (Ziehgriff links).
  • Deaktivieren: Mit der Checkbox einzelne Einträge temporär ausblenden.
  • Löschen: Über den roten Papierkorb-Button.
    • +
  • Bearbeiten: Der Edit-Button öffnet einen Dialog. Bei URLs lassen sich dort Adresse, Zoom, Query-Parameter-Passthrough und Zeitsteuerung ändern; bei Bildern, Videos und HTML-Seiten die Zeitsteuerung.
    • +
  • Zeitsteuerung: Einträge können nur zu bestimmten Zeiten laufen – siehe Zeitsteuerung. Ein Badge Zeit in der Playlist-Zeile zeigt an, dass ein Eintrag zeitgesteuert ist; der Tooltip nennt die Einstellung im Klartext.
  • Query-Parameter-Passthrough: Per URL-Edit-Button (Stift-Icon) im Playlist-Eintrag kann pro URL gesteuert werden, ob Query-Parameter von der Player-URL an die Playlist-URL übergeben werden. Standardmäßig aus – Checkbox "Query-Parameter an diese URL übergeben" aktivieren wenn gewünscht. Ein Link-Icon in der Playlist-Zeile zeigt den Status: = an, = aus.

    • Änderungen an der Playlist werden automatisch gespeichert. Der Player lädt die Seite automatisch neu (via Hash-Prüfung).

    +
    +

    Zeitsteuerung

    +
    +

    Jeder Playlist-Eintrag – URL, Bild, Video oder HTML-Seite – kann nur zu bestimmten Zeiten laufen. Das gilt für die Playlist eines Screens genauso wie für die Priority-Playlist.

    + +

    Einstellen: beim Anlegen im Tab "Medien" unter Zeitsteuerung, oder nachträglich über den Edit-Button des Eintrags. Häkchen bei "Zeitgesteuerte Wiedergabe" setzen und einen Modus wählen:

    + + + + + + + + + + + + + + + + + + + + + + +
    ModusBedeutungFelder
    EinmaligLäuft einmal in einem zusammenhängenden Zeitraum – auch über mehrere Tage am Stück.Start und Ende jeweils mit Datum und Uhrzeit
    TäglichLäuft jeden Tag im selben Zeitfenster.Von / Bis als Uhrzeit, optional "Gültig von / bis"
    WöchentlichWie täglich, aber nur an den angehakten Wochentagen.Von / Bis als Uhrzeit, Wochentage, optional "Gültig von / bis"
    + +

    Gültig von / bis ist optional und begrenzt, an welchen Tagen das Zeitfenster überhaupt greift. Beide Grenzen lassen sich einzeln setzen und zählen den genannten Tag mit. Ohne Angabe läuft die Wiedergabe unbefristet.

    + +

    Beispiele:

    +
      +
    • Täglich, 08:00 bis 12:00, ohne Gültigkeitszeitraum → jeden Vormittag, unbefristet.
      • +
    • Täglich, 08:00 bis 12:00, gültig vom 10.09. bis 20.09. → nur an diesen elf Tagen.
      • +
    • Wöchentlich, 09:00 bis 17:00, Mo/Mi/Fr → nur an diesen drei Tagen während der Bürozeit.
      • +
    • Täglich, 22:00 bis 02:00 → abends bis in die Nacht hinein, über Mitternacht hinweg.
      • +
    + +

    Gut zu wissen:

    +
      +
    • Bei "Täglich" und "Wöchentlich" zählt nur die Uhrzeit – ein Datum wird ausschliesslich unter "Gültig von / bis" angegeben.
      • +
    • Bei "Täglich" gilt automatisch jeder Wochentag; die Auswahl der Wochentage erscheint deshalb nur bei "Wöchentlich".
      • +
    • Ein Fenster über Mitternacht gehört zum Tag seines Starts: "Mi 22:00–02:00" läuft Mittwochabend bis Donnerstagfrüh.
      • +
    • Die Checkbox links im Playlist-Eintrag wirkt weiterhin unabhängig davon – ein deaktivierter Eintrag läuft auch innerhalb seines Zeitfensters nicht.
      • +
    • Der Player merkt von selbst, wenn ein Zeitfenster beginnt oder endet, und lädt neu. Ein manueller Eingriff am Screen ist nicht nötig.
      • +
    + +

    Es gilt die Uhrzeit des Servers, nicht die des Players.

    +
    +
    +

    Priority-Playlist

    @@ -119,6 +175,7 @@
  • Aufruf über /admin/<standort>/priority
  • Globale Medien und URLs verwalten, ebenfalls per Drag & Drop
  • Priority muss in der Konfiguration aktiviert sein (config.json → priority.enabled)
    • +
  • Die Zeitsteuerung steht hier genauso zur Verfügung wie in den Screen-Playlists