playback-svc

playback-svc

Playback de styx: resuelve un PlaybackIntent en un PlaybackPlan composicional y explicable y abre la entrega en el daemon; decide además quién sube ficheros (ingesta con SCT de scope ingest). Los bytes de vídeo nunca pasan por aquí. ## Errores Todo error es un Problem Details (RFC 9457) servido como `application/problem+json`, con `type`, `title`, `status` y un `code` estable. Los errores de dominio añaden `retryable` y `category` (`transient`, `permanent` o `recoverable`). Los de framework son `400 parse` (JSON roto), `404 not-found` (ruta inexistente) y `422 validation` (con `on`; `property` y `detail` sólo fuera de producción). Las denegaciones del Bearer son `401 unauthenticated` o `reauth-required`, `403 forbidden` y `429 rate-limited` (con `Retry-After`). Ningún problem repite el valor recibido y un recurso de otro actor responde 404, sin oráculo.

Liveness del proceso

GET
/health

Responde 200 mientras el proceso atiende peticiones; no comprueba dependencias. La usan el HEALTHCHECK de la imagen y el compose (con GET: HEAD es opt-in en Elysia 2).

Response Body

application/json

curl -X GET "https://example.com/health"
{  "service": "playback-svc",  "status": "ok",  "timestamp": 0,  "uptime": 0,  "version": "string"}

Abrir una sesión de ingesta (SCT ingest + endpoint del daemon)

POST
/ingest/sessions

Abre una sesión de ingesta para un fichero de sizeBytes y devuelve el endpoint de conduit en el daemon y la SCT de scope ingest. 429 si el actor ya tiene abiertas todas las permitidas; 413 si el fichero pasa del tope del nodo. Los bytes van directos al daemon, nunca por aquí.

Acceso: Bearer de identity con policy resource:ingest-session:create.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token de identity-svc (JWT EdDSA, caducidad corta). Se verifica en local y después contra la sesión viva (revocation-aware).

In: header

Request Body

application/json

Tamaño del fichero a subir; la capability lo fija como tope.

TypeScript Definitions

Use the request body type in TypeScript.

Tamaño del fichero a subir; la capability lo fija como tope.

sizeBytes*integer
Range0 <= value <= 1099511627776

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/ingest/sessions" \  -H "Content-Type: application/json" \  -d '{    "sizeBytes": 0  }'
{  "capability": {    "expiresAt": 0,    "token": "string"  },  "endpoint": "string",  "maxBytes": 0,  "sessionId": "string"}

Abortar una sesión de ingesta propia

DELETE
/ingest/sessions/{sessionId}

Aborta la sesión y el daemon revoca su capability. Una sesión de otro actor es 404, salvo para admin/owner.

Acceso: Bearer de identity con policy resource:ingest-session:close.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token de identity-svc (JWT EdDSA, caducidad corta). Se verifica en local y después contra la sesión viva (revocation-aware).

In: header

Path Parameters

sessionId*string
Match^ing_[0-9a-f]{32}$

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X DELETE "https://example.com/ingest/sessions/string"
{  "closed": true}

Renovar la capability de una sesión de ingesta propia

POST
/ingest/sessions/{sessionId}/token

Emite una capability nueva para reanudar la subida. Sólo el dueño; 429 si la sesión agotó su cupo de renovaciones.

Acceso: Bearer de identity con policy resource:ingest-session:renew.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token de identity-svc (JWT EdDSA, caducidad corta). Se verifica en local y después contra la sesión viva (revocation-aware).

In: header

Path Parameters

sessionId*string
Match^ing_[0-9a-f]{32}$

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/ingest/sessions/string/token"
{  "capability": {    "expiresAt": 0,    "token": "string"  }}

Abrir una sesión de playback (PlaybackIntent → SessionDescriptor)

POST
/sessions

El Planner resuelve el intent en un PlaybackPlan composicional (mode derivado, no lo manda el cliente) y la entrega; la sesión y su capability quedan ligadas al actor. Sin MediaIndex del asset: PLAYBACK_NO_CAPABILITIES.

Acceso: Bearer de identity con policy resource:asset:play.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token de identity-svc (JWT EdDSA, caducidad corta). Se verifica en local y después contra la sesión viva (revocation-aware).

In: header

Request Body

application/json

Intent de reproducción: asset y capabilities del cliente (video, audio y contenedores obligatorios), con preferencias opcionales. Las entradas de capability viajan sin cerrar su vocabulario (forward-compat).

TypeScript Definitions

Use the request body type in TypeScript.

Intent de reproducción: asset y capabilities del cliente (video, audio y contenedores obligatorios), con preferencias opcionales. Las entradas de capability viajan sin cerrar su vocabulario (forward-compat).

intent*

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/sessions" \  -H "Content-Type: application/json" \  -d '{    "intent": {      "assetId": "string",      "client": {        "audio": [          null        ],        "containers": [          null        ],        "video": [          null        ]      }    }  }'
{  "descriptor": {    "actor": {      "roles": [        "string"      ],      "service": "string",      "sessionId": "string",      "userId": "string"    },    "assetId": "string",    "createdAt": "string",    "delivery": {      "certHash": "string",      "endpoint": "string",      "packaging": {        "capability": "string",        "codecs": "string",        "engine": "zig",        "packagingId": "string",        "segments": 1,        "targetDurationS": 1      },      "tcpEndpoint": "string",      "tokenTtlMs": 0,      "transport": "string"    },    "expiresAt": "string",    "plan": {      "audio": {        "action": "copy",        "channels": "mono",        "codec": "aac"      },      "container": {        "action": "copy",        "input": "matroska",        "output": "matroska"      },      "delivery": {        "tokenTtlMs": 0,        "transport": "string",        "url": "string"      },      "estimatedCost": {        "score": 0,        "serverSideCompute": true,        "tier": "free"      },      "mode": "direct",      "reasons": [        {          "kind": "container-direct",          "message": "string"        }      ],      "source": {        "kind": "string",        "score": 0      },      "subtitles": {        "action": "none",        "format": "srt"      },      "video": {        "action": "copy",        "codec": "h264",        "filters": [          {            "kind": "scale",            "params": [              "string"            ]          }        ]      }    },    "sessionId": "string"  }}

Cerrar una sesión empaquetada propia (ClosePackaging en el daemon)

DELETE
/sessions/{sessionId}

Cierra en el daemon una sesión empaquetada (pkg_*) del actor. La de otro actor responde 404, igual que una inexistente.

Acceso: Bearer de identity con policy resource:playback-session:close.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token de identity-svc (JWT EdDSA, caducidad corta). Se verifica en local y después contra la sesión viva (revocation-aware).

In: header

Path Parameters

sessionId*string
Match^pkg_[0-9a-f]{32}$

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X DELETE "https://example.com/sessions/string"
{  "closed": true}

Reportar métricas de reproducción de una entrega propia (OB2)

POST
/sessions/{sessionId}/metrics

Lote acotado (a lo sumo 32 eventos) de TTFF, seek, stalls, cambios de rendition y errores medidos por el reproductor del navegador. Sólo el dueño de la entrega; una ajena o inexistente responde 404. Cada entrega tiene un presupuesto de eventos: lo que lo excede se descarta (dropped), no se rechaza. El motor y el modo los pone el servidor.

Acceso: Bearer de identity con policy resource:playback-session:report.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token de identity-svc (JWT EdDSA, caducidad corta). Se verifica en local y después contra la sesión viva (revocation-aware).

In: header

Path Parameters

sessionId*string
Match^(pkg|sess)_[0-9a-f]{32}$

Request Body

application/json

Lote de métricas de reproducción de una sesión propia (a lo sumo 32 eventos).

TypeScript Definitions

Use the request body type in TypeScript.

Lote de métricas de reproducción de una sesión propia (a lo sumo 32 eventos).

events*array<|||||>
Items1 <= items <= 32
player*string

Value in

  • "vidstack"
  • "limeplay"

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/sessions/string/metrics" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "ms": 0,        "t": "ttff"      }    ],    "player": "vidstack"  }'
{  "accepted": 0,  "dropped": 0}

Renovar el SCT de lectura de una entrega propia (SEC-Z13)

POST
/sessions/{sessionId}/token

Emite un SCT de lectura nuevo del mismo sid, actor y recurso presentando el vigente como prueba de posesión. Sólo el dueño; 403 si el SCT no es el último emitido (anti-replay) o está caducado más allá del skew; 429 sin cupo de renovaciones; 410 pasada la edad máxima de la entrega. Una entrega de otro actor o inexistente responde 404.

Acceso: Bearer de identity con policy resource:playback-session:renew.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token de identity-svc (JWT EdDSA, caducidad corta). Se verifica en local y después contra la sesión viva (revocation-aware).

In: header

Path Parameters

sessionId*string
Match^(pkg|sess)_[0-9a-f]{32}$

Request Body

application/json

SCT de lectura vigente (o caducado hace menos que el skew de 30 s) de la misma entrega.

TypeScript Definitions

Use the request body type in TypeScript.

SCT de lectura vigente (o caducado hace menos que el skew de 30 s) de la misma entrega.

capability*string
Match^[A-Za-z0-9_-]{272}$

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/sessions/string/token" \  -H "Content-Type: application/json" \  -d '{    "capability": "string"  }'
{  "capability": {    "expiresAt": 0,    "token": "string",    "ttlMs": 1  }}

Componente, versión, tren y commit del binario que corre

GET
/version

Response Body

application/json

curl -X GET "https://example.com/version"
{  "commit": "string",  "component": "string",  "train": "string",  "version": "string"}

Componente, versión, tren y commit del binario que corre GET

Anterior

Liveness del proceso GET

Responde 200 mientras el proceso atiende peticiones; no comprueba dependencias. La usan el HEALTHCHECK de la imagen y el compose (con GET: HEAD es opt-in en Elysia 2).