Documentación de Reproductor de musica

Otra Vida Musica (ov_musica)

Que hace

ov_musica es un reproductor de musica para jugadores en servidores FiveM con qb-core. Los jugadores buscan canciones, arman una cola y escuchan la musica en el vehiculo, con sonido 3D que viaja con el coche, o "solo para mi" a pie.

Lo mas importante:

Busqueda de canciones desde la interfaz, con limite de resultados y tiempo de espera entre busquedas.
Cola por fuente de sonido: cada vehiculo tiene su cola, y cada jugador tiene la suya para escuchar en privado ("personal").
Sonido 3D que sigue al vehiculo: lo oyen los jugadores cercanos. El volumen baja con la distancia y el sonido se amortigua cuando el vehiculo esta cerrado y quien escucha esta fuera. Motos, descapotables con techo abierto, puertas abiertas y ventanas rotas no aislan el sonido.
Ecualizador de 7 bandas (60, 150, 400, 1000, 3000, 8000 y 16000 Hz), presets (Plano, SuperBass, Reggaeton, Trap, Club, Rock, Voces) y modo Super Bass.
Control del reproductor: pausa, reanudar, siguiente, reiniciar, volumen, repetir, quitar de la cola, vaciar y parar.
Listas de reproduccion por personaje, guardadas en base de datos.
Control por conductor: por defecto solo el conductor controla la musica del vehiculo; cualquier ocupante puede buscar y agregar canciones.

Importante: el recurso necesita un servicio externo de busqueda y descarga y un CDN donde quedan los archivos de audio (ver Requisitos). El servidor del recurso solo decide que suena y desde que segundo; cada cliente reproduce el audio con su propio motor.

Requisitos

Requisito	Detalle
Framework	`qb-core`
Dependencias declaradas en el fxmanifest	`ox_lib`, `oxmysql`, `qb-core`
Lua	5.4 (`lua54 'yes'`)
Base de datos	MySQL o MariaDB, mediante `oxmysql`
Servicio de busqueda y descarga	Servicio HTTP propio que el servidor FiveM pueda alcanzar. El recurso le hace peticiones `POST` a las rutas `/buscar` (con `q` y `n`) y `/preparar` (con `id`) enviando la cabecera `X-Clave`
CDN o servidor web de archivos	Direccion publica desde la que los jugadores descargan los audios. Debe permitir reproduccion desde la interfaz (el motor de audio carga los archivos con `crossOrigin = 'anonymous'`, asi que el servidor de archivos debe enviar las cabeceras CORS)

El codigo del servidor no usa otros recursos mas alla de qb-core y ox_lib.

No verificado: el servicio de busqueda y descarga no forma parte de los archivos de este recurso. Su implementacion (programa que busca, descarga, convierte y publica el audio en el CDN) debe proporcionarse por separado. Consulta con el soporte de la tienda como obtenerlo o que contrato debe cumplir.

Instalacion

Descarga el recurso desde el Portal de Cfx.re (seccion de assets comprados) con la cuenta Cfx.re con la que hiciste la compra. El recurso viene protegido con Asset Escrow de Cfx.re: solo funciona en servidores cuya clave de licencia pertenece a tu cuenta.
Copia la carpeta ov_musica dentro de resources de tu servidor.
Prepara el servicio de busqueda y descarga y el CDN (ver Requisitos).
Agrega las convars en server.cfg, antes de ensure ov_musica:

   set ov_musica_clave "una-clave-larga-y-secreta"
   set ov_musica_api "http://127.0.0.1:3410"
   setr ov_musica_cdn "https://tu-cdn.ejemplo"

ov_musica_clave: secreto compartido con el servicio; solo lo lee el servidor. Si esta vacia, la consola avisa y no se podra buscar ni descargar.
ov_musica_api: direccion del servicio. Por defecto http://127.0.0.1:3410.
ov_musica_cdn: direccion publica de los audios. Usa setr (replicada) porque la leen los clientes. Reemplaza el valor por defecto de shared/config.lua por tu propio CDN.
Agrega en server.cfg, despues de ox_lib, oxmysql y qb-core:

   ensure ov_musica

Inicia el servidor. No hay archivo .sql: al arrancar se crea sola la tabla ov_musica_listas (CREATE TABLE IF NOT EXISTS).

Archivos editables: en el fxmanifest.lua el bloque escrow_ignore deja sin cifrar shared/config.lua y toda la carpeta html/ (interfaz web y motor de audio). El resto del codigo (client/ y server/) va cifrado por Asset Escrow.

Configuracion

Todo esta en shared/config.lua. Opciones principales:

Clave	Valor por defecto	Para que sirve
`Config.ApiUrl`	convar `ov_musica_api`, o `http://127.0.0.1:3410`	Direccion del servicio de busqueda y descarga
`Config.ApiClave`	convar `ov_musica_clave`, o vacio	Clave secreta del servicio
`Config.Cdn`	convar `ov_musica_cdn`, o la direccion de ejemplo incluida	Direccion publica de los audios
`Config.ApiTiempoMs`	`300000`	Constante de tiempo para descargas nuevas
`Config.MaxCola`	`30`	Canciones en la cola de una fuente
`Config.MaxListas`	`15`	Listas por jugador
`Config.MaxPistasLista`	`100`	Canciones por lista
`Config.CooldownBusquedaMs`	`1500`	Espera entre busquedas por jugador
`Config.CooldownAgregarMs`	`2500`	Espera entre canciones agregadas
`Config.MaxResultados`	`10`	Resultados por busqueda
`Config.VolumenInicial`	`0.6`	Volumen al empezar
`Config.Distancia`	`60.0`	Metros a los que se oye un vehiculo
`Config.DistanciaSincronia`	`120.0`	Mas alla de esta distancia el cliente deja de reproducirlo
`Config.IntervaloPosMs`	`50`	Cada cuanto se envia la posicion al motor de audio
`Config.ApagarVacioSeg`	`300`	Un vehiculo sin nadie dentro deja de sonar tras este tiempo
`Config.AtenuacionCerrado`	`900`	Frecuencia (Hz) del filtro con el vehiculo cerrado y el oyente fuera
`Config.Control`	`'conductor'`	`'conductor'`: solo el conductor controla; `'todos'`: cualquier ocupante
`Config.Tecla`	`'U'`	Tecla por defecto para abrir el reproductor
`Config.Comando`	`'musica'`	Comando del reproductor
`Config.Bandas`	`{ 60, 150, 400, 1000, 3000, 8000, 16000 }`	Frecuencias del ecualizador
`Config.EqMax`	`12`	Ganancia maxima del ecualizador en dB
`Config.Presets`	7 presets	Valores de cada preset (una ganancia por banda)
`Config.PresetInicial`	`'Plano'`	Preset con el que empieza una fuente nueva

Puedes agregar presets propios anadiendo una entrada a Config.Presets con una ganancia por cada banda.

Comandos y permisos

Elemento	Detalle
`/musica`	Abre o cierra el reproductor (el nombre sale de `Config.Comando`)
Tecla `U`	Atajo registrado con `RegisterKeyMapping`. Cada jugador puede cambiarla en Ajustes, Teclas, FiveM
Permisos ACE	El recurso no define permisos ACE

Exports del cliente

Export	Uso
`Abrir(ctx)`	Abre el reproductor desde otro script. `ctx` puede ser `'vehiculo'` o `'personal'`; si se omite, el recurso elige segun si el jugador va en un vehiculo

exports.ov_musica:Abrir('personal')

Eventos (uso interno): ov_musica:estado, ov_musica:todos y ov_musica:pedirTodo. No estan pensados para llamarlos desde otros recursos.

Como se usa

Pulsa U (o escribe /musica) para abrir el reproductor.
Elige el modo: vehiculo (solo si vas dentro de uno) o solo para mi.
Busca una cancion por nombre (minimo 2 letras) y agregala a la cola. La primera empieza a sonar al terminar de prepararse.
Con el control del reproductor puedes pausar, reanudar, pasar a la siguiente, reiniciar, subir o bajar el volumen, activar repetir, quitar canciones de la cola o vaciarla.
Abre el ecualizador para elegir un preset, mover las 7 bandas o activar Super Bass.
Crea listas con tus canciones favoritas y reproducelas despues con un clic.
En vehiculo, los jugadores cercanos escuchan la musica. Si el vehiculo esta cerrado, desde afuera se oye amortiguada.

Notas: si una cancion supera la duracion permitida por el servicio, el reproductor avisa que es demasiado larga. Con Config.Control = 'conductor', los pasajeros pueden agregar canciones, pero solo el conductor puede pausar o cambiar el volumen y el ecualizador.

Para administradores

Pon en marcha el servicio de busqueda y el CDN antes de iniciar el recurso, y define las tres convars.
Revisa la consola al arrancar: si falta ov_musica_clave veras un aviso en amarillo.
Ajusta los limites en shared/config.lua (cola, listas, tiempos de espera) segun la carga de tu servidor.
Para que cualquier ocupante controle la musica de un vehiculo, cambia Config.Control a 'todos'.
Los audios los guarda el servicio en el CDN. La limpieza de archivos antiguos depende de ese servicio, no del recurso.
Las listas de los jugadores estan en la tabla ov_musica_listas, asociadas al citizenid.

Preguntas frecuentes

No encuentra canciones o dice que el servicio no responde. Revisa que el servicio este activo, que ov_musica_api apunte a su direccion, que ov_musica_clave coincida con la del servicio y que el servidor FiveM pueda conectarse a esa direccion.

La cancion se agrega pero no suena. Comprueba ov_musica_cdn: debe ser publica, accesible desde los clientes y con cabeceras CORS. Los clientes descargan el audio desde esa direccion.

Puedo limitar la musica a ciertos jugadores? El recurso no incluye permisos por jugador. Puedes restringir el acceso desde otros scripts, por ejemplo llamando al export Abrir solo cuando tu logica lo permita, aunque el comando /musica seguira disponible.

Cambio el limite de la cola o las listas? Si, en Config.MaxCola, Config.MaxListas y Config.MaxPistasLista dentro de shared/config.lua.

Funciona sin vehiculo? Si, con el modo "solo para mi", que solo lo oye quien lo activa.

Donde veo los errores? En la consola del servidor (mensajes [ov_musica]) y en la consola F8 del cliente.

Actualizaciones y soporte

Las versiones nuevas aparecen en el Portal de Cfx.re (en tus recursos comprados) y en la tienda. Descargalas con la misma cuenta Cfx.re de la compra y reemplaza la carpeta, conservando tus cambios en shared/config.lua. Para soporte, abre un ticket en el Discord de la tienda: [enlace de soporte]. Indica la version del recurso, el error de consola y los pasos para reproducirlo.