senzapaura_es/docs/jukebox-programacion-horaria.md

# Juke-box: reproducción y configuración

Actualizado el 14 de septiembre de 2026.

## Pantallas

- **/juke-box:** hero de 100vh, con el botón dorado «Play JukeBox» y «Configura tu Jukebox» debajo del título. El pie del sitio aparece inmediatamente después del hero. No se muestra la colección ni el editor debajo.
- **/juke-box/configurar:** colección «Mis jukebox», creación, edición y consulta de las programaciones. «Abrir reproductor» vuelve al hero con el jukebox elegido.
- **/juke-box/nuevo** y **/juke-box/[id]/editar:** comparten el editor. Guardar y cancelar vuelven a configuración; guardar no inicia la reproducción.

«Play JukeBox» despliega todos los jukebox con su nombre y descripción. Elegir uno inicia su reproducción. Su nombre, estado y botón Detener se muestran en la misma fila de acciones en escritorio. Si todavía no hay ninguno, el hero indica que se debe crear desde configuración. El acceso anónimo utiliza el popup de cuenta.

La frase «Tu música, a su hora.» queda debajo de Juke-box; su tamaño tipográfico se adapta al ancho del título conservando el espaciado natural entre palabras.

## Uso del editor

Escribir el nombre y la descripción del jukebox en la cabecera del editor.

1. Crear una franja. Se identifica automáticamente como Franja 1, Franja 2, etc.; no hay campo de nombre ni selector de zona horaria.
2. Elegir «Todo el día» o un horario de inicio y fin. Se rechazan solapamientos dentro del mismo jukebox.
3. Elegir «Todo el catálogo» o «Listas y canciones». La selección preparada se conserva al alternar entre ambas opciones.
4. Elegir reproducción secuencial o aleatoria para esa franja. Las canciones y listas seleccionadas se pueden ordenar y retirar.
5. «Guardar franja» persiste la franja seleccionada, el nombre y la descripción y mantiene abierto el editor. No guarda los cambios pendientes de otras franjas. «Guardar jukebox» persiste todos los cambios y vuelve a configuración. Cada registro conserva su revisión independiente.

Cancelar un jukebox nuevo no crea un registro vacío. El historial del navegador conserva el borrador. Se pueden deshacer cambios y recuperar una franja eliminada. La eliminación de un jukebox requiere confirmación dentro del editor.

## Reproducción

Solo un jukebox controla el reproductor de la pestaña a la vez. Editar o guardar otro no lo detiene. Una nueva pulsación de Play aplica la revisión guardada seleccionada.

Las franjas se repiten diariamente. Pueden cruzar medianoche; el inicio está incluido y el final excluido. El contenido se repite hasta terminar la franja, cambia al comenzar la siguiente y queda en espera durante los huecos. Estas reglas se explican en el editor.

En secuencial se respeta el orden visible y el orden interno de las listas. En aleatoria se barajan todas las canciones de la franja, incluida la primera; al comenzar una nueva vuelta se evita repetir inmediatamente la última canción.

La programación y el audio permanecen activos al navegar. Su icono, nombre, estado y acciones se agrupan en la barra del reproductor, además del estado del hero. Si no hay franja activa, queda visible una barra compacta de espera.

Elegir una canción suspende temporalmente el jukebox: conserva pista, segundo, posición y orden de la cola. Al terminar la canción o pulsar su pausa en la web vuelve automáticamente; «Continuar» permite volver inmediatamente. Al reproducir un álbum o lista completos, el retorno automático espera al final de esa selección, salvo que se pulse pausa o «Continuar». Varias selecciones consecutivas conservan el punto de retorno original. La pausa del propio jukebox se mantiene hasta pulsar play; las pausas técnicas, como abrir un vídeo o pausar desde el sistema, no arrancan otro audio.

La vuelta recupera el punto guardado si sigue vigente la misma franja; si ha cambiado, empieza la actual. Sin franja queda en espera. Una franja del día siguiente no recupera un punto antiguo, y las franjas nocturnas se identifican en su zona horaria. Pausar el jukebox impide que el reloj vuelva a arrancarlo: Play valida la franja vigente al reanudar. Si estaba pausado antes de elegir una canción manual, su final o pausa lo devuelve todavía pausado; «Continuar» lo reanuda expresamente. «Detener» cancela el retorno sin cortar la canción manual. Cerrar sesión o perder el acceso detiene la programación y el audio.

«Detener» conserva el jukebox seleccionado y sus controles, con estado «Detenido» y botón «Reproducir». Desarma el reloj y vacía la escucha del jukebox, sin borrar su nombre, descripción ni franjas guardadas. Si suena una selección manual, la deja continuar y cancela el retorno automático. «Reproducir» inicia una nueva sesión según la franja vigente; «Eliminar Jukebox» sigue siendo una acción distinta dentro de configuración.

Configuración, creación y edición comparten una navegación compacta con «Volver al Juke-box». Las migas no acumulan su separación con otro relleno superior de la página.

La web debe permanecer abierta y el dispositivo activo. Recargar requiere pulsar Play de nuevo. La zona horaria se obtiene del dispositivo al crear y queda guardada. Las listas y el catálogo se resuelven al iniciar la sesión de reproducción.

## Persistencia y permisos

La migración 0037_jukeboxes_independientes.sql crea la tabla jukebox y migra las programaciones anteriores no vacías a un primer jukebox por cuenta, conservando horarios y contenidos. No elimina la tabla anterior.

Cada registro tiene ID, propietario, número, nombre, descripción, programación y revisión. Las migraciones 0038 y 0039 añaden nombre y descripción a los registros existentes. El servidor comprueba sesión, prestación Juke-box, pertenencia de listas, canciones válidas, origen de las peticiones y revisión. Una revisión antigua no sobrescribe un guardado posterior. El endpoint anterior devuelve 410 para impedir escrituras desde el editor antiguo.

## Verificación

La suite de navegador usa cuentas suscritas temporales que elimina al terminar. Comprueba creación de dos jukebox, guardados independientes, edición durante reproducción, cancelación, historial, aislamiento de cuentas, selección desde el hero, horario con audio real, solapamientos y eliminación. También verifica Continuar, el retorno tras un final real del audio, el cambio de franja durante la interrupción y el regreso desde configuración y edición.

La revisión visual comprueba el hero a 100vh, el pie inmediatamente después, ausencia de gestión bajo el hero, botones originales y adaptación móvil. Las pruebas de dominio y reproductor cubren horarios, medianoche, modos y cambios de franja.

Para repetir en desarrollo, con el servidor en http://127.0.0.1:4180 y el acceso de pruebas habilitado:

- npx vitest run src/lib/programacion-jukebox.spec.ts src/lib/player/player.svelte.spec.ts
- npx playwright test --config playwright.jukebox.config.ts
- npm run check:sitio

La suite utiliza la conexión de desarrollo configurada en .env; no introduce ejemplos en la cuenta del usuario.

Los botones principales de los formularios utilizan navy en el tema claro y celeste en el oscuro, mediante tokens globales. El Play del hero conserva el dorado.

Los controles exclusivos de horario, modo, origen y tipo de contenido utilizan GrupoToggle: una barra común con el segmento activo verde en ambos temas. Sus tokens y estilos residen en app.css. El contenido del hero reserva un margen inferior de 12vh, acotado con el espaciado global, más la altura del reproductor cuando está visible.

La barra utiliza los tokens del sitio: títulos de canción y jukebox de 16 px e información secundaria de 14 px. «Continuar» conserva el dorado del reproductor, con letra de 13 px, peso normal y altura compacta de 36 px. El icono para detener permanece junto a esta acción y al nombre del jukebox. Se elimina la etiqueta fija «Calidad de escucha», que no describía el audio real. En móvil, la canción y los controles de transporte comparten fila; el progreso y el módulo del jukebox ocupan las siguientes.

El editor reúne título, estado de guardado y acciones en su cabecera. El nombre y la descripción preceden a un panel común de franjas y edición, con horario, reproducción y contenido agrupados. La colección muestra la programación junto al jukebox seleccionado en escritorio y debajo en móvil.

Las tablas de canciones integran el control de reproducción sobre la portada, sin una columna independiente. Aparece al pasar el ratón por la fila, recibir foco de teclado o reproducir la canción; en pantallas táctiles permanece visible. Las pruebas comprueban reproducción, pausa, teclado, tamaño estable de la portada y ausencia de desbordamiento, además de generar capturas de la barra, la colección y el editor en claro, oscuro y móvil.