Medios embebidos: audio, vídeo y fichas con markeup-media

La skill markeup-media —«Escribe bloques embed, audio, video, book y film del vault»— es una de las habilidades que el sistema MarkeUP tiene escritas para Hermes Agent y para Cline. Esta página es su ficha pública: lo que sabe hacer, cuándo se usa y qué comandos ejecuta.

Un vídeo, un audio o la ficha de un libro se escriben como un bloque, no como HTML a mano: esta skill controla esa traducción.

El texto de la sección «Instrucciones del canon» está transcrito del fichero fuente —que se escribe sin tildes por convención de su propio gate—, así que es exactamente lo que lee el agente cuando le pides algo. La cabecera y esta entradilla sí están redactadas para leerlas.

Dato	Valor
Skill	`markeup-media`
Responsabilidad	Escribe bloques embed, audio, video, book y film del vault.
Versión	1.1.0
Autoría	uriszarernesto-blip · licencia MIT
Plataformas	linux · macos
Tags del canon	media · embed · audio · video · book · film · csp · markeup
Skills relacionadas	markeup-content · markeup-frontmatter · markeup-cli · markeup-seo
Fuente	`~/.hermes/skills/markeup/markeup-media/SKILL.md`

Responsabilidad unica: meter un video, un audio o la ficha de un libro o una pelicula en una nota, de la forma que el gate acepta.

Detalle de implementacion: docs/media.md · fichas de libro: docs/books.md · guia de autorizacion para quien escribe: el post Documentacion/doc-medios-embebidos.md. Referencia de claves: references/blocks-reference.md.

Un post lleva un video, un audio o la ficha de un libro o una pelicula.
El gate rechaza un bloque que ya existe: npm run validate:media.
Se toca una cache (media:fetch, films:fetch, books:fetch) o un poster local.
La ficha de un libro no esta en la cache: se crea con npm run add:book (ver mas abajo).
Se cambia el frame-src de la CSP o la lista de proveedores de la fachada.

Despues de tocar una cache, el HTML ya renderizado no siempre se rehace: mira «Despues de tocar una cache» mas abajo.

Un bloque cercado, nunca HTML a mano. El HTML lo emite el plugin (remark-media), no la persona que escribe. Escribir un <audio> o un <iframe> a mano es un error: el embed nunca se sirve como marco (la fachada inyecta el <iframe> al clic).

```embed
provider: youtube
url: https://youtu.be/3zeqJ5tqmaQ
title: Astro Suite for Obsidian
caption: Demo oficial del plugin
start: 0:30
```

```audio
src: /aud/teoria-polivagal.mp3
title: Teoria polivagal
```

La azucar de Obsidian (![alt](url), ![[url]], ![[archivo.mp3]]) tambien se traduce, pero el bloque es la forma que admite title, caption y start: la azucar sale como aviso del gate.

Lenguaje	Para	Claves	Limite
`embed`	Terceros (YouTube, Vimeo, Spotify, SoundCloud, iVoox)	`provider`, `id`, `url`, `embed`, `title`, `caption`, `start`, `type`, `nocookie`, `poster`	4 por nota
`audio`	MP3 local	`src`, `title`, `caption`, `loop`	25 MiB
`video`	Video local	`src`, `poster`, `title`, `caption`, `loop`	25 MiB
`book`	Ficha desde la cache	`isbn`, `caption`, `poster`	ISBN con ficha en `scripts/data/books.json`
`film`	Ficha de pelicula	`tmdb`, `title`, `year`, `director`, `poster`, `nota`, `caption`, `synopsis`, `url`	`tmdb` con ficha en `scripts/data/films.json`, o la ficha a mano

Una clave que el lenguaje no admite es ERROR: proveedor: en lugar de provider: no se publica “como si nada”.
src tiene que ser una ruta publica (/aud/..., /video/...) y existir.
title es obligatorio: sin el, el reproductor se queda sin nombre accesible.
Hasta 4 embeds por nota; los audios/videos locales, 25 MiB.

Que	Comando	Cache versionada
Posters de los embeds	`npm run media:fetch`	`scripts/data/media.json` + `public/img/media/`
Fichas de pelicula (TMDB)	`npm run films:fetch`	`scripts/data/films.json`
Fichas de libro (Google Books / Open Library)	`npm run books:fetch`	`scripts/data/books.json`

books:ensure es la red de seguridad de astro dev (corre en predev): la ficha de un libro recien escrito se resuelve al pintar.
Sin TMDB_TOKEN (o TMDB_API_KEY) no hay films:fetch: la ficha se escribe a mano o degrada con aviso visible.
Sin ficha, el gate bloquea: isbn o tmdb sin entrada en la cache es error.
npm run books:prune quita de books.json las fichas que ningun post usa (tras borrar o renombrar un post; la cache deja de arrastrar libros muertos).

Si el libro no esta en la cache, la ficha se crea con el comando: no se inventa el ISBN, no se escribe el JSON a mano y no se delega a un subagente.

npm run add:book -- --slug <slug-del-post> --isbn <isbn-de-13-digitos>
npm run validate:books      # GATE: bookIsbn del frontmatter <-> ficha en la cache

add:book resuelve la ficha (Google Books / Open Library), la guarda en scripts/data/books.json, baja la portada y escribe el bookIsbn en el frontmatter.

Con --buscar / --elegir revisas la ficha antes de aceptarla (lookup verificado); --isbn <isbn> --force publica aunque la relevancia texto ↔ libro salga baja (mira el ISBN a mano). El bloque del cuerpo queda asi:

```book
isbn: 9788472455672
caption: Edicion de Kairos (2005)
```

books:fetch y books:ensure refrescan la cache; no sustituyen a add:book cuando la ficha no existe.

Astro guarda el HTML ya renderizado de cada nota indexado por el digest de su .md. Si lo unico que cambia es un input externo (el poster que baja media:fetch, la ficha, el plugin), el digest no se mueve, Astro reutiliza el HTML viejo y el post se publica con el hueco. Por eso npm run content:cache corre dentro de build (y hay --check, --preflight, --force, --json).

Aviso del dev server: esa cache la comparte astro dev y content:cache no la borra si hay un dev vivo (lo dice y sigue). Borrarla con el dev abierto lo deja sirviendo el vault vacio (/posts sin posts) hasta reiniciarlo. Paso el 2026-09-30.

La tabla PROVIDERS (en scripts/mjs/lib/media-spec.mjs) y el frame-src de public/_headers son la misma lista escrita en dos sitios: si divergen, el navegador bloquea el marco y la pagina se queda en negro. Lo compara el gate (validate:media); npm run build tambien mira el frame-src.

src/lib/podcasts.ts recorre los posts con el mismo parser (extraerBloques + parseMediaBlock), asi que publicar un audio lo anade a /podcasts sin tocar nada. Un audio = una entrada (dedup por src).

cd ~/markeup
npm run validate:media              # GATE (esta en build, verify:content y deploy)
npm run validate:media -- --strict  # ademas, 0 avisos
npm run validate:books              # bookIsbn <-> ficha
npm run test                        # media.test.ts · facade.test.ts · player.test.ts

Error del gate	Causa	Arreglo
Proveedor desconocido / clave no admitida	Typo en `provider:` o clave que ese lenguaje no acepta	Ver la tabla de arriba
`src` local inexistente	Ruta mal escrita o archivo fuera de `public/`	Corregir la ruta o mover el archivo
`isbn` sin ficha	El libro no esta en la cache	`npm run add:book -- --slug <slug> --isbn <isbn>` (crea la ficha; `books:fetch` solo refresca)
`tmdb` sin ficha	Falta la ficha de la pelicula	`TMDB_TOKEN=... npm run films:fetch`
Pide poster y no esta	El poster declarado no esta en `public/`	`npm run media:fetch` o quitar `poster`
`frame-src` desincronizado	Proveedor nuevo en `PROVIDERS` sin CSP (o al reves)	Anadir el origen en los dos sitios
HTML viejo con hueco	Cache de render obsoleta	`npm run content:cache -- --force` (con el dev cerrado)

Escribe bloques; jamas HTML de medio a mano.
Un embed nuevo se prueba con npm run validate:media antes de dar el post por hecho: esta dentro de npm run verify:content.
Tras media:fetch / films:fetch / books:fetch, el build se encarga de la cache: no hay que borrarla a mano.
Los posters son locales a proposito: el build no pide la miniatura a un tercero antes del clic.

references/blocks-reference.md — claves por lenguaje, ejemplos validos y errores.
markeup-content — donde cae el bloque dentro del cuerpo.
Codigo: src/lib/remark-media.js, src/lib/media/, scripts/mjs/validate-media.mjs.

¿Quieres saber cómo se piden estas cosas? La guía completa está en skills de Hermes Agent, con la chuleta de objetivos y los casos paso a paso.

Medios embebidos

Medios embebidos: audio, vídeo y fichas con markeup-media

Posts que enlazan a este artículo