# Synced TVs: documentación

> YouTube y una biblioteca de películas gratuita en cualquier televisor o pantalla, sincronizados para todos los que estén cerca.

- URL: https://xexstudio.com/es/docs/synced-tvs
- Versión: 1.0.2
- Ficha del producto: https://xexstudio.com/es/scripts/synced-tvs
Televisores sincronizados para FiveM. Acércate a cualquier televisor, abre el mando y pon un canal, una película,
un enlace de YouTube o de Vimeo. Todos los que estén cerca ven y oyen el mismo segundo,
incluidos los jugadores que llegan tarde.

Standalone sobre ox_lib. ESX, QBCore y Qbox solo se usan para bloquear pantallas por trabajo.

Creado por [XeX](https://xexstudio.com). Las capturas y el resto de mis scripts están en
[xexstudio.com](https://xexstudio.com/scripts/synced-tvs).

## Características

- Canales 24/7 definidos en la config, con guía de canales por categoría y canal arriba / abajo. Vienen tres
  configurados (cine clásico, clásicos de terror y dibujos animados de los años 40), todos películas de dominio
  público del Internet Archive.
- Los canales se mantienen en antena por sí solos: cada fuente puede tener respaldos, las fuentes en directo se
  comprueban cada pocos minutos y un canal basado en un canal de YouTube sigue siempre su emisión en directo actual.
- Biblioteca de películas en el mando: miles de películas de dominio público del Internet Archive, con selecciones
  destacadas, búsqueda y géneros.
- YouTube (vídeos, shorts, directos y la emisión en directo actual de un canal), Vimeo y archivos de vídeo o streams
  de los hosts que permitas. Los enlaces se comprueban en el servidor antes de reproducirse.
- Cola, bucle, avance y retroceso, y resincronización. La cola sigue avanzando aunque nadie mire.
- Pantallas fijas en props del mapa o en props generados, con reproducción automática y bloqueos por ACE o por trabajo
  y rango.
- El volumen se atenúa con la distancia y a través de las paredes. Cada jugador puede silenciar las pantallas solo
  para sí mismo.
- Solo se renderizan las pantallas más cercanas (3 por defecto). Las pantallas sin nadie cerca no cuestan nada.
- ox_target o qb-target, un comando y una tecla opcional.
- Inglés y español.

## Requisitos

- [ox_lib](https://github.com/overextended/ox_lib)
- Opcional: ox_target o qb-target, y ESX, QBCore o Qbox para los bloqueos por trabajo

## Instalación

1. Pon `xex_tv` en tu carpeta de recursos.
2. Añádelo a `server.cfg` después de ox_lib (y después de tu framework si usas bloqueos por trabajo):
   ```cfg
   ensure xex_tv
   ```
3. El idioma sigue al de ox_lib: `setr ox:locale en` o `es`.

## Configuración

Todo está en `config.lua`, con un comentario en cada opción.

| Sección | |
| --- | --- |
| `Config.UI` | Nombre de marca, título y color de acento del mando |
| `Config.Interaction` | Comando, target, tecla, texto de ayuda y distancias |
| `Config.Permissions` | ACE opcional para usar las pantallas, y el ACE de administración |
| `Config.Sources` | YouTube y Vimeo activados o desactivados |
| `Config.AllowedMediaHosts` | Hosts desde los que los jugadores pueden pegar archivos de vídeo y streams. Vacío significa ninguno |
| `Config.Library` | Biblioteca activada o desactivada, películas destacadas y películas bloqueadas |
| `Config.Queue` | Cola activada o desactivada, y su tamaño |
| `Config.Channels` | Canales de televisión, sus categorías y fuentes |
| `Config.Playback` | Volumen por defecto, distancia, paredes, pantallas renderizadas a la vez y URL del reproductor |
| `Config.Locations` | Pantallas fijas |
| `Config.Models` | Modelos de televisor y sus render targets |

### Qué pueden pegar los jugadores

| Fuente | Ejemplo |
| --- | --- |
| YouTube | `https://www.youtube.com/watch?v=…`, `youtu.be/…`, `/shorts/…`, `/live/…` o el id del vídeo |
| El directo de un canal de YouTube | `https://www.youtube.com/@channel/live` o `ytlive:@channel` |
| Vimeo | `https://vimeo.com/<id>`, `https://vimeo.com/<id>/<hash>` (no listado) o `vimeo:<id>` |
| Biblioteca | `https://archive.org/details/<id>` o `archive:<id>` |
| Archivo de vídeo o stream | `https://<allowed host>/file.mp4` o `https://<allowed host>/live.m3u8` |

El avance y retroceso y el «siguiente» automático de la cola necesitan la duración del vídeo, que YouTube, Vimeo, la
biblioteca y los archivos de vídeo proporcionan. Un stream en directo se reproduce hasta que alguien pone otra cosa o
apaga la pantalla; tras una pausa se reanuda en el momento en directo, como un televisor.

Algunos vídeos de YouTube y Vimeo solo se reproducen en los sitios web que elige su propietario. Vimeo lo indica antes
de reproducir; YouTube no siempre, y la pantalla muestra `YOUTUBE_150` y lo explica.

### Biblioteca de películas

Las películas provienen de la colección `feature_films` del Internet Archive. Solo se listan las subidas marcadas como
dominio público, lo que deja fuera la mayoría de las copias de películas todavía bajo copyright, y los títulos para
adultos se filtran. Los enlaces pegados a mano siguen las mismas reglas.

El archivo lo suben los usuarios. Si ves una película que no quieres, añade su id a `Config.Library.blocked`. Los
jugadores reproducen las películas en streaming desde archive.org, así que archive.org ve su IP, igual que YouTube.

### Canales

Los canales son lo que lista la guía de canales del mando, agrupados por categoría, con canal arriba / abajo mientras
ves uno. Arrancan con el recurso y siguen reproduciéndose mire alguien o no, de modo que todas las pantallas en un
canal muestran el mismo momento.

```lua
Config.Channels = {
    enabled = true,
    checkInterval = 180, -- seconds between checks of a live source
    list = {
        { id = 'noir', label = 'Noir', category = 'movies', shuffle = true, sources = { 'archive:Detour', 'archive:ScarletStreet' } },
        {
            id = 'news', label = 'News', category = 'news',
            sources = {
                'https://example.com/live/master.m3u8', -- a live stream (HLS)
                'ytlive:@channel', -- backup: whatever that YouTube channel is airing live
                'https://www.youtube.com/live/<id>', -- backup: one live stream
            },
        },
    },
}
```

Las fuentes se reproducen en orden. Una fuente en directo se reproduce hasta que falla; entonces la siguiente toma el
relevo, así que coloca los respaldos después de ella. Los vídeos y las películas se reproducen uno tras otro (con
`shuffle` el orden cambia en cada ronda). El servidor comprueba las fuentes en directo cada `checkInterval` segundos,
sigue a un canal de YouTube hasta su nuevo stream cuando empieza otro, y omite una fuente que deja de responder
durante 10 minutos. Cuando los jugadores cercanos a una pantalla informan de que un canal no se puede reproducir (dos
jugadores, o uno que pueda controlar la pantalla), el canal pasa también a su siguiente fuente.

Categorías: `news`, `sports`, `music`, `movies`, `kids`, `nature`, `documentary` y `entertainment` están traducidas;
cualquier otra palabra se muestra tal cual.

Los canales que vienen configurados son películas y dibujos animados de dominio público del Internet Archive: el
recurso no incluye ninguna fuente de cadenas, de música ni de otros terceros, y lo que añadas a la lista es
responsabilidad tuya. Una fuente que falla (un stream que cambia de sitio, se bloquea por región o termina) se omite:
la siguiente toma el relevo y la fallida se vuelve a comprobar más tarde. La consola se mantiene en silencio: un canal
imprime una línea cuando se queda sin nada que reproducir, y `Config.Debug = true` imprime por qué falla cada fuente.
Cuando nada funciona, el canal espera un minuto y vuelve a intentarlo, cada vez más tarde (hasta 10 minutos).

YouTube responde a muchas IP de hosting con una página de inicio de sesión en vez del canal, así que en tu servidor
`ytlive:` puede no ver lo que un canal está emitiendo, y el canal pasa a su siguiente fuente. Pon detrás, como
respaldo, el directo que el canal está emitiendo, `https://www.youtube.com/live/<id>`: un único directo, comprobado
por el oEmbed de YouTube (que esas IP sí pueden usar) y descartado cuando las pantallas informan de que ha terminado.
Cuando el canal empiece otro directo, abre `youtube.com/@canal/live` en un navegador y pon el nuevo id en la config.
Las películas de archive.org se recuerdan en el servidor una vez resueltas (almacén KVP), así que tras el primer
arranque los canales y las pantallas fijas arrancan aunque archive.org esté caído. Un stream de televisión en directo
(`.m3u8`) solo se reproduce si su host permite que los navegadores lo lean (CORS); el servidor lo comprueba antes de
usarlo.

Una pantalla en un canal no se puede pausar, avanzar o retroceder ni encolar: los jugadores cambian de canal o ponen
otra cosa.

Los elementos de archive.org de la configuración no tienen por qué formar parte de la biblioteca de películas (los
dibujos animados configurados no lo son). Los jugadores solo pueden pegar películas de la biblioteca.

### Pantallas fijas

```lua
Config.Locations = {
    {
        label = 'Vinewood cinema',
        model = 'v_ilev_cin_screen',
        coords = vec3(-1426.3, -248.1, 23.3),
        spawn = false, -- true: the resource places the prop (set heading too)
        autoplay = 'channel:horror', -- a channel, a film ('archive:<id>') or a link
        volume = 40,
        loop = true,
        locked = { ace = 'xex_tv.cinema', jobs = { cinema = 0 } }, -- job = minimum grade
    },
}
```

Cualquiera puede ver una pantalla bloqueada. Solo el ACE, los trabajos listados y `xex_tv.admin` pueden cambiarla.
Para los props del mapa, `coords` debe estar a menos de 0,75 m del prop: ponte a su lado y usa las coordenadas que
muestra `/tvdebug`.

### Permisos

```cfg
# Only if Config.Permissions.ace = 'xex_tv.use'
add_ace group.vip xex_tv.use allow
# Every screen, locked ones included
add_ace group.admin xex_tv.admin allow
```

## Límites conocidos

- Los televisores de modelos que comparten un render target (la mayoría usa `tvscreen`) no pueden mostrar cosas
  distintas uno junto a otro: solo se dibuja el más cercano de cada render target.
- Algunos vídeos de YouTube solo se reproducen en los sitios web que permite su propietario (`YOUTUBE_150`); lo mismo
  ocurre con Vimeo.
- Los streams en directo se ven desde el momento en directo, así que dos pantallas con el mismo stream pueden ir unos
  segundos desfasadas.
- Algunas cadenas solo muestran su stream en algunos países. Cada jugador lo ve desde su propia conexión.
- Una pantalla en pausa durante una hora se apaga.

## Error 153 de YouTube

Si YouTube se niega a reproducir en el navegador del juego en tu servidor (`YOUTUBE_153`), aloja `ui/player/` y
`ui/fonts/` en tu propio dominio HTTPS, manteniendo ambas carpetas una junto a la otra, y configura:

```lua
Config.Playback.playerUrl = 'https://tv.example.com/player/player.html'
```

## Exports

```lua
-- server
local screenId = exports.xex_tv:playAtCoords(vec3(100.0, 200.0, 30.0), `prop_tv_flat_01`, 'channel:noir', {
    volume = 25, bucket = 0,
})
exports.xex_tv:queue(screenId, 'archive:his_girl_friday')
local screen = exports.xex_tv:getScreen(screenId)
exports.xex_tv:stop(screenId)

-- client: open the remote for the closest TV
exports.xex_tv:open()
```

`playAtCoords` también acepta `offset` (segundos) y `loop`. Devuelve el id de la pantalla de inmediato y la pantalla
arranca una vez comprobado el enlace, normalmente en menos de un segundo. `queue` funciona de la misma manera. Los
enlaces rechazados se imprimen en la consola del servidor.

## Seguridad

Los jugadores solo envían peticiones. El servidor comprueba el modelo del televisor, la distancia y el bucket del
jugador, los permisos y un tiempo de espera, analiza cada enlace por sí mismo y construye las URL de archive.org. Los
archivos de vídeo y los streams que pegan los jugadores solo se aceptan de los hosts que listes, porque todos los
jugadores se conectan a ellos y el host ve su IP. Los canales y las pantallas fijas usan las fuentes que escribiste en
la configuración.

## Licencia

MIT. Úsalo, modifícalo y compártelo; conserva el aviso de copyright. Consulta LICENSE.

Los streams en directo se reproducen con [hls.js](https://github.com/video-dev/hls.js) (Apache 2.0), incluido en
`ui/player/vendor` con su licencia.
