cescobar
2219b3abc0
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.
25 KiB
G Radio Client — Manual de usuario
Versión 0.1.2
Índice
- Introducción
- Requisitos del sistema
- Instalación
- Configuración del servidor
- Conexión al servidor
- Interfaz principal
- Panel Player
- Buscador de audio
- Panel Pautaje
- Panel Parrilla
- Panel Botonera
- Panel Reportes
- Conexión por Internet (relay)
- 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
sudo dpkg -i gr-client_0.1.2_amd64.deb
O con resolución automática de dependencias:
sudo apt install ./gr-client_0.1.2_amd64.deb
Ejecutar
gr-client
O bien desde el menú de aplicaciones: buscar G Radio Client.
Desinstalar
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:
# 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).
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:
# 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)
- Dejar el checkbox Internet desactivado.
- Ingresar la IP o hostname del equipo servidor (ej:
192.168.1.100oservidor-radio). - Ingresar el puerto (por defecto:
7777). - Ingresar el token si el servidor lo tiene configurado. Dejar vacío si no hay contraseña.
- 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
- Buscar el archivo en el panel Buscador (izquierda).
- Hacer clic y arrastrar el resultado hacia la lista de la playlist.
- 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]
- Seleccionar el tipo de reporte.
- Ingresar la fecha en formato
YYYYMMDD(por defecto: hoy). - 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
- Activar el checkbox Internet en el panel de conexión.
- Ingresar el ID de 8 dígitos del servidor.
- Ingresar el Token (obligatorio).
- 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)
- Verificar que el servidor esté ejecutándose:
ps aux | grep radio-player - Verificar que el puerto esté abierto:
ss -tlnp | grep 7777 - Verificar que el token ingresado en el cliente coincide con el del servidor.
- Verificar que no hay firewall bloqueando el puerto:
# En el servidor sudo ufw allow 7777/tcp
No se puede conectar (relay)
- Verificar que el relay esté habilitado en
gradio.config(línea 7 =1). - Verificar que el servidor haya impreso
==> Relay registrado con ID: XXXXXXXXal iniciar. - Verificar que el ID ingresado en el cliente coincide exactamente con el del servidor.
- Verificar que el token no está vacío (obligatorio en modo relay).
- 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