cescobar/G-Radio-Remoto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Commit inicial: G Radio Remoto (gr-client)

Browse Source 
Cliente remoto GTK4 para G Radio Player: se conecta al servidor TCP
embebido en radio-player para controlar el reproductor y editar
programación (pautaje, parrilla, botonera, buscador, reportes) desde
otra máquina de la LAN.
This commit is contained in:
cescobar
2026-08-23 01:15:15 -05:00
commit 2219b3abc0
28 changed files with 7332 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MANUAL.md
+663
View File
@@ -0,0 +1,663 @@
# 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*