# Crossfade [![CI](https://github.com/tg099/crossfade/actions/workflows/ci.yml/badge.svg)](https://github.com/tg099/crossfade/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/tg099/crossfade?sort=semver)](https://github.com/tg099/crossfade/releases) [![Image](https://img.shields.io/badge/ghcr.io-tg099%2Fcrossfade-2496ED?logo=docker&logoColor=white)](https://github.com/tg099/crossfade/pkgs/container/crossfade) [![License: PolyForm Strict 1.0.0](https://img.shields.io/badge/license-PolyForm%20Strict%201.0.0-blue)](LICENSE) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/tg099) [English](README.md) · **Deutsch** Selbst gehostete Web-App, die deine Musiksammlungen zwischen Musik-Streamingdiensten synchron hält ([welche das sind](#unterstützte-dienste)): in eine Richtung, in beide Richtungen oder in Gruppen, inklusive Löschungen. Mehrere Personen teilen sich eine Instanz, jede mit eigenen Diensten und Fades. Nur Admins legen Nutzer an und verwalten sie.

Buy me a coffee

Übersicht: deine Fades, neue Songs der Woche, was gerade dazugekommen ist und was Freunde beigesteuert haben

| Ein Fade | Deine Mediathek | |---|---| | ![Ein Fade mit Sammlungen bei drei Diensten und Statistik, dunkel](docs/screenshots/desktop-dark.png) | ![Alle Songs aller Dienste in einer Liste, mit Filtern nach Dienst, Interpret, Album und Fade](docs/screenshots/library-dark.png) | | Auf dem Telefon | Mit einem Freund geteilt | Mediathek unterwegs | |---|---|---| | ![Übersicht auf dem Telefon](docs/screenshots/phone-light.png) | ![Ein mit einem Freund geteilter Fade auf dem Telefon, dunkel](docs/screenshots/phone-fade-dark.png) | ![Die Mediathek auf dem Telefon](docs/screenshots/phone-library-light.png) | ## Begriffe - **Sammlung**: die Lieblingssongs, die Mediathek oder eine Playlist bei einem Dienst. - **Fade**: eine Gruppe von Sammlungen, die zusammen synchron gehalten werden. Jede Sammlung im Fade hat eine Rolle: - *beide Richtungen*: sendet eigene Änderungen und empfängt die der anderen - *sendet*: nur Quelle - *empfängt*: nur Ziel; was du dort selbst entfernst, wird nicht wieder hinzugefügt - Dieselbe Sammlung darf in mehreren Fades stecken; der Editor warnt, wenn sie aus zwei Fades Löschungen empfängt. | Aufbau | Beispiel | |---|---| | In eine Richtung | Playlist „Gym“ bei Dienst A *sendet* → Playlist „Gym“ bei Dienst B *empfängt* | | In beide Richtungen | Lieblingssongs bei Dienst A ↔ Lieblingssongs bei Dienst B | | Gruppe | Lieblingssongs bei A ↔ bei B ↔ bei C | Freunde auf derselben Instanz können einen Fade teilen: Jede Person steuert eine eigene Sammlung bei und sieht immer nur den Fade selbst, nie die Mediathek der anderen. ## Unterstützte Dienste | Dienst | Sammlungen | Anmeldung | Schnittstelle | |---|---|---|---| | Apple Music | Lieblingssongs, Mediathek, Playlists | Cookie aus dem Web-Player | Inoffiziell (die des Web-Players) | | Spotify | Lieblingssongs, Playlists | Spotify-Login; der Admin registriert einmalig eine App | Offizielle Web API | | YouTube Music | Lieblingsmusik, Mediathek-Songs, Playlists | Request aus dem Browser kopieren oder Google-Code (dann nur Lieblingsvideos und Playlists) | Inoffiziell (die der Web-App); mit Google-Code die offizielle YouTube Data API | | TIDAL | Meine Titel, Playlists | TIDAL-Login; der Admin registriert einmalig eine App | Offizielle TIDAL API | | Deezer | Lieblingstitel, Playlists | Cookie aus dem Web-Player | Inoffiziell (die des Web-Players); Katalog über die öffentliche API | Wie du die einzelnen Dienste verbindest, steht unter [Dienste einrichten](#dienste-einrichten). Ein neuer Dienst ist ein Modul in `crossfade/providers/`; Wünsche gern als [Issue](https://github.com/tg099/crossfade/issues). ## Installation Crossfade ist ein einziges Docker-Image (`ghcr.io/tg099/crossfade`, amd64 und arm64), ohne Datenbankserver oder weitere Abhängigkeiten. **Schritt-für-Schritt-Anleitung: [docs/install.md](docs/install.md)** (Englisch), mit diesen Varianten: | Du hast … | Variante | |---|---| | Einen Server mit Domain | [Docker Compose mit automatischem HTTPS](docs/install.md#a-docker-compose-with-automatic-https) (inkl. Caddy) | | Schon einen Reverse Proxy (Nginx Proxy Manager, Traefik …) | [Hinter deinem Reverse Proxy](docs/install.md#b-behind-your-existing-reverse-proxy) | | Willst es nur ausprobieren | [Schnellstart mit `docker run`](docs/install.md#c-quick-start-with-docker-run) | | Einen Unraid-Server | [docs/unraid.md](docs/unraid.md) | Kurzfassung, auf einem Server, auf den deine Domain zeigt (Ports 80/443 offen): ```sh mkdir crossfade && cd crossfade curl -O https://raw.githubusercontent.com/tg099/crossfade/main/docker-compose.yml \ -O https://raw.githubusercontent.com/tg099/crossfade/main/Caddyfile \ -o .env https://raw.githubusercontent.com/tg099/crossfade/main/.env.example openssl rand -base64 48 # → CROSSFADE_SECRET_KEY in .env, außerdem CROSSFADE_DOMAIN setzen docker compose up -d ``` Dann `https://` öffnen und das Admin-Konto anlegen. **`CROSSFADE_SECRET_KEY` danach nie ändern**, sonst lassen sich gespeicherte Logins nicht mehr entschlüsseln. Aktualisieren: `docker compose pull && docker compose up -d`. [Updates, Tags, Backups und Fehlerbehebung](docs/install.md#updating) stehen in der Anleitung. Zum Ausprobieren auf dem eigenen Rechner: `docker run -d -p 8765:8765 -v crossfade-data:/data ghcr.io/tg099/crossfade`, dann öffnen. Selbst bauen: in `docker-compose.yml` die Zeile `build: .` aktivieren und `docker compose up -d --build`. ## Dienste einrichten Jede Person verbindet ihre eigenen Konten in der App (**Konto → Dienste**); die App führt durch die Schritte. Manche Dienste brauchen vorher eine einmalige Einrichtung durch den Admin. ### Spotify (einmalig, Admin) 1. [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) → App anlegen (Web API). 2. Redirect URI: `https:///api/services/spotify/callback` 3. Unter *User Management* die Spotify-Konten aller Nutzer eintragen. 4. Client ID in Crossfade unter **Konto → App-Zugänge** eintragen (oder `SPOTIFY_CLIENT_ID` setzen). Einschränkungen von Spotify für Apps im Entwicklungsmodus (seit 2026): Konten brauchen **Premium**, höchstens **5 Nutzer** pro App. ### YouTube Music - **Über den Browser** (funktioniert immer): auf music.youtube.com bei einem Request „Als cURL kopieren“ und einfügen. Die App zeigt die Schritte. - **Mit Google-Code** (optional): Google-Cloud-Projekt mit der YouTube Data API v3 und einem OAuth-Client vom Typ „Fernseher und Geräte mit begrenzter Eingabe“ anlegen, dann Client ID/Secret unter **Konto → App-Zugänge** eintragen. Google lehnt diesen Weg bei YouTube Music zeitweise ab; der Browser-Weg funktioniert dann trotzdem. ### Apple Music Cookie `media-user-token` von music.apple.com kopieren und einfügen. Kein Apple-Developer-Account nötig; die App nutzt dieselbe Schnittstelle wie der Web-Player von Apple. ### TIDAL (einmalig, Admin) 1. [TIDAL Developer Dashboard](https://developer.tidal.com/dashboard) → App anlegen. 2. Redirect URI: `https:///api/services/tidal/callback` 3. Scopes `user.read`, `collection.read`, `collection.write`, `playlists.read`, `playlists.write` und `search.read` freischalten. 4. Client ID (und Secret) in Crossfade unter **Konto → App-Zugänge** eintragen (oder `TIDAL_CLIENT_ID`/`TIDAL_CLIENT_SECRET` setzen). Mit dem Secret kann Crossfade auch für Nutzer ohne TIDAL-Konto im TIDAL-Katalog suchen. TIDAL gibt Drittanbieter-Apps keine Hörproben, deshalb lassen sich TIDAL-Versionen in Crossfade nicht anhören. ### Deezer Cookie `arl` von deezer.com kopieren und einfügen. Deezer nimmt keine neuen Entwickler-Apps mehr an, deshalb geht es über die Schnittstelle des Web-Players; Suche und Hörproben kommen aus der öffentlichen Deezer-API. Das Cookie hält meist einige Monate und wird ungültig, wenn du dich bei Deezer abmeldest. ## Wie synchronisiert wird Jeder Fade merkt sich, welche Songs er kennt und wo er sie zuletzt gesehen hat. 1. Alle Sammlungen werden gelesen; Songs werden dienstübergreifend als derselbe Song erkannt (ISRC, Titel, Interpret, Dauer). 2. Neu in einer sendenden Sammlung → wird zu allen empfangenden hinzugefügt (Suche im Katalog des Ziels, Ergebnisse werden zwischengespeichert). 3. Aus einer sendenden Sammlung verschwunden, in der er vorher gesehen wurde → wird überall entfernt (wenn *Löschungen übertragen* an ist). 4. Unsichere Treffer landen als **offene Songs** im Fade: Vorschlag wählen, Link einfügen oder ignorieren. Was du von Hand zuordnest (oder als Version wählst), gilt überall: in allen Fades, auch bei Freunden, und beim Hinzufügen zur Mediathek. Deine Zuordnungen stehen unter **Konto → Zuordnungen**, dort änderst oder entfernst du sie. ### Schutzmechanismen - Der **erste Sync** führt nur zusammen, er löscht nie. - Gelöscht werden nur Songs, die vorher in einer Sammlung **gesehen** wurden. Ein gerade hinzugefügter Song, den der Dienst noch nicht anzeigt, gilt als „ausstehend“, nicht als gelöscht. - Eine **leere Liste** von einem Dienst, obwohl dort Songs bekannt sind → der Sync bricht ab. - **Sicherheitsgrenze** pro Fade (Standard: mehr als 10 Songs bzw. 20 %): mehr Löschungen als erlaubt → wartet auf Bestätigung. Automatische Syncs bestätigen nie. Die Rückfrage lässt sich pro Fade abschalten. - Fehlgeschlagene Löschungen werden beim nächsten Sync erneut versucht, statt rückgängig gemacht zu werden. - Bittet ein Dienst um eine **Pause** (Kontingent aufgebraucht oder länger als eine Minute warten), schickt Crossfade ihm bis dahin nichts. Fades warten statt zu scheitern, Songs, die dort noch gesucht werden müssen, gelten nicht als „nicht gefunden“, und nach der Pause geht der Sync von allein weiter. Der Systemzustand zeigt die Pause an. - Die **Vorschau** zeigt jeden Sync, ohne etwas zu ändern. ## Mehr als Sync - **KI-Assistenten und Stimmungs-Playlists** (**Konto → KI-Assistenten**): Über den eingebauten MCP-Server kann dein Assistent deine Mediathek durchsuchen und vergleichen, Playlists für frei beschriebene Stimmungen vorbereiten, Fades verwalten, offene Songs zuordnen, Dubletten aufräumen und die Zeitreise nutzen. Persönliche Schlüssel trennen Lesen, Synchronisieren und Verwalten. Änderungen setzt der Assistent selbst um, nur Löschungen bestätigst du direkt auf der Übersicht (auch per Link und auf Wunsch Benachrichtigung). Einordnungen zu Stimmung und Genre stammen vom verbundenen Assistenten, mit Sicherheitseinschätzung und geschützten persönlichen Korrekturen. [Einrichtung, Werkzeuge und Grenzen](docs/mcp.md) (Englisch). - **In Playlists einsortieren** (im Fade-Editor oder mit der Vorlage **Likes einsortieren**): Eine empfangende Sammlung kann nur die Songs bekommen, die zu einer Regel passen – Stimmungen, Genres, Tags, Sprachen, Energie, Interpreten oder „alles Übrige“. Neue Songs werden bei jedem Sync einsortiert. Eine sendende Sammlung wie deine Likes kann als Eingang dienen: Ein Song verschwindet dort, sobald er in allen passenden Playlists angekommen ist (viele auf einmal warten auf Bestätigung). Stimmungen und Genres kommen von deinem KI-Assistenten oder deinen eigenen Tags; Songs ohne Einordnung warten, bis sie eine haben. - **Reihenfolge der Likes:** Likes aus mehreren Diensten kommen in der Reihenfolge an, in der du sie geliked hast, das Neueste oben – nach dem Datum, wo ein Dienst es verrät, sonst nach den Songs drumherum. Schon durcheinander geratene Likes lassen sich im Fade geraderücken (**Likes in Like-Reihenfolge bringen**): Crossfade zeigt pro Like-Sammlung, wie viele Songs anders stehen, und verschiebt die ausgewählten, indem es sie einzeln entliked und gleich wieder liked, ohne dass einer verloren geht. Eine Playlist, die nur Likes empfängt (auch deine eigene im Fade eines Freundes), lässt sich genauso ordnen, der früheste Like oben: Songs, die falsch stehen, werden entfernt und hinten wieder angefügt. Das kann nur, wem die Playlist gehört. - **Zeitreise:** Jedes Mal, wenn Crossfade eine Sammlung komplett liest, merkt es sich ihren Inhalt, aber nur wenn sich etwas geändert hat. In der Mediathek (Uhr-Symbol) oder bei einer Sammlung im Fade wählst du einen Zeitpunkt, siehst, was seitdem verschwunden und dazugekommen ist, und holst einzelne Songs zurück oder setzt die Sammlung genau auf diesen Stand. Die letzten 7 Tage bleiben komplett, danach ein Stand pro Tag für 90 Tage. - **Benachrichtigungen** (**Konto → Benachrichtigungen**): per [ntfy](https://ntfy.sh), Webhook (Discord und Slack werden erkannt, sonst JSON, z. B. für Home Assistant) oder E-Mail über einen SMTP-Server, den der Admin unter **App-Zugänge** einträgt. Pro Kanal wählbar: Anmeldung geht nicht mehr oder läuft bald ab, ein Sync wartet auf dich, neue offene Songs, wiederholt gescheiterte Syncs, Freunde und für Admins eine neue Version. Jedes Problem wird nur einmal gemeldet, in der Sprache der Person (ihre Einstellung, sonst die ihres Browsers). - **Anmeldungen prüfen:** Crossfade probiert jede Anmeldung zweimal am Tag aus, auch wenn sie in keinem Fade steckt, und merkt sich, wann sie abläuft, wenn der Dienst es verrät (z. B. bei Google-Apps im Testmodus nach 7 Tagen). - **Systemzustand** (nur Admins, **Konto → Systemzustand**): Anfragen, Fehler, Ausbremsungen und Dauer pro Dienst und Stunde, Syncs der letzten 24 Stunden, Datenbank, Backups, freier Speicher und die letzten Fehler. Nur Zahlen, nichts Privates. - **Backups** (nur Admins, **Konto → Backups**): Crossfade sichert seine Datenbank bei jedem Start und einmal am Tag. Du kannst von Hand sichern, Backups herunterladen und wiederherstellen (auch aus einer heruntergeladenen Datei, z. B. beim Umzug auf einen neuen Server). Vor dem Wiederherstellen wird der jetzige Stand noch gesichert. Der geheime Schlüssel steckt nie in einem Backup: Bewahre ihn getrennt auf. - **Update-Hinweis** (nur Admins): Zweimal am Tag schaut Crossfade bei den GitHub-Releases nach und zeigt eine neue Version auf der Übersicht und unter **Konto**. Entwicklungsversionen schauen nie nach; `CROSSFADE_UPDATE_CHECK=false` schaltet es ab. - **Erste Schritte:** Neue Nutzer bekommen auf der Übersicht eine Checkliste (Dienste verbinden, erster Fade, erster Sync, Benachrichtigungen), bis alles eingerichtet ist oder sie sie ausblenden. - **Für jemanden einrichten** (nur Admins, **Konto → Nutzer** → eine Person → **Als diese Person anmelden**): Der Admin sieht Crossfade so wie diese Person und kann für sie Dienste verbinden, Fades bauen und Einstellungen ändern. Der Besuch endet nach zwei Stunden von selbst, ein Banner oben bringt den Admin mit einem Tipp zurück. Passwort und KI-Assistenten der Person sowie die Admin-Seiten bleiben dabei gesperrt, und bei anderen Admins geht es nicht. ## Sicherheit - Logins bei den Diensten werden verschlüsselt gespeichert, mit einem Schlüssel aus `CROSSFADE_SECRET_KEY`. - Passwörter mit scrypt gehasht, Sitzungen als HttpOnly-Cookies (über HTTPS mit Secure), CSRF-Schutz über einen Pflicht-Header, strenge Content Security Policy, Begrenzung der Anmeldeversuche. - Keine Selbstregistrierung: Nur Admins legen Nutzer an. Neue Nutzer bekommen ein Startpasswort und wählen beim ersten Anmelden ein eigenes. Sicherheitslücke gefunden? Bitte [privat melden](https://github.com/tg099/crossfade/security/advisories/new), nicht als öffentliches Issue. ## Entwicklung ```sh python3.12 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt .venv/bin/python -m pytest -q # Tests für Engine und API cd web && npm install && npm run dev # Frontend mit Proxy auf :8765 .venv/bin/uvicorn crossfade.api.app:app --port 8765 --reload ``` Lokal ohne Docker: `./start.sh` (baut das Frontend bei Bedarf und läuft unter http://127.0.0.1:8765). Bitte Syncs nicht gegen deine echten Konten testen: nimm ein eigenes `CROSSFADE_DATA_DIR` mit Testdaten. | Pfad | Inhalt | |---|---| | `crossfade/engine.py` | Sync-Logik eines Fades | | `crossfade/identity.py` | Song-Identität über Dienste hinweg, Katalogsuche | | `crossfade/matcher.py` | Abgleich nach Titel, Interpret, Dauer, ISRC | | `crossfade/providers/` | Ein Modul pro [unterstütztem Dienst](#unterstützte-dienste) | | `crossfade/worker.py` | Zeitplan, Hintergrund-Syncs, Live-Fortschritt | | `crossfade/catalog.py` | Die Mediathek: alle Songs aller Dienste, Hinzufügen und Entfernen in einem Rutsch | | `crossfade/sorting.py` | Regeln, die Songs im Fade in Playlists einsortieren | | `crossfade/sharing.py` | Freunde und geteilte Fades, wer was sehen darf | | `crossfade/history.py` | Zeitreise: Stände der Sammlungen und Wiederherstellen | | `crossfade/mcp_server.py` | MCP-Server für KI-Assistenten | | `crossfade/api/` | HTTP-API, Anmeldung, Nutzerverwaltung | | `web/` | Oberfläche (SvelteKit, statisch gebaut) | Umgebungsvariablen: siehe `.env.example`. Zusätzlich `CROSSFADE_DATA_DIR`, `CROSSFADE_BASE_URL`, `CROSSFADE_WEB_DIR`, `CROSSFADE_SECURE_COOKIES` und `CROSSFADE_BACKUP_ON_START`. Die Oberfläche nutzt ein Liquid-Glass-Design für Telefon und Desktop, mit Hell/Dunkel/System und Deutsch und Englisch (Texte in `web/src/lib/ui/lang/`, beide Dateien haben dieselben Schlüssel). Die Screenshots in `docs/screenshots/` zeigen ausgedachte Personen und generierte Cover auf einer Wegwerf-Datenbank, nie echte Konten. ### Releases Die Version steht nur im Release-Tag; im Code gibt es nichts hochzuzählen. 1. GitHub → *Releases* → *Draft a new release* → neuer Tag `vX.Y.Z` auf `main` → *Generate release notes* (gruppiert nach PR-Labels: `breaking`, `enhancement`, `bug`, `security`, `dependencies`) → *Publish*. 2. Der Workflow *Release image* führt die Tests aus, baut das Image, startet es einmal als Smoke-Test, prüft es auf kritische Sicherheitslücken und pusht erst dann `X.Y.Z`, `X.Y`, `latest` und `testing` für amd64 und arm64 (Vorabversionen, Tag `vX.Y.Z-rc.N` + *Set as a pre-release*, bekommen nur `X.Y.Z-…` und `testing`), mit SBOM und signierter Build-Provenienz. Image prüfen: `gh attestation verify oci://ghcr.io/tg099/crossfade:X.Y.Z -R tg099/crossfade`. ## Mitmachen Fehler und Ideen gern als [Issue](https://github.com/tg099/crossfade/issues), Fragen in den [Discussions](https://github.com/tg099/crossfade/discussions). Pull Requests werden per Squash gemergt; mit einem PR stimmst du den Beitragsbedingungen der [Lizenz](LICENSE) zu. ## Projekt unterstützen Crossfade ist kostenlos, der Quellcode ist offen einsehbar, und es entsteht in meiner Freizeit. Wenn es deine Musik synchron hält, hilft ein Kaffee, dass es weitergeht. Danke! ☕ Buy me a coffee ## Haftungsausschluss Crossfade steht in keiner Verbindung zu den unterstützten Diensten oder den Unternehmen dahinter. Dienste, die in der [Liste](#unterstützte-dienste) als *inoffiziell* markiert sind, werden über ihre Web-Schnittstellen angesprochen, die sich jederzeit ändern können. Die Nutzung erfolgt auf eigenes Risiko und im Rahmen der Bedingungen des jeweiligen Dienstes. ## Lizenz [PolyForm Strict License 1.0.0](LICENSE) mit zusätzlichen Erlaubnissen. Kurz gesagt: - Du darfst Crossfade kostenlos für dich nutzen und kostenlos für Freunde und Familie bereitstellen. - Keine kommerzielle Nutzung, kein Verkauf (auch nicht des Zugangs), keine Weitergabe und keine eigenen, geänderten Versionen oder Forks. - Änderungen sind nur erlaubt, um sie hier als Pull Request vorzuschlagen. Rechtlich verbindlich ist der englische Text in [LICENSE](LICENSE).