Filterbare Ansicht einer Rekordbox-Library mit gepflegten SoundCloud-Links. Rein statisch, kein Backend, keine Datenbank. Zwei Betriebsmodi aus derselben Codebase.
| Modus | Wann | Was er kann |
|---|---|---|
| Admin | lokal, npm run dev oder Build mit VITE_ADMIN=true |
XML importieren, Sichtbarkeit pflegen, SoundCloud-Links zuordnen, exportieren |
| Öffentlich | GitHub Pages | liest public/data/library.json, read-only, Filter in der URL |
npm install
npm run dev # Admin-Modus
npm run test # Parser- und Logiktests
npm run build # Produktionsbundle- In Rekordbox die Sammlung als XML exportieren.
npm run devstarten und die XML über den File-Picker laden. Die Datei wird nur im Browser verarbeitet.- Sichtbarkeit festlegen (siehe unten) und SoundCloud-Links nachtragen.
- Über „Exportieren“ herunterladen:
library.jsonnachpublic/data/library.jsonlegen und committen.matches.jsonsichern und beim nächsten Start wieder laden. Sie überlebt einen Re-Import der XML, weil zu jedem Eintrag Dateiname und Fingerprint mitgespeichert werden.library.local.jsonbleibt lokal, sie steht in.gitignore.
- Push auf
main– der Workflow in.github/workflows/deploy.ymlbaut und deployt.
Zwischenstände liegen im localStorage, ein Reload verliert also nichts. Der Export ist
trotzdem die einzige dauerhafte Sicherung.
Bei statischem Hosting ist alles einsehbar, was in der JSON steht – auch was das UI ausblendet. Deshalb:
library.jsonenthält ausschließlich Tracks mitisPublic === true. Nicht-öffentliche Tracks werden vollständig entfernt, nicht nur markiert.TRACK@Locationenthält den vollen lokalen Pfad inklusive Windows-Benutzername. Der Pfad landet in keiner exportierten Datei; intern dient nur der reine Dateiname als Fallback-Match-Key und wird nirgends angezeigt.- Vor dem Export bestätigst du eine Vorschau mit „X von Y Tracks werden öffentlich exportiert“ samt Aufschlüsselung nach Genre-Ordner.
Die erste zutreffende Regel gewinnt:
- Manueller Per-Track-Override (Augen-Symbol in der Zeile). Schlägt alles andere.
- Ohne Genre-Ordner ist immer privat. Tracks aus Top-Level-Playlists wie
newoderMüllgehören dazu. - Schlüsselwort in MyTags oder Kommentar (
Dub,Promo,Unreleased,WIP,Bootleg, konfigurierbar). - Ordner-Default je Top-Level-Genre-Ordner.
- Sonst: privat.
Regel 3 steht bewusst vor dem Ordner-Default. Sie kann ausschließlich auf privat schalten und
wäre hinter einem freigebenden Ordner-Default wirkungslos. Titel und Dateiname werden nicht
durchsucht, sonst würde jeder (… Bootleg)-Remix fälschlich verschwinden.
- Genre – Name des Top-Level-Ordners (
NODE Type="0"), sonstUngrouped. - Subgenre –
TRACK@Genre. Sub-Subgenre –TRACK@Album. - qualityTier –
Losslessbei FLAC/WAV/AIFF/ALAC, sonstHighab 320,Mediumab 192, darunterLow. - upgradeCandidate –
qualityTieristMediumoderLow, oderSampleRate < 44100. - hasCues („Ist vorbereitet“) – mindestens ein Hot Cue mit
Num >= 1. Der Cue aufNum=0zählt nicht, den setzt Rekordbox bei fast jedem Track automatisch. - MyTags – aus
Comments, Rekordbox schreibt sie als C-Kommentar-Blöcke. - Tonart –
TRACK@Tonalityist bereits Camelot und wird um Open Key und Tonartnamen ergänzt.
SoundCloud-Links und Overrides hängen an einem stabilen Schlüssel, nicht an der TrackID, die
sich beim Neuaufbau der Library ändern kann. Beim Import wird kaskadierend zugeordnet:
TrackID- normalisierter Dateiname aus
Location - normalisiert
artist|title|totalTime(auf 5 Sekunden gerundet)
Trifft Ebene 2 oder 3, wird der Eintrag auf die neue TrackID umgeschrieben. Mehrdeutige
Fingerprints werden verworfen, damit ein Link nicht am falschen Track landet. Nach dem Import
zeigt ein Banner, wie viele Zuordnungen übernommen wurden und wie viele verwaist sind.
Die offizielle API setzt eine App-Registrierung voraus, die ein Artist-Pro-Abo verlangt. Ohne Credentials gibt es weder Suche noch Playlist-Erstellung, und inoffizielle Endpoints kommen nicht in Frage. Die Link-Pflege ist deshalb halbautomatisch:
- Icon in der Zeile öffnet die vorbereitete SoundCloud-Suche in einem neuen Tab.
- URL zurück ins Eingabefeld einfügen.
- Die App verifiziert sie über den credential-freien oEmbed-Endpoint und zeigt Titel und Artwork.
- Bei mehreren Kandidaten stehen die Vorschauen nebeneinander, einer wird ausgewählt.
Über „Links“ in der Kopfzeile gibt es eine Warteschlange aller Tracks ohne Link.
Die Match-Struktur ist auf späteres API-Matching vorbereitet:
{ matchKey, soundcloudUrl, confidence, source: 'manual' | 'api', verifiedAt }. Ein Nachrüsten
erfordert keine Änderung an der Persistenz.
scripts/scrape-soundcloud.mjs übernimmt das „ersten Treffer finden“ für viele Tracks auf
einmal. Da SoundCloud keine offene Such-API hat und CORS blockt, rendert das Skript die
Suchseite in einem headless Chromium (Playwright), greift die Top-Treffer ab, verifiziert jeden
über denselben oEmbed-Endpoint wie die App und scort ihn per Fuzzy-Vergleich von Artist + Titel.
Einmalig einrichten:
npm install
npx playwright install chromium # lädt den Browser (~150 MB)Lauf:
npm run sc:scrape # alle offenen Tracks, headless
npm run sc:scrape -- --limit 20 # nur die ersten 20
npm run sc:scrape -- --min-score 0.72 # strenger auto-übernehmen
npm run sc:scrape -- --dry-run # nichts schreiben, nur ReportAblauf: library.xml + vorhandene matches.json werden gelesen; jeder Track ohne Link wird
gesucht. Liegt der beste verifizierte Kandidat über --min-score (Default 0.62), landet er als
source: "api" mit dem Score als confidence in matches.json. Alles darunter bleibt offen und
wird in sc-report.md mit dem besten gefundenen Kandidaten aufgelistet. Bestehende Matches –
besonders manuell gesetzte – werden nie überschrieben (--redo-api erlaubt nur ein erneutes
Durchprobieren der automatischen). Danach in der App „matches.json laden“: Auto-Treffer sind
normale Links, unsichere Tracks stehen weiter in der Bulk-Queue zum manuellen Abarbeiten.
Wichtige Flags: --xml, --matches, --report, --min-score, --limit, --delay (Pause
zwischen Tracks, Default 1800 ms), --candidates (Treffer je Track, Default 4), --headful
(Browser sichtbar), --redo-api, --dry-run. node scripts/scrape-soundcloud.mjs --help zeigt
alles.
Die gefilterte Ansicht ist die teilbare Playlist – alle aktiven Filter stehen in der URL. Zusätzlich lässt sich die aktuelle Auswahl herunterladen als CSV (alle Felder), M3U8 (nur im Admin-Modus, braucht die lokalen Pfade) und als reine Linkliste.
Die öffentliche Seite ist mit einem Passwort geschützt. Weil GitHub Pages rein statisch
ausliefert, wäre ein JS-Passwortvergleich wirkungslos – die Daten lägen trotzdem im Klartext im
Netzwerk-Tab. Deshalb wird die ganze Library samt SoundCloud-Links AES-256-GCM-verschlüsselt;
der Schlüssel wird per PBKDF2 (210 000 Iterationen) aus dem Passwort abgeleitet und existiert nur
im Browser, nachdem das richtige Passwort eingegeben wurde. Auf GitHub liegt ausschließlich
Chiffretext (public/data/library.enc.json).
Verschlüsselte Daten erzeugen bzw. aktualisieren (liest library.xml + matches.json, nimmt
alle Tracks auf, da passwortgeschützt):
npm run build:public -- "DEIN PASSWORT"
git add public/data/library.enc.json
git commit -m "Library aktualisiert" && git pushlibrary.xml bleibt gitignored – nur der Chiffretext wird committet. Der GitHub-Actions-Workflow
(.github/workflows/deploy.yml) baut die App und deployt nach Pages; das Passwort taucht nirgends
im Repo oder in der CI auf. Zum Passwort ändern einfach neu verschlüsseln und committen.
Besucher sehen zuerst einen Passwortschirm; nach Eingabe wird die Library im Browser entschlüsselt und das Passwort für die Sitzung gemerkt (kein erneutes Fragen bei Reload).
Ehrliche Einordnung: Das schützt den Inhalt wirksam vor zufälligen Besuchern und Suchmaschinen, ist aber ein einzelnes geteiltes Geheimnis. Wer das Passwort kennt, kann die entschlüsselten Daten auch weitergeben. Für eine halb-private Sammlung unter Freunden ist das angemessen; es ersetzt keine echte Nutzerverwaltung.
| Variable | Default | Zweck |
|---|---|---|
VITE_ADMIN |
in npm run dev implizit an |
true erzwingt den Admin-Modus im Build |
VITE_BASE |
/LibraryOverview/ |
Base-Path für GitHub Pages, im Workflow aus dem Repo-Namen gesetzt |
PUBLIC_LIB_PASSWORD |
– | optionales Passwort für npm run build:public statt als Argument |
Kein Playback lokaler Dateien, kein Schreibzugriff auf Rekordbox, kein Multi-User, keine Nutzerverwaltung (nur ein geteiltes Passwort), keine Datenbank, kein Backend.