README.md

---
title: Audio Denoise
emoji: 🎙️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: "6.9.0"
python_version: "3.12"
app_file: app.py
pinned: false
short_description: Limpieza de voz y control de entregas de audio
---

# 🎙️ Limpieza y control de voz — documentación técnica

> **¿Vas a usar la app?** Todo lo que necesitas está en la pestaña **❓ Ayuda** de la propia app.
> Este documento es para mantenerla: cómo está hecha, cómo crear proyectos nuevos y cómo publicarla.

La app reduce el ruido de grabaciones de voz sin perder naturalidad y comprueba que cada audio cumple la especificación técnica de un cliente (un *perfil*). Si no cumple, genera la versión corregida y un informe en Excel. Funciona en Hugging Face con **ZeroGPU**; si no hay cuota de GPU, sigue en CPU automáticamente.

---

## 1. Publicar cambios en Hugging Face

El código vive en GitHub y el Space es una copia que se actualiza con un botón.

1. Los cambios tienen que estar en la rama `main` de GitHub. Si vienen en otra rama, primero hay que fusionar el *pull request* con **Merge pull request**.
2. En GitHub: **Actions** → **Desplegar en Hugging Face** → **Run workflow** → **Run workflow**.
3. Al cabo de un minuto aparece ✅. El Space se reconstruye solo: con cambios en `requirements.txt` o `packages.txt` tarda 5–10 minutos; si no, menos de uno.

Configuración, una sola vez (ya hecha):

| Dónde | Qué |
|---|---|
| GitHub → Settings → Secrets and variables → Actions → **Secrets** | `HF_TOKEN`: token de Hugging Face de tipo **Write** |
| GitHub → … → **Variables** (opcional) | `HF_SPACE`: si no existe, se usa `Azuredraco/audio-denoise` |

Alternativa desde el PC: `python scripts/deploy_hf.py --space Azuredraco/audio-denoise`. Usa el token de `hf auth login` o el de la variable de entorno `HF_TOKEN`.

El Space queda como copia exacta del repositorio, sin `tests/`, `scripts/` ni `.github/`.

### Versión para Windows

Cada vez que entra un cambio en `main`, GitHub construye **solo** la versión de escritorio (workflow *Versión para Windows*). La prueba en un Windows real y la publica en **https://huggingface.co/Azuredraco/limpieza-de-voz-windows**. El Space tiene un enlace a esa página. Tarda unos 15–20 minutos. También se puede lanzar a mano desde **Actions → Versión para Windows → Run workflow**.

- **Instalador** `Instalar-Limpieza-de-voz.exe`: no pide permisos de administrador. Crea accesos directos en el escritorio y en el menú Inicio, y al ejecutar uno nuevo actualiza encima.
- **Portable** `Limpieza-de-voz-portable.zip`: se descomprime y se abre con `Iniciar.bat`.
- Lleva dentro su propio Python 3.11, las dependencias (PyTorch CPU) y los modelos: **funciona sin internet**. Ocupa ~1 GB instalado.
- Por dentro es la misma app (`app.py`) en `127.0.0.1`. `desktop/iniciar.py` la arranca y abre el navegador; la ventana negra es el servidor.
- Ficheros: `desktop/` (lanzador, prueba de humo, icono, script de Inno Setup y publicación) y `requirements-desktop.txt`.

El repositorio de GitHub es privado, por eso el instalador se publica en Hugging Face: así se descarga sin necesidad de cuenta.

---

## 2. Perfiles de proyecto (`perfiles/*.yaml`)

Cada proyecto o cliente es un fichero YAML. Al crear uno nuevo, aparece solo en el desplegable «Proyecto».

| Fichero | Nombre en la app | Uso |
|---|---|---|
| `multiling_es-es_01.yaml` | MultiLing · voz femenina es-ES (40 min) | Encargo MultiLing: WAV PCM, 48 kHz, ≥ 24 bits, SNR ≥ 50 dB. Sin recortes ni cambios de volumen (el cliente quiere la toma entera). Controla los 6 entregables y el objetivo de 40 min. |
| `analizador_v4.yaml` | Proyecto 12 h 30 min · mismas reglas que el analizador v4 | Las mismas reglas que el *Analizador de audio v4* en HTML: WAV PCM 24 bits, 48 kHz, mono, pico ≤ −3 dBFS, RMS de voz −30…−20 dBFS, ruido ≤ −40 dB y silencios de 0,5–0,7 s. |
| `asr_dialogo_dos_pistas.yaml` | ASR · diálogo a dos pistas | Encargo ASR Dual-Track: WAV PCM 16 bits, 48 kHz, mono, espectro > 22 kHz, ruido de fondo ≤ −50 dBFS, voz > 5000 (escala 16 bits), sin saturación. Arranca en nivel «Solo formato» (el PDF pide sin procesado). Comprueba parejas de pistas (misma duración, sin voz cruzada). |
| `libre.yaml` | Solo limpiar ruido · sin reglas de cliente | Solo limpieza; conserva formato, frecuencia y canales. |

### Crear un perfil nuevo
Copia el que más se parezca, cámbiale el nombre al fichero y edita los valores. Todas las secciones son opcionales: lo que no pongas no se comprueba.

```yaml
nombre: "Cliente X · audiolibro (10 h)"      # lo que se ve en el desplegable
descripcion: "WAV 24 bits · 44,1 kHz · …"    # resumen técnico de una línea
explicacion: |                               # lo que ve el usuario bajo el desplegable (Markdown)
  - **Qué pide el cliente:** …
  - **Qué hace la corrección:** …
orden: 3                                     # posición en el desplegable
procesar_siempre: false                      # true = limpiar aunque ya cumpla

formato:
  contenedor: WAV         # WAV | FLAC | AIFF
  pcm_entero: true        # exige PCM entero (no coma flotante)
  bits: 24                # exactamente 24…  (o bien)  bits_min: 24  → 24 o más
  frecuencia: 48000       # Hz; la corrección remuestrea
  ancho_banda_min_hz: 22000   # el espectro debe llegar más allá (detecta audio filtrado, comprimido o de 44,1 kHz)
  canales: 1              # 1 = exige mono (la casilla «Convertir a mono» sale marcada); null = sin requisito

niveles:
  pico_max_dbfs: -3.0     # techo de picos (se aplica limitador)
  rms_voz: {min: -30, max: -20, objetivo: -25}   # volumen medio de la voz; corrige al objetivo
  amplitud_voz_min: 5000  # muestra más alta de la voz en escala de 16 bits (0–32767)

ruido:
  snr_min_db: 50          # voz activa frente a ruido de las pausas
  ruido_relativo_max_db: -40   # primeros/últimos 0,4 s frente a la voz (criterio del analizador v4)
  ruido_fondo_max_dbfs: -50    # nivel absoluto del ruido de las pausas

silencios:                # null = no tocar inicio ni final
  min_s: 0.5
  max_s: 0.7
  objetivo_s: 0.6
  relleno: tono_sala      # tono_sala (ruido ambiente real, recomendado) | digital (ceros)

saturacion_max_muestras: 0
pistas_pareadas: false    # true = diálogo a dos pistas: comprueba duraciones idénticas y voz cruzada

procesado:                # valores por defecto de «Opciones avanzadas»
  reduccion_db: 24        # 12 Suave · 24 Natural · 36 Fuerte · null Máximo
  paso_alto_hz: 70        # null = sin filtro
  conservar_ultrasonidos: true
  salida: {contenedor: WAV, subtipo: PCM_24}   # null = como el original
  modo_defecto: ninja     # nivel de procesado inicial: formato | permitido | ninja (el usuario lo cambia en la app)

entregables:              # opcional: control de ficheros y duración total
  objetivo_total_s: 2400
  ficheros:
    - {nombre: "nonverbal_laughter", duracion_min_s: 30}
    - {nombre: "full recording_part 1", duracion_aprox_s: 760}
```

Los nombres de los entregables se comparan sin distinguir mayúsculas, extensión, espacios ni guiones bajos.

---

## 3. Cómo funciona

### Cadena de corrección (`pipeline.py`)
1. **Canales:** se conservan, salvo que se marque «Convertir a mono».
2. **Paso alto** Butterworth de fase cero, a 70 Hz por defecto. Quita retumbes, golpes graves y DC.
3. **Remuestreo** con SoX VHQ (fase lineal, sin desfase) a la frecuencia exigida.
4. **DeepFilterNet3** a 48 kHz, por bloques de 60 s con 5 s de contexto y fundido cruzado. Así los ficheros de 30 min o más tienen memoria acotada y llamadas a GPU cortas.
   - Si no se alcanza el ruido exigido, se escala la reducción: 24 → 36 dB → sin límite.
   - Como último recurso, un expansor de −15 dB solo en las pausas, con 100 ms de margen antes de la voz y 200 ms después.
5. **Más de 48 kHz:** la banda > 20 kHz no pasa por el modelo. Se conserva del original mediante un cruce FIR complementario, con una ganancia que sigue la reducción aplicada en 12–20 kHz.
6. **Silencios inicial/final:** recorte, o relleno con tono de sala (el tramo sin voz más silencioso de la propia toma, con fundidos de potencia constante).
7. **Nivel:** ganancia hasta el RMS objetivo y limitador de picos con anticipación. El limitador es un mínimo deslizante suavizado, sin sobreoscilación garantizada.
8. **Escritura** (dither TPDF si se baja a 16 bits) y **nueva medición del fichero escrito**: la columna «Después» es real.

### Métricas (`metrics.py`, `dnsmos.py`)
- **Pico** (dBFS) y **pico real** (dBTP, sobremuestreo ×4, por bloques).
- **RMS de voz** entre la primera y la última voz, como el analizador v4.
- **Ruido relativo** de los primeros/últimos 0,4 s frente a la voz.
- **SNR**: voz activa frente a ruido de pausas.
- **Silencios**: la detección de voz ignora clics y golpes de menos de 120 ms.
- **Saturación** y **LUFS** (BS.1770-4; coeficientes verificados con la tabla ITU).
- **DNSMOS** P.835 de Microsoft: SIG (voz), BAK (fondo) y OVRL (global), de 1 a 5. Usa como mucho 10 ventanas de 9 s repartidas por el audio. Es opcional («⭐ Poner nota de calidad al corregir», desmarcada por defecto) porque en CPUs modestas triplica el tiempo.

### ZeroGPU
- `denoise_core.py` coloca el modelo en `cuda` a nivel de módulo (patrón oficial de ZeroGPU) y decora la inferencia con `@spaces.GPU` y duración dinámica. Cada llamada cubre hasta 5 min de audio.
- **La GPU solo se usa con audios de 90 s o más.** Para audios cortos, la espera de ZeroGPU (cola, asignación, comprobación de cuota) cuesta más que procesar en CPU.
- Si una llamada falla (cuota, cola, timeout), el resto del fichero va por CPU con el mismo resultado. Durante 15 minutos no se vuelve a intentar con GPU, para no repetir la espera.
- Si el original tiene mucho más ruido del permitido, la corrección empieza directamente por el escalón de reducción necesario. Así no se pasa el modelo varias veces.
- Cuota diaria según la documentación de HF: 2 min sin sesión, 5 min con cuenta gratuita, 40 min con PRO.

### Ficheros
| Fichero | Contenido |
|---|---|
| `app.py` | Interfaz Gradio y textos de ayuda para el usuario |
| `ui_html.py` | Tarjetas de resultados, CSS (móvil, modo claro/oscuro) |
| `pipeline.py` | Analizar y corregir según un perfil |
| `denoise_core.py` | DeepFilterNet3 + ZeroGPU + respaldo en CPU |
| `dsp.py` | Remuestreo, filtros, detección de voz, silencios, limitador, expansor |
| `metrics.py` · `dnsmos.py` | Mediciones |
| `profiles.py` · `perfiles/` | Carga de perfiles y comprobaciones |
| `vad.py` | Detector de voz neuronal (Silero VAD) para los ruidos sueltos |
| `pairs.py` | Parejas de pistas: misma duración y voz cruzada |
| `report.py` | Informe Excel y CSV |
| `audio_io.py` | Lectura (soundfile o ffmpeg) y escritura |
| `models.py` | Descarga de modelos (DeepFilterNet3, DNSMOS, Silero VAD) verificada por SHA-256 |

---

## 4. Trabajo en local (Windows / PyCharm)

```bash
python -m venv .venv
.venv\Scripts\activate            # Linux/Mac: source .venv/bin/activate
pip install -r requirements-dev.txt
python app.py                     # http://localhost:7860
python -m pytest -q tests
```

`deepfilternet` 0.5.6 compila una parte en Rust si no hay paquete precompilado para tu sistema; en Windows hay que instalar [Rust](https://rustup.rs) la primera vez. Las versiones están fijadas en `requirements.txt`: `deepfilternet` exige `numpy < 2` y ZeroGPU exige `torch ≥ 2.8`. Los modelos se descargan la primera vez en `~/.cache/audio-denoise`.

## Créditos
- [DeepFilterNet](https://github.com/Rikorose/DeepFilterNet) (H. Schröter et al.), reducción de ruido.
- [DNSMOS](https://github.com/microsoft/DNS-Challenge/tree/master/DNSMOS) (Microsoft), calidad percibida.