Modelo de datos

Especificado. Esta página describe el comportamiento objetivo. El diseño está en dec-0127, que enmienda dec-0126. Los dos se lockearon juntos el 2026-10-02. Todavía no hay código. Lo que dice obliga a la implementación.

La idea en una fraseCopiar enlace

El fichero manda. El título, la sinopsis, los ids de TMDb o IMDb, la edición, las referencias al artwork, la portada, las marcas de intro y créditos y tus correcciones manuales viven dentro del propio vídeo. Si descargas ese fichero y lo abres en VLC o lo mandas por AirPlay, ya lleva sus metadatos. Si pierdes la base de datos, Styx la reconstruye leyendo los ficheros.

Qué hay dentro del ficheroCopiar enlace

Dos cosas, escritas juntas por el daemon (cómo se escribe sin tocar el vídeo: Metadatos en el fichero):

1. styx.json: el documento completo de la obra, en JSON canónico (RFC 8785), siempre con los mismos bytes para el mismo contenido.
   • En Matroska va como adjunto styx.json.
   • En MP4 va como item ----:dev.mks2508.styx:doc dentro de moov/udta/meta/ilst.
   • Ocupa como mucho 256 KiB y no lleva imágenes: las referencia por su sha256.
2. La proyección a tags estándar (©nam, desc, covr… en MP4; TITLE, Attachments… en Matroska), más la portada. Es lo que leen los reproductores de terceros. Se deriva siempre de styx.json.

Los capítulos de intro y créditos se escriben como capítulos nativos del contenedor.

Dónde vive cada datoCopiar enlace

Nada tuyo viaja en el fichero: ni progreso, ni perfil, ni hogar, ni rutas.

Por qué listar es rápidoCopiar enlace

El catálogo guarda un índice derivado de los ficheros: lo justo para listar, buscar, ordenar y filtrar, más el documento completo como caché.

• Una página de la biblioteca, una búsqueda, los rails o la ficha de una película cuestan cero lecturas de fichero.
• Si algo aún no está indexado, aparece como "pendiente" y llega en cuanto se lee. La página no espera al disco.
• En frío (primer escaneo, reconstrucción), Styx pide los documentos al daemon por lotes. El daemon lee sólo la región de metadatos de cada fichero: ni el vídeo ni las imágenes.

Cómo se detectan los cambiosCopiar enlace

Cada documento tiene un metadataHash (BLAKE3 de styx.json), guardado en el índice.

1. En cada reescaneo, Styx compara primero lo barato: tamaño, fecha de modificación e inodo. Si no cambió nada, no lee nada.
2. Si cambió, lee sólo el documento y compara el hash.

Qué pasa entonces:

Cachés de la web y de las appsCopiar enlace

• Cada respuesta lleva ETag con el hash. Si el cliente ya lo tiene, recibe un 304 sin cuerpo.
• Un feed de cambios (library.changes, con una revisión que sólo avanza) dice qué cambió desde la última vez. Además llega empujado por tiempo real.
• El cliente guarda los items por id y hash. Es la única copia fuera del servidor.

ArtworkCopiar enlace

• Todas las imágenes se guardan en un almacén direccionado por contenido (sha256). Sólo la portada viaja además dentro del fichero.
• Las sirve el daemon en /art/<sha256>/<variante>, con URLs que nunca cambian y caché "inmutable" en el navegador. Una imagen nueva es una URL nueva.
• Los tamaños para cada pantalla se generan al indexar, en un proceso aislado. El servidor de imágenes no decodifica nada.
• Si el almacén se pierde, la portada sale del fichero y el resto se vuelve a pedir a su proveedor, verificado por hash.

Ids que no cambianCopiar enlace

• El id de un asset sale de la huella del contenido: el mismo vídeo tiene el mismo id en cualquier carpeta y en cualquier servidor.
• El id de una obra sale de un workUid guardado en styx.json.
• Tu progreso y tus listas siguen apuntando a lo correcto después de reconstruir el índice o de mover la biblioteca.

EnriquecimientoCopiar enlace

• El plugin de enriquecimiento de Styx viene activado por defecto. Busca metadatos y artwork con los proveedores que configures (TMDb, TheTVDB, fanart.tv, tus NFO de Jellyfin, los tags que ya tenga el fichero), en el orden que elijas por campo.
• Se puede desactivar por biblioteca o sustituir por otro plugin.
• Tus correcciones manuales se guardan como locks dentro del fichero, y ningún proveedor las pisa.

DescargasCopiar enlace

Todo lo que descargas de Styx lleva su styx.json y su portada, también si pides otro formato o códec y Styx lo genera al vuelo. Un fichero descargado se describe solo, también sin conexión.

Decidido en el lockCopiar enlace

Las preguntas de dec-0127 §13 se cerraron el 2026-10-02:

• la escritura en el fichero viene activada en las raíces que gestiona Styx (ingesta, canónicas, creadas desde la UI); en una biblioteca existente, el asistente te ofrece activarla;
• el índice guarda el styx.json entero, direccionado por su hash, y de ahí proyecta lo que hace falta para listar;
• las ediciones de herramientas de terceros se adoptan si son válidas y se descartan si son basura, y sólo te pregunta cuando hace falta que decidas;
• el artwork se sirve con una credencial de sesión ligada a tu cuenta;
• tu estado se reparte: playback-svc guarda el progreso y las sesiones, y catalog-svc lo visto, favoritos y listas;
• los ids de asset y de obra salen del propio fichero;
• los proveedores sin clave vienen activados, y el primer arranque te pide la clave de TMDb.