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

79 lines
3.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Findings – Musikwiedergabe auf macOS (2026-11-10)
## Problem
Die Logs zeigten:
```text
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.