Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Rekordbox Library Explorer

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

Schnellstart

npm install
npm run dev      # Admin-Modus
npm run test     # Parser- und Logiktests
npm run build    # Produktionsbundle

Workflow

  1. In Rekordbox die Sammlung als XML exportieren.
  2. npm run dev starten und die XML über den File-Picker laden. Die Datei wird nur im Browser verarbeitet.
  3. Sichtbarkeit festlegen (siehe unten) und SoundCloud-Links nachtragen.
  4. Über „Exportieren“ herunterladen:
    • library.json nach public/data/library.json legen und committen.
    • matches.json sichern 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.json bleibt lokal, sie steht in .gitignore.
  5. Push auf main – der Workflow in .github/workflows/deploy.yml baut und deployt.

Zwischenstände liegen im localStorage, ein Reload verliert also nichts. Der Export ist trotzdem die einzige dauerhafte Sicherung.

Datenschutz

Bei statischem Hosting ist alles einsehbar, was in der JSON steht – auch was das UI ausblendet. Deshalb:

  • library.json enthält ausschließlich Tracks mit isPublic === true. Nicht-öffentliche Tracks werden vollständig entfernt, nicht nur markiert.
  • TRACK@Location enthä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.

Wie isPublic bestimmt wird

Die erste zutreffende Regel gewinnt:

  1. Manueller Per-Track-Override (Augen-Symbol in der Zeile). Schlägt alles andere.
  2. Ohne Genre-Ordner ist immer privat. Tracks aus Top-Level-Playlists wie new oder Müll gehören dazu.
  3. Schlüsselwort in MyTags oder Kommentar (Dub, Promo, Unreleased, WIP, Bootleg, konfigurierbar).
  4. Ordner-Default je Top-Level-Genre-Ordner.
  5. 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.

Abgeleitete Felder

  • Genre – Name des Top-Level-Ordners (NODE Type="0"), sonst Ungrouped.
  • Subgenre – TRACK@Genre. Sub-Subgenre – TRACK@Album.
  • qualityTier – Lossless bei FLAC/WAV/AIFF/ALAC, sonst High ab 320, Medium ab 192, darunter Low.
  • upgradeCandidate – qualityTier ist Medium oder Low, oder SampleRate < 44100.
  • hasCues („Ist vorbereitet“) – mindestens ein Hot Cue mit Num >= 1. Der Cue auf Num=0 zählt nicht, den setzt Rekordbox bei fast jedem Track automatisch.
  • MyTags – aus Comments, Rekordbox schreibt sie als C-Kommentar-Blöcke.
  • Tonart – TRACK@Tonality ist bereits Camelot und wird um Open Key und Tonartnamen ergänzt.

Match-Key

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:

  1. TrackID
  2. normalisierter Dateiname aus Location
  3. 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.

SoundCloud

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:

  1. Icon in der Zeile öffnet die vorbereitete SoundCloud-Suche in einem neuen Tab.
  2. URL zurück ins Eingabefeld einfügen.
  3. Die App verifiziert sie über den credential-freien oEmbed-Endpoint und zeigt Titel und Artwork.
  4. 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.

Auto-Matcher (Batch)

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 Report

Ablauf: 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.

Teilen und Exportieren

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.

Passwortgeschützt auf GitHub Pages deployen

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 push

library.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.

Konfiguration

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

Nicht-Ziele

Kein Playback lokaler Dateien, kein Schreibzugriff auf Rekordbox, kein Multi-User, keine Nutzerverwaltung (nur ein geteiltes Passwort), keine Datenbank, kein Backend.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages