# GR Processor — Manual de Usuario
**Versión 0.2.0 · Sistema de procesamiento de audio multiband para radio FM**

---

## Índice

1. [Introducción](#1-introducción)
2. [Instalación y requisitos](#2-instalación-y-requisitos)
3. [Inicio rápido](#3-inicio-rápido)
4. [Interfaz Modo Escritorio](#4-interfaz-modo-escritorio)
5. [Interfaz Modo Rack 3U](#5-interfaz-modo-rack-3u)
6. [Controles globales](#6-controles-globales)
7. [Procesamiento por banda](#7-procesamiento-por-banda)
8. [Sección MPX](#8-sección-mpx)
9. [Presets](#9-presets)
10. [Stand By y comparación A/B](#10-stand-by-y-comparación-ab)
11. [Cadena de procesamiento DSP](#11-cadena-de-procesamiento-dsp)
12. [Parámetros de referencia por género](#12-parámetros-de-referencia-por-género)
13. [Solución de problemas](#13-solución-de-problemas)

---

## 1. Introducción

**GR Processor** es un procesador de audio multiband diseñado para emisoras de radio FM. Procesa el audio en tiempo real separándolo en hasta **6 bandas de frecuencia independientes**, aplicando compresor, clipper y control de ganancia a cada banda antes de sumarlas en una señal de alta densidad sonora, lista para transmisión.

El procesador incluye un **codificador MPX** para la generación de la señal estéreo FM según el estándar ITU-R BS.450 (pre-énfasis 75 µs NRSC o 50 µs ITU), activo cuando la tarjeta de salida opera a ≥ 96 kHz.

---

## 2. Instalación y requisitos

### Requisitos del sistema

| Componente | Mínimo | Recomendado |
|-----------|--------|-------------|
| OS | Linux (ALSA/PipeWire) | Debian 12+ / Ubuntu 22.04+ |
| CPU | x86_64 o ARM64 | Cualquier dual-core moderno |
| RAM | 256 MB | 512 MB |
| Audio | Tarjeta ALSA compatible | 2 tarjetas separadas (entrada/salida) |
| Latencia | 512 frames (~10 ms) | 256 frames (~5 ms) |

### Compilar desde fuente

```bash
# Dependencias
sudo apt install build-essential libgtk-4-dev libasound2-dev pkg-config

# Instalar Rust (si no está)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env

# Compilar
cd gr-processor
cargo build --release

# Ejecutar
RUST_LOG=info ./target/release/gr-processor
```

---

## 3. Inicio rápido

1. **Conectar audio**: conecta la fuente de audio (reproductor, consola) a la **tarjeta de entrada** y el destino (excitador FM, grabadora) a la **tarjeta de salida**. Si solo hay una tarjeta, se usa la misma para entrada y salida (loopback).

2. **Arrancar la aplicación**: `./target/release/gr-processor`

3. **Verificar audio**: los metros **INPUT** (arriba) deben moverse al recibir audio. Los metros **OUTPUT** muestran la señal procesada.

4. **Cargar un preset**: en el selector **PRESET** (arriba a la derecha), elige **VOICE** para locutores o **ROCK** para música general, y pulsa **▶ LOAD**.

5. **Ajustar**: mueve el control **OUT GAIN** hasta que el nivel de salida sea el deseado. El limitador **LIM** controla el pico máximo (normalmente −0.3 dBFS).

6. **Stand By**: pulsa **⏸ STAND BY** para comparar la señal sin procesar con la procesada. Cuando está activo, el audio pasa directo sin ningún efecto DSP.

---

## 4. Interfaz Modo Escritorio

El modo escritorio muestra el procesador en pantalla completa con todos los controles visibles simultáneamente.

```
┌──────────────────────────────────────────────────────────────┐
│ [Logo] GR PROCESSOR   [IN] [OUT] [LIM]    PRESET ▼ [LOAD][SAVE]│
├──────────────────────────────────────────────────────────────┤
│BANDS│  B1   │  B2   │  B3   │  B4   │  B5   │  B6   │MPX │OUT│
│IN─ │ [VU GR│ VU GR │ VU GR │ VU GR │ VU GR │ VU GR]│    │LIM│
│    │ THR   │ THR   │  ...  │       │       │       │    │   │
│    │ RAT   │  ...  │       │       │       │       │    │   │
│    │ ATK   │       │       │       │       │       │    │   │
│    │ REL   │       │       │       │       │       │    │   │
│    │ GAIN  │       │       │       │       │       │    │   │
│    │[CLIP] │       │       │       │       │       │    │   │
│    │ LVL   │       │       │       │       │       │    │   │
│    │ [ON]  │       │       │       │       │       │    │   │
└──────────────────────────────────────────────────────────────┘
```

### Columnas de banda (B1–B6)

Cada columna representa una banda de frecuencias. Las bandas inactivas (más allá del número seleccionado) aparecen **atenuadas** (22% de opacidad).

| Elemento | Descripción |
|----------|-------------|
| **B1..B6** | Número de banda y rango de frecuencias |
| **VU** | Vúmetro LED del nivel de señal en esa banda (verde → amarillo → rojo) |
| **GR** | Meter de Gain Reduction — indica cuánta compresión se está aplicando (azul, desde arriba) |
| **THR** | Umbral de compresión (dBFS) |
| **RATIO** | Relación de compresión (1:1 = sin compresión, 20:1 = limitador) |
| **ATK** | Tiempo de ataque en ms — rapidez con que reacciona al nivel superado |
| **REL** | Tiempo de release en ms — rapidez con que suelta la ganancia |
| **GAIN** | Makeup gain (dB) — compensación de nivel después de comprimir |
| **CLIP** | Activa/desactiva el clipper suave (tanh) en esa banda |
| **LVL** | Nivel de clipper (dBFS) — nivel al que empieza el clipping suave |
| **ON** | Activa/desactiva el procesamiento completo de la banda (bypass de banda) |

---

## 5. Interfaz Modo Rack 3U

El modo Rack simula visualmente el **frente de un procesador de rack de 3 unidades** (19", 133 mm de altura). Es ideal para uso en estudio o sala de control.

```
┌──────────┬───────────────────────────┬──────────┬──────┬────────┬────────────────┐
│[Logo]    │ B1   B2   B3   B4   B5  B6│ IN   OUT │ MPX  │MPX OUT │PRESET▼ OUT LIM│
│GR PROC.  │[VU][VU][VU][VU][VU][VU]  │[##] [##] │      │ [##]   │        ─── ─  │
│BANDS [▲▼]│[GR][GR][GR][GR][GR][GR]  │[LIM][LIM]│      │        │⏸ STAND BY     │
│IN [─────]│                           │          │      │        │                │
└──────────┴───────────────────────────┴──────────┴──────┴────────┴────────────────┘
┌─ BAND CONFIG ─ [B1●][B2][B3][B4][B5][B6] ─────────────────────────────────────[▲]┐
│        THR     RATIO    ATK     REL     GAIN    CLIP LVL   [CLIP] [ON]            │
└────────────────────────────────────────────────────────────────────────────────────┘
```

### Cajón de configuración de banda

El **cajón** (panel inferior deslizable) se abre haciendo **clic en cualquier banda** del strip. Contiene los mismos knobs de configuración que el modo escritorio.

- **Pestañas B1–B6**: cambian la banda configurada sin cerrar el cajón
- **Botón ▲**: cierra el cajón
- El cajón se abre con animación suave hacia abajo

### Cambio de modo

La **barra de modo** (visible en ambas vistas):
- **⊞ ESCRITORIO** — vista expandida con todas las columnas
- **▣ RACK 3U** — vista compacta estilo rack de 19"

---

## 6. Controles globales

### BANDS (SpinButton, 2–6)

Selecciona el número de bandas activas. Al cambiar:
- Las frecuencias de corte se ajustan automáticamente para cubrir todo el espectro (20 Hz – 20 kHz)
- Las bandas excedentes se atenúan visualmente y dejan de procesar

**Crossovers por defecto según número de bandas:**

| Bandas | Frecuencias de corte |
|--------|---------------------|
| 2 | 800 Hz |
| 3 | 300 Hz · 3 kHz |
| 4 | 150 Hz · 1 kHz · 6 kHz |
| 5 | 120 Hz · 400 Hz · 2 kHz · 6 kHz |
| 6 | 80 Hz · 320 Hz · 1.2 kHz · 4.8 kHz · 12 kHz |

### IN GAIN / OUT GAIN (deslizador, −12 a +12 dB)

- **IN GAIN**: ganancia aplicada a la entrada antes de cualquier procesamiento. Útil para nivelar la señal de entrada.
- **OUT GAIN**: ganancia aplicada a la salida después del limitador. Controla el nivel final entregado a la tarjeta de salida.

### LIMITER (deslizador, −6 a 0 dBFS)

Umbral del limitador de pico final (brick-wall). El limitador actúa sobre la señal sumada después de todas las bandas. Valor típico para FM: **−0.3 dBFS**.

---

## 7. Procesamiento por banda

El audio pasa por la siguiente cadena en cada banda:

```
Entrada → [Crossover LR4] → [Compresor] → [Clipper] → Suma → [Limitador] → Salida
```

### Crossover Linkwitz-Riley 4° orden (LR4)

El crossover divide la señal usando filtros **Linkwitz-Riley de 4° orden** (cascada de dos Butterworth de 2° orden). Propiedades:
- La suma de todas las bandas es plana en magnitud (sin coloración)
- −6 dB en la frecuencia de corte
- Fase coherente entre bandas

### Compresor (linked stereo, feed-forward, RMS)

**Linked stereo**: L y R reciben la misma ganancia calculada a partir de la potencia total (L² + R²). Preserva la imagen estéreo durante la compresión.

**Feed-forward**: detecta el nivel en la entrada (no la salida). Comportamiento más predecible.

**Parámetros:**

| Parámetro | Rango | Efecto |
|-----------|-------|--------|
| **THR** (Threshold) | −60 a 0 dBFS | Nivel a partir del cual comprime |
| **RATIO** | 1:1 a 20:1 | Fuerza de la compresión. 1:1 = transparente, ∞:1 = limitador |
| **ATK** (Attack) | 0.1 a 200 ms | Rapidez de respuesta. Valores bajos = compresión más agresiva |
| **REL** (Release) | 10 a 2000 ms | Tiempo para soltar la ganancia. Valores altos = más "pump" |
| **GAIN** (Makeup) | 0 a 24 dB | Compensa la ganancia perdida por la compresión |

**Indicador GR** (Gain Reduction): el meter azul de cada banda muestra cuánta reducción de ganancia está aplicando el compresor. Si el meter GR está inactivo, no hay compresión en esa banda.

### Clipper suave (tanh)

Aplica una función tangente hiperbólica que limita el nivel de forma suave, generando armónicos impares que suenan musicalmente densos (similar a la saturación de transformadores analógicos).

| Parámetro | Efecto |
|-----------|--------|
| **CLIP** (checkbox) | Activa/desactiva el clipper en la banda |
| **LVL** | Nivel al que el clipper entra en acción (−12 a 0 dBFS) |

**Consejo**: para sonido de radio denso, usar CLIP habilitado con LVL entre −1 y −0.5 dBFS.

---

## 8. Sección MPX

El codificador MPX convierte la señal estéreo procesada en la señal compuesta FM estándar.

### Señal MPX FM estándar (ITU-R BS.450)

```
MPX = (L+R)×0.45  +  Piloto(19kHz)×0.09  +  (L−R)×0.45×cos(38kHz)
      ─────────────  ─────────────────────   ──────────────────────────
      Canal principal  Tono piloto estéreo    Subportadora DSB-SC
      monocompatible   (señaliza estéreo)     (contiene diferencia L−R)
```

El receptor FM usa el piloto de 19 kHz para regenerar los 38 kHz y demodular el canal de diferencia (L−R), reconstruyendo L y R.

**Requisito de sample rate**: la subportadora de 38 kHz requiere que la tarjeta de salida opere a **≥ 96 kHz**. A 48 kHz, el procesador entrega solo el canal principal (L+R) con pre-énfasis aplicado (compatible mono).

### Controles MPX

| Control | Descripción |
|---------|-------------|
| **Switch ON/OFF** | Activa la codificación MPX |
| **75 µs (NRSC)** | Pre-énfasis según estándar norteamericano (EE.UU., Canadá, Japón) |
| **50 µs (ITU)** | Pre-énfasis según estándar europeo / internacional |
| **MPX LEVEL** | Nivel de salida de la señal MPX (dB) |
| **PILOT 19kHz** | Porcentaje del piloto (estándar: 9%) |
| **MPX OUT** | Metros de nivel de la señal MPX compuesta |

### Pre-énfasis

El pre-énfasis boosteea las altas frecuencias antes de la transmisión para mejorar la relación señal/ruido. El receptor aplica la curva inversa (de-énfasis). Escoge el estándar según tu región:

- **75 µs**: América del Norte, Japón
- **50 µs**: Europa, América del Sur, Asia, África, Australia

---

## 9. Presets

Los presets guardan toda la configuración de procesamiento (bandas, compresores, crossover, MPX). **No guardan** la selección de tarjeta de audio ni el sample rate.

### Presets de fábrica

| Preset | Bandas | Descripción |
|--------|--------|-------------|
| **ROCK** | 5 | Compresión agresiva (ratio 4–5:1), énfasis en medios 400Hz–2kHz, clips a −0.5 dBFS. Para rock, pop y formatos de alta densidad. |
| **BLUE** | 5 | Suave y cálido (ratio 2.5–3:1), lento. Blues, jazz, R&B. Preserva la dinámica natural. |
| **CLASIC** | 5 | Muy transparente (ratio 1.5–2:1), tiempos largos. Clásica, orquestal. Mínima coloración. |
| **VOICE** | 5 | Optimizado para locutores FM: presencia vocal intensa en 400Hz–2kHz (+7 dB makeup), de-essing agresivo (8:1) en 2–6kHz. |
| **HARD BASS** | 6 | Electrónica, hip-hop. Sub bestial (<80 Hz: ratio 8:1, +12 dB makeup), 6 bandas con crossover extendido a 12kHz. |
| **STRONG** | 5 | Máxima densidad y loudness. Todas las bandas a 8:1, +10 dB makeup, limiter −0.1 dBFS. Radio de alta competencia. |

### Guardar preset de usuario

1. Ajusta los parámetros a tu gusto
2. Pulsa **● SAVE** (arriba a la derecha)
3. Introduce un nombre y confirma
4. El preset se guarda en `~/.config/gr-processor/presets/<nombre>.json`

Los presets de usuario aparecen al final del selector, después de los presets de fábrica.

### Editar o eliminar presets de usuario

Los presets son archivos JSON en `~/.config/gr-processor/presets/`. Puedes editarlos con cualquier editor de texto o eliminarlos para quitarlos del selector.

---

## 10. Stand By y comparación A/B

El botón **⏸ STAND BY** (barra de modo, visible en ambas interfaces) activa el **bypass total del procesamiento**.

Cuando está activo:
- El audio pasa directamente de entrada a salida **sin ningún procesamiento DSP**
- Los metros INPUT y OUTPUT siguen mostrando niveles
- El botón cambia a **▶ BYPASS ON** con color rojo como indicador visual
- El indicador GR del limitador se pone a cero

### Uso recomendado para comparación A/B

1. Configura el procesador normalmente (ajusta presets, compresores, etc.)
2. Sube el **OUT GAIN** hasta nivelar el volumen percibido entre bypass y procesado
3. Alterna **STAND BY** para comparar instantáneamente

> **Nota importante**: la señal en bypass puede tener picos más altos (no hay limitador). Baja el OUT GAIN antes de activar STAND BY si hay riesgo de sobremodulación en la transmisión.

---

## 11. Cadena de procesamiento DSP

```
Entrada estéreo (ALSA/PipeWire)
        │
        ▼
   [IN GAIN] ── ganancia de entrada
        │
        ▼
  ┌─ CROSSOVER ─────────────────────────────────────────┐
  │  Filtros Linkwitz-Riley 4° orden por cada punto    │
  │  de corte. Suma de todas las bandas = señal plana  │
  └──────┬──────┬──────┬──────┬──────┬─────────────────┘
         ▼      ▼      ▼      ▼      ▼      ▼
       [B1]   [B2]   [B3]   [B4]   [B5]   [B6]
         │      │      │      │      │      │
    [COMP] x 6  │  Compresor linked-stereo RMS feed-forward
    [CLIP] x 6  │  Clipper suave (tanh)
         │      │      │      │      │      │
         └──────┴──────┴──────┴──────┴──────┘
                        │
                        ▼
                  [SUMA de bandas]
                        │
                        ▼
             [LIMITADOR final brick-wall]
                        │
                        ▼
            [MPX ENCODER] ── si está activo
            (pre-énfasis + piloto + DSB-SC)
                        │
                        ▼
               [OUT GAIN] ── ganancia de salida
                        │
                        ▼
       Salida estéreo (ALSA/PipeWire)
```

---

## 12. Parámetros de referencia por género

### Radio pop/rock contemporáneo

| Parámetro | Valor |
|-----------|-------|
| Bandas | 5 |
| Crossover | 120 · 400 · 2k · 6k Hz |
| Threshold (todas) | −20 a −18 dBFS |
| Ratio (graves/medios) | 4:1 – 5:1 |
| Attack | 5 – 10 ms |
| Release | 80 – 150 ms |
| Makeup gain | 4 – 6 dB |
| Clip level | −0.5 dBFS |
| Limiter | −0.3 dBFS |

### Radio de noticias / locutores

| Parámetro | Valor |
|-----------|-------|
| Bandas | 4–5 |
| Threshold B3 (400–2k) | −14 dBFS (presencia vocal) |
| Ratio B3 | 6:1 |
| Makeup B3 | 7 dB |
| Threshold B4 (2k–6k) | −16 dBFS (de-essing) |
| Ratio B4 | 8:1 |
| Attack | 2 – 5 ms |
| Limiter | −0.2 dBFS |

### Música electrónica / dance

| Parámetro | Valor |
|-----------|-------|
| Bandas | 6 |
| Crossover | 80 · 320 · 1.2k · 4.8k · 12k Hz |
| Threshold B1 (<80 Hz) | −16 dBFS |
| Ratio B1 | 8:1 |
| Makeup B1 | 12 dB |
| Clip B1 | −0.3 dBFS |
| Output gain | −2 dB (compensar el boost de graves) |

---

## 13. Solución de problemas

### No hay audio en la salida

1. Verifica que los metros **INPUT** se muevan — si no hay señal de entrada, revisa la tarjeta y la fuente.
2. Asegúrate de que el botón **⏸ STAND BY** no esté activo (bypass reduce el volumen si IN GAIN ≠ OUT GAIN).
3. Revisa **OUT GAIN** — puede estar en −12 dB.
4. Los logs en terminal muestran los dispositivos abiertos: `Entrada: hw:0` / `Salida: hw:1`.

### Los metros de banda no se mueven

El motor de audio abre los dispositivos al arrancar. Si hay error, aparece en la terminal. Solución común:
```bash
# Liberar el dispositivo de audio
fuser -k /dev/snd/*
# Reiniciar PipeWire
systemctl --user restart pipewire
```

### La compresión no se escucha

Verifica que el umbral (THR) esté **por debajo** del nivel de la señal. Si la señal promedio es −20 dBFS y el threshold está en −10 dBFS, nunca se comprimirá. Baja el threshold hasta que el metro **GR** muestre reducción.

### Distorsión excesiva

- Reduce el **Makeup Gain** (GAIN) de las bandas con más GR
- Sube el threshold (THR) para comprimir menos
- Verifica el nivel de **CLIP LVL** — si está muy alto puede introducir distorsión audible
- Activa **STAND BY** para verificar si la distorsión viene del procesador o de la fuente

### El modo MPX no funciona a 48 kHz

Normal. A 48 kHz el Nyquist es 24 kHz — la subportadora de 38 kHz queda fuera del rango representable. La sección MPX está activa pero solo genera el canal principal con pre-énfasis. Para MPX estéreo completo, configura la tarjeta a **96 kHz o superior**.

### La aplicación no abre (segunda instancia)

GR Processor es single-instance por diseño. Si ya hay una instancia corriendo, la nueva simplemente la activa. Para forzar un reinicio:
```bash
pkill gr-processor && ./target/release/gr-processor
```

---

## Licencia y créditos

GR Processor es software libre desarrollado con Rust + GTK4.
Librería de audio CPAL · Filtros LR4 según Audio EQ Cookbook (Robert Bristow-Johnson)

---

*GR Processor v0.2.0 · gradio.net*
