rinkplanner/docs/findings-2026-11-10-mac-music.md
torsten e23520e630 fix: reuse identical music files instead of numbered copies
- compare size and SHA-256 before copying a track into the routine folder
- keep the file the current routine already references when content matches
- convert M4A/AAC into a scratch file and dedupe it by content
- extend playback tests for repeated loads and same-name variants
2026-11-10 20:27:25 +01:00

3.2 KiB
Raw Blame History

Findings – Musikwiedergabe auf macOS (2026-11-10)

Problem

Die Logs zeigten:

ERROR: Failed to decode mp3 file. Make sure it is a valid mp3 audio file.
ERROR: This AudioStreamMP3 does not have an audio file assigned to it.

Die betroffenen Dateien hießen .mp3, waren aber tatsächlich M4A/AAC-Container (ftypM4A). Godot spielt nur MP3, OGG Vorbis und WAV nativ ab. Zusätzlich wählt afconvert seinen Demuxer über die Dateiendung, sodass eine M4A-Datei mit .mp3-Endung auch dort zunächst scheiterte.

Umsetzung

  • Neue Hilfsklasse AudioFile (src/core/io/audio_file.gd):
    • erkennt MP3, OGG, WAV und ISO-Container (M4A/AAC/MP4) an den echten Dateibytes, nicht an der Endung;
    • lädt MP3/OGG/WAV über die Godot-Audio-Streams.
  • macOS-Konvertierung mit /usr/bin/afconvert:
    • Ausgabe als mono PCM-WAV, 44,1 kHz, 16 Bit;
    • -l 1 verhindert WAVE_FORMAT_EXTENSIBLE, das Godots WAV-Loader nicht akzeptiert;
    • --no-filler entfernt den FLLR-Block, den Godot ebenfalls nicht erwartet;
    • Dateien mit falscher Endung (z. B. M4A als .mp3) werden für die Konvertierung als temporäre .m4a-Kopie bereitgestellt.
  • load_music_from_path() konvertiert M4A/AAC beim Import und speichert das erzeugte WAV in user://routines/.
  • _load_music_stream() konvertiert auch bereits referenzierte Altdateien beim Laden automatisch und verwendet danach das WAV.
  • FileDialog bietet zusätzlich .m4a und .aac an; RoutineFile akzeptiert diese Endungen.
  • Nicht abspielbare Dateien zeigen in der Playback-Leiste „(nicht abspielbar)“ und einen erklärenden Tooltip.

Tests

Neue tests/run_audio_tests.gd:

  • Header-Erkennung für MP3, OGG, WAV und als .mp3 getarntes M4A.
  • Laden eines PCM-WAV.
  • macOS: WAV→M4A mit afconvert, M4A→WAV über AudioFile, Laden des Ergebnisses.
  • macOS: M4A als .mp3 wird über den Endungs-Fallback korrekt konvertiert.

./tools/test.sh führt den neuen Audiotest mit aus.

Grenzen

  • M4A/AAC wird nur auf macOS automatisch konvertiert. Windows/Linux brauchen weiterhin MP3, OGG oder WAV.
  • Die konvertierte WAV-Datei ist deutlich größer als das M4A-Original (mono 44,1 kHz, ca. 5 MB pro Minute), bleibt aber unter dem 64-MB-Limit für übliche Kür-Musik.

Nachtrag: keine nummerierten Musik-Duplikate

Jedes erneute Laden desselben Stücks legte bisher eine neue Kopie an (… 2.mp3, … 3.mp3, …), weil der Zielname nur auf Existenz geprüft wurde.

  • _resolve_music_copy_name() vergleicht jetzt Größe und SHA-256 des vorhandenen Ziels mit der Quelle.
  • Identischer Inhalt → die vorhandene Datei wird weiterverwendet (needs_copy = false). Das gilt auch für die Datei, die die aktuelle Kür bereits referenziert, sodass ein erneutes Laden den Namen gar nicht ändert.
  • Nur bei gleichem Namen und abweichendem Inhalt entsteht weiterhin ein nummerierter Name.
  • M4A/AAC wird zuerst in eine Scratch-Datei (user://_music_import_*.wav) konvertiert und danach inhaltsbasiert einsortiert; die Scratch-Datei wird immer entfernt.

Tests in run_playback_tests.gd: zweimal dasselbe Stück laden behält den Namen und erzeugt kein … 2.wav; ein anderes Stück gleichen Namens bekommt eine Nummer, die beim erneuten Laden stabil bleibt.