# Audio Vision V2: lokale Einrichtung und Verwendung

Verifiziert am 2026-09-20 auf macOS arm64 mit Python 3.12. Eigene Umgebung: `~/skills/fl-stuido-enhance/.venv-analysis`. Versionen: WhisperX 3.8.6, Essentia 2.1b6.dev1389, Praat/Parselmouth 0.4.7. Vollständiger Paketstand: `scripts/requirements-analysis.txt`; kein plattformübergreifend getestetes Lockfile.

## Vorhandene Fähigkeiten

- Essentia: geschätztes Tempo, Beatpositionen und Onsets. Bekannte Projekt-Beats bleiben eine separate Referenz. Half-/Double-Time, Offbeats und ungenaue Anschläge prüfen.
- Praat: F0 und Burg-Formanten F1–F3 für isolierte Stimmen. Formanten in laut F0-Schätzung stimmlosen Bereichen werden ausgelassen. Rauheit, Doubles und Effekte können die Schätzung verfälschen. F0-Suchbereich 60–600 Hz; Formantgrenze 5500 Hz: technische Annahmen, keine Klangvorlieben.
- WhisperX: lokale Transkription plus Wort-/Zeichenausrichtung. Keine bestätigten Silben oder Phoneme; Text und Schnittgrenzen überprüfen. Korrigierter Text kann per Datei vorgegeben werden.
- HTML-Bericht mit Player, anklickbaren Wörtern, Zeitbereich und exportierbarer JSON-Annotation. Bilder und Messdaten liegen daneben. Kein synchroner A/B-Vergleich und keine Lautheitsanpassung.
- Quellen werden gelesen; `preview.wav` ist eine unnormalisierte Float-Kopie des gewählten Fensters. Keine Änderung am FL-Projekt und kein automatischer Schnitt.

Nicht vorhanden: direktes Hören durch den Hauptagenten, Wahrnehmungsmodell, Harmonie/Chroma oder ein allgemeiner Wohlklang-Score. LUFS/True Peak ist inzwischen separat über `scripts/measure_loudness.py` verfügbar; siehe [Vergleich und Review](comparison-review.md). Der V2-Einzeldatei-Viewer selbst bleibt unverändert.

## Aufruf

Aus dem Skill-Verzeichnis, mit absoluten Audio-/Ausgabepfaden:

```bash
MPLCONFIGDIR=/tmp/fl-vision-mpl .venv-analysis/bin/python scripts/analysis_v2.py /absolut/vocal.wav --out /absolut/report --role vocal --bpm 130 --timeline-offset 3.6923076923 --rhythm-audio /absolut/mix.wav --speech --language en
```

Pfade, BPM und Versatz sind Beispiele. `--language de` nutzt deutsche Erkennung/Ausrichtung; das deutsche Ausrichtungsmodell wird beim ersten Aufruf heruntergeladen und wurde hier noch nicht am Material geprüft. Ohne `--speech` keine Sprachmodellnutzung. Auf einem Mix `--role mix` verwenden; dort wird keine monophone F0-/Formantanalyse angewendet.

- `--start`/`--end`: Zeitfenster innerhalb der Quelldatei, höchstens 120 Sekunden.
- `--timeline-offset`: Playlistposition des Quelldatei-Anfangs. Gemeinsame Zeit = Quellzeit + Versatz; für beschnittene Dateien den tatsächlichen Ursprung angeben.
- `--beat-offset`: Beat-Nullpunkt auf derselben gemeinsamen Zeitachse. Das Projekt-BPM hat Vorrang vor automatischen Schätzungen.
- `--rhythm-audio`: optionaler Gesamtmix mit Zeitursprung 0 und maximal 120 Sekunden. Keine unabhängige Verschiebung dieser Rhythmusquelle implementiert; bei anderem Ursprung erst korrekt ausgerichteten Export verwenden.
- `--transcript-file /absolut/text.txt` zusammen mit `--speech`: vorgegebenen Text ausrichten. Auch dann sind die Grenzen Schätzungen.
- `--speech-json /absolut/speech.json`: bereits ermittelte Wortzeiten statt `--speech` wiederverwenden. Quellhash, analysiertes Signal und Zeitursprung müssen passen; Ausgabe in separatem Ordner erzeugen.

`report.html` im lokalen Browser öffnen; den ganzen Berichtsordner zusammenhalten. PNGs mit dem Bildwerkzeug tatsächlich ansehen, JSON prüfen. Benutzerannotation enthält Quellhash, gemeinsamen Zeitbereich und Kommentar; nur projektbezogen verwenden. Player-Zeitbegrenzung verwendet Browser-Ereignisse und ist nicht samplegenau. Der automatische Browser-Test war durch die Browser-URL-Richtlinie blockiert; Player/Annotation sind implementiert, aber noch nicht im Browser funktional verifiziert.

## Laufzeit und Modelle

WhisperX läuft hier auf CPU mit int8, Modell `small`, Silero-VAD, ohne Sprechertrennung. Modelle liegen unter `.models`; Audio bleibt lokal. Netzwerk dient initialen Modelldownloads; weitere Sprache/Modelle benötigen weitere Downloads. Bekannte Bibliotheks-Telemetrie ist im Sprachmodul deaktiviert. Kein API-Schlüssel erforderlich.

Die getestete WAV-Pipeline lädt mit SoundFile und übergibt NumPy-Audio an WhisperX. Beim Import meldet der ungenutzte Pyannote/TorchCodec-Decoder fehlende FFmpeg-Dylibs; diese Warnung verhindert den geprüften Ablauf nicht. Beliebige Video-/Audioformate, Sprechertrennung und TorchCodec-Dateidekodierung sind nicht eingerichtet. Das installierte `imageio-ffmpeg` ersetzt diese Dylibs nicht.

Native Essentia-Berechnungen blieben in der Codex-Sandbox zeitweise hängen; außerhalb liefen sie erfolgreich. Bei Hängern nicht unbegrenzt neu starten: betroffenen Prozess eingrenzen und normalen lokalen Lauf nutzen, soweit autorisiert.

## Neuinstallation und Prüfung

Bestehende V1-Umgebung beibehalten. Auf einem anderen System zuerst Python-/Wheel-Kompatibilität prüfen; der Paketstand wurde nur auf diesem Mac getestet.

```bash
python3.12 -m venv .venv-analysis
.venv-analysis/bin/python -m pip install -r scripts/requirements-analysis.txt
MPLCONFIGDIR=/tmp/fl-vision-mpl PYTHONPATH=scripts .venv-analysis/bin/python -m unittest discover -s tests -v
```

Technische Tests: bekannte Sinustonhöhe, Stille/stimmlose Lücken, kurze Dateien, gegenphasige Kanäle, Resampling, Beatgrid und synthetischer 120-BPM-Klick, unveränderte Quelle, Cache-Zeitzuordnung, Ausgabe-Kollision und HTML-Escaping. Zusätzlich am vorhandenen Rap-Ausschnitt ausgeführt: 26 automatisch ausgerichtete Wörter und 129,75 BPM im zugehörigen 130-BPM-Mix. Dies belegt Werkzeugfunktion, nicht musikalische Qualität.

Primärdokumentation: [WhisperX](https://github.com/m-bain/whisperX), [Essentia RhythmExtractor2013](https://essentia.upf.edu/reference/std_RhythmExtractor2013.html), [Praat/Parselmouth](https://parselmouth.readthedocs.io/en/stable/).
