# Formato del documento: vídeos

> Los recursos de vídeo: YouTube, Vimeo, archivos propios y flujos HLS, lo que muestra cada salida, los campos de un vídeo, su portada y su dirección, los reproductores, el VDT y los paquetes, y los vídeos que se reproducen en las páginas de Folio

- Versión HTML: https://postext.dev/es/docs/document-format-videos
- Última actualización: 2026-11-11
- Tiempo de lectura: 10 min
- Otros idiomas: [en](https://postext.dev/en/docs/document-format-videos.md), [ca](https://postext.dev/ca/docs/document-format-videos.md), [de](https://postext.dev/de/docs/document-format-videos.md), [fr](https://postext.dev/fr/docs/document-format-videos.md), [it](https://postext.dev/it/docs/document-format-videos.md), [pt](https://postext.dev/pt/docs/document-format-videos.md), [zh](https://postext.dev/zh/docs/document-format-videos.md), [ja](https://postext.dev/ja/docs/document-format-videos.md), [ar](https://postext.dev/ar/docs/document-format-videos.md)

## En pocas palabras

Esta página explica los vídeos de un libro. Un vídeo puede venir de YouTube o de Vimeo, o ser un archivo propio. Se cita en el texto como una imagen y lleva una numeración propia, como las figuras y las tablas. En papel y en PDF muestra un fotograma con una marca de reproducción y un código QR que abre el vídeo. La vista web y los libros electrónicos lo reproducen. En el libro en 3D, un clic sobre el fotograma reproduce el vídeo en la misma página, y sigue en marcha mientras pasa la hoja.

Un vídeo es un recurso, como una imagen: se declara una vez, se cita en el texto y flota hasta el primer hueco libre después de su referencia. Las referencias, la numeración, la colocación y el ajuste del texto se explican en [Formato del documento: imágenes y tablas](https://postext.dev/es/docs/document-format-resources.md); lo que sigue es propio de los vídeos.

> [Vídeos en tus libros: QR en papel, reproductor en pantalla y película en la página, con Postext](https://youtu.be/sSMqbiI9r1w) · 4:10

## Vídeos

Un recurso de **vídeo** (`kind: 'video'`) es un vídeo de YouTube o de Vimeo, o un vídeo propio: un archivo guardado en el libro (MP4, WebM) o uno que está en una dirección web, ya sea un archivo en un servidor o un **flujo HLS** (una lista de reproducción `.m3u8`). Se coloca, lleva pie, flota y se cita como una imagen, y se numera en una serie propia: el tipo integrado `video` imprime *Vídeo 1.1*, *Vídeo 1.2*… junto a *Figura 1.1* y *Tabla 1.1* (consulta [Configuración › Tipos de recurso](https://postext.dev/es/docs/configuration-resources.md#tipos-de-recurso)). Cada salida lo muestra como puede:

| Salida | Qué muestra |
| --- | --- |
| Canvas, PDF | La **portada**, un fotograma del vídeo, con una marca de reproducción y un código QR que abre el vídeo ([Configuración › Estilo de vídeo](https://postext.dev/es/docs/configuration-resources.md#estilo-de-vídeo)). En el PDF la portada es además un enlace al vídeo. |
| Folio | La portada, tal como se imprime. Un clic sobre ella reproduce el vídeo **en la propia página**, y el vídeo sigue reproduciéndose mientras se pasa la hoja (consulta [Vídeos en las páginas de Folio](https://postext.dev/es/docs/document-format-videos.md#vídeos-en-las-páginas-de-folio) más abajo). Los vídeos de YouTube y Vimeo se quedan en su portada. |
| Visor HTML | El **reproductor** del vídeo: el de YouTube o el de Vimeo, o el reproductor HTML5 del navegador para un archivo o una dirección. Un flujo HLS se reproduce de forma nativa en Safari y en las versiones recientes de Chrome; en los demás navegadores, la aplicación anfitriona añade un reproductor como hls.js, igual que hace el Sandbox. Con `videoStyle.html: 'poster'`, muestra en su lugar la portada impresa. |
| EPUB | Un archivo se reproduce en el reproductor del propio sistema de lectura, empaquetado en el libro o leído desde su dirección de producción. Un vídeo de YouTube o de Vimeo se muestra como su portada, enlazada con el vídeo: un EPUB no puede insertar el reproductor de una página web. Un flujo HLS también se muestra como su portada enlazada: una lista de reproducción HLS no es ninguno de los tipos de medio que un EPUB puede reproducir. Si el sistema de lectura ejecuta scripts, los archivos de una misma página o capítulo respetan `player.exclusive`: al empezar uno se pausan los demás con los que no se reproduce a la vez. |

```ts
const charla: Resource = {
  id: 'charla-farero', typeId: 'video', kind: 'video',
  caption: 'El farero explica la lámpara.',
  altText: 'Un farero junto a la lámpara',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'charla.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // empieza en 0:30; el enlace impreso también
  },
};
```

El texto cita un vídeo igual que una figura: `:ref{id="charla-farero"}` imprime *Vídeo 1.1* y hace flotar la portada al primer hueco libre después de la referencia, y `::resource{id="charla-farero"}` con `placement.position: 'here'` la coloca dentro del texto. Los campos de `Resource.video` (`ResourceVideo`):

| Campo | Tipo | Significado |
| --- | --- | --- |
| `source` | `'youtube'` · `'vimeo'` · `'file'` | Desde dónde se reproduce el vídeo: una página de YouTube o de Vimeo, o un vídeo propio (`'file'`), subido o en una dirección web. |
| `url` | `string` | YouTube o Vimeo: la dirección del vídeo, en cualquiera de sus formas (una página de reproducción, `youtu.be`, Shorts, un enlace de inserción, `youtube-nocookie.com`; una página de Vimeo, la de un canal o un enlace oculto con su hash). Un archivo: su **dirección de producción**, donde lo encontrará el libro publicado. Un vídeo propio sin archivo se reproduce desde esta dirección: un MP4 o WebM en un servidor, o un flujo HLS (`…/master.m3u8`). |
| `fileId`, `format` | `string` | Un archivo: el vídeo subido, guardado aparte como un mapa de bits, y su formato: `'mp4'`, `'webm'`, `'ogv'`, `'mov'`, o `'hls'` para un flujo HLS. Si no se indica, lo determina la extensión de la dirección (`.m3u8` es `'hls'`) y, en su defecto, es `'mp4'`. |
| `poster` | `{ fileId, format, width, height }` | El fotograma de portada, un mapa de bits. |
| `width`, `height`, `duration` | `number` | El tamaño del fotograma del vídeo en px (su proporción cuando no hay portada) y su duración en segundos. |
| `posterTime` | `number` | El segundo del archivo cuyo fotograma se usa como portada; se guarda para poder volver a elegirlo. |
| `start`, `end` | `number` | Reproduce desde el segundo `start` hasta el `end`. El código QR y el enlace del PDF también empiezan en `start`. |
| `player` | `VideoPlayerOptions` | Las opciones de reproductor de este vídeo, que se aplican sobre `videoStyle.player`. |

**La portada.** Se compone a la medida de su hueco (o a la fracción `placement.width` de ella), con su propia proporción y sea cual sea su tamaño en píxeles: un fotograma del tamaño de una pantalla se amplía en lugar de imprimirse pequeño. Como un mapa de bits, puede tener una [zona segura](https://postext.dev/es/docs/document-format-resources.md#zona-segura) y seguir `placement.align`. Un vídeo sin portada imprime un recuadro oscuro con la proporción del vídeo (16:9 si no se indica otra) y sus elementos superpuestos, y da el aviso de contenido `videoWithoutPoster`. En el Sandbox, la portada de un vídeo de YouTube o de Vimeo se descarga de la plataforma al escribir su dirección, y la de un archivo es un fotograma que eliges en el vídeo.

**La dirección.** El código QR y el enlace del PDF abren la página del vídeo, `https://youtu.be/<id>` o `https://vimeo.com/<id>`, a partir de `start`. Un archivo no tiene página: abren su dirección de producción, que es también desde donde se reproduce un vídeo sin archivo propio (un MP4 en un servidor, un flujo HLS). Si no la tiene, la versión impresa no lleva código QR ni enlace (`videoWithoutUrl`), y una salida HTML o EPUB que no incluye el archivo muestra la portada. Una dirección de YouTube o de Vimeo que no corresponde a ningún vídeo de esa plataforma da el aviso `videoUrlInvalid`, y se muestra la portada en lugar de un reproductor.

**Los reproductores.** Las opciones del reproductor (controles, botón de descarga, pantalla completa, menú de velocidad, imagen en imagen, envío a otra pantalla, reproducción automática, inicio sin sonido, repetición, precarga, inserción con privacidad mejorada) se fijan para todo el libro en `videoStyle.player` y para un solo vídeo en `video.player`; cada reproductor aplica las que puede (consulta [Configuración › Estilo de vídeo](https://postext.dev/es/docs/configuration-resources.md#estilo-de-vídeo)). El backend HTML recibe la URL reproducible de un archivo mediante la opción `resourceVideoUrl(fileId)`, igual que recibe las imágenes mediante `resourceImageUrl`, y si no la tiene recurre a la dirección de producción. Su opción `videos: { files, streams, hls }` elige entre reproductor y portada según el origen, por encima de `videoStyle.html` (`hls`, para un vídeo que se reproduce desde una dirección HLS, sigue a `files` si no se indica); el generador de EPUB la usa. Un `<video>` que reproduce una dirección HLS lleva `data-pt-hls`, para que la aplicación anfitriona pueda darle un reproductor en los navegadores sin HLS nativo (Safari y las versiones recientes de Chrome lo reproducen tal cual). En un libro de derecha a izquierda, el reproductor y los elementos superpuestos de la portada no se reflejan, igual que una imagen, para que el código QR se pueda leer.

**En el VDT.** El bloque de recurso de un vídeo tiene `kind: 'video'`, su portada como `fileId` / `format` (se dibuja como un mapa de bits) y `video` (`VDTResourceVideo`): el `link` al que se envía al lector, la `embedUrl` de YouTube o de Vimeo con las opciones del reproductor aplicadas, el `fileId` de un archivo, el `mimeType` de un vídeo propio (el de su archivo o, si solo tiene dirección, el de esta; `application/vnd.apple.mpegurl` para HLS), el intervalo `start` / `end`, el `player` resuelto, `linkPoster`, `html` y los elementos superpuestos `playMark` y `qr` (los módulos del QR como filas de `'0'` / `'1'`), con rectángulos relativos a la esquina superior izquierda de la imagen. Una aplicación anfitriona que dibuje los vídeos por su cuenta dispone de las funciones que exporta `postext`: `parseVideoUrl`, `videoWatchUrl`, `resourceVideoLink`, `videoEmbedUrl`, `videoEmbedAllow`, `videoElementAttributes`, `mediaFragment`, `videoMimeType`, `videoFormatOfUrl`, `resourceVideoFormat`, `isHlsMimeType`, `HLS_MIME_TYPE`, `youtubePosterUrls`, `encodeQr`, `layoutVideo`, `playMarkTriangle` y `qrModuleRuns`.

**En un paquete.** Un `.postext` incluye el archivo (`resources/<id>.mp4`) y la portada (`resources/<id>.poster.jpg`): la entrada del manifiesto los indica en `file` y `poster`, da el tamaño de la portada en `width` / `height` y guarda el resto en `video`, sin ids de archivo. `bundleVideoUrl(bundle)` es el resolutor de `resourceVideoUrl` para los archivos de un paquete. Un vídeo que se reproduce solo desde una dirección no lleva archivo: su entrada tiene únicamente la portada. En un paquete bilingüe, cada idioma puede dar a un vídeo su propio `poster` y su propio `video` (otro montaje, en su propia dirección) en `localized[…].resources`.

### Vídeos en las páginas de Folio

En el [libro en 3D](https://postext.dev/es/docs/configuration-html-folio-epub.md#un-libro-en-3d-postext-folio), un vídeo propio se reproduce en la página en la que está impreso. Un clic en la portada lo pone en marcha ahí mismo, haga lo que haga el puntero sobre el libro (pasar páginas, orbitar la vista o seleccionar texto): el shader de la página dibuja los fotogramas del vídeo sobre la portada, de modo que la imagen se dobla y se curva con el papel al pasar la hoja, y el vídeo sigue reproduciéndose mientras tanto. Un clic en un vídeo en marcha lo pausa, otro en un vídeo en pausa lo reanuda, y la barra espaciadora o Intro hacen lo mismo con el primer vídeo de la doble página abierta. Al poner en marcha otro vídeo se detiene el que estaba sonando (vuelve a su portada), y un vídeo se detiene cuando el libro se queda quieto en una doble página donde ya no aparece, o al llegar a su `end`. Sobre un vídeo que puede reproducir, el puntero toma forma de mano; un arrastre que empieza sobre él sigue pasando la página o girando la vista. Un vídeo que debe reproducirse solo (`video.player.autoplay`) arranca por sí mismo la primera vez que el libro se queda quieto en su doble página, cuando el libro ya se ha asentado (también si la aplicación anfitriona lo maqueta por etapas), y no vuelve a hacerlo en ese visor.

Un vídeo que se reproduce junto a otros (`video.player.exclusive: false`, desde postext 1.18) cambia las dos reglas. Al empezarlo solo se detienen los vídeos exclusivos, así que varios vídeos de este tipo pueden reproducirse a la vez; si se empieza un vídeo exclusivo, también este se detiene. Con `autoplay`, empieza sin sonido cada vez que el libro se detiene en su doble página, y se para cuando se pasa a otra: los bucles sin sonido (`loop`) de una página se reproducen juntos cada vez que el lector llega a ella.

- **Qué se reproduce.** Un archivo (la aplicación anfitriona convierte su `fileId` en una URL con la opción `videoUrl`; en el Sandbox es una URL de objeto) o, si no lo hay, su dirección: MP4, WebM o un flujo HLS. Un flujo HLS se reproduce con [hls.js](https://github.com/video-dev/hls.js) en todo navegador que tenga Media Source Extensions (se carga la primera vez que se reproduce un vídeo; es una dependencia opcional, de tipo *peer*, de `postext-folio`), limitado a la variante más cercana al tamaño que tiene la imagen en pantalla, de modo que una imagen de unos cientos de píxeles de alto nunca descarga una variante 4K; si no, se recurre al HLS propio del navegador. Sus peticiones llevan un parámetro `pt-cors` propio, para que la caché del navegador nunca les entregue una copia que otro reproductor descargó sin CORS. YouTube y Vimeo se reproducen en iframes, que WebGL no puede dibujar: un clic en su portada pasa la página, como en cualquier otro punto.
- **Lecturas entre orígenes.** WebGL solo dibuja un vídeo si su servidor permite leerlo (CORS, `Access-Control-Allow-Origin`). Un vídeo que no se puede leer se queda en su portada, y `onVideo` recibe `error`.
- **Sonido.** El clic permite que el vídeo se reproduzca con sonido; si el navegador aun así lo impide, se reproduce silenciado. Un vídeo que arranca solo tiene sonido si el lector ya ha hecho clic o ha escrito en la página (llegar a ella pasando páginas cuenta); si no, empieza silenciado, y un clic sobre él le da sonido antes de que el siguiente lo pause. `video.player.muted` lo hace empezar sin sonido, `loop` lo repite, y `start` / `end` delimitan la parte que se reproduce.
- **En cualquier página.** La imagen se dibuja donde la pone la maquetación: girada en un recurso girado, sin girar en una página vertical y sin reflejar en un libro de derecha a izquierda, igual que la portada. Si la portada se recorta dentro de su [zona segura](https://postext.dev/es/docs/document-format-resources.md#zona-segura), el vídeo se recorta del mismo modo.
- **Sin WebGL2**, o con la preferencia de movimiento reducido, el vídeo se reproduce en un `<video>` HTML colocado sobre la página.

```ts
const book = createFolioFromDocument(container, doc, {
  // La URL reproducible de un vídeo subido (una URL de objeto sobre sus bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();
```

`videos: false` lo desactiva. `toggleVideoAt({ page, x, y })` hace lo mismo que un clic en ese punto, y `pageVideoSpots(page, doc)` indica dónde está cada vídeo de una página, para una aplicación anfitriona que dibuje sus propios controles.

Dos recetas del Recetario incluyen vídeos: la n.º 131, [Programa de cineclub con códigos QR en las portadas](https://postext.dev/es/cookbook/film-club-video-qr.md), imprime cada película como una tarjeta de título con la marca de reproducción y un código QR, y la n.º 132, [Hoja de prácticas con vídeos que se ven en pantalla y EPUB](https://postext.dev/es/cookbook/pendulum-lab-video-players.md), fija las opciones del reproductor de la edición HTML y empaqueta sus propios vídeos en un EPUB de maquetación fija.

## Ejemplos en el Recetario

### Vídeos

- [N.º 131 Programa de cineclub con códigos QR en las portadas](https://postext.dev/es/cookbook/film-club-video-qr.md)
- [N.º 132 Hoja de prácticas con vídeos que se ven en pantalla y EPUB](https://postext.dev/es/cookbook/pendulum-lab-video-players.md)
- [N.º 136 Un periódico vivo con fotos que se mueven](https://postext.dev/es/cookbook/living-newspaper-video-loops.md)
