# G Radio Client — Manual de usuario

**Versión 0.1.2**

---

## Índice

1. [Introducción](#1-introducción)
2. [Requisitos del sistema](#2-requisitos-del-sistema)
3. [Instalación](#3-instalación)
4. [Configuración del servidor](#4-configuración-del-servidor)
5. [Conexión al servidor](#5-conexión-al-servidor)
6. [Interfaz principal](#6-interfaz-principal)
7. [Panel Player](#7-panel-player)
8. [Buscador de audio](#8-buscador-de-audio)
9. [Panel Pautaje](#9-panel-pautaje)
10. [Panel Parrilla](#10-panel-parrilla)
11. [Panel Botonera](#11-panel-botonera)
12. [Panel Reportes](#12-panel-reportes)
13. [Conexión por Internet (relay)](#13-conexión-por-internet-relay)
14. [Solución de problemas](#14-solución-de-problemas)

---

## 1. Introducción

**G Radio Client** (`gr-client`) es una aplicación GTK4 que permite controlar remotamente un servidor **G Radio Player** desde cualquier computadora de la red local o desde internet a través del sistema de relay.

Desde el cliente se puede:

- Controlar la reproducción en tiempo real (play, pausa, stop, skip, volumen)
- Gestionar la playlist del servidor
- Editar la parrilla musical (programación horaria)
- Editar el pautaje comercial y de eventos
- Buscar archivos de audio en el servidor y arrastrarlos a la programación
- Operar la botonera de sonidos de acceso rápido
- Consultar reportes de audios emitidos

Toda la operación se realiza sobre los archivos del servidor; el cliente no almacena contenido propio.

---

## 2. Requisitos del sistema

### Equipo cliente

| Componente | Versión mínima |
|---|---|
| GTK4 | 4.6 |
| glib | 2.72 |
| Debian / Ubuntu | 22.04 LTS o posterior |
| Red | LAN o internet con acceso al servidor |

### Equipo servidor

El servidor debe tener instalado y en ejecución **G Radio Player** (`gradio-player`) versión **0.2.9** o posterior, con el servidor TCP activo.

---

## 3. Instalación

### Desde el paquete .deb

```bash
sudo dpkg -i gr-client_0.1.2_amd64.deb
```

O con resolución automática de dependencias:

```bash
sudo apt install ./gr-client_0.1.2_amd64.deb
```

### Ejecutar

```bash
gr-client
```

O bien desde el menú de aplicaciones: buscar **G Radio Client**.

### Desinstalar

```bash
sudo apt remove gr-client
```

---

## 4. Configuración del servidor

Antes de conectar el cliente es necesario configurar correctamente el servidor G Radio Player para que acepte conexiones remotas.

### 4.1 Archivo de configuración del servidor

El servidor lee su configuración desde:

```
~/.gradio/data/tmp/gradio.config
```

El archivo tiene una línea por campo, en este orden:

```
Nombre de la radio
Dispositivo de audio (ej: default)
G Radio
Duración del crossfade en segundos (ej: 3.0)
Puerto del servidor gr-client (ej: 7777)
Token de autenticación (vacío = sin contraseña)
Relay habilitado (0 = no, 1 = sí)
ID del relay (8 dígitos, ej: 12345678)
```

**Ejemplo de archivo `gradio.config`:**

```
Radio Ejemplo FM
default
G Radio
3.0
7777
mi-token-seguro
0
00000000
```

> La primera vez que se ejecuta `gradio.sh`, el archivo se crea automáticamente con valores por defecto. Se puede editar con cualquier editor de texto mientras el servidor está detenido, o desde la ventana de configuración dentro de la aplicación.

### 4.2 Puerto del servidor

Por defecto el servidor escucha en el puerto **7777** TCP. Para cambiarlo, editar la línea 5 del archivo `gradio.config`.

Asegurarse de que el puerto esté abierto en el firewall del equipo servidor:

```bash
# Verificar que el servidor está escuchando
ss -tlnp | grep 7777
```

### 4.3 Token de autenticación

El token es una contraseña compartida entre el servidor y todos los clientes. Puede ser cualquier cadena de texto.

- Si la línea del token está **vacía**, el servidor acepta cualquier conexión sin contraseña.
- Si tiene contenido, el cliente **debe** ingresar el mismo token para conectarse.

**Recomendación:** usar siempre token cuando el servidor sea accesible desde internet.

### 4.4 Habilitación del relay (acceso remoto por internet)

Para acceder al servidor desde fuera de la red local se usa el sistema de relay. Ver la sección [13. Conexión por Internet (relay)](#13-conexión-por-internet-relay).

Para habilitarlo, poner `1` en la línea 7 y un ID de 8 dígitos en la línea 8 del archivo `gradio.config`. El servidor se conectará automáticamente al relay al iniciarse.

### 4.5 Verificar que el servidor está activo

Al ejecutar `gradio.sh` el servidor TCP se inicia automáticamente junto con el reproductor. Para verificarlo:

```bash
# Ver procesos activos
ps aux | grep radio-player

# Ver puerto abierto
ss -tlnp | grep 7777
```

El cliente mostrará la versión del servidor al conectarse correctamente (ej: `● Conectado v0.2.9`).

---

## 5. Conexión al servidor

### 5.1 Panel de conexión

En la parte superior de la ventana principal se encuentra el panel de conexión:

```
┌──────────────────────────────────────────────────────────────────┐
│  Servidor: [192.168.1.100]  Puerto: [7777]  Token: [••••••••]   │
│  [ ] Internet   ID: [________]   [Conectar]   ● Desconectado    │
└──────────────────────────────────────────────────────────────────┘
```

### 5.2 Conexión en red local (LAN)

1. Dejar el checkbox **Internet** desactivado.
2. Ingresar la **IP o hostname** del equipo servidor (ej: `192.168.1.100` o `servidor-radio`).
3. Ingresar el **puerto** (por defecto: `7777`).
4. Ingresar el **token** si el servidor lo tiene configurado. Dejar vacío si no hay contraseña.
5. Hacer clic en **Conectar**.

El indicador de estado cambia a:

| Estado | Indicador |
|---|---|
| Desconectado | ● Desconectado (gris) |
| Conectando | ⟳ Conectando… |
| Conectado | ● Conectado v0.2.9 (verde) |
| Error | ✗ Error: descripción (rojo) |

### 5.3 Verificar la conexión

Al conectarse correctamente:

- El indicador muestra verde con la versión del servidor.
- El panel Player se actualiza con el estado actual de reproducción.
- La playlist del servidor se carga automáticamente.
- Todos los controles se habilitan.

### 5.4 Reconexión automática

Si la conexión se interrumpe, el cliente intenta reconectarse automáticamente con retroceso exponencial (primero cada 5 segundos, luego aumenta hasta 120 segundos).

---

## 6. Interfaz principal

La ventana principal (1400 × 750 px) se divide en dos áreas:

```
┌─────────────────────────────────────────────────────────────────┐
│          Panel de conexión (parte superior)                     │
├──────────────────────┬──────────────────────────────────────────┤
│                      │  ┌──────────────────────────────────┐   │
│                      │  │  ▶ Player                        │   │
│   Buscador           │  ├──────────────────────────────────┤   │
│   (siempre visible)  │  │  📅 Pautaje                     │   │
│                      │  ├──────────────────────────────────┤   │
│   - Campo de búsqueda│  │  🎵 Parrilla                    │   │
│   - Botón buscar     │  ├──────────────────────────────────┤   │
│   - Lista resultados │  │  🎛 Botonera                    │   │
│   - Drag-and-drop    │  ├──────────────────────────────────┤   │
│                      │  │  📊 Reportes                    │   │
│                      │  └──────────────────────────────────┘   │
└──────────────────────┴──────────────────────────────────────────┘
```

El **Buscador** permanece visible en todo momento a la izquierda. Los paneles funcionales se acceden por pestañas en el área derecha.

---

## 7. Panel Player

El panel Player permite controlar la reproducción en tiempo real sobre el servidor.

### 7.1 Información del track actual

```
┌─────────────────────────────────────────────────────┐
│  ♪  Nombre del track actual                         │
│  01:23 ──────────────●──────────────── 03:45        │
│  Volumen: ────────────●──── 85                      │
└─────────────────────────────────────────────────────┘
```

- **Título:** nombre del archivo en reproducción (sin extensión).
- **Barra de progreso:** posición actual / duración total. Solo lectura.
- **Slider de volumen:** ajusta el volumen de música (0–100). El volumen se aplica en el servidor.

### 7.2 Controles de reproducción

| Botón | Función |
|---|---|
| ▶ Play | Inicia la reproducción |
| ⏸ Pausa | Pausa / reanuda |
| ⏹ Stop | Detiene la reproducción |
| ⏭ Stop After | Detiene al terminar el track actual |
| → Skip | Salta al siguiente track de la playlist |

Todos los controles están deshabilitados cuando el cliente está desconectado.

### 7.3 Playlist

Lista las canciones en cola para reproducción en el servidor.

```
┌──┬────┬─────────────────────────────┬──────────┬──────────────┐
│  │ #  │ Título                      │ Duración │ Acciones     │
├──┼────┼─────────────────────────────┼──────────┼──────────────┤
│▶ │ 1  │ Canción actual              │ 03:45    │ ▶  ↑  ↓  ✗  │
│  │ 2  │ Siguiente canción           │ 04:12    │ ▶  ↑  ↓  ✗  │
│  │ 3  │ Otra canción más            │ 02:58    │ ▶  ↑  ↓  ✗  │
└──┴────┴─────────────────────────────┴──────────┴──────────────┘
```

| Botón | Función |
|---|---|
| ▶ | Reproducir este track inmediatamente |
| ↑ | Mover una posición arriba |
| ↓ | Mover una posición abajo |
| ✗ | Eliminar de la playlist |

### 7.4 Agregar tracks a la playlist

**Método principal: drag-and-drop desde el Buscador**

1. Buscar el archivo en el panel Buscador (izquierda).
2. Hacer clic y arrastrar el resultado hacia la lista de la playlist.
3. Soltar en la posición deseada.

La duración se obtiene automáticamente del servidor.

La playlist se actualiza en tiempo real: si otro operador modifica la playlist en el servidor o desde otro cliente, los cambios se reflejan automáticamente.

---

## 8. Buscador de audio

El buscador permite localizar archivos de audio almacenados en el servidor y arrastrarlos a cualquier panel.

### 8.1 Búsqueda

```
┌─────────────────────────────────┐
│ Buscar: [adele           ] 🔍  │
│ En:     [/home/radio/mus  ]     │
│                          ⟳ Índice │
├─────────────────────────────────┤
│ Nombre         │ Duración       │
│ Rolling.mp3    │ 03:43.000      │
│ Someone.mp3    │ 04:52.000      │
│ Hello.mp3      │ 04:55.000      │
└─────────────────────────────────┘
```

- **Buscar:** nombre del archivo (parcial, sin distinguir mayúsculas).
- **En:** ruta opcional para limitar la búsqueda a una carpeta específica. Si se deja vacío, busca en todo el servidor.
- **Botón 🔍 o Enter:** ejecuta la búsqueda.
- **Botón ⟳ Índice:** actualiza la base de datos de búsqueda en el servidor. Necesario si se agregaron archivos nuevos recientemente.

> La búsqueda usa una base de datos local del servidor (`~/.gradio/locatedb`). Si los resultados no incluyen archivos recientes, hacer clic en **⟳ Índice** para actualizar.

### 8.2 Menú contextual (clic derecho)

| Opción | Función |
|---|---|
| ▶ Reproducir ahora | Envía el archivo al servidor para reproducción inmediata |
| + Agregar al playlist | Lo añade al final de la playlist |
| 📋 Copiar ruta | Copia la ruta completa al portapapeles |

### 8.3 Drag-and-drop

Los archivos del buscador pueden arrastrarse hacia:

| Destino | Efecto |
|---|---|
| Playlist (panel Player) | Agrega el track a la playlist en la posición soltada |
| Panel Pautaje | Crea una nueva entrada comercial con ese archivo |
| Panel Parrilla | Agrega el archivo como item en la hora seleccionada |

---

## 9. Panel Pautaje

Permite editar la programación de comerciales, eventos y eventos en espera del servidor.

### 9.1 Tipos de pautaje

El panel tiene tres pestañas:

| Pestaña | Carpeta en servidor | Uso |
|---|---|---|
| Comerciales | `~/.gradio/data/comerciales/` | Publicidad programada |
| Eventos | `~/.gradio/data/eventos/` | Eventos instantáneos |
| Eventos-Espera | `~/.gradio/data/eventos-espera/` | Eventos en cola |

### 9.2 Selección de hora y minuto

```
Hora: [10 ▾]   Minuto: [30 ▾]   [⟳ Cargar]
```

- **Hora:** 00 a 23.
- **Minuto:** 00, 05, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55.
- Hacer clic en **⟳ Cargar** para ver las entradas de esa franja horaria.

### 9.3 Tabla de entradas

```
┌──────────────────────────────┬──────────┬──────────┬──────────┐
│ Archivo                      │ Días     │ Inicio   │ Fin      │
├──────────────────────────────┼──────────┼──────────┼──────────┤
│ /radio/comerciales/spot1.mp3 │ 12345    │ 20250101 │ 20251231 │
│ /radio/comerciales/spot2.mp3 │ 1234567  │ 20250601 │ 20250630 │
└──────────────────────────────┴──────────┴──────────┴──────────┘
```

**Columna Días:** máscara numérica donde cada dígito representa un día de la semana:

```
1 = Lunes   2 = Martes  3 = Miércoles  4 = Jueves
5 = Viernes  6 = Sábado  7 = Domingo
```

Ejemplo: `135` = solo Lunes, Miércoles y Viernes.

**Columna Inicio / Fin:** fechas en formato `YYYYMMDD`. Fuera de ese rango el audio no se emite.

### 9.4 Barra de herramientas

| Botón | Función |
|---|---|
| + Nueva | Abre el diálogo para agregar una entrada |
| ✏ Editar | Edita la entrada seleccionada |
| ✗ Eliminar | Borra la entrada seleccionada |
| ↑ / ↓ | Cambia el orden de reproducción |
| 💾 Guardar | Envía los cambios al servidor |

> Los cambios **no se aplican hasta presionar 💾 Guardar**.

### 9.5 Diálogo de nueva entrada / edición

```
Ruta:  [/radio/comerciales/spot1.mp3              ]

Días activos:
[✓] Lun  [✓] Mar  [✓] Mié  [✓] Jue  [✓] Vie  [ ] Sáb  [ ] Dom

Inicio: [20250101]        Fin: [20251231]

                              [Cancelar]  [Aceptar]
```

- **Ruta:** ruta completa del archivo en el servidor. Se puede pegar desde el buscador.
- **Días activos:** marcar los días en que debe emitirse.
- **Inicio / Fin:** período de vigencia en formato `YYYYMMDD`.

### 9.6 Drag-and-drop desde el buscador

Arrastrar un archivo desde el Buscador hacia la tabla de pautaje crea automáticamente una nueva entrada con:

- Ruta = archivo arrastrado
- Días = todos (1234567)
- Inicio y Fin = fecha actual

Editar la entrada para ajustar días y fechas según corresponda.

---

## 10. Panel Parrilla

Permite editar la programación musical horaria del servidor.

### 10.1 Selección de día y hora

```
Día:  [Lunes ▾]    Hora: [10 ▾]    [⟳ Cargar]
```

Seleccionar el día de la semana y la hora (00–23), luego hacer clic en **⟳ Cargar**.

### 10.2 Lista de items

```
┌────┬──────────────────────────────────────────────┐
│ #  │ Item                                         │
├────┼──────────────────────────────────────────────┤
│ 1  │ Hora                                         │
│ 2  │ /radio/musica/pop/*                          │
│ 3  │ /radio/musica/pop/cancion-especial.mp3       │
│ 4  │ /radio/musica/rock/*                         │
└────┴──────────────────────────────────────────────┘
```

Tipos de item:

| Item | Comportamiento |
|---|---|
| `/ruta/archivo.mp3` | Reproduce ese archivo exacto |
| `/ruta/carpeta/*` | Elige un archivo al azar de esa carpeta |
| `Hora` | Reproduce el jingle de hora correspondiente |
| `http://stream.url` | Conecta al stream de internet |

### 10.3 Barra de herramientas

| Botón | Función |
|---|---|
| + Archivo | Agrega una ruta de archivo específico |
| + Carpeta/* | Agrega una carpeta para selección aleatoria |
| + Hora | Inserta el marcador de jingle de hora |
| + URL | Agrega una URL de streaming |
| ✗ Eliminar | Elimina el item seleccionado |
| ↑ / ↓ | Cambia el orden |
| 💾 Guardar | Envía los cambios al servidor |

> Los cambios **no se aplican hasta presionar 💾 Guardar**.

### 10.4 Drag-and-drop desde el buscador

Arrastrar un archivo desde el Buscador hacia la lista de parrilla lo agrega como item de archivo específico en la posición donde se suelta.

---

## 11. Panel Botonera

La botonera es una grilla de botones de acceso rápido para reproducir audios con un solo clic.

### 11.1 Vista de la botonera

```
┌────────────┬────────────┬────────────┬────────────┐
│  Intro     │  Cierre    │  Cortina   │  Jingle 1  │
│  (rojo)    │  (azul)    │  (verde)   │  (naranja) │
├────────────┼────────────┼────────────┼────────────┤
│  ...       │  ...       │  ...       │  ...       │
└────────────┴────────────┴────────────┴────────────┘
```

- Hasta 100 botones organizados en filas de 8.
- Cada botón tiene etiqueta, color y una ruta de audio asignada.

### 11.2 Usar un botón

**Clic izquierdo** sobre cualquier botón → el servidor reproduce ese audio inmediatamente (interrumpe la música con duck de volumen si está configurado).

### 11.3 Editar un botón

**Clic derecho** sobre un botón → abre el diálogo de edición:

```
Etiqueta:  [Intro programa     ]
Ruta:      [/radio/jingles/intro.mp3]
Color:     [█ #FF5500         ]  (selector de color)

                     [Cancelar]  [Aceptar]
```

### 11.4 Guardar cambios

Los cambios en la botonera se envían al servidor con el botón **💾 Guardar** de la barra de herramientas. Para recargar desde el servidor usar **⟳ Cargar**.

---

## 12. Panel Reportes

Muestra reportes de actividad generados por el servidor.

### 12.1 Uso

```
Reporte: [Audios emitidos ▾]    Fecha: [20260419]    [⟳ Cargar]
```

1. Seleccionar el tipo de reporte.
2. Ingresar la fecha en formato `YYYYMMDD` (por defecto: hoy).
3. Hacer clic en **⟳ Cargar**.

### 12.2 Tipos de reporte disponibles

| Tipo | Contenido |
|---|---|
| Audios emitidos | Lista de todos los audios reproducidos en la fecha indicada |
| Playlist actual | Estado actual de la cola de música |
| Comerciales activos | Pautaje vigente para el día y hora actual |
| Eventos activos | Eventos programados vigentes |

El resultado se muestra en una vista de texto de solo lectura, útil para auditoría y verificación de programación.

---

## 13. Conexión por Internet (relay)

El sistema de relay permite acceder al servidor desde fuera de la red local sin necesidad de configurar puertos en el router.

### 13.1 Cómo funciona

```
gr-client  ──WSS──→  relay.gradio.net  ──TCP──→  servidor G Radio Player
           Internet                    LAN local
```

El servidor G Radio Player mantiene una conexión persistente con el relay usando un **ID de 8 dígitos**. El cliente se conecta al relay con ese mismo ID y el tráfico se reenvía transparentemente.

### 13.2 Configuración en el servidor

Editar `~/.gradio/data/tmp/gradio.config` en el equipo servidor:

```
...
1          ← línea 7: relay habilitado (1 = sí)
12345678   ← línea 8: ID de 8 dígitos (elegir uno único)
```

Reiniciar el servidor para que tome efecto. Al iniciar, el servidor mostrará en consola:

```
==> Relay registrado con ID: 12345678
```

**Importante:** el token de autenticación es obligatorio cuando se usa relay.

### 13.3 Conexión desde el cliente

1. Activar el checkbox **Internet** en el panel de conexión.
2. Ingresar el **ID** de 8 dígitos del servidor.
3. Ingresar el **Token** (obligatorio).
4. Hacer clic en **Conectar**.

```
┌───────────────────────────────────────────────────────────────┐
│  [✓] Internet   ID: [12345678]   Token: [mi-token-seguro]    │
│                                                   [Conectar]  │
└───────────────────────────────────────────────────────────────┘
```

> En modo relay el campo Servidor y Puerto se ignoran.

### 13.4 Seguridad

- Usar siempre un token robusto en conexiones por internet.
- El tráfico entre cliente y relay viaja cifrado (WSS/TLS).
- El ID del relay no es secreto, pero sin el token correcto no se puede controlar el servidor.

---

## 14. Solución de problemas

### No se puede conectar (LAN)

1. Verificar que el servidor esté ejecutándose:
   ```bash
   ps aux | grep radio-player
   ```
2. Verificar que el puerto esté abierto:
   ```bash
   ss -tlnp | grep 7777
   ```
3. Verificar que el token ingresado en el cliente coincide con el del servidor.
4. Verificar que no hay firewall bloqueando el puerto:
   ```bash
   # En el servidor
   sudo ufw allow 7777/tcp
   ```

### No se puede conectar (relay)

1. Verificar que el relay esté habilitado en `gradio.config` (línea 7 = `1`).
2. Verificar que el servidor haya impreso `==> Relay registrado con ID: XXXXXXXX` al iniciar.
3. Verificar que el ID ingresado en el cliente coincide exactamente con el del servidor.
4. Verificar que el token no está vacío (obligatorio en modo relay).
5. Verificar conectividad a internet desde el servidor.

### El buscador no encuentra archivos recientes

Hacer clic en **⟳ Índice** en el panel Buscador para actualizar la base de datos del servidor. El proceso puede tardar unos minutos dependiendo de la cantidad de archivos.

### Los cambios en parrilla o pautaje no surten efecto

Verificar que se presionó **💾 Guardar** después de editar. Los cambios no se envían al servidor hasta confirmarlos.

### La playlist no se actualiza automáticamente

La actualización automática requiere conexión activa. Verificar el indicador de estado en el panel de conexión. Si está en rojo, el cliente perdió la conexión y está intentando reconectarse.

### El servidor muestra "cliente conectado" pero los controles están deshabilitados

Cerrar y reabrir la aplicación cliente. Si persiste, verificar que la versión del servidor es compatible (0.2.9 o posterior).

---

*G Radio Player / G Radio Client — Sistema de automatización de radio profesional*