absolution-omega / README.md
2Btainment's picture
v1.1 Ω FUSION + display name Tune-Whisperer; keeps owner-only library/guest isolation (fusion scoped), Demucs 120s, /data
e880b2b verified
|
Raw History Blame Contribute Delete
34.6 kB
---
title: Tune-Whisperer
emoji: 🎧
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
hf_oauth: true
short_description: Forensic audio lab – HPSS + Demucs stems, arrangement mixer
---
> **Hugging Face Space note:** Public demo instance. The project library is owner-only (HF login as 2Btainment); every other visitor works in an isolated guest workspace (auto-deleted after 24 h). Demucs htdemucs v4 runs on CPU (max. 120 s audio per job); HPSS has no duration limit. Upload limit 200 MiB. Projects are stored in an attached HF Storage Bucket at `/data` if mounted, otherwise in `/tmp` (lost on restart). Do not upload private/confidential audio.
# Tune-Whisperer — FUSION STUDIO v1.1
**Ein Projekt → eine Quelldatei → Ω FUSION → alle lokal tatsächlich erzeugbaren Stems.**
Das neue **Ω FUSION — One-Step Stem Engine** kombiniert die bisher getrennten
Arbeitsgänge. Es gibt **einen Startknopf**, **einen Jobstatus** und
**eine gemeinsame Studio-Timeline** mit pro Spur ausgewiesener Herkunft.
## Start
Windows: `start_windows.bat`. macOS/Linux: `bash start.sh`.
Oder manuell mit Python 3.11+:
```bash
python -m venv .venv
# Windows: .venv\\Scripts\\Activate.ps1
# macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pytest -q
python -m uvicorn app.server:app --host 127.0.0.1 --port 8000
```
Dann `http://127.0.0.1:8000` öffnen, Audiodatei importieren und
**Ω FUSION — Alles in einem Schritt trennen** wählen.
## Was passiert in einem einzigen Job?
1. **Vorinventur:** Das kleine lokale Modell schätzt mögliche Klangklassen.
Diese Hypothesen sind keine isolierten Instrumente.
2. **Primärseparation:** Falls Demucs lokal mit kompatiblen Gewichten und
Laufzeit verfügbar ist: `Vocals`, `Drums`, `Bass`, `Other`, `Residual`.
Sonst: HPSS mit `Harmonic`, `Percussive`, `Residual`.
3. **Kick/Bassline-Ableitung:** Im Demucs-Modus wird das Kick-Tiefband aus
**Drums** und die Bassline aus **Bass** geschätzt; im HPSS-Modus aus
**Percussive** beziehungsweise **Harmonic**.
Diese geschätzten Bänder werden den Elternspuren rechnerisch abgezogen,
damit sie im neutralen Gesamtmix nicht doppelt enthalten sind.
4. **Störstellen-Scan:** Klickverdacht wird markiert. Kein Auto-Denoising
und keine stillschweigende Löschung. Erst nach ausdrücklicher Auswahl
einer Reparatur wird eine eigene `Noise`-Differenzspur erzeugt.
5. **Optionale OMNISTEM-Verarbeitung:** Im Trennplan vorhandene und technisch
unterstützte zusätzliche DSP-Proxies (etwa Höhen-/Mittenimpulse) werden
aus existierenden Elternstems kompensiert abgeleitet.
6. **Provenienz & Mix:** Alle tatsächlich vorhandenen Spuren stehen im
Mixer bereit. Unter **Herkunft aller Spuren** steht, welche Spuren
auf KI-Separation oder geschätzter DSP-Zerlegung beruhen.
**Es gibt kein Wunder-Output:** Ohne Demucs keine gesonderten Vocal-Stems.
Ohne manuelle Freigabe keine vermeintlich "bereinigte" Noise-Audiospur.
Keine ungeprüfte Instrumentenerkennung oder perfekte Restaurierung behaupten.
## KI-Adapter aktivieren (optional)
Die optionale Demucs-Abhängigkeit wird mit `python -m pip install -e ".[neural]"`
installiert. Die kompatiblen **lokalen Modellgewichte** müssen separat rechtmäßig
bereitgestellt und über `ABSOLUTION_DEMUCS_REPO` angegeben werden. Die
Oberfläche und die API markieren den Adapter erst dann als verfügbar,
wenn **Laufzeit und Checkpoints** vorhanden sind.
Keine Gewichte werden vom Projekt automatisch heruntergeladen.
Demucs v4 unterstützt hier nur die feste 4-Stem-Separation, keine
Textsteuerung für beliebige Instrumente.
## Störschutz
Die unveränderte Datei wird erhalten. Die Klickanalyse ist nur ein Verdacht.
Die Noise-Differenzspur wird nach manueller Genehmigung hörbar dem
neutralen Stem-Mix hinzugefügt. **Mute auf Noise** entfernt ausschließlich
den freigegebenen Reparaturanteil, keine zusätzlich vermuteten Klanganteile.
## API
`POST /api/v1/jobs/fusion` mit
```json
{"project_id":"<UUID>", "mode":"auto", "include_event_proxies":true, "scan_noise":true}
```
`mode` kann `auto`, `neural` oder `dsp` sein.
Status: `GET /api/v1/jobs/{job_id}`.
Provenienz und aktuelle Stems: `GET /api/v1/projects/{project_id}`.
## Installation und Sicherheit
Nur lokal auf `127.0.0.1` verwenden; es gibt keine Nutzer-Authentifizierung.
Aufträge sind prozesslokal und werden bei Server-Neustart nicht fortgesetzt.
Kein Remote-Dienst, keine Telemetrie und keine automatischen Modell-Downloads.
Die Stems werden als separate Float-WAV-Dateien berechnet. Bei langen Tracks
beachten: Demucs benötigt unter Umständen viel RAM/VRAM.
## Tests
`python -m pytest -q` prüft echte API-Integration, Audioexport, Mix-Konsistenz,
Modellbereitschaft und UI-Verträge. Das separate Browser-End-to-End-Verhalten
gegen einen laufenden HTTP-Server wurde hier nicht vollständig geprüft.
---
## Historische Dokumentation
# Tune-Whisperer — Photoreal Unified Studio v1.0
**Eine einzige Studio-Seite.** Datei importieren → Spuren analysieren und trennen → Bass/Störereignisse gezielt behandeln → Mix exportieren.
## Schnellstart
Windows: `start_windows.bat`
macOS / Linux: `bash start.sh`
Alternative, falls Startskripte nicht passen:
```bash
python -m venv .venv
# Windows: .venv\\Scripts\\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -e '.[dev]'
python -m uvicorn app.server:app --host 127.0.0.1 --port 8000
```
Öffne `http://127.0.0.1:8000`.
**Studio-Navigation:** Oben ist immer das aktive Projekt samt Quelldatei sichtbar. Über **Projekte** öffnest du die durchsuchbare Bibliothek (Shortcut `Strg/Cmd+K`); über **+ Datei importieren** entsteht für jede neue Datei ein eigenständiges Projekt. Alle Werkzeuge liegen rechts in drei Bereichen: `Analysieren & trennen`, `Bass & Störungen`, `Export & Qualitätsbericht`.
**Originalschutz:** Originaldateien bleiben unverändert, echte Stems werden im Mixer angezeigt. Mute/Solo/Gain/Pan sowie Filter/Sättigung/Stereobreite wirken auf den nächsten berechneten Mix. Kick und Bassline sind DSP-Schätzungen und werden im neutralen Mix gegen Basisstems kompensiert. Die Störspur ist eine ausdrücklich freigegebene Reparatur-Differenz; der neutrale Mix lässt sie hörbar.
**Bildgestaltung:** Das lokal eingebundene Studiofoto erzeugt die warme, photorealistische Atmosphäre. Die Steuerflächen, Wellenformen und Regler bleiben echter HTML-/Canvas-Code. Es werden keine CDNs, Bild-APIs oder Telemetriedienste aufgerufen.
## Technische Grenzen
- HPSS trennt harmonische und perkussive Signalanteile, keine garantierten Einzelinstrumente.
- Das kleine lokale KI-Modell erstellt begrenzte Instrumentenhypothesen auf Basis synthetischer Trainingsdaten.
- Demucs kann nur mit lokal installierten kompatiblen Modellgewichten genutzt werden.
- Der Störscan identifiziert Verdachtsstellen; vollautomatische, garantiert musikverlustfreie Rauschminderung existiert nicht.
- Für Tempo- und unabhängige Tonhöhenbearbeitung wird lokal FFmpeg mit Rubber-Band-Filter benötigt.
- Projektjobs liegen im Speicher des lokalen Servers. Das System ist **kein abgesicherter öffentlicher Mehrbenutzerdienst**.
## Tests
`python -m pytest -q`
Mehr zur technischen Architektur und den Audio-Modulen steht im Ordner `docs/`.
---
# Tune-Whisperer — v0.9 · Unified Studio Workspace
**Ein Projekt. Eine eindeutig benannte Quelldatei. Alle echten Werkzeuge an einem Ort.**
## Neue Bedienoberfläche
Die frühere Navigation mit separaten Seiten (Import, Arrangement, Bass, Noise,
Stems, Forensik) wurde durch **ein einziges Studio** ersetzt:
- **Links: Projektbibliothek.** Projekte anhand Namen oder Quelldatei suchen,
wechseln, umbenennen und neue Projekte durch Dateiimport erzeugen. Beim
Import wird keine Quelldatei in einem anderen Projekt überschrieben.
- **Oben: aktive Quelle.** Dateiname, Hash-Ausschnitt, Dauer, Abtastrate,
Anzahl aktiver Stems und Original-Wiedergabe bleiben immer sichtbar.
- **Mitte: Master-Übersicht und Stereo-Mixer.** Farbige Wellenformen für
die tatsächlichen Stems, Transport/Seek, Gain, Mute, Solo, Panorama,
Effekt-Racks und Render-Vorschau.
- **Rechts: kontextabhängiger Inspector.** Workflow, KI-Trennplan,
BASS-CORE, NOISE-CORE und Export/Diagnostik. Keine Funktions-Unterseiten.
- **Unten: ein gemeinsamer Jobstatus.** Separations-, Bass-, Noise-,
OMNISTEM- und Mix-Jobs melden Fortschritt im selben Studio.
Die gesamte Oberfläche ist in `app/static/index.html`, `studio.css`,
`studio.js` implementiert. Alte, nicht mehr verwendete JavaScript-/CSS-Frontends
wurden entfernt. Kein CDN, keine Telemetrie und keine automatischen Cloud-Uploads.
## Schnellstart
Python 3.11+ und unterstützte System-Audio-Codecs bereitstellen:
```bash
python -m venv .venv
source .venv/bin/activate # Windows: .venv\\Scripts\\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q
python -m uvicorn app.server:app --host 127.0.0.1 --port 8000
```
Alternativ `start_windows.bat` bzw. `bash start.sh`; Browser:
**http://127.0.0.1:8000**
1. **Audio importieren**: Neues Projekt erzeugt; Quelle steht immer oben.
2. **Workflow**: Mini-KI-Vorinventur optional, Basis-Separation mit HPSS.
Demucs nur bei vorhandenen vertrauenswürdigen lokalen Gewichten.
3. **KI-Plan**: Hypothesen umbenennen, prüfen und technisch mögliche
Proxy-Spuren ausführen. Nicht unterstützte Instrumente bleiben blockiert.
4. **Bass**: Kick/Bassline als additive Stems plus einstellbare Bassbearbeitung.
Optionaler separater FFmpeg-Virtual-Bass-2.1-Export.
5. **Störung**: Scan ohne Änderungen; auffällige Klickstellen bewusst
auswählen und reparieren. Die Differenz wird als **NOISE**-Stem sichtbar
und bleibt im neutralen Mix zunächst hörbar.
6. **Spur-Mixer**: Gain, Mute/Solo, Panorama, Filter, Sättigung, Breite,
optional Tempo/Pitch (FFmpeg/Rubber Band), dann **Mix rendern**.
7. **Export**: Original, Stems-ZIP, Mix-WAV, Bass/Noise-Pakete im gleichen
Inspector. Einstellungen wirken nur auf einen neu berechneten Mix.
### Datei- und Projektsicherheit
Jedes Projekt besitzt derzeit **genau eine Quell-Audiodatei**. Die neue
durchsuchbare lokale Bibliothek (`GET /api/v1/projects`) listet alle
verfügbaren Projekte und zeigt die zugeordnete Datei. Projektumbenennung
erfolgt über `PATCH /api/v1/projects/{id}`. Die Quelldatei bleibt unverändert.
Projekt- und Jobverwaltung sind lokal und nicht als öffentlicher
Mehrbenutzerdienst abgesichert. Vor öffentlichem Deployment sind Authentifizierung,
Autorisierung und Upload-/Speicherhärtung erforderlich.
### Wahrheits- und Klangschutz
- HPSS liefert spektrale Harmonic/Percussive/Residual-Anteile, **keine**
garantiert instrumentreinen Stems.
- OMEGA-TAG Mini ist auf synthetischen Signalen feinjustiert; Empfehlungen
sind **unsichere Vorinventur**, keine verlässliche Instrumentenerkennung.
- BASS-CORE und OMNISTEM-DSP-Proxies sind Näherungen.
- NOISE-CORE repariert nur freigegebene Kandidaten. Keine automatische
Breitband-Entrauschung und keine Behauptung absoluter Verlustfreiheit.
- Der neutrale additive Stem-Graph rekonstruiert die Quelle innerhalb
dokumentierter numerischer Toleranz; das beweist **nicht** Quellenreinheit.
- Alle Audioeffekte werden erst beim expliziten Render verarbeitet.
Nach Reglereingriffen wird ein alter Mix als veraltet markiert.
### Technische Prüfungen
Tests: `python -m pytest -q` (API, DSP/Audio, Projektbibliothek, Mix,
Bass, Noise, OMNISTEM, Oberfläche/Static-Verteilung).
Syntax: `node --check app/static/studio.js`.
Browsersimulation: isolierte UI-Prüfung mit echten Demo-Stem-Waveforms und
kontrollierten API-Antworten. Der Testbrowser konnte nicht direkt zu localhost
navigieren; ein vollständiger produktionsnaher Browser-End-to-End-Test
ist damit **nicht** abgedeckt.
---
# Tune-Whisperer — v0.8 · OMNISTEM Plan Runner
## Neu in v0.8
**Planen → Fähigkeitsprüfung → Ausführen → echte Audiospuren.**
Im Ω STUDIO Mini-KI-Analyse durchführen, gewünschte Ziele markieren und
**Plan prüfen** drücken. Die Anzeige unterscheidet:
- **AUDIO VORHANDEN:** Bereits separiertes, echtes Audiosignal (z. B. Demucs-Vocals).
- **DSP-PROXY:** Zusätzliche spektrale Mitten-/Höhenimpuls-Schätzung aus `percussive`
oder `drums`; keine validierte Snare- oder Hi-Hat-Isolation.
- **NICHT VERFÜGBAR:** Ohne passendes lokales Modell kein Instrumenten-Stem
und keine vorgetäuschte „KI-Trennung“.
Klicke **Plan ausführen**, um die ausgewählten, unterstützten Mikrospuren zu erzeugen.
Dafür müssen zunächst **HPSS** (lokal verfügbar) oder **Demucs** (optionale lokale
Gewichte) Basisstems erzeugt worden sein. Der Mini-KI-Checkpoint wird weiterhin
lokal mitgeliefert und ist ausschließlich auf **synthetische** Mischungen feinjustiert.
Er benennt unsichere Hypothesen und ersetzt keine professionelle Instrumentenerkennung.
Die percussive/drums Elternspur wird um jede neu gebildete Proxy-Spur vermindert.
Ohne Gain/FX im Mixer ist die ursprüngliche Quellensumme deshalb erhalten; ein
Streaming-Rekonstruktionstest prüft das. Unterschiedliche Planläufe nutzen jeweils
den vor-OMNISTEM-Graphen und verdoppeln alte Proxies nicht.
**Klangschutz:** Kein automatisches Noise-Gating, keine unerlaubten Reparaturen,
keine heimliche Normalisierung. NOISE bleibt eine nur manuell freigegebene Differenzspur.
### Bedienung
1. Lokales Studio starten und Audio importieren.
2. „Mini-KI analysieren“ und Trennziele prüfen; ohne Vorschläge manuell ergänzen,
jedoch sind nur unterstützte IDs ausführbar.
3. „Separation starten“ mit HPSS oder lokal installiertem Demucs.
4. „Plan prüfen“ lesen; blockierte Ziele bleiben sichtbar.
5. „Plan ausführen“ → echte neue Stems erscheinen als farbige Tracks.
6. Gain, Mute, Solo, Panorama, Effekte, Mix und Stem-Export wie bisher verwenden.
Weitere Modelle für tatsächliche per-Instrument-Separation, textkonditionierte
Quellenselektion, verifizierte neural Denoising-Funktionen und echte LFE-Integration
in Stereo-Mixing bleiben ausdrücklich **nicht implementiert**.
## Technische API
- `GET /api/v1/projects/{id}/omnistem/plan` – kompiliert den gespeicherten Plan
gegen tatsächlich vorhandene Audioquellen, ohne Audiodateien zu verändern.
- `POST /api/v1/projects/{id}/omnistem/run` – asynchroner Plan-Runner.
- `GET /api/v1/projects/{id}/omnistem/report` – ausgeführter Stand und Grenzen.
- `GET /api/v1/projects/{id}/stems` – aktuelle additive echte Stems.
- `POST /api/v1/jobs/mix` – gemischtes WAV ohne pauschales Mastering.
**Start:** `bash start.sh` oder unter Windows `start_windows.bat`;
Browser `http://127.0.0.1:8000`. Tests `python -m pytest -q`.
Kein öffentlicher Mehrbenutzerbetrieb, keine automatische Modell-Downloads,
keine Telemetrie. Abhängig vom lokalen System sind Codec-Bibliotheken und
FFmpeg/Rubber Band für optionale Funktionalität erforderlich.
---
# Tune-Whisperer — v0.7 · Unified Multitrack Studio · BASS/NOISE Lanes
**Lokales Fullstack-Audiostudio.** Enthält alle Funktionen aus v0.4 (BASS-CORE, NOISE-CORE,
Virtual Bass, HPSS, optional Demucs) und zusätzlich ein farbiges Mehrspur-Arrangement.
## Schnellstart
1. ZIP entpacken. **Python 3.11+** muss installiert sein.
2. Windows: `start_windows.bat` ausführen. macOS/Linux: `bash start.sh`.
3. Browser: **http://127.0.0.1:8000**.
4. Im **Ω STUDIO** oben **Datei importieren** oder **Demo laden**.
5. Optional **Mini-KI analysieren** → Hypothesen prüfen und **Plan speichern**.
6. **Separation starten** (HPSS ist immer verfügbar; Demucs benötigt lokale Modellgewichte).
7. In der **Element-Kontrolle** auf **Kick & Bassline als Spuren** klicken.
8. **Störungen scannen**, verdächtige Stellen manuell auswählen und **Auswahl reparieren**.
Nur nach einer solchen Freigabe entsteht eine echte, separate **STÖRSPUR**.
9. Bestehende Stems werden dabei rechnerisch kompensiert. Alle Spuren zusammen
ergeben beim neutralen Mix wieder das Original, soweit der Ausgangsseparator
numerisch konsistent ist. **Die Störspur bleibt zunächst hörbar**.
10. Für die gezielte Entfernung bestätigter Klickanteile die Störspur mit **M** stummschalten.
11. Für jede Spur Gain, Mute, Solo, Stereo-Fader und Effekte einstellen →
**Mix berechnen**, anhören und WAV/ZIP exportieren.
**Beispiel direkt starten, ohne Startskript:**
```bash
python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q
python -m uvicorn app.server:app --host 127.0.0.1 --port 8000
```
## v0.7 — Debugging: BASS-CORE + NOISE-CORE sind echte zusätzliche Arrangement-Lanes
- **KICK** (`kick_core`): tiefes, transient-orientiertes Bassband; keine sichere Kick-Isolation.
- **BASSLINE** (`bassline_core`): tiefes, tonales Bassband; keine sichere Instrument-Isolation.
- **STÖRSPUR** (`noise_difference`): genau die **explizit freigegebenen** Reparaturdifferenzen
(`Original − repariert`). Ohne freigegebene Klickreparatur gibt es diese Spur nicht.
- **Kompensierte Basisstems**: das System zieht die drei zusätzlichen Signalanteile von
den tatsächlichen Basisstems ab. Die Zusatz-Lanes **verdoppeln niemals** die Bassenergie.
- Bei HPSS werden Bassline und Kick aus `harmonic` bzw. `percussive` kompensiert, die
Stördifferenz aus `residual`. Mit Demucs werden `bass`, `drums` und `residual` verwendet.
Ohne Grundseparation wird der Originalmix als `source_body` herangezogen.
- Eine neutrale Summe aller Lanes bleibt die Originalmischung. Nichtdestuktive Bearbeitung;
ein neuer Stereo-Mix wird nur auf ausdrücklichen Wunsch gerendert.
- **Klangschutz:** Noise-Lane ist nicht stumm. `M` auf NOISE bewirkt erst nach manueller
Freigabe die tatsächliche Korrektur. `S` ermöglicht differenzbasiertes Abhören.
- Die bestehenden Bass-Optimierungs-Ausgaben (mit optional synthetischen Obertönen)
bleiben separate Audition/Exports und werden **nicht** automatisch in den neutralen
Gesamtmix addiert.
- **Kdenlive/FFmpeg Virtual Bass** bleibt separater 2.1-LFE-Export. Kein Import in
den Stereo-Mixer, weil dieser eine andere Kanalbelegung hat.
### Technische Grenzen
- Kein Stems-„Magie“: HPSS ist eine spektrale Abschätzung; Demucs braucht geprüfte,
lokal bereitgestellte Gewichte. Mini-TAG benennt nur Hypothesen.
- NOISE-CORE extrahiert bisher nur manuell akzeptierte Reparaturdifferenzen,
nicht zuverlässig jede Art von Umgebungsrauschen.
- Der Mixer rechnet mit WAV Float32, kann bei starken Gain-/FX-Änderungen >0 dBFS
ausgeben und meldet das ausdrücklich.
- Das Bauen zusätzlicher Spuren legt WAV-Dateien im `omega_data`-Ordner ab.
Alte Graphgenerationen werden für laufende Projekte nicht automatisch gelöscht.
- Das lokale Backend hat weder Mehrnutzer-Authentifizierung noch dauerhafte Jobs.
Nicht ungeschützt ins öffentliche Internet stellen.
### Funktionen und Komponenten
- Mehrspur-Arrangement mit einzelnen Instrumenten-/Signalstems je nach verfügbarem Modell.
- Jedes *tatsächlich* verfügbare Audio-Stem erhält eigene Farbe und samplebasierte
Waveform-Visualisierung, links Lautstärke/Mute/Solo, mittig L/C/R-Pan, rechts
ausklappbare Effekte (Low-Cut, High-Cut, Sättigung, Stereobreite).
- Farbig überlagerte Gesamtübersicht, klickbare Zeitleiste und Scroll/Zoom.
- **OMEGA-TAG Mini**: Offline-MLP (35 Features → 32 tanh Neuronen → 6 Sigmoid-Ausgaben).
Mitgeliefertes `.npz`-Checkpoint wurde zweistufig auf **synthetischen Signalen**
trainiert und anschließend auf **synthetischen Mischungen feinjustiert**.
Es erkennt *nur* Klangtexturen: Bass-ähnlich, Kick-ähnlich, Snare-ähnlich,
Hi-Hat-ähnlich, harmonische Mitten und rauschähnliche Anteile.
**Keine trainierte oder validierte Instrumentenerkennung auf echter Musik.**
- Editable Trennziele (bis 128 aus Ressourcen-/Sicherheitsgründen).
Das Speichern eines Ziels separiert **keine** zusätzliche Audiospur.
- Nichtdestruktiver, chunkweiser Stereo-Float32-Mix mit Gain, Mute, Solo,
Panorama, Hoch-/Tiefpass, Stereo Width und harmonischer Sättigung.
- Optional von 50–200 % unabhängiges Tempo und ±12 Halbtöne transponieren
mittels **FFmpeg mit Rubber Band Filter**.
Der Button wird ohne Rubber Band deaktiviert, nicht simuliert.
- WAV-Float32-Export und messbarer Pegelbericht einschließlich möglicher
Überschreitung von 0 dBFS.
### Integritätsregeln
- Original wird niemals in-place überschrieben. Quellen und Export werden
in getrennten Projektordnern gespeichert.
- Kein Eingriff und kein Sound Processing ohne explizites **Mix berechnen**.
- Gespeicherte KI-Trennplan-Hypothesen sind ausdrücklich nicht als isolierte
Instrumentenspuren bezeichnet.
- HPSS ist **kein Instrumentenerkennungsmodell**, sondern strukturelle Trennung.
Demucs v4 ist optional und bietet vier Grobkategorien; es zerlegt nicht beliebig
viele benannte Instrumente.
- Waveforms werden für rasche Anzeige sparsam gesampelt; sie sind **keine**
vollständige Peak- oder Forensikmessung.
- Synthetisch generierte Oberwellen, Tontranspositionen und FX sind
Klangänderungen, **keine** Rekonstruktion physisch nachweisbarer fehlender Daten.
- Kein automatisches Mastering, kein pauschales Denoising oder 0-dB-Normalisieren.
### Tooling und Deployment
- Python / FastAPI / NumPy / SciPy / SoundFile.
- Frontend: eigenständiges HTML/CSS/JavaScript, kein CDN, keine fremde Cloud.
- Startet als lokaler Browser-Webserver; optional Docker Compose (nicht
als produktionsbereite Public-Cloud-Anwendung absichern).
- FFmpeg ist für Grundfunktionen nicht erforderlich, für spezielle Dateiformate,
Virtual Bass und unabhängige Pitch/Tempo-Transformation hingegen erforderlich.
- `start.sh`/`.bat` installieren Python-Abhängigkeiten über pip und benötigen bei
Erstinstallation Netzwerkzugang; die Anwendung selbst ruft danach keine
externen Server auf.
- Keine Benutzeranmeldung, keine öffentliche Mehrnutzer-Bereitstellung.
- Datenspeicherung in `omega_data/`, falls nicht über `ABSOLUTION_DATA_DIR` geändert.
### Tests
```bash
python -m pip install -e ".[dev]"
python -m pytest -q
node --check app/static/app.js
node --check app/static/arrangement.js
```
Neue Tests: neutrale Summierung, Solo/Mute, Panorama, FX, Wellenform-API,
synthetisches Mini-Modell, Plan-Persistenz, tatsächliche Mix-Jobs und WAV-Export.
### Neue API
```
POST /api/v1/projects/{id}/inventory Mini-Tagging, synchron (lokal)
PUT /api/v1/projects/{id}/plan editierbare Zielhypothesen
GET /api/v1/projects/{id}/wave/{stem} sparsames Wellenform-Sampling
POST /api/v1/jobs/mix Offline-Mix-Job
GET /api/v1/jobs/{job_id} Fortschritt
GET /api/v1/projects/{id}/mixer Mix-Report und gespeicherte Parameter
GET /api/v1/projects/{id}/mixer/audio WAV-Export
```
Request-Body für Mix-Jobs:
```json
{
"project_id": "<PROJECT_UUID>",
"tracks": {
"harmonic": {"gain_db": -2.0, "pan": -0.2, "mute": false, "solo": false,
"highpass_hz": 25, "lowpass_hz": 0, "drive": 0.1, "width": 1.0}
},
"tempo": 1.0,
"pitch_semitones": 0
}
```
Nicht spezifizierte Stems sind ohne Effekte und bei 0 dB enthalten. Solo-Modus
spielt ausschließlich Solo-markierte, nicht stumm geschaltete Stems.
### Forschungsstatus
Weitere getrennte Instrumente benötigen leistungsfähige bedingte oder
hierarchische KI-Separatoren plus realistisch evaluiertes Modellrouting.
Das integrierte Mini-Modell ist hierfür nur eine Vorinventur, kein universelles
Separationsmodell. Das Projekt bleibt eine lokale Forschungs-/Prototyp-Version.
Weitere Details: `docs/ARRANGEMENT_STUDIO.md` sowie das historische
NOISE-/BASS-CORE-Material unten.
---
# Tune-Whisperer — v0.4.0 · NOISE-CORE + BASS-CORE
> Local-first audio-forensics workbench with BASS-CORE (experimental DSP-derived kick/bassline
> estimates, non-destructive bass processing and optional use of pre-separated HPSS/Demucs stems).
## Starten
1. Das ZIP entpacken.
2. `start_windows.bat` (Windows) oder `bash start.sh` (macOS/Linux) im Projektordner starten.
3. `http://127.0.0.1:8000` im Browser öffnen.
4. Unter **Studio** WAV/FLAC/AIFF/OGG/unterstütztes MP3 importieren oder Demo laden.
5. Den Bereich **BASS-CORE** öffnen, Preset/Regler wählen und **Bass analysieren & optimieren** drücken.
6. **Bassband vorher/nachher**, Kick-/Bassline-Schätzung, erzeugte Obertöne und Vollmix anhören.
7. Einzel-WAVs oder **Alle Bass-Tracks herunterladen** (ZIP) exportieren.
Mit vorhandenem HPSS-Ergebnis kann BASS-CORE die harmonischen/perkussiven Stems als
Quellenhypothese verwenden. Bei korrekt konfiguriertem Demucs und vorab generierten
`bass`/`drums`-Stems nutzt die Engine diese als Ausgangspunkt. Ein manueller Modus
erzwingt entsprechende Quellen und wird mit HTTP 409 abgelehnt, falls sie fehlen.
## Neu: NOISE-CORE Ω — PRESERVE FIRST (v0.4)
**Hauptregel:** Erhaltung von Musik, Luft, Hall, feinen Transienten und dem
Original hat Vorrang vor der Störminderung. Es gibt **keine Garantie**,
dass eine Reparatur bei Überlagerungen ausschließlich Störgeräusche ändert.
Daher setzt diese Version die Reparatur nicht automatisch ein.
**Bedienung**
1. Importiere eine Audiodatei im Studio.
2. Öffne **NOISE-CORE** und wähle **Störspur analysieren**.
3. Überprüfe einzelne Klick-Verdachtsfälle durch Anhören des Originals.
Kein Ereignis ist vorab ausgewählt; die Klick-Erkennung ist nur eine
Heuristik, **kein KI-Detektor** und kein Beweis für eine Störung.
4. Wähle einzelne geprüfte Ereignisse und die Reparaturstärke aus.
5. Bestätige die Reparatur. Es werden **nur die ausgewählten einzelnen
Samples** interpoliert; keine sonstigen Samples gezielt verändert.
6. Höre **Clean** und insbesondere **Differenzspur** an und exportiere
beide als WAV 32-bit Float plus JSON-Bericht.
Die Differenzspur ist exakt als `Original - Clean` berechnet (vor
Float32-Dateiquantisierung). Sie kann echte musikalische Inhalte enthalten.
Ein kleiner numerischer Rekonstruktionsfehler beweist **nicht**, dass die
Veränderung hörpsychologisch unbedenklich ist.
**Was absichtlich NICHT automatisiert ist**
- Keine pauschale Broadband-Noise-Reduction und kein Spectral-Gate.
- Keine 50/60-Hz-Notches ohne Prüfung, da Bassnoten oder Obertöne betroffen sein können.
- Keine generative Resynthese verlorener Musik.
- Keine selbständige Klassifikation als „sicheres Störgeräusch“.
- Keine angebliche KI-Qualität, wo nur Heuristiken vorliegen.
Tonal-Indikatoren bei 50/60/100/120 Hz sind ausschließlich **mehrdeutige
Spektralspitzen**, die ohne automatischen Eingriff angezeigt werden.
Ein Scan unterstützt auch Audiodateien von mehr als 180 Sekunden; RAM
bleibt durch blockweise Verarbeitung begrenzt. Die Dateigrößen-
und Speicherplatzgrenzen bleiben bestehen.
**API:**
- `POST /api/v1/jobs/noise/scan` mit `{"project_id": "[UUID]"}`;
- `POST /api/v1/jobs/noise/repair` mit `{"project_id":"[UUID]", "approved_samples":[4321], "strength":0.8}`;
- `GET /api/v1/projects/{id}/noise` für Scan/Repair-Bericht;
- `GET /api/v1/projects/{id}/noise/audio/{clean|difference}`;
- `GET /api/v1/projects/{id}/noise/export`.
## Neu: Kdenlive-kompatibler Virtual-Bass-Export (optional)
BASS-CORE bietet einen **separaten FFmpeg-Virtualbass-Adapter** (nur falls
`ffmpeg` mit Filter `virtualbass` lokal verfügbar ist). Dieser Filter
konvertiert **2-Kanal-Stereo → 2.1**. Die ursprünglichen Stereo-Kanäle werden
vom Filter unverändert weitergegeben; der dritte Kanal ist ein künstlich
generierter LFE-Kanal. Ein neuer Bass-Ton wird **nicht zurückgewonnen**.
Wähle in BASS-CORE `Cutoff` 100–500 Hz, `Strength` 0.5–3, starte den Export
und lade `ABSOLUTION_VIRTUAL_BASS_2_1.wav` herunter (WAV Float32).
Nur für echte Stereoquellen. Eine echte 2.1-Wiedergabekette wird empfohlen;
Browser-Audio unterstützt dreikanalige WAV-Dateien nicht zuverlässig.
Die LFE-Amplitude kann 0 dBFS überschreiten und muss im Zielsystem geprüft werden.
Offizielle Filterbeschreibung: https://ffmpeg.org/ffmpeg-filters.html#virtualbass
**API:**
- `POST /api/v1/jobs/bass/virtual` (`project_id`, `cutoff_hz`, `strength`);
- `GET /api/v1/projects/{id}/virtualbass`;
- `GET /api/v1/projects/{id}/virtualbass/audio` (2.1-WAV).
### Warum keine Normalisierung auf −0,01 dB vor Analyse/Trennung?
Weil Verstärkung keine fehlende Information wiederherstellt und spätere
Bearbeitung bei nahezu Vollaussteuerung leichter übersteuert. Originalpegel
unverändert halten; falls ein Modell Normalisierung braucht, nur reversible
temporäre Kopien mit dokumentiertem Verstärkungsfaktor verwenden.
Output-True-Peak-Messung nach der Bearbeitung, nicht aggressives
Pre-Normalizing. **−0,01 dBFS Sample-Peak ist keine Garantie für
−0,01 dBTP (True Peak).**
## Verarbeitung: BASS-CORE v0.3
- **DSP-Modus:** 45–350-Hz Tiefband mittels Zero-Phase-Crossover. Ein
transientenbasierter Maskierungsansatz schätzt Kick vs. Bassline.
Dies ist **keine** unabhängige Instrumentenquellentrennung.
- **HPSS-Modus:** Tiefband der vorab separierten `percussive`- und `harmonic`-Spuren.
Harmonische Instrumente außer Bass und tiefe Schlagzeuganteile können überlappen.
- **Demucs-Modus:** Tiefband der vorab geschätzten `drums`- und `bass`-Spuren.
Erfordert lokale Demucs-Gewichte und erfolgreiche Separation; automatische Downloads AUS.
- **Processing:** Pegelregler für Kick/Bassline, Bass-Subgain, Rumpelfilter,
symmetrische nichtlineare Obertongenerierung, Stereo-zu-Mono unter Grenzfrequenz,
Dry/Wet-Mischung.
- **Output-Ceiling:** nach dem Rendern wird *der optimierte Mix* bei Bedarf
global abgesenkt. Das ist **kein True-Peak-Limiter**. Einzelstems bleiben
unverändert und dürfen Peaks > 0 dBFS enthalten (WAV 32-bit Float).
- **Export:** `bass_band`, `kick_estimate`, `bassline_estimate`, `other_unprocessed`,
`harmonics_added`, `bass_optimized`, `mix_optimized`, jeweils WAV Float32 plus
separate PCM16-Hörvorschauen. ZIP enthält `bass_report.json`.
- **Consistency:** Die Zerlegung `kick_estimate + bassline_estimate +
other_unprocessed` entspricht dem eingelesenen Mix innerhalb einer numerischen
Toleranz. Das beweist nicht die semantische Reinheit.
Der Inspector zeigt Energien für Frequenzbänder von 20–1280 Hz aus dem ersten
Audio-Chunk. Er stellt keine Tonhöhen oder einzelnen Instrumente fest.
## Grenzen und Sicherheit
- Originaldateien bleiben unverändert gespeichert, inklusive SHA-256.
- Keine feste 180-Sekunden-Grenze. Maximalgröße standardmäßig 1024 MiB
(konfigurierbar über `ABSOLUTION_MAX_UPLOAD_MIB` bis 4096).
- Chunkweise/offline Verarbeitung vermindert, **eliminiert aber nicht** mögliche
Artefakte an Blockgrenzen. Sie kann erhebliche Diskkapazität erfordern
(sieben Float32-WAVs plus Vorschauen).
- Kein echtes Deep-Learning für die DSP-Schätzung. Keine Noten-/F0-Reparatur,
keine intelligenten Sub-Oszillatoren, kein echtes De-Clip, kein vollautomatisches KI-De-Noise, kein Echtzeit-Audio,
kein VST3-/AU-Hosting in v0.3. Diese Funktionen sind auf der Roadmap.
- Nicht für öffentliche Mehrbenutzer-Deployments geeignet:
Benutzeranmeldung, Job-Persistenz, Rate Limiting und Plugin-Sandbox fehlen.
- Keine Telemetrie und keine externen Modell-Downloads durch diese Anwendung.
- Für optionale Bibliotheken wie Demucs, Pedalboard/Surge XT und kommerzielle
VST-Plugins gelten jeweils eigene Lizenz-/Checkpoints-/Nutzungsbedingungen.
## Entwickler: API und Tests
```bash
python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows PowerShell:
# .venv\\Scripts\\Activate.ps1
pip install -e ".[dev]"
python -m pytest -q
python -m uvicorn app.server:app --host 127.0.0.1 --port 8000
```
### Wichtige API-Pfade
| HTTP | Pfad | Beschreibung |
|---|---|---|
| POST | `/api/v1/projects` | Projekt anlegen |
| POST | `/api/v1/assets` | WAV/FLAC/etc. importieren |
| POST | `/api/v1/jobs/separate` | HPSS oder optional Demucs |
| POST | `/api/v1/jobs/bass` | Neuer BASS-CORE-Job |
| GET | `/api/v1/jobs/{job_id}` | Status/Fortschritt |
| GET | `/api/v1/projects/{id}/bass` | Quelle, Report, Outputs |
| GET | `/api/v1/projects/{id}/bass/audio/{track}` | Master; `?preview=true` für Player |
| GET | `/api/v1/projects/{id}/bass/export` | ZIP aller Bass-Stems |
| GET | `/docs` | Interaktive OpenAPI-Dokumentation |
Beispiel-JSON für `/api/v1/jobs/bass`:
```json
{
"project_id": "[UUID-AUS-DER-PROJEKT-ANLAGE]",
"source_mode": "auto",
"crossover_hz": 220,
"kick_focus": 0.75,
"kick_gain_db": 2.0,
"bass_gain_db": 1.0,
"sub_gain_db": 1.5,
"harmonics": 0.35,
"lowcut_hz": 22,
"mono_below_hz": 100,
"wet": 1.0,
"ceiling_dbfs": -1.0
}
```
## KI-Roadmap nach Erhaltungs-Priorität
1. **AI Noise Event Triage:** Click-vs-Instrumenten-Transient-Klassifikator
auf echten musikalischen Negativbeispielen, mit Unsicherheits-Gating/
Abstention; keine automatische Massenreparatur.
2. **Source-aware Noise:** Zwischen Bass, Schlagzeug, Stimmen und Rest
separieren; Störhypothese gezielt im betreffenden Stem prüfen.
3. **Harmonic Preservation:** Zeit-Frequenz-Masken mit Erhaltung von
Noten, Harmonischen, Atemgeräuschen, Hallfahnen und Transienten.
Nicht sicher unterscheidbare Energie bleibt im Original.
4. **Independent Repair Judge:** Automatische Vorher-/Nachher-Prüfung,
Difference-Stem, Nulltests, Blindhörtest und Leckage-/Transientmetriken.
5. Echte Bass-/Drum-Separation durch modellbasierte Quellenzerlegung und
mehrstufige Kick-/Bassline-/808-Klassifikation.
6. Semantischer Low-End-Eventgraph mit validiertem F0- und Transienten-Tracking.
7. Optionaler phase-/pitch-locked Sub-Synthesizer unter Unsicherheits-Gating.
8. Selektive Event-Reparatur (z. B. Clicks und Dropouts) mit Provenance.
9. Geschützter, separat betriebener VST3-/AU-Host und kommerzielle Lizenzprüfung;
externe Plugins dürfen niemals ungeprüft im API-Prozess laufen.
10. True-Peak-Meter/Limiter, Oversampling, A/B-Loudness-Matching, Listening Benchmarks
und getrennte quantitative Benchmarks mit Ground Truth.
Alle Forschungsstufen sind noch nicht implementiert. Eine mathematisch
saubere Restmischung ist nicht gleichbedeutend mit perfekten Original-Stems.
## Weitere Dokumentation
Siehe `docs/ARCHITECTURE.md`, `docs/LICENSE_AND_SECURITY.md`, `docs/WEBSITE.md`.
## Dokumentation NOISE-CORE
Siehe `docs/NOISE_CORE_DESIGN.md` für Schutzprinzipien, Grenzen und Teststrategie.