Receptor

El receptor es una app web (Vue + Shaka Player, con ExoPlayer en Android TV y AVPlay en Samsung) que corre en Samsung Tizen, LG webOS, Android TV, Hisense VIDAA y navegadores. Esta sección es para quien quiera entender el protocolo o construir su propio receptor.

Ciclo de vida

1. POST /v1/receivers con { "platform": "tizen" | "webos" | "android" | "vidaa" | "web" } → receiverId, receiverSecret y el primer estado.
2. Abrir el flujo de eventos: pedir un ticket con POST /v1/receivers/{id}/events-ticket y abrir GET /v1/receivers/{id}/events?ticket=<ticket>. El ticket sirve una vez y dura 30 s; pide uno nuevo en cada reconexión.
3. Latido: GET /v1/receivers/{id}/state al menos cada 45 s, aunque el flujo esté abierto.
4. Renovar el código antes de que caduque: POST /v1/receivers/{id}/code. Programa la renovación con codeExpiresIn (milisegundos restantes), no con codeExpiresAt: el reloj de muchos TVs está desfasado.
5. Informar la reproducción: PUT /v1/receivers/{id}/playback (ver abajo).
6. Desconectar desde el TV: DELETE /v1/receivers/{id}/session.

Las llamadas del receptor se autentican con la cabecera X-Receiver-Secret y van siempre por https. El secreto nunca va en la URL: EventSource no permite cabeceras, por eso existe el ticket. Un receptor que sí pueda enviar cabeceras puede abrir el flujo con X-Receiver-Secret directamente.

Eventos (SSE)

• event: state — el ReceiverState completo al conectar y en cada cambio de conexión. Incluye pendingCast y commands, así que lo que llegó mientras el TV reconectaba aparece en el primer state.
• event: cast — un Cast nuevo; reemplaza al actual.
• event: command — una orden del teléfono (Command). Ignora las de otro castId y las que ya aplicaste (mismo commandId: pueden llegar también dentro de state.commands).
• : ping cada 20 s. Se permiten 2 flujos abiertos a la vez por receptor; el flujo se cierra solo si el receptor caduca. No mantiene vivo al receptor (un socket medio cerrado de un TV apagado seguiría recibiendo pings); para eso está el latido. Sin latido, el receptor caduca a los 2 minutos.

Si el flujo falla, el receptor oficial consulta GET /v1/receivers/{id}/state cada 3 segundos (los comandos de los últimos 10 s vienen en commands) y vuelve a intentar SSE cada minuto.

Informar la reproducción

PUT /v1/receivers/{id}/playback con el estado completo (PlaybackReport): al recibir un video (loading), en cada cambio (estado, pistas, volumen, salto, comando aplicado con su lastCommandId) y cada 5 s mientras reproduce. Al salir del reproductor, stopped; si falla, failed con error. El servidor deriva de ahí el estado del envío que ve el teléfono.

Los id de pista son tuyos: cadenas que luego vuelven en los comandos subtitles y audio.

Comandos que hay que aplicar

play, pause, stop (salir del reproductor), seek (position), skip (seconds), volume (level 0–100), mute (muted), subtitles (trackId o null), audio (trackId). Muestra en pantalla lo que hace cada uno, para que quien mira el TV entienda qué pasó.