README.md

---
title: AudioSR Wzbogacanie Probek
emoji: 🎙️
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 6.17.3
python_version: "3.10"
app_file: app.py
pinned: false
---

# AudioSR — wzbogacanie krótkich próbek głosu (CPU / darmowy)

Twój Space do super-rozdzielczości audio (AudioSR, k2-fsa/haoheliu): krótki klip → 48 kHz.
Próbki służą jako **referencja do klonowania głosu** (RVC/Applio + zero-shot TTS OmniVoice).
UI w kolorystyce Lektor AI. Pole do wrzucenia próbki → odtwarzacz + przycisk pobierania WAV.

## Tryb NO-FIDDLE — backend ustawiony za Ciebie

Cały „know-how" przetwarzania jest **zaszyty w backendzie** — nie ma czego dłubać.
Frontend ma **TYLKO dwie kontrolki**:

- **DDIM steps** — suwak jakość vs czas (więcej kroków = lepiej, ale wolniej).
- **Normalizuj** — przełącznik dwustopniowej normalizacji (LUFS → sufit szczytu).

Stałe backendu (hardcode, nie do ruszania): model `basic`, guidance `3.5`, seed `42`,
`latent_t_per_second = 12.8`.

## Pipeline

```
(opcjonalny zewnętrzny UVR5 de-reverb)
        ↓
AudioSR (super-rozdzielczość, 48 kHz)   ← AudioSR ZAWSZE przed normalizacją
        ↓
przycięcie paddingu AudioSR do długości wejścia
        ↓
postproc.process(...)   ← czyszczenie + normalizacja (czysty DSP, testowalny)
        ↓
zapis WAV 48 kHz (odtwarzacz + pobieranie)
```

### Normalizuj **WŁĄCZONE** (kolejność istotna)

1. **force-mono** — embeddery (hubert / contentvec / spin-v2) oczekują mono; stereo grozi
   kasowaniem fazy.
2. **usunięcie DC** — odjęcie składowej stałej.
3. **high-pass ~75 Hz** — Butterworth rz. 2, **zero-phase** (`scipy` filtfilt) — zdejmuje
   rumble/szum sieciowy, **nie rusza barwy** głosu, nie rozmywa transjentów.
4. **LUFS normalize → -18 LUFS** — wg **ITU-R BS.1770-4** (`pyloudnorm` Meter, K-weighting);
   podnosi percepcyjną głośność/gęstość, by model uczył się barwy także z cichszych miejsc.
   Odporny fallback dla bardzo krótkich/cichych klipów (mniejszy block_size → RMS).
5. **sufit szczytu -1 dB** — **wyłącznie redukcja wzmocnienia** (gain-down), gdy szczyt > -1 dB.
   **Zero kompresji / limitera / clipingu** — czysta zmiana skali (nie myli embedderów).

Wynik zapisywany jako **WAV 16-bit PCM** (`subtype=PCM_16`) — sufit -1 dB istnieje właśnie po to,
by kontener nigdy nie obciął na ±1.0.

> **Kompromis LUFS ↔ szczyt (uczciwie):** przy pojedynczym głośnym transjencie (plozja, klik)
> sufit -1 dB może zejść wzmocnieniem na tyle, że cel **-18 LUFS nie zostanie dotrzymany** — bez
> limitera nie da się mieć obu naraz, a limitera świadomie NIE dodajemy (psułby barwę). W takim
> wypadku apka **wypisuje pomarańczowe ostrzeżenie** z brakującą liczbą dB (zamiast cicho udawać
> sukces) i sugeruje ręczne wyciszenie transjentu w Audacity. Na normalnej mowie cel -18 wchodzi.

### Normalizuj **WYŁĄCZONE**

force-mono → dopasowanie poziomu **RMS** wyjścia do oryginału → bezpiecznik szczytu **0.99**
(bez high-passu / LUFS). To dotychczasowe, łagodne zachowanie.

## Co ŚWIADOMIE pominięto (i dlaczego)

Backend bierze tylko **uniwersalnie bezpieczne, automatyzowalne** kroki. Pomijamy te, które
agy (red-team Gemini 3.1 Pro) sam ostrzega, że są **niebezpieczne w ciemno**:

- **Spektralna redukcja szumu** — #1 zabójca barwy; nie da się wiarygodnie auto-profilować.
- **Wycięcie rezonansu EQ** — szkodliwe na już-czystym audio.
- **UVR5 de-reverb** — narzędzie **zewnętrzne**, nie wbudowane w apkę.
- **Ręczne usuwanie klików/plozji** — nieautomatyzowalne bezpiecznie (wymaga ucha).
- **Kompresja / limiter / noise gate / boost EQ** — spłaszczają dynamikę, zabijają transjenty,
  podbijają sybilanty → szkodzą jako referencja TTS/RVC.

**Warunkowy de-esser** (tnij 6–8 kHz o ≤3 dB tylko gdy pasmo gorące) jest **zaimplementowany,
ale domyślnie WYŁĄCZONY** (`postproc.DEESS_ENABLED = False`): w trybie w pełni automatycznym
de-essing w ciemno ryzykuje zmatowienie spółgłosek, które AudioSR dopiero odbudował.

> Źródło prawdy o jakości to jakość **nagrania** (cichy pokój) > każdy post-processing.
> Próbkowania **nie schodzimy** w dół — RVC sam zresampluje do 32k/40k w preprocesie Applio.

## Architektura plików

- `app.py` — UI Gradio + orkiestracja AudioSR (model cache, progress/ETA, padding trim).
- `postproc.py` — **czysty DSP** (numpy/scipy/soundfile/pyloudnorm), bez gradio →
  testowalny lokalnie: `python postproc.py` (samotest: DC, LUFS, sufit, krótki klip).
- `viz.py` — wykres widma (wierzchołki / góra pasma) jako `<img>`.

`scipy==1.10.1` i `pyloudnorm==0.1.1` są **przypięte** pod `numpy==1.23.5`/py3.10 (koła
manylinux cp310 zweryfikowane) — bez tego resolver mógłby ściągnąć scipy zbudowane pod
numpy 2.x i wywalić build. Importy DSP są dodatkowo **miękkie**: brak scipy → pomiń HPF,
brak pyloudnorm → RMS-fallback (apka degraduje, nie pada).

## Hosting (darmowy)

- Nowy Space → SDK **Gradio**, Hardware **CPU basic (free)**, Visibility **Private**
  (Twój głos zostaje u Ciebie).
- Wgraj: `app.py`, `postproc.py`, `viz.py`, `requirements.txt`, `README.md`.
- **CPU**: 1 klip ≈ ~2 min (dyfuzja). Domyślnie model **basic**, **24 kroki**.

## Uwaga

Pierwsze uruchomienie pobiera checkpointy AudioSR z HF (kilka GB) — pierwszy klip wolniejszy.