# Audio-Vision: implementierter Stand und Ausbau

## V1: lokale Signalbilder vorhanden

`scripts/analyze_audio.py` liest Mono-/Stereo-Audio lokal und schreibt `timeline.png`, `spectrum.png`, `analysis.json` und `report.html`. Das Original bleibt unverändert; keine Uploads und keine FL-Änderungen. Der Bericht enthält Wellenform-Min/Max, Kurzzeit-RMS, Spektrogramm, Spektralfluss, zeitabhängige Stereo-Korrelation, Quellhash und optional ein vom Projekt übernommenes Beatgrid.

Benötigt Python mit `numpy`, `soundfile` und `matplotlib`; siehe `scripts/requirements.txt`. Nutze eine geeignete vorhandene Umgebung oder richte eine lokale virtuelle Umgebung ein. Keine globalen Python-Pakete ungefragt überschreiben.

```bash
python3 scripts/analyze_audio.py /absolut/track.wav --out /absolut/report --bpm 130
python3 scripts/analyze_audio.py /absolut/track.wav --out /absolut/detail --start 6 --end 7.5 --bpm 130 --beat-offset 0
```

Die Pfade im Beispiel sind Argumentbeispiele, keine vorhandenen Dateien; Skriptpfad relativ zum Skill-Verzeichnis. Tempo 130 ist ebenfalls nur ein Beispiel. Verwende pro Quelle/Fenster einen eigenen Ausgabeordner. Maximal 120 s pro Analysefenster; längere Tracks in ausgewiesenen Fenstern analysieren. Zeitangaben beziehen sich auf die Quelle, nicht automatisch auf die FL-Playlist.

Öffne die PNGs selbst mit dem Bildwerkzeug. Bei Bedarf kann der Nutzer `report.html` im Browser öffnen. Vergleiche immer identische Frequenz-/Pegelbereiche. Die STFT benutzt 1024 Samples, 256 Samples Hop und Hann-Fenster; eine kurze Endauffüllung kann den letzten RMS-Punkt absenken. Zeit-/Frequenzauflösung begrenzen Interpretationen.

**Grenzen von V1:** ausschließlich Signalmerkmale. V2 ergänzt Wortausrichtung, Beat-/Onsetschätzung, F0/Formanten und Player/Projektannotation; siehe unten. Audio-Wahrnehmung, bestätigte Silben, Harmonie, Qualitätsmodell und automatische Korrektur sind weiterhin nicht vorhanden. LUFS/True Peak ist separat nach [Vergleich und Review](comparison-review.md) messbar.


Die lokale Installation unter `~/skills/fl-stuido-enhance` besitzt eine eigene `.venv`. Verwende dort bevorzugt `.venv/bin/python scripts/analyze_audio.py ...`. Bei einer kopierten ZIP-Version ist die Umgebung nicht enthalten; richte sie bei Bedarf mit `python3 -m venv .venv` und `.venv/bin/python -m pip install -r scripts/requirements.txt` ein. Für Matplotlib einen beschreibbaren Cache im jeweiligen Arbeitsordner über `MPLCONFIGDIR` setzen.

## V2: lokal implementiert

[Einrichtung, Aufruf und Grenzen](analysis-v2.md): `scripts/analysis_v2.py` kombiniert V1 mit Essentia, Praat/Parselmouth und optional WhisperX. Gemeinsame Zeitachse, getrennte Projekt-/Schätzmarker, anklickbare Wortzeiten und exportierbare Projektannotation. Nutze Original-Stems und bekannte Projektparameter. Die technische Pipeline wurde an Testsignalen und dem vorhandenen Rap-Ausschnitt geprüft; die Browser-Funktion des Players noch nicht.

Noch auszubauen: bestätigte Phonem-/Silbengrenzen, Harmonie/Chroma, Beziehungen zwischen mehreren Stems und musikalische Evaluation. Keine automatisch erkannte Grenze direkt als Schnittfreigabe behandeln.

## V3: einfacher Dialog am Track

Als Projekt-Prototyp implementiert und im Browser geprüft: lokaler A/B-Player mit gemeinsamem Zeitbereich, dokumentierter Lautheitsanpassung, Wellenform, Messplots und Wortmarkern. Noch kein allgemeiner V3-Generator im Skill. Siehe [Vergleich und Review](comparison-review.md) für reproduzierbares Beispiel und Grenzen. Nutzer kann „hier“, „A/B/beide schlecht“ und Freitext hinterlassen. Speichere Datei-ID, Bereich und Urteil als Projektannotation, nicht als Geschmacksprofil. Prüfe Synchronität; keine überlagerte Autoplay-Wiedergabe.

## Optional: Audio-Modell

Aktuelle Kandidaten und Dokumentation stehen in `research.md`. Audio-Modell-Urteile sind eine zusätzliche Beobachtungsebene mit eigenen Fehlern, keine garantierte Wahrnehmung des Hauptagenten. Anbieter, Dateien, Autorisierung, Zugang und Kosten vor Übertragung klären. Keine API-Schlüssel in Notizen speichern.

## Weiterentwicklung prüfen

Teste neue Messfunktionen an einfachen bekannten Signalen und an einem echten Ausschnitt. Prüfe Quellenunveränderlichkeit, Zeitachse, Kanalbehandlung, Stille, sehr kurze Dateien und sinnvolle Fehlermeldungen. Öffne erzeugte Bilder selbst. Gute technische Tests ersetzen nicht die musikalische Evaluation am Track.

## Stimmeinsatz und FX-Beziehung: lokal implementiert

`scripts/measure_entry_clearance.py` prüft getrennte, zeitgleich exportierte Lead-/FX-Stems. JSON, PNG und Markdown zeigen Signalangriff, Wortmarkerabweichung, Effekt-Abstand, aktive Überlappung und Energieverhältnis. Schwellen-/Rasterbereich und unaufgelöste Grenzen werden ausgewiesen. [Anwendung und Grenzen](entry-clearance.md). Kein bestätigtes Phonem-Alignment oder psychoakustisches Maskierungsmodell.
