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.