# Límite entre esta API y el SDK oficial de LiveKit

Este documento existe para que un integrador externo (frontend web propio,
app Flutter propia, o un frontend de terceros que un cliente construya)
sepa exactamente qué parte de una videollamada gestiona esta API REST y
qué parte gestiona el SDK oficial de LiveKit — para que nunca intente
reimplementar señalización WebRTC contra esta API.

## Qué SÍ hace esta API (aprovisionamiento)

Esta API solo crea y gestiona los **recursos** alrededor de una llamada:

- **Tokens de acceso** (`POST /api/v1/livekit/token`, `POST
  /api/v1/audio/create-call`, `POST /api/v1/video/create-call`): genera un
  JWT firmado con los permisos de LiveKit (`RoomJoin`, nombre de sala,
  identidad) y devuelve, junto al token, la URL del servidor LiveKit
  (`wss://livekit.aurasede.es`) a la que hay que conectarse.
- **Grabaciones** (`/api/v1/recordings/*`): inicia/detiene una grabación
  vía el cliente oficial `lksdk.EgressClient` contra el servicio
  `livekit/egress` (Docker oficial) — este servidor Go nunca toca paquetes
  RTP ni hace la mezcla de audio/vídeo él mismo.
- **Documentos adjuntados** (`/api/v1/documents/*`): almacenamiento y
  descarga de ficheros compartidos durante una llamada. El aviso de que
  hay un documento nuevo viaja por el *data channel* de LiveKit (parte del
  SDK), no por esta API.
- **Ciclo de vida** (`/api/v1/webhooks/livekit`, uso interno): recibe los
  webhooks del propio servidor LiveKit para cerrar salas/grabaciones
  huérfanas — un integrador externo nunca llama a este endpoint.

## Qué NO hace esta API (eso es el SDK oficial de LiveKit)

Todo lo que ocurre **durante** la llamada en sí —conexión WebRTC,
señalización, publicación/suscripción de pistas de audio/vídeo, calidad
adaptativa, reconexión— lo gestiona el **SDK oficial de LiveKit**, nunca
esta API:

- Web / frontend propio: SDK JS/TS `livekit-client`
  (https://github.com/livekit/client-sdk-js).
- App Flutter propia: paquete oficial `livekit_client`
  (https://pub.dev/packages/livekit_client).
- Frontends de terceros: cualquiera de los SDKs oficiales de LiveKit para
  su plataforma (hay para iOS, Android, Unity, React Native, etc.).

El flujo correcto de integración es siempre:

1. El cliente llama a esta API REST para obtener `{ token, url,
   room_name }`.
2. El cliente pasa ese `token` y esa `url` directamente al SDK oficial de
   LiveKit correspondiente a su plataforma.
3. El SDK oficial hace `room.connect(url, token)` y gestiona toda la
   señalización WebRTC real contra el servidor LiveKit
   (`livekit.aurasede.es`) — esta API REST ya no interviene en la llamada.

**Regla explícita para cualquier integrador:** si necesitas algo relacionado
con audio/vídeo en tiempo real (mutear, cambiar cámara, compartir
pantalla, calidad de red...), es una llamada al SDK oficial de LiveKit, no
un endpoint nuevo en esta API. Si crees que necesitas "hablar WebRTC/RTP a
mano" contra esta API, es una señal de que algo está mal planteado — parar
y reconsiderar antes de implementarlo (ver
[[feedback_infra_vs_code]] en la memoria del proyecto: ya pasó una vez con
Egress y produjo grabaciones corruptas).