Vorwort

Herzlich willkommen zum DJ-Tool.

Dieses Tool ist aus meinem persönlichen Bedarf entstanden. Als DJ ist es wichtig, Tracks vorzubereiten. Dazu gehört nicht nur die Anpassung der Lautstärke, sondern auch die Konvertierung des Ausgangsmaterials in verschiedene Formate. Für eine gut strukturierte Musiksammlung spielen ferner ID3 Tags eine große Rolle.

Anstatt mehrere Tools zu benutzen, wollte ich eine einfache, zuverlässige Möglichkeit, meine Audiodateien für Streaming-Plattformen entsprechend vorzubereiten, und zwar in einem Tool, welches meine Bedarfe deckt.

Herausgekommen ist mein DJ-Tool.

Das DJ-Tool normalisiert WAV- und MP3-Dateien auf den Streaming-Standard von −14 LUFS / −1 dBTP, konvertiert zwischen Formaten und bietet einen vollständigen ID3-Tag-Editor mit automatischer BPM- und Tonart-Erkennung, Anbindung an MusicBrainz und Discogs sowie CSV-Im-/Export und Rekordbox-XML-Export.

Ferner ist es für macOS (Silicon) und Windows 10/11 verfügbar.

Ich hoffe, dass auch Dein Workflow damit erleichtert wird.

Viel Spaß im Mix!

DJ Cataclysm

1 Systemvoraussetzungen und Einschränkungen

1.1 Systemvoraussetzungen

• macOS: Apple Silicon (ARM64), macOS 12 Monterey oder neuer.

• Windows: Windows 10 oder Windows 11, 64-Bit.

• Arbeitsspeicher: min. 4 GB RAM empfohlen.

• Speicherplatz: ca. 200 MB für die App (ohne Audiodateien).

ffmpeg ist vollständig im App-Bundle enthalten. Es muss keine weitere Software installiert werden.

1.2 Einschränkungen

• Das DJ-Tool läuft in einer virtualisierten Windows-10/11-Umgebung auf Apple-Silicon-Macs (z. B. Parallels), allerdings steht der Audioplayer dort aufgrund fehlender ARM64-Audiotreiber nicht zur Verfügung.

• Das rekursive Scannen von Ordnern wird nicht unterstützt — es werden nur Dateien geladen, die sich direkt im ausgewählten Ordner befinden, nicht jedoch solche in Unterordnern.

• Die BPM- und Tonart-Erkennung arbeitet vollständig offline und lokal. Die Ergebnisse können geringfügig von anderer DJ-Software abweichen.

2 Installation

2.1 Installation macOS

• Das DMG-Archiv öffnen (Doppelklick auf dj_mac.dmg).

• Die App-Datei in den Ordner /Programme (Applications) ziehen.

• Beim ersten Start erscheint möglicherweise eine Gatekeeper-Warnung. In diesem Fall im Terminal folgenden Befehl ausführen:

xattr -cr "/Applications/DJ Cataclysm - DJ-Tool.app"

• Die App über den Finder oder Launchpad starten.

ffmpeg ist vollständig im App-Bundle enthalten (Contents/Frameworks/ffmpeg). Es muss keine weitere Software installiert werden.

2.2 Installation Windows

• Das Archiv dj_win.zip entpacken (z.B. in C:\Programme\DJ-Tool\).

• Die Datei DJ Cataclysm - DJ-Tool.exe durch Doppelklick starten.

• Windows Defender SmartScreen kann beim ersten Start eine Warnung anzeigen. Auf "Weitere Informationen" und dann "Trotzdem ausführen" klicken.

ffmpeg.exe liegt im selben Ordner wie die Executable und wird automatisch gefunden. Die beiden Dateien müssen immer zusammen bleiben – ffmpeg.exe darf nicht verschoben werden.

3 Oberfläche im Überblick

3.1 Hauptfenster und Navigation

Die App startet mit dem Hauptfenster und zeigt die Navigationsleiste (links) sowie das untere Ausgabefenster an.

Das Hauptfenster besteht aus drei Bereichen:

3.1.1 Kopfzeile

Die Kopfzeile enthält den App-Namen, die Versionsnummer und ein Sprach- Dropdown. Die Sprache lässt sich auf DE, EN, ES, IT, PL oder RU umschalten. Nach der Auswahl muss die App neu gestartet werden, damit die Sprachänderung wirksam wird.

3.1.2 Navigation

Die Tab-Leiste enthält die folgenden 5 Menüeinträge:

• Normalisierung

• Konvertierung

• ID3-Tags

• Batch & Export

• Dateiinfos

3.1.3 Log-Bereich

Beim Log-Bereich (unten) handelt es sich um ein scrollbares Ausgabefenster mit Statusmeldungen. Die Höhe lässt sich durch Ziehen der Griffleiste (• • •) zwischen Inhalt und Log vergrößern oder verkleinern.

Die Navigationsleiste wird beim Start der App vollständig geladen. Ein Wechsel zwischen den Menüeinträgen ist jederzeit möglich. Laufende Prozesse (z. B. Normalisierung) werden davon nicht unterbrochen.

3.2 Kurze Beschreibung der Hauptfunktionen

3.2.1 Normalisierung

Die Normalisierungsfunktion passt die Lautstärke von Audiodateien auf den Streaming-Standard −14 LUFS / −1 dBTP an. Originale werden nicht verändert.

3.2.2 Konvertierung

Im Menübereich Konvertierung kannst Du Audiodateien zwischen MP3, WAV und FLAC umwandeln, optional mit wählbarer Bitrate bei MP3.

3.2.3 ID3-Tags

Hier findest du einen vollständigen Metadaten-Editor mit Online-Anbindung an MusicBrainz, Discogs und Spotify sowie lokaler BPM- und Tonart- Erkennung, Cover-Artwork-Verwaltung, Fingerprint-Suche (AcoustID) und einem Audio-Player.

3.2.4 Batch & Export

Alle Werkzeuge die auf die gesamte geladene Dateiliste (ID3-Tags) wirken sind hier dargestellt:

• Batch Online-Tagging und Coversuche

• Analyse von BPM und Key

• ReplayGain berechnen, Plattform-Vergleich

• Batch-Umbenennen

• Genre normalisieren

• Batch-Feld setzen

• Auto-Sortierung

• CSV-Export/-Import

• Rekordbox-XML-Export, Traktor NML, Serato M3U

• Camelot Wheel, harmonisch sortieren

• Duplikate suchen

3.2.5 Dateiinfos

Darstellung verschiedener Dateieigenschaften in Listenform.

4 Normalisierung

4.1 Hintergrund: Was bedeutet −14 LUFS?

LUFS steht für Loudness Units relative to Full Scale – die Maßeinheit für integrierte Lautheit nach dem Standard ITU-R BS.1770-4. Streaming-Plattformen normalisieren alle Inhalte auf einen Zielwert:

• Spotify, YouTube, Tidal: −14 LUFS

• Apple Music: −16 LUFS

• Beatport, SoundCloud: −8 LUFS (keine automatische Lautheitsanpassung)

Der True Peak (dBTP) begrenzt den maximalen Signalpegel nach der Analog-Digital-Wandlung. Der Standardwert −1 dBTP verhindert Clipping bei verlustbehafteter Wiedergabe (Bluetooth, AAC-Streaming). Das DJ-Tool normalisiert nach dem Standard ITU-R BS.1770-4 auf den einstellbaren Zielwert und begrenzt gleichzeitig den True Peak.

Peak-Limiting: Falls die Verstärkung auf −14 LUFS den True Peak über −1 dBTP heben würde, wird der Gain automatisch zurückgenommen, bis der Peak-Grenzwert eingehalten ist. Im Log erscheint dann [PEAK-LIMITED]. Das ist korrektes Verhalten – nicht ein Fehler.

• ffmpeg dekodiert die MP3 verlustfrei zu unkomprimiertem PCM-Audio (32-Bit Float, f32le-Format).

• pyloudnorm misst die integrierte Lautheit (LUFS) und berechnet den nötigen Gain-Faktor.

• ffmpeg kodiert das Ergebnis mit der Originalbitrate als neue MP3-Datei.

Hinweis: Die Rekodierung ist technisch eine Generation Loss. Bei hohen Bitraten (192–320 kbps) ist der Qualitätsverlust praktisch nicht hörbar. Für professionelle Zwecke empfiehlt sich die Arbeit mit WAV als Quelldatei und MP3-Konvertierung als letzten Schritt.

4.2 Audio-Dateien auswählen

• Dateien wählen ...: Einzelne oder mehrere Audio-Dateien per Datei-Dialog auswählen.

• Ordner wählen ...: Einen kompletten Ordner mit Audio-Dateien einlesen.

• Ausgabeordner wählen ...: Zielordner für die normalisierten Kopien festlegen.

Alle Dateien werden in den Ausgabeordner kopiert und nur dort wird die Normalisierung durchgeführt. Deine originalen Audio-Dateien werden nicht verändert.

4.3 Normalisierungs-Parameter

Als Standard sind −14,0 LUFS und −1,0 dBTP eingestellt. Diese Werte kannst Du anpassen und über die Schaltfläche Standard wiederherstellen zurücksetzen.

4.4 Normalisieren / Analysieren

Erst durch Klicken der Schaltfläche Dateien normalisieren werden die Dateien im Ausgabeordner normalisiert. Mit Dateien analysieren (nur messen) werden LUFS-Wert und True Peak gemessen, ohne Änderungen zu schreiben. Nützlich zur Kontrolle, ob Tracks bereits auf dem Zielwert liegen.

4.5 Ausgabe

Das untere Ausgabefenster zeigt Statusmeldungen zu jeder verarbeiteten Datei, inklusive gemessener LUFS-Werte, angewendetem Gain und eventueller Fehler.

5 Konvertierung

Der Tab Konvertierung wandelt Audiodateien zwischen den Formaten MP3, WAV und FLAC um. Akzeptierte Eingabeformate: MP3, WAV, FLAC, OGG, M4A, AAC, WMA, AIFF, OPUS.

5.1 Dateien wählen

• Dateien wählen ...: Einzelne oder mehrere Audiodateien auswählen.

• Ordner wählen ...: Einen kompletten Ordner mit Audiodateien einlesen.

• Ausgabeordner wählen ...: Zielordner für die konvertierten Dateien festlegen. Originale werden nicht verändert.

5.2 Zielformat & Bitrate

• MP3: Verlustbehaftetes Format für maximale Kompatibilität. Bitrate wählbar: 128 / 192 / 256 / 320 kbps.

• WAV: Unkomprimiertes Format. Höchste Qualität, größte Dateien.

• FLAC: Verlustfreie Komprimierung. Kleinere Dateien als WAV, identische Qualität. Unterstützt von den meisten modernen DJ-Programmen.

5.3 Konvertieren

Der Konvertierungsprozess startet durch Klick auf Dateien konvertieren. Die Konvertierung erfolgt ohne Anpassung der Lautstärke.

Tipp: Wer Normalisierung und Konvertierung kombinieren möchte, normalisiert zuerst (WAV → WAV, normalisiert) und konvertiert dann das Ergebnis in das Zielformat.

6 ID3-Tags

Der Navigationspunkt ID3-Tags ist das Herzstück des DJ-Tools für die Musikbibliotheks-Verwaltung. Hier lassen sich Metadaten lesen, bearbeiten, automatisch beziehen und speichern – einzeln oder über den Navigationspunkt Batch & Export für die gesamte Sammlung.

6.1 Was sind ID3-Tags?

ID3-Tags sind Metadaten-Container, die direkt in Audiodateien eingebettet werden. Sie enthalten Informationen wie Titel, Künstler, Album, Genre, BPM und Tonart – all das, was DJ-Software, Musik-Player und Streaming-Dienste brauchen, um einen Track zu identifizieren und anzuzeigen.

Technisch unterscheidet man:

• ID3v2.3 (MP3): Der in der DJ-Welt am weitesten verbreitete Standard. Das DJ-Tool liest und schreibt ausschließlich ID3v2.3 – kompatibel mit allen gängigen DJ-Programmen.

• RIFF INFO / ID3v2 (WAV): WAV-Dateien können ebenfalls ID3-Tags tragen. Das DJ-Tool unterstützt dies vollständig.

• VorbisComment (FLAC, OGG): Metadatenformat für verlustfreie Formate – wird per tinytag gelesen.

Warum sind korrekte ID3-Tags für DJs wichtig?

• DJ-Programe zeigen Titel, Artist, BPM und Tonart direkt aus den Tags an.

• BPM-Werte im Tag ersparen erneutes Analysieren in der DJ-Software.

• Tonart (Camelot) ermöglicht harmonisches Mixen ohne Noten (z.B. A-Moll).

• Cover-Artwork erscheint auf Hardware-DJ-Playern auf dem Display.

6.2 Audiodateien laden

Auch hier hast Du die Möglichkeit, einzelne, mehrere oder einen kompletten Ordner mit Audio-Dateien zu laden.

• Dateien wählen ...: Einzelne oder mehrere Audiodateien laden. Alle Formate (MP3, WAV, FLAC, OGG, M4A, AAC, WMA, AIFF, OPUS) werden akzeptiert.

• Ordner wählen ...: Einen kompletten Ordner mit Audiodateien einlesen (nicht rekursiv, d. h. nur die Dateien direkt im Ordner, keine Unterordner).

Nach dem Laden erscheint jede Datei in der Dateiliste rechts. Ein Klick auf einen Eintrag öffnet den Track im Editor links.

6.2.1 Dateilisten-Farben

Die Dateiliste färbt Einträge nach Tag-Vollständigkeit:

• Schwarz: Sowohl Titel als auch Künstler-Tag sind vorhanden.

• Blau: Nur eines der beiden (Titel oder Künstler) ist vorhanden.

• Rot: Weder Titel noch Künstler-Tag sind vorhanden.

6.2.2 Suche und Sortierung

• Suchen-Eingabefeld: Filtert die angezeigte Liste nach dem eingetippten Text. Alle Batch-Operationen arbeiten immer auf der vollständigen Liste.

• Sortier-Dropdown: Sortiert die Anzeige nach Name, Titel, Künstler, Album, Album-Künstler, Jahr, Track-Nr, Genre, BPM, Tonart, Energie, Rating, Kommentar, Camelot.

6.3 Tag-Felder imDetail

Unter Tags bearbeiten werden alle verfügbaren Metadatenfelder angezeigt und sind direkt editierbar. Sofern ein Cover vorhanden ist, wird dieses ebenfalls dargestellt.

6.3.1 Titel (ID3-Frame: TIT2)

Der Tracktitel, so wie er auf dem Display des Hardware-DJ-Players oder in der DJ-Software erscheinen soll. Beispiel: "Bassline (Original Mix)". Unicode wird vollständig unterstützt.

6.3.2 Künstler (TPE1)

Der Haupt-Interpret des Tracks. Bei mehreren Künstlern üblich: "Artist 1 & Artist 2" oder "Artist 1, Artist 2".

6.3.3 Album (TALB)

Der Album- oder EP-Name. Für Single-Releases: häufig identisch mit dem Titel oder z. B. "Bassline EP".

6.3.4 Album-Künstler (TPE2)

Wird genutzt bei Compilations oder VA-Alben (Various Artists). Beispiel: "Various Artists". Bibliotheksprogramme nutzen TPE2 zur Album-Gruppierung – alle Tracks mit gleichem Album-Künstler erscheinen unter demselben Ordner.

6.3.5 Jahr (TDRC)

Das Veröffentlichungsjahr als vierstellige Zahl, z. B. "2024".

6.3.6 Track-Nr. (TRCK)

Position des Tracks im Album. Format: "5" oder mit Gesamtanzahl "5/12".

6.3.7 Genre (TCON)

Das Musik-Genre. Freier Text. Empfehlung: konsistente Schreibweise verwenden, z. B. immer "Techno" statt manchmal "techno" oder "TECHNO". Die Funktion "Genre normalisieren" im Batch & Export-Tab hilft dabei.

6.3.8 BPM (TBPM)

Beats per Minute – das Tempo des Tracks. Wird entweder manuell eingetragen oder automatisch per BPM-Analyse ermittelt. Ganzzahliger Wert, z. B. "128".

6.3.9 Tonart (TKEY)

Die musikalische Tonart in Standard-Notation: "C", "C#m", "Dm", "F#" usw. Groß-B = Dur, kleines m = Moll. Das DJ-Tool zeigt den zugehörigen Camelot- Code (z. B. "12A") direkt neben dem Eingabefeld an.

6.3.10 Energie (TXXX:Energy)

Ein Energie-Wert von 1 bis 10, der die Intensität des Tracks beschreibt. Wird als TXXX-Frame mit der Beschreibung "Energy" gespeichert, dem gleichen
Format, das Mixed In Key, Rekordbox und Traktor verwenden.
Beispiel: Intro-Track = 2–3, Peak-Time-Banger = 9–10.

6.3.11 Label (TPUB)

Das Plattenlabel der Veröffentlichung, z. B. "Drumcode", "Ninja Tune", "Self- Released".

6.3.12 Komponist (TCOM)

Der Komponist oder Produzent – oft identisch mit dem Künstler, kann aber bei Remix-Releases abweichen.

6.3.13 Rating (POPM) – Sternbewertung 1–5

Eine persönliche Bewertung des Tracks von 1 bis 5 Sternen. Wird als POPM- Frame gespeichert. Neben dem Eingabefeld erscheint automatisch die Stern- Darstellung, z. B. ★★★☆☆ für 3.

6.3.14 Kommentar (COMM)

Freitext-Kommentar ohne festes Format. Beispiele: "Lieblings-Opener", "Habe ich beim Festival gespielt", "Original Mix", Remix-Notizen.

6.4 Online-Quellen: MusicBrainz, Discogs, Spotify

Das DJ-Tool kann Metadaten automatisch aus drei verschiedenen Online-Datenbanken beziehen. Die Quelle wird über die Radiobuttons ausgewählt.

6.4.1 MusicBrainz

MusicBrainz ist eine freie, gemeinschaftlich gepflegte Musikdatenbank. Keine Anmeldung erforderlich, keine API-Keys nötig. Was wird gesucht: Die App sendet Künstler + Titel – bei Treffer werden Titel, Künstler, Album, Album- Künstler, Jahr und Genre eingetragen. Zusätzlich lädt die App automatisch das Cover-Artwork aus dem Cover Art Archive (coverartarchive.org).

Hinweis: MusicBrainz ist besonders stark bei bekannten Releases aus Rock, Pop, Hip-Hop und klassischer Musik. Für Vinyl-Releases aus der Clubszene (alte Techno/House-Weißlabel-Platten) ist Discogs oft vollständiger.

6.4.2 Discogs

Discogs ist die weltweit größte Plattendatenbank, spezialisiert auf physische Releases. Besonders stark für elektronische Musik, DJ-Releases und Remixes.

Einmalige Verbindung per OAuth: Discogs erfordert ein kostenloses Konto und eine einmalige Anmeldung über den Button "Discogs verbinden ...". Dabei öffnet sich ein Browser-Fenster, in dem Du Dich einloggst und der App Zugriff gewährst.

Der Zugriffstoken wird lokal gespeichert (~/.dj_tool_discogs_token.json) und muss nur einmal eingerichtet werden.

6.4.3 Spotify

Spotify enthält praktisch jeden modernen Track mit korrektem Titel, Künstler, Album und Albumcover. Darüber hinaus liefert die Spotify Web API über den Endpunkt /v1/audio-features auch Tempo (BPM) und Tonart, die automatisch in die entsprechenden Felder eingetragen werden.

Als besonderes Feature ist es möglich, die ID3-Tags über Spotify zu beziehen.

Hierfür benötigst Du eigene API-Credentials (Client ID + Client Secret) – jeder Nutzer verwendet seinen eigenen kostenlosen Spotify-Developer-Zugang. Das ist erforderlich, weil Spotifys Nutzungsbedingungen das Einbetten eines geteilten API-Keys in verteilte Software ausdrücklich untersagen.

Spotify-API-Key einrichten (einmalig, ca. 2 Minuten)

• Öffne developer.spotify.com/dashboard und melde Dich mit Deinem Spotify-Konto an (kostenlos).

• Klicke auf "Create app".

• Vergib einen beliebigen App-Namen (z. B. "DJ Tool"), trage als Redirect URI http://localhost ein und bestätige.

• Wechsle zu Settings → kopiere Client ID und Client Secret.

• Klicke in der App auf "Spotify verbinden ..." und trage Client ID und Client Secret ein.

Die Credentials werden lokal in ~/.dj_tool_spotify.json gespeichert und müssen nur einmal eingetragen werden.

Zusammenfassung: Spotify liefert Titel, Künstler, Album, Album-Künstler, Jahr, BPM, Tonart und Cover-Artwork – ein vollständiges Set aller wichtigen Metadaten in einem Schritt.

6.5 Schaltflächen im Detail

6.5.1 Online einlesen

Liest die Metadaten des aktuell ausgewählten Tracks aus der gewählten Online-Quelle ein und füllt alle passenden Felder im Editor aus. Cover- Artwork wird ebenfalls geladen, wenn vorhanden.

Wichtig: "Online einlesen" verändert nichts an der Datei. Erst "Speichern" schreibt die Tags dauerhaft in die Datei. Vor jedem "Online einlesen" wird automatisch ein Undo-Snapshot gespeichert.

6.5.2 Speichern

Schreibt alle geänderten Felder und das Cover-Artwork als ID3-Tags in die Datei. Vor dem Speichern erscheint ein Diff-Dialog (Feld | Vorher | Nachher): Nur Felder mit tatsächlichen Änderungen werden aufgelistet. Bei "Abbrechen" wird nichts gespeichert.

6.5.3 Aus Dateinamen

Extrahiert Künstler und Titel aus dem Dateinamen. Muster: "Künstler - Titel".

Beispiel:

• "DJ Cataclysm - Bassline.mp3" → Künstler: "DJ Cataclysm", Titel: "Bassline"

• "01. DJ Cataclysm - Dark Matter.mp3" → Track-Nr.: "01", Künstler: "DJ Cataclysm", Titel: "Dark Matter"

Praktisch für Ordner mit schlecht getaggten Tracks, bei denen der Dateiname das korrekte Muster "Künstler - Titel" trägt.

BPM + Tonart analysieren:

Analysiert das Audio des aktuell geladenen Tracks und ermittelt BPM und Tonart vollständig lokal – ohne Internetverbindung.

BPM-Erkennung:

• Das Audio wird auf 22.050 Hz heruntergerechnet (maximal 90 Sekunden analysiert).

• Ein STFT (Short-Time Fourier Transform) berechnet den Spektralfluss – hohe Werte entsprechen Beats/Impulsen.

• Autokorrelation bestimmt das dominierende Tempo im Bereich 60–200 BPM.

• Oktav-Auflösung: Werte unter 80 BPM werden verdoppelt, über 160 BPM halbiert.

Tonart-Erkennung (Krumhansl-Schmuckler-Algorithmus, 1990):

• STFT im Bereich 65–2100 Hz (relevante Grundtöne der meisten Instrumente).

• Chromagramm: 12 Chroma-Klassen (je eine pro Halbton), über alle Frames gemittelt.

• Korrelation gegen Dur- und Moll-Profile → die Tonart mit der höchsten Korrelation wird ausgewählt.

• Ergebnis in Standard-Notation ("C", "F#m" usw.) + Camelot-Code direkt daneben.

Hinweis: BPM- und Tonart-Werte erscheinen zunächst nur im Editor. "Speichern" ist nötig, um sie in die Datei zu schreiben.

6.5.4 Rückgängig

Macht die letzte Änderung im Editor rückgängig. Die App speichert automatisch Snapshots vor: "Online einlesen", "Aus Dateinamen", "BPM + Tonart analysieren" und "Tags einfügen" (bis zu 20 Snapshots). Wechsel zu einer anderen Datei löscht den Undo-Stapel.

6.5.5 Tags kopieren / Tags einfügen

"Tags kopieren" speichert alle Felder und das Cover-Artwork in eine interne Zwischenablage. "Tags einfügen" überträgt diese Werte auf eine andere Datei. Praktisch: Album-Infos von einem Referenz-Track auf mehrere andere übertragen.

6.5.6 Fingerprint-Suche (AcoustID)

Die Fingerprint-Suche identifiziert einen Track anhand seines Klangs – unabhängig von Dateinamen oder vorhandenen Tags. Nützlich für:

• Tracks ohne jegliche Tags ("unbekannte" Dateien).

• Tracks mit falschen oder veralteten Tags.

• Eigene Edits/Bootlegs eines bekannten Originals.

Ablauf:

• Audio-Fingerprint berechnen: Das externe Tool fpcalc (Chromaprint) analysiert die Audiodatei und erzeugt einen kompakten akustischen Fingerabdruck. Dieser ist unabhängig von Lautstärke, Bitrate oder kleinen Qualitätsunterschieden.

• AcoustID-Datenbank abfragen: Fingerprint und Dateilänge werden an die AcoustID-API gesendet. Die Datenbank gibt Treffer mit Konfidenz-Wert (0–1) zurück. Ein Wert über 0,7 gilt als zuverlässig.

• MusicBrainz-IDs auflösen: AcoustID liefert MusicBrainz-Recording-IDs. Darüber werden Titel, Künstler, Album und Jahr aus MusicBrainz geladen.

Voraussetzungen:

• fpcalc (Chromaprint) muss separat installiert sein:

• macOS: brew install chromaprint

• Windows: fpcalc.exe aus den GitHub-Releases laden und neben ffmpeg.exe ablegen

• Ein eigener AcoustID-API-Key ist erforderlich (kostenlos unter acoustid.org). Er wird beim ersten Klick abgefragt und in ~/.dj_tool_acoustid.json gespeichert.

Ohne fpcalc bleibt der Fingerprint-Button deaktiviert und ist nicht zugänglich.

6.6 Cover-Artwork

Das Cover-Artwork wird als APIC-Frame (Attached Picture) im ID3-Tag gespeichert. Es erscheint in DJ-Software, auf CDJ-Displays und in Music-Apps.

• Automatisch via "Online einlesen" (von MusicBrainz, Discogs oder Spotify).

• Manuell via "Wählen ...": Öffnet einen Datei-Dialog für JPEG/PNG-Dateien. Empfehlung: mindestens 600 × 600 Pixel, unter 500 KB.

• "Entfernen" löscht das APIC-Frame aus dem ID3-Tag.

6.7 Track anhören

Mit den Schaltflächen Abspielen und Stop kannst Du einen ausgewählten Song zum Reinhören starten bzw. stoppen. Der Player gibt direkt über das Standard-Audiogerät wieder und stoppt automatisch bei Auswahl einer anderen Datei.

Einschränkung: Auf ARM64-Macs unter Windows (Parallels) steht kein Audio-Interface zur Verfügung – der Player ist in diesem Fall nicht nutzbar.

7 Batch & Export

Der Navigationspunkt Batch & Export enthält alle Werkzeuge, die auf die gesamte geladene Dateiliste wirken. Dateien müssen zuerst im Tab ID3-Tags geladen werden.

Rechts im Batch-Tab erscheint eine Übersicht der geladenen Dateien. Ein Klick auf einen Eintrag wechselt direkt in den ID3-Tags-Tab und öffnet die Datei im Editor.

Wichtig: Alle Batch-Operationen arbeiten immer auf der vollständigen geladenen Dateiliste, nicht auf der gefilterten Anzeige.

7.1 Online-Tagging

7.1.1 Alle taggen & speichern

Führt für jeden Track automatisch eine Online-Suche bei der gewählten Quelle durch und speichert die Ergebnisse sofort. Zwischen den Anfragen wird eine Pause von mindestens 1 Sekunde eingehalten (API-Vorgabe). Ist kein Treffer vorhanden, bleibt die Datei unverändert.

7.1.2 Cover für alle ohne Bild

Sucht für Tracks ohne Cover-Artwork automatisch ein passendes Bild und speichert es als APIC-Frame in die Datei. Tracks mit vorhandenem Cover werden übersprungen. Alle bestehenden Tags (Titel, Künstler, BPM usw.) bleiben vollständig erhalten.

7.2 Analyse

7.2.1 BPM + Tonart analysieren

Identisch zur Einzel-Analyse, aber für alle geladenen Tracks nacheinander. Die Ergebnisse werden sofort in die ID3-Tags geschrieben.

7.2.2 ReplayGain berechnen

ReplayGain ist ein Lautstärke-Normalisierungsstandard, der die Audiodaten nicht verändert, sondern einen Gain-Wert als Metadaten-Tag speichert. Kompatible Abspielerprogramme (foobar2000, VLC, MusicBee) lesen diesen Wert und passen die Wiedergabelautstärke dynamisch an.

ReplayGain vs. LUFS-Normalisierung

• Verändert die Audiodaten permanent.

• Geeignet für Streaming-Plattformen und DJ-Software die kein ReplayGain unterstützt.

ReplayGain

• Verändert die Audiodaten nicht – nur ein Tag wird gesetzt.

• Nur in ReplayGain-fähigen Playern wirksam (foobar2000, VLC, MusicBee, Clementine).

• Ideal für eine Sammlung ohne Qualitätsverlust normalisieren.

Wie wird der ReplayGain berechnet?

Referenzpegel: −18 LUFS (ReplayGain 2.0 Standard, ITU-R BS.1770-4)

Formel:

replaygain_track_gain = −18 − (gemessener LUFS des Tracks) [in dB]

Beispiele:

• Track misst −12 LUFS → Gain = −18 − (−12) = −6,0 dB → Player dreht um 6 dB herunter

• Track misst −22 LUFS → Gain = −18 − (−22) = +4,0 dB → Player dreht um 4 dB herauf

• Track misst −18 LUFS → Gain = 0,0 dB → keine Anpassung

7.2.3 Plattform-Vergleich

Misst die LUFS-Lautheit jedes geladenen Tracks und zeigt an, wie viel Gain jede Streaming-Plattform anwenden würde:

• Spotify: −14 LUFS

• Apple Music: −16 LUFS

• YouTube: −14 LUFS

• Tidal: −14 LUFS

• Beatport: −8 LUFS (kein automatisches Loudness Management)

• SoundCloud: −8 LUFS (kein automatisches Loudness Management)

Positiver Wert in der Ausgabe: Plattform dreht Track hoch (Track leiser als Ziel). Negativer Wert: Plattform würde herunterdrehen (Track lauter als Ziel).

Für Beatport und SoundCloud: Da diese kein automatisches Loudness-Management betreiben, hört man exakt das, was hochgeladen wurde. Tracks für diese Plattformen sollten auf −8 bis −10 LUFS normalisiert werden.

7.3 Batch-Umbenennen

Benennt alle geladenen Dateien nach einem frei definierbaren Schema um.

Beispiele:

• {artist} - {title} → "DJ Cataclysm - Bassline.mp3"

• {tracknumber} - {artist} - {title} → "07 - Artist X - My Track.wav"

• {bpm}_{artist}_{title} → "128_DJ Cat_Dark Matter.mp3"

Fehlende Tags: Ist ein Feld leer, wird der Token durch einen leeren String ersetzt. Die Dateiendung (.mp3, .wav usw.) bleibt immer erhalten.

Immer die Vorschau prüfen! Das Umbenennen kann mit "Umbenennen rückgängig" zurückgesetzt werden (bis zu 20 Schritte).

7.4 Batch-Feld setzen

Setzt ein bestimmtes Metadatenfeld für alle geladenen Dateien auf denselben Wert. Verfügbare Felder: Genre, Album-Künstler, Label, Komponist, Kommentar. Ein leerer Wert löscht das Feld.

7.4.1 Genre normalisieren

Vereinheitlicht Schreibweisen häufiger Genre-Bezeichnungen, z.B.:

• "techno" → "Techno"

• "DRUM AND BASS" → "Drum and Bass"

• "house music" → "House Music"

7.5 Auto-Sortierung

Sortiert die geladenen Dateien automatisch in Unterordner nach einem frei definierbaren Schema.

Verfügbare Tokens:

• {genre} → Genre-Tag, z. B. "Techno"

• {artist} → Künstler-Tag

• {year} → Jahr aus dem Datum-Tag, z. B. "2024"

• {title} → Titel-Tag

Verfügbare Tokens in der Auto-Sortierung: {genre}, {artist}, {year}, {title}. Kein {album}, {tracknumber} oder {bpm}.

7.5.1 Beispiel-Schemas und entstehende Ordnerstrukturen

• {genre}/{artist} → Techno/DJ Cataclysm/Bassline.mp3

• {genre}/{year} → Techno/2024/ (alle Techno-Tracks aus 2024)

• {genre}/{artist}/{year} → Techno/DJ Cataclysm/2024/Bassline.mp3

• {year} → alle Tracks nur nach Jahr sortiert

7.5.2 Was passiert bei fehlenden Tags?

• Fehlendes Genre → Ordner "Unknown Genre"

• Fehlender Artist → Ordner "Unknown Artist"

• Fehlendes Jahr → Ordner "Unknown Year"

7.5.3 Verschieben vs. Kopieren

• Verschieben: Datei wird aus dem Quellordner entfernt. Vorsicht bei erster Nutzung!

• Kopieren: Datei bleibt im Quellordner, wird zusätzlich im Zielordner abgelegt. Empfohlen für den ersten Einsatz.

Immer die Vorschau prüfen bevor die Operation bestätigt wird.

7.6 CSV & Export

7.6.1 CSV exportieren

Speichert alle Metadaten der geladenen Tracks als semikolon-getrennte CSV- Datei mit UTF-8 BOM-Encoding (Excel-kompatibel).

Enthaltene Spalten: Dateiname · Titel · Künstler · Album · Album-Künstler · Jahr · Track-Nr. · Genre · BPM · Tonart · Energie · Label · Komponist · Rating · Kommentar

7.6.2 CSV importieren

Liest eine bearbeitete CSV-Datei zurück. Die Zuordnung erfolgt über den Dateinamen. Nicht gefundene Dateien werden übersprungen und im Log vermerkt.

Typischer Workflow:

• Tracks laden, CSV exportieren.

• CSV in Excel öffnen: Felder bearbeiten (Genre für alle Tracks setzen, Jahreszahlen korrigieren, fehlende Titel ergänzen).

• Bearbeitete CSV zurückimportieren → alle gefundenen Tracks werden aktualisiert.

7.6.3 Rekordbox XML

Erzeugt eine XML-Datei im DJ_PLAYLISTS-Format für Pioneer Rekordbox 6. Enthält Titel, Künstler, Album, Genre, BPM (2 Nachkommastellen) und Tonart. Import: Datei → Bibliothek → Rekordbox XML → Importieren.

7.6.4 Traktor NML / Serato M3U

Exportiert eine Sammlung für Native Instruments Traktor (NML) bzw. eine Playlist-Datei für Serato DJ (M3U).

7.6.5 Gespeicherte Tags

Das DJ-Tool schreibt zwei TXXX-Frames in die ID3-Tags:

• replaygain_track_gain: z. B. "-6.00 dB" – der anzuwendende Gain-Wert.

• replaygain_track_peak: z. B. "0.950000" – normierter Peak-Wert (1.0 = 0 dBFS).

ReplayGain und LUFS-Normalisierung schließen sich nicht aus: Ein Track kann gleichzeitig auf −14 LUFS normalisiert UND mit einem ReplayGain-Tag versehen sein. In den meisten DJ-Setups ist LUFS-Normalisierung die praktischere Lösung.

7.7 Duplikate

Duplikate suchen erkennt doppelt vorhandene Tracks anhand von Künstler und Titel (Groß-/Kleinschreibung wird ignoriert). Gefundene Duplikate werden im Ausgabe-fenster aufgelistet. Nützlich, um redundante Kopien in der Bibliothek zu identifi-zieren.

Das Tool löscht keine Dateien automatisch. Der Nutzer entscheidet welche Version behalten wird.

7.8 Harmonic Mix

7.8.1 Das Camelot-Wheel

Das Camelot-Wheel ordnet jeder der 24 Tonarten, eine Kombination aus Zahl (1–12) und Buchstabe (A=Moll, B=Dur) zu. Harmonisch kompatibel sind: gleiche Zahl (A↔B), Nachbarzahlen (±1).

Vollständige Zuordnung (Camelot → Tonart):

1A = Am / 1B = C
2A = Em / 2B = G
3A = Bm / 3B = D
4A = F#m / 4B = A
5A = C#m / 5B = E
6A = G#m / 6B = B
7A = D#m / 7B = F#
8A = Bbm / 8B = Db
9A = Fm / 9B = Ab
10A = Cm / 10B = Eb
11A = Gm / 11B = Bb
12A = Dm / 12B = F

7.8.2 Camelot-Rad anzeigen

Öffnet ein interaktives Camelot-Wheel als modales Fenster. Äußerer Ring: Dur (B). Innerer Ring: Moll (A). Orangefarbene Punkte zeigen Tracks aus der geladenen Dateiliste in diesem Camelot-Feld.

7.8.3 Harmonisch sortieren

Sortiert die geladene Dateiliste nach Camelot-Nummer (1→12), dann Buchstabe (B vor A). Aufeinanderfolgende Tracks sind so harmonisch miteinander kompatibel – ideal für die Setlist-Planung.

8 Dateiinfos

Unter Dateiinfos werden technische Details zu den Tracks aufgelistet, die im Tab ID3-Tags geladen wurden.

Spalten der Tabelle:

• Dateiname – vollständiger Dateiname.

• Format – Audioformat (MP3, WAV, FLAC usw.).

• Samplerate – Abtastrate in Hz (z. B. 44.100, 48.000).

• Bit-Tiefe – Auflösung in Bit (z. B. 16, 24 Bit; "–" bei MP3).

• Kanäle – 1 = Mono, 2 = Stereo.

• Tracklänge – Spielzeit als mm:ss.

• Größe – Dateigröße in MB.

• BPM – Wert aus dem ID3-Tag (TBPM).

• Tonart – Wert aus dem ID3-Tag (TKEY).

• kbps – Bitrate (relevant für MP3/AAC).

Die Tabelle wird aktualisiert, wenn sich die geladene Dateiliste ändert. Ein Klick auf eine Spaltenüberschrift sortiert die Tabelle nach diesem Wert.

9 Updates

Über die Schaltfläche Auf Updates prüfen kann eine neuere Version der Software heruntergeladen werden. Die App holt eine kleine JSON-Datei (version.json) vom Server und vergleicht die enthaltene Versionsnummer mit der installierten Version.

• Keine neuere Version verfügbar → Meldung "Du hast die aktuelle Version".

• Neuere Version verfügbar → Dialog mit Versionshinweis und Download-Link (djcataclysm.com).

Dabei werden keine persönlichen Daten übertragen.

9.1 Changelog

Eine vollständige Übersicht aller Änderungen je Version ist unter djcataclysm.com/changelog.html verfügbar.

9.2 Hilfe

Die Schaltfläche Hilfe öffnet ein Popup mit den Links zur Website und dem Handbuch.

Außerdem wird die Kontakt-E-Mail-Adresse angezeigt.

Viel Spaß im Mix!

DJ Cataclysm

10 Marken und Urheberrechte Dritter

Die in diesem Handbuch u.U. genannten Produkt- und Markennamen sind Eigentum ihrer jeweiligen Inhaber. Rekordbox ist eine eingetragene Marke der Pioneer DJ Corporation. Serato ist eine eingetragene Marke der Serato Audio Research Ltd. Traktor ist eine eingetragene Marke der Native Instruments GmbH. Mixed In Key ist eine Marke der Mixed In Key LLC. Spotify ist eine eingetragene Marke der Spotify AB. Apple Music und macOS sind Marken der Apple Inc. YouTube ist eine Marke der Google LLC. Tidal ist eine Marke der Aspiro AB. SoundCloud ist eine Marke der SoundCloud Ltd. Beatport ist eine Marke der Beatport, LLC. Discogs ist eine Marke der Zink Media, LLC. Windows ist eine eingetragene Marke der Microsoft Corporation. foobar2000 ist ein Produkt von Peter Pawlowski.

MusicBrainz und AcoustID sind Projekte der MetaBrainz Foundation. ffmpeg und Chromaprint sind freie Open-Source-Projekte unter ihren jeweiligen Lizenzen.

DJ Cataclysm – DJ-Tool ist weder mit den genannten Unternehmen, Organisationen oder Projekten verbunden noch wird es von diesen gesponsert oder befürwortet. Die Nennung der Marken erfolgt ausschließlich zu Zwecken der Kompatibilitäts-beschreibung und Produktidentifikation.

Lizenzen und Drittanbieter-Software

Überblick

Dieses Dokument listet alle Software-Bibliotheken und externen Dienste, die in der Anwendung »DJ Cataclysm – DJ-Tool« eingesetzt werden. Die App läuft auf macOS (Apple Silicon) sowie Windows 10/11. Für jede Komponente werden Lizenz, Version, Verwendungszweck und Umfang der Nutzung dokumentiert.

Enthaltene Features:

• Lautheits-Normalisierung (WAV + MP3)
• Audio-Konvertierung (alle Formate → MP3/WAV/FLAC)
• ID3-Tag-Editor (Titel, Künstler, Album, Jahr, Track-Nr., Genre, BPM, Tonart/Key, Energie, Label (TPUB), Komponist (TCOM), Rating (POPM, 1–5 Sterne), Kommentar, Cover-Art)
• automatische BPM-Erkennung (Autocorrelation der Onset-Hüllkurve)
• automatische Tonart-Erkennung (Krumhansl-Schmuckler 1990, Chroma-Profil- Korrelation)
• Batch-Umbenennen nach Tag-Schema
• Felder aus Dateinamen befüllen
• Tag-Diff vor dem Speichern
• Batch-Feld setzen für alle geladenen Dateien
• Sort- und Filterfunktion in der Dateiliste
• Markierung fehlender Tags (rot/amber/weiß)
• Cover-Art-Anzeige und -Einbettung (APIC-Frame)
• automatischer Cover-Fetch über Cover Art Archive
• Online-Tag-Suche via MusicBrainz oder Discogs (OAuth 1.0a)
• Mini-Audioplayer (Vorschau-Wiedergabe im ID3-Editor)
• Trackdauer-Anzeige in der Dateiliste
• LUFS-Analyse ohne Normalisierung (nur messen, keine Dateiänderung)
• CSV-Export/Import der ID3-Tags (Excel-kompatibel)
• Tags kopieren/einfügen zwischen Tracks
• Undo für Tag-Änderungen (bis 20 Schritte)
• Rekordbox-XML-Export (DJ_PLAYLISTS-Format, Rekordbox 6)
• Traktor NML-Export
• Serato M3U-Export
• Batch & Export-Tab (Batch-Umbenennen, Batch-Feld setzen, Auto-Sortierung, Duplikate-Erkennung)
• Online-Tagging via Spotify (Client Credentials)
• AcoustID-Fingerprint-Suche (optionaler fpcalc-Binary)
• ReplayGain-Berechnung (ReplayGain 2.0, −18 LUFS Referenz)
• Plattform-Vergleich (Spotify, Apple Music, YouTube, Tidal, Beatport, SoundCloud)
• Camelot-Rad-Visualisierung
• harmonische Sortierung nach Camelot-Code
• Genre-Normalisierung
• Dateiinfos-Tab (Format, Samplerate, Bit-Tiefe, Kanäle, Dauer, Größe)
• Batch-Cover-Fetch für alle Tracks ohne Bild

Zweisprachige Oberfläche (DE / EN): Sprachumschaltung per Dropdown in der Kopfzeile, Einstellung wird in ~/.dj_tool_config.json gespeichert.

Update-Funktion: Prüfung auf neue App-Versionen per Schaltfläche „Auf Updates prüfen" in der Kopfzeile (zusätzlich im Menü: Hilfe → Auf Updates prüfen …) (HTTP-Abfrage einer Versions-JSON auf dem Server; bei verfügbarem Update wird Download-Link im Browser geöffnet).

ffmpeg ist ab dieser Version vollständig im macOS-Bundle enthalten (statischer arm64-Build aus imageio-ffmpeg v7.1). Der Nutzer muss nichts separat installieren.

Komponenten-Übersicht

Komponente Lizenz Version Verwendungszweck Umfang der Nutzung

Python 3 PSF License 2.0

3.14.2 (macOS) / 3.12.9 (Windows)

Laufzeitumgebung. Standardbibliotheken: tkinter, struct, json, urllib, threading, subprocess, platform, sys, io, hmac, hashlib, base64, secrets, webbrowser.

Vollständig ins App-Bundle eingebettet via PyInstaller. Keine Änderungen.

(kommerziell frei)

pyloudnorm MIT License

0.2.0 Lautheitsmessung und Gain-Berechnung nach ITU-R BS.1770-4. Ziel: −14 LUFS / −1 dBTP.

Als Python-Modul importiert und ins Bundle eingebettet. Keine Modifikation.

(kommerziell frei)

soundfile BSD 3-Clause

0.13.1 Lesen und Schreiben von WAV- und FLAC- Audiodateien als NumPy-Float-Arrays.

Als Python-Modul importiert und ins Bundle eingebettet. Keine Modifikation.

(kommerziell frei)

numpy BSD 3-Clause

2.4.4 Verarbeitung von Audio-Sample-Arrays (pyloudnorm, soundfile). Direkt genutzt für BPM- und Tonart-Detection: Autocorrelation, Chroma-Profil-Korrelation (Krumhansl- Schmuckler).

Als Python-Modul importiert. Keine Modifikation.

(kommerziell frei)

scipy BSD 3-Clause

1.17.1 Signal-Verarbeitung für BPM- und Tonart- Detection: STFT (scipy.signal.stft), Resampling (resample_poly), Korrelationsberechnung (numpy.corrcoef). Bereits indirekt über pyloudnorm.signal im Bundle enthalten.

Als Python-Modul importiert und ins Bundle eingebettet. Keine Modifikation.

(kommerziell frei)

tinytag MIT License

2.2.1 Fallback-Lesebibliothek für Metadaten (FLAC, OGG, M4A, AIFF). Liest auch BPM.

Als Python-Modul importiert. Keine Modifikation.

(kommerziell frei)

sounddevice MIT License

0.5.5 Audio-Wiedergabe im ID3-Tab (Mini-Player: Abspielen, Pause, Stop, Positionsanzeige). Optionale Abhängigkeit — bei Fehlen erscheint ein Hinweistext statt der Player-Schaltflächen.

Optionaler Import (_HAS_SD- Flag). Ins Bundle eingebettet wenn vorhanden. Keine Modifikation.

(kommerziell frei)

Pillow (PIL) HPND License**

12.2.0 Dekodierung und Skalierung von JPEG-/PNG- Cover-Art für die Thumbnail-Anzeige im ID3- Editor (128 × 128 px).

Als Python-Modul importiert und ins Bundle eingebettet. Nur UI- Vorschau — APIC-Rohdaten-

(kommerziell frei)

Speicherung erfolgt ohne Pillow.

Spotify Web API Freier Webdienst (mit Registrierung)

GPL 2.0

7.1 MP3-Dekodierung (PCM-Pipe), MP3- Neukodierung nach Normalisierung, Audio- Konvertierung (alle Formate → MP3/WAV/FLAC), Bitrate-Erkennung.

Statischer arm64-Build, eingebettet in Contents/Frameworks/ des macOS-Bundles. Externer Prozess via subprocess — keine Verlinkung, kein 'Derived Work'. Nutzer kann die Binary ersetzen (Dateisystem-Zugriff möglich).

(statischer Build

- konform umgesetzt

mit libx264/x265)

Online-Suche nach Titel, Künstler, Album, Jahr, Track-Nr., Cover-Art. Nutzer trägt eigene Client ID / Client Secret ein (Spotify Developer Dashboard).

Quelle:

imageio-ffmpeg v7.1

HTTP via urllib. Client Credentials Flow (kein OAuth-Token im Nutzer-Account). Rate-Limit per Code erzwungen. Kein Massenspeichern. AcoustID API + fpcalc

(Chromaprint) API: Freier Webdienst, API- Key erforderlich (kostenlos).

fpcalc-Binary: Chromaprint, LGPL 2.1 — optionale externe Abhängigkeit. fpcalc wird NICHT gebündelt; Nutzer installiert es separat (macOS: brew install chromaprint; Windows: fpcalc.exe neben ffmpeg.exe ablegen (github.com/acoustid/chromaprint/releases)). Fingerprint-Berechnung über fpcalc (subprocess), Lookup via AcoustID-API (urllib). Keine LGPL-Pflichten für unsere App, da keine Verlinkung. Feature bleibt deaktiviert, wenn fpcalc nicht gefunden wird. ffmpeg (macOS, gebündelt)

ffmpeg (Windows, beigelegt) LGPL 2.1

8.1 Gleiche Funktionen wie macOS-Version. ffmpeg.exe liegt neben der App- Executable im dist-Ordner. Externer Prozess via subprocess. Nutzer kann die Binary ersetzen.

(essentials-Build von

gyan.dev,

ohne GPL-Komponenten)

imageio-ffmpeg BSD 2-Clause

0.6.0 Stellt den statischen macOS arm64 ffmpeg- Build bereit, der ins Bundle eingebettet wird.

Nur im Build-Prozess (Binary wird kopiert). imageio-ffmpeg wird zur Laufzeit nicht importiert

(kommerziell frei)

und ist nicht im Bundle enthalten.

PyInstaller GPL 2.0 mit

6.20.0 Baut das macOS .app-Bundle und den Windows-Ordner aus dem Python-Skript.

Nur im Build-Prozess. Nicht an Endnutzer weitergegeben. Bootloader-Ausnahme erlaubt proprietäre kommerzielle Apps.

Bootloader-Ausnahme

(kommerziell frei*)

MusicBrainz API Freier Webdienst

— Online-Suche nach Titel, Künstler, Album, Jahr, Track-Nr.

Nur auf Nutzerinteraktion. HTTP via urllib. Rate-Limit ≥ 1 s per Code. User-Agent korrekt gesetzt.

- konform umgesetzt

Cover Art Archive API Freier Webdienst

— Automatischer Download von Album-Cover-Art nach erfolgreicher Tag-Suche.

Nur auf Nutzerinteraktion. HTTP via urllib. Gleicher User-Agent wie MusicBrainz. Fehler werden silent behandelt.

- konform umgesetzt

* GPL-Bootloader-Ausnahme: erlaubt proprietäre kommerzielle Apps ohne Quellcode-Offenlegung.

** HPND (Historical Permission Notice and Disclaimer): OSI-genehmigte permissive Lizenz, vergleichbar MIT/BSD.

ffmpeg — Einbettung und Lizenz-Details

macOS — statischer Build im Bundle

Ab dieser Version ist ffmpeg vollständig im macOS-App-Bundle enthalten. Der Nutzer muss nichts separat installieren.

• Quelle: imageio-ffmpeg Python-Package (BSD-2-Clause), Version 0.6.0
• ffmpeg-Binary: v7.1, statischer arm64-Build (Apple Silicon)
• Build-Konfiguration: --enable-gpl, inkl. libx264/libx265 → GPL 2.0
• Speicherort im Bundle: Contents/Frameworks/ffmpeg
• Eingebettet via PyInstaller: --add-binary "ffmpeg:."

Da ffmpeg ausschliesslich als externer Prozess aufgerufen wird (subprocess), entsteht kein 'Derived Work' unserer Anwendung. Die GPL gilt nur für ffmpeg selbst.

GPL-Anforderungen für die Verteilung des ffmpeg-Binaries:

• Urheberrechtshinweis: ffmpeg-Projekt (ffmpeg.org) mit Copyright-Vermerk
• Lizenz: GPL 2.0, zugänglich unter https://www.gnu.org/licenses/gpl-2.0.html
• Quellcode: verfügbar unter https://ffmpeg.org/download.html
• Austauschbarkeit: Nutzer können die Binary in Contents/Frameworks/ ersetzen

Windows — LGPL-Build beigelegt

Auf Windows wird ffmpeg.exe zusammen mit der Anwendung im Distributions- Ordner ausgeliefert. Die App sucht ffmpeg in folgender Priorität:

1. Neben der Executable (dist-Ordner) — bevorzugter Pfad 2. System-PATH: winget install Gyan.FFmpeg 3. Bekannte Pfade: C:\ffmpeg\bin\ffmpeg.exe C:\Program Files\ffmpeg\bin\ffmpeg.exe

Der beigelegte Build stammt von gyan.dev (Gyan Deshpande), LGPL 2.1 'essentials' (ohne GPL-Komponenten wie libx264). LGPL-Anforderung: Nutzer kann ffmpeg.exe ersetzen — gewährleistet durch die separate Datei im dist-Ordner.

ffmpeg-Erkennung im Code

_find_ffmpeg() sucht in folgender Priorität (wenn als Bundle gestartet):

1. Contents/Frameworks/ (macOS .app — --add-binary Zielort)

2. sys._MEIPASS/ (PyInstaller _internal/)

3. neben sys.executable (Windows: user legt ffmpeg.exe daneben)

4. shutil.which('ffmpeg') (System-PATH)

5. Bekannte Pfade (Homebrew, C:\ffmpeg\bin\, ...)

Plattform-Abstraktion im Code

Plattformunterschiede werden über Konstanten am Dateianfang gesteuert:

_WINDOWS = platform.system() == 'Windows'

FONT_UI = 'Segoe UI' if _WINDOWS else 'Helvetica Neue'

FONT_MONO = 'Consolas' if _WINDOWS else 'Menlo'

Build-Prozess

macOS (muss auf einem Mac mit Apple Silicon durchgeführt werden):

python3 -m PyInstaller --windowed --name "DJ Cataclysm - DJ- Tool" --onedir \

--add-binary "ffmpeg:." [--exclude-module ...] normalize_gui.py

Windows (muss auf einem Windows-Rechner durchgeführt werden):

python -m PyInstaller --noconsole --name "DJ Cataclysm - DJ- Tool" --onedir ^

--version-file version_info.txt [--exclude-module ...] normalize_gui.py

Nach dem Windows-Build: ffmpeg.exe (LGPL-Build von gyan.dev) in dist\DJ Cataclysm - DJ-Tool\ kopieren.

MusicBrainz und Cover Art Archive — Nutzungsbedingungen

MusicBrainz API

Die MusicBrainz-API ist kostenlos und kommerziell nutzbar. Umgesetzte Anforderungen:

• User-Agent:

_MB_UA = "DJ_Cataclysm_-_DJ-Tool_v1.0.0 (dj.cataclysm.contact@gmail.com)"

• Rate-Limiting: max. 1 Anfrage/Sekunde, per Code erzwungen (Einzelsuche + Batch).
• Datenspeicherung: Tags nur lokal in Nutzerdateien. Kein Cache, keine DB, kein Upload.
• Kommerzielle Nutzung: erlaubt laut musicbrainz.org/doc/About/Data_License.

Cover Art Archive API

Das Cover Art Archive (coverartarchive.org) wird nach einer erfolgreichen MusicBrainz-Suche automatisch abgefragt:

• Endpunkt: https://coverartarchive.org/release/{release_id}/front
• User-Agent: identisch mit MusicBrainz-Anfragen.
• Fehlerbehandlung: HTTP 404 oder Timeout werden silent behandelt.
• Speicherung: Cover wird als APIC-Frame in die Audiodatei geschrieben, nur wenn der Nutzer explizit auf »Speichern« klickt.

Hinweis zum Urheberrecht: Album-Cover-Art ist urheberrechtlich geschützt. Das Einbetten in eigene Musikdateien ist Standardpraxis bei Tag-Editoren (iTunes, foobar2000, MusicBrainz Picard). Die Verantwortung liegt beim Endnutzer.

Discogs API

Die Discogs-API wird als Alternative zu MusicBrainz für Online-Tag-Suche und Cover-Art-Download genutzt. Sie erfordert OAuth 1.0a-Authentifizierung:

• Authentifizierung: OAuth 1.0a Desktop-PIN-Flow (oob callback). Consumer Key/Secret fest in der App hinterlegt. Access-Token wird nach einmaliger Anmeldung in ~/.dj_tool_discogs_token.json lokal gespeichert.
• OAuth-Implementierung: vollständig mit Python-Standardbibliothek (hmac, hashlib, base64, secrets) — keine zusätzliche OAuth-Bibliothek erforderlich.
• Rate-Limiting: ≥ 1 Anfrage/Sekunde per Code erzwungen (_discogs_last_req).
• User-Agent: _DISCOGS_UA korrekt gesetzt.
• Datenspeicherung: Tags nur lokal in Nutzerdateien. OAuth-Token lokal in ~/.dj_tool_discogs_token.json. Kein Cache, keine DB, kein Upload.
• Nutzungsbedingungen: Discogs API erlaubt kommerzielle Nutzung bei korrekter OAuth-Authentifizierung und Einhaltung der Rate-Limits.

Gesamtbewertung für den kommerziellen Vertrieb

• Eingebettete Bibliotheken (pyloudnorm, soundfile, numpy, scipy, tinytag, Pillow, sounddevice): MIT/BSD/HPND — keine Copyleft-Pflichten, kommerziell uneingeschränkt.
• ffmpeg macOS (GPL, gebündelt): Nur Subprocess-Aufruf, kein Linking → kein 'Derived Work', unser App-Code ist nicht GPL-pflichtig. GPL-Pflichten erfüllt: Lizenzhinweis, Quellcode-Link, Binary austauschbar.
• ffmpeg Windows (LGPL, beigelegt): kein Linking → kein 'Derived Work'. LGPL- Pflicht: austauschbare ffmpeg.exe im dist-Ordner gewährleistet.
• imageio-ffmpeg: BSD-2-Clause, nur Build-Tool, nicht im Bundle enthalten.
• PyInstaller: nur Build-Tool, Bootloader-Ausnahme erlaubt proprietären Vertrieb.
• Pillow: HPND, uneingeschränkt kommerziell, vollständig ins Bundle eingebettet.
• MusicBrainz API: vollständig konform (User-Agent, Rate-Limiting, kein Massenspeichern).
• Cover Art Archive: technisch konform. Urheberrecht der Bilder beim jeweiligen Rechteinhaber — Verantwortung beim Endnutzer (Standardpraxis bei Tag- Editoren).
• Discogs API: konform (OAuth 1.0a, Rate-Limiting ≥ 1 s, User-Agent, Token lokal gespeichert). Kommerzielle Nutzung laut Nutzungsbedingungen erlaubt.
• Update-Funktion (Schaltfläche in der Kopfzeile + Menüpunkt Hilfe → Auf Updates prüfen …): Verwendet ausschließlich Python-Standardbibliothek (urllib, json, webbrowser, threading) — keine neue Abhängigkeit, keine Copyleft- Pflichten. paramiko (LGPL 2.1) wird nur im Entwickler-Upload-Skript genutzt, nicht ins App-Bundle eingebettet und nicht an Endnutzer weitergegeben. Kein Lizenz-Hindernis.
• BPM- und Tonart-Erkennung: Vollständig implementiert mit numpy (BSD) und scipy (BSD) — kein proprietäres Modell, keine neue Abhängigkeit mit Copyleft- Pflichten. Algorithmus: Krumhansl-Schmuckler-Schlüsselprofil-Korrelation (1990, Public Domain). TKEY-Frame nach ID3v2.3-Standard. Kein Lizenz-Hindernis.
• Spotify API: kein proprietäres SDK verwendet; nur urllib (Standardbibliothek). Keine Copyleft-Pflichten. API-Nutzung erfordert Nutzer-eigene Credentials (kein App-eigener Key). Konform mit Spotify Developer ToS für persönliche/nicht- kommerzielle Nutzung.
• AcoustID API: kostenloser Webdienst, API-Key vom Nutzer einzutragen. fpcalc (Chromaprint, LGPL 2.1): nur externer Prozessaufruf (subprocess), kein Linking → kein Derived Work, keine LGPL-Pflicht für die App. Feature ist optional und ohne fpcalc nicht zugänglich. Kein Lizenz-Hindernis.
• ReplayGain, Plattform-Vergleich, Camelot-Rad, Harmonic Sort, Genre- Normalisierung, Auto-Sortierung, Duplikate-Erkennung: Vollständig mit numpy (BSD), scipy (BSD), soundfile (BSD), Python-Standardbibliothek implementiert. Keine neuen Abhängigkeiten, keine neuen Lizenz-Pflichten.
• CSV-Export/Import, Tags kopieren/einfügen, Undo, Rekordbox-XML-Export, LUFS-Analyse, Mini-Audioplayer, Trackdauer, Discogs-OAuth: Vollständig mit Python-Standardbibliothek (csv, xml.etree.ElementTree) und bereits lizenzierten Abhängigkeiten (pyloudnorm, numpy, scipy, soundfile) implementiert. Keine neuen Bibliotheken, keine neuen Lizenz-Pflichten.

Gesamturteil: Keine Lizenz-bedingten Hindernisse für kommerziellen Verkauf als proprietäre Closed-Source-Software auf macOS und Windows.