rinkplanner/docs/sync.md
torsten 74d9d6b61f feat: Cloud-Sync über Dropbox und Google Drive
- FTP-Sync durch Cloud-Backends ersetzt (Dropbox, Google Drive)
- OAuth-Flow mit nutzereigenen Tokens und App-Key-Konfiguration
- Zeit-Tooltips für Timeline-Labels und Abschnittsbanner beim Playback
- Tests, Build-Konfiguration und Doku aktualisiert
2026-11-09 06:25:21 +01:00

9.2 KiB
Raw Blame History

Kür-Sync über Cloud-Speicher

Der Abgleich zwischen Desktop und Tablet läuft manuell über den eigenen Cloud-Speicher des Nutzers: Google Drive oder Dropbox. Es gibt kein Konto auf einem Rinkplanner-Server. Jeder Nutzer verbindet sein eigenes Konto; die App speichert nur den Refresh-Token lokal auf dem Gerät.

Einrichten

  1. Auf beiden Geräten: Datei → Sync-Einstellungen…
  2. Anbieter wählen: Dropbox oder Google Drive.
  3. Verbinden… drücken und im Browser mit dem eigenen Konto anmelden:
    • Google Drive: Die App zeigt einen Code und öffnet die Google-Anmeldeseite. Nach der Bestätigung im Browser schließt sich der Dialog automatisch.
    • Dropbox: Die App öffnet die Dropbox-Seite. Den dort angezeigten Code in das Feld einfügen und Verbinden drücken.
  4. Cloud-Ordner festlegen. Bei Dropbox ist das standardmäßig der App-Ordner selbst (Apps/<App-Name>); bei Google Drive legt die App standardmäßig den Ordner Rinkplanner an. Ein leerer Eintrag bedeutet „Cloud-Hauptordner des Anbieters“.
  5. Speichern.

Danach Datei → Jetzt synchronisieren.

Auf dem Tablet muss das Konto ebenfalls einmal verbunden werden. Beide Geräte können dasselbe Google-/Dropbox-Konto verwenden; der Abgleich läuft über den gemeinsamen Cloud-Ordner.

Was passiert

  • Jede Kür liegt als .json unter user://routines/ und wird 1:1 in den Cloud-Ordner gespiegelt (flach, keine Unterordner). Gehört eine Musikdatei zur Kür (.mp3, .ogg, .wav), liegt sie im selben Ordner und wird mit denselben Regeln hoch- und heruntergeladen. Legacy-.tres-Dateien werden weiterhin mit synchronisiert, damit bestehende Installationen ihre Cloud-Kopien nicht verlieren; neue Speicherungen schreiben .json. Beim Laden wird eine .tres vor dem ResourceLoader gegen eine Whitelist geprüft (nur Modellskripte, kein eingebettetes GDScript).
  • Der Sync vergleicht pro Datei den letzten gemeinsamen Stand (user://sync_state.cfg) mit den aktuellen Zeitstempeln:
Lage Aktion
nur lokal, noch nie synchronisiert hochladen
nur in der Cloud herunterladen
seit dem letzten Sync nur lokal geändert hochladen
seit dem letzten Sync nur in der Cloud geändert herunterladen
beidseitig geändert (seit dem letzten Sync) Konflikt: lokale Fassung bleibt Hauptdatei, Cloud-Fassung kommt als (Server …)-Kopie dazu
Datei auf einer Seite gelöscht nichts tun (keine Löschweitergabe)
erster Sync, Datei auf beiden Seiten Cloud übernimmt: Cloud-Fassung wird Hauptdatei, lokale Fassung bleibt als (Lokal …)-Kopie

Wie kommt eine Kür vom Desktop aufs Tablet?

  1. Auf dem Desktop die Kür speichern (Datei → Speichern) und synchronisieren.
  2. Auf dem Tablet zuerst synchronisieren, dann Datei → Öffnen. Die Kür wird heruntergeladen und erscheint in der Liste.

Wichtig: Der Abgleich ordnet Dateien über den Dateinamen zu (der aus dem Kür-Titel entsteht). Eine Kür mit demselben Namen auf beiden Geräten ist kein „Update“, sondern eine Kollision:

  • Erster Sync einer Datei auf beiden Seiten (kein gemeinsamer Stand): Die Cloud-Fassung übernimmt den Namen, die lokale Fassung bleibt als name (Lokal JJJJ-MM-TT HHMM).json daneben. So bekommt ein neues Gerät die gemeinsame Version, ohne die lokale Arbeit zu verlieren.
  • Beide Seiten seit dem letzten Sync geändert: Die lokale Fassung bleibt Hauptdatei, die Cloud-Fassung kommt als name (Server JJJJ-MM-TT HHMM).json dazu. Beim nächsten Sync wird diese Kopie als neue Kür hochgeladen. Zusammenführen musst du selbst. Die Kopien behalten die Endung der Ausgangsdatei; bei Legacy-.tres entstehen also weiterhin .tres-Kopien.

Wenn du auf dem Tablet also eine leere „Testkür1“ anlegst, obwohl es die Desktop-Version schon gibt, hast du nach dem Sync zwei Dateien: die Desktop-Version unter dem normalen Namen und deine leere Fassung als testkür1 (Lokal …).json. Besser: erst synchronisieren, dann die vorhandene Kür öffnen und bearbeiten.

  • Vor dem Sync wird eine geänderte, bereits gespeicherte Kür automatisch gespeichert. Eine noch nie gespeicherte Kür öffnet zuerst „Speichern unter“.
  • Läuft der Sync, zeigt die Statusleiste den Fortschritt; danach erscheint eine Zusammenfassung (hochgeladen / heruntergeladen / Konflikte / Fehler).
  • Ist die geöffnete Kür vom Download betroffen und ungespeichert, wird sie nicht überschrieben – es erscheint ein Hinweis.

Technik

Datei Aufgabe
src/core/sync/remote_store.gd gemeinsame Schnittstelle der Cloud-Anbieter
src/core/sync/dropbox_store.gd Dropbox-API (App-Ordner, files/list_folder, files/upload, files/download, files/move_v2)
src/core/sync/google_drive_store.gd Google-Drive-API v3 (drive.file-Scope, Ordner Rinkplanner, Multipart-Upload, alt=media-Download)
src/core/sync/cloud_http.gd blockierender HTTPS-Client für den Worker-Thread
src/core/sync/cloud_auth.gd Refresh-Token, Access-Token-Erneuerung
src/core/sync/cloud_oauth_job.gd Google-Device-Flow und Dropbox-PKCE-Flow
src/core/sync/sync_app_config.gd App-Client-ID/App-Key laden
src/core/sync/sync_plan.gd reine Vergleichslogik, Konfliktnamen, Zeitstempel
src/core/sync/routine_sync.gd Ablauf, Datei-Ersetzung, Sync-Stand
  • Der Sync läuft in einem Thread; die Oberfläche bleibt bedienbar und pollt den Fortschritt in _process.
  • Cloud-Uploads sind einzelne, atomare HTTP-Anfragen (Dropbox files/upload mit mode: overwrite, Google Drive Multipart-Upload). Ein zusätzliches .uploading-Umbenennen wie beim alten FTP-Sync entfällt.
  • Downloads landen in name.part und ersetzen die Zieldatei erst danach.
  • Heruntergeladene .json-Dateien werden als JSON validiert; Legacy-.tres laufen vor dem Laden durch die Whitelist in RoutineFile. Ein manipuliertes Cloud-Konto kann damit keine eingebetteten GDScripts ausführen.
  • Neue Speicherungen sind JSON; der Sync akzeptiert weiterhin .tres, damit bestehende Dateien in der Cloud und auf dem Tablet nicht verschwinden.
  • Musikdateien werden als normale Anhänge der Kür behandelt: Die JSON nennt nur den Dateinamen (music_file), die Datei liegt daneben. Ändert sich die Musik auf einem Gerät, lädt der nächste Sync sie hoch; auf dem anderen Gerät wird sie heruntergeladen und beim Öffnen der Kür verwendet. Konfliktkopien behalten die Audio-Endung (z. B. kuer (Server …).mp3).
  • Eigene Timeline-Labels stehen in der Kür-JSON (timeline_labels) und werden ohne Zusatzdateien mit der Kür übertragen.
  • Refresh-Tokens liegen in user://sync.cfg (Klartext, app-privat). Auf Android ist das der interne App-Speicher, auf dem Desktop ~/.local/share/godot/app_userdata/Rinkplanner/. Nutzerpasswörter werden nicht gespeichert. Nach einem Kontowechsel oder Anbieterwechsel wird user://sync_state.cfg zurückgesetzt, damit alte Zeitstempel keinen falschen Konflikt auslösen.
  • Android braucht die INTERNET-Berechtigung – ist im APK gesetzt.

Datenschutz und Musiklizenzen

  • Bei Google Drive nutzt die App den Scope drive.file: Sie sieht nur Dateien, die Rinkplanner selbst angelegt hat, nicht das übrige Drive.
  • Bei Dropbox ist die App auf einen App-Ordner beschränkt.
  • Musikdateien werden im Konto des Nutzers gespeichert. Es gibt keinen zentralen Rinkplanner-Speicher und keine Weitergabe zwischen Konten. Die Verantwortung für die Nutzungsrechte liegt beim Nutzer.
  • Die App zeigt diesen Hinweis in den Sync-Einstellungen und sollte ihn auch in der Datenschutzerklärung für Stores führen.

Einrichtung der OAuth-Apps

Die App-Registrierung bei Google und Dropbox, die nötigen Scopes und die Werte in docs/credentials.txt stehen in docs/cloud-setup.md.

Grenzen

  • Kein automatischer Sync, kein Push, kein Locking. Zwei Geräte, die gleichzeitig synchronisieren, können sich überholen; der Konfliktfall verhindert dann Datenverlust, nicht aber doppelte Dateien.
  • Löschungen werden nicht übertragen (bewusst, um Versehen nicht zu multiplizieren).
  • Umbenennen einer Kür wirkt wie „neu lokal“ + „nur Cloud“: beide Fassungen landen nebeneinander.
  • Sehr große Kürsammlungen werden vollständig verglichen; für hunderte Dateien ist das noch unkritisch, für tausende wäre ein Manifest sinnvoll.
  • Dropbox-Uploads sind auf 150 MB pro Datei begrenzt (App-Ordner-Apps). Für Kür-JSONs und übliche Musikdateien reicht das; größere Dateien müssten chunked hochgeladen werden.
  • Google Drive erlaubt technisch mehrere Dateien mit demselben Namen. Der Sync sucht die erste passende Datei und führt bestehende Duplikate aus anderen Quellen nicht zusammen.

Migration vom FTP-Sync

Der frühere FTP-/FTPS-Sync ist entfernt. Alte user://sync.cfg-Einträge (host, port, user, password, ftps, verify_certificate) werden ignoriert; beim ersten Öffnen der Sync-Einstellungen muss ein Cloud-Konto verbunden werden. Die Dateien im alten FTP-Verzeichnis werden nicht automatisch übernommen: Wer sie behalten will, kopiert sie einmalig manuell in den Cloud-Ordner oder verbindet beide Geräte mit demselben Cloud-Konto und lädt die lokalen Kürdateien hoch.