cescobar/G-Radio-Remoto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
62f341ea5385e136885676c2225a510f9a8834d1
G-Radio-Remoto/MANUAL.md
T
cescobar 2219b3abc0 Commit inicial: G Radio Remoto (gr-client) 
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.
2026-08-23 01:15:15 -05:00

664 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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*
Reference in New Issue View Git Blame Copy Permalink