Spaces:
Paused
Paused
File size: 34,604 Bytes
1b88372 e880b2b 29c3be9 1b88372 29c3be9 1b88372 6049960 607c4f0 1b88372 6049960 29c3be9 e880b2b 544e3ba e880b2b ea9092c e880b2b ea9092c e880b2b 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 ca4ec99 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 ca4ec99 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 e880b2b 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 29c3be9 607c4f0 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 | ---
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.
|