rinkplanner/docs/findings-2026-11-10-mac-music.md
torsten 6172d311bc feat: Sport-Theme, Küren-Verwaltung und Sync-Konflikte
- zentrales Sport-Theme für das Weißbrett
- Küren im Sync umbenennen, löschen und Musikzuordnung aufräumen
- Konfliktbereinigung mit Vorschau und gezieltem Löschen
- Sync nutzt saved_at aus der Kür statt Gerätezeit
- Schrittsequenzen über Mehrfachauswahl gruppieren
- Startskript aktualisiert den class_name-Cache bei Änderungen
2026-11-11 13:14:14 +01:00

97 lines
4 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.
## Nachtrag (2026-11-11): Entscheidungsdialog statt Nummern-Suffix
Der nummerierte Name bei abweichendem Inhalt entfällt. Der Import zeigt
jetzt einen Dialog mit **Bestehende verwenden**, **Überschreiben** und
**Abbrechen**:
- **Bestehende verwenden** referenziert die vorhandene Datei, ohne sie zu
verändern.
- **Überschreiben** ersetzt die vorhandene Datei atomar unter demselben
Namen.
- **Abbrechen** lässt Datei und Kür unverändert.
- Identischer Inhalt wird weiterhin ohne Nachfrage wiederverwendet.
- Ein Zahlen-Suffix wie `… 2.mp3` wird nie mehr erzeugt.
`_resolve_music_copy_name()` ist dafür zur Coroutine geworden und wartet auf
das Signal `music_conflict_decided`; die eigentliche Kopie übernimmt
`_store_music_copy()` über eine temporäre Datei und `.bak`-Rotation.