# Format del document: vídeos

> Els recursos de vídeo: YouTube, Vimeo, fitxers propis i fluxos HLS, què mostra cada sortida, els camps d'un vídeo, la portada i l'adreça, els reproductors, el VDT i els paquets, i els vídeos que es reprodueixen a les pàgines de Folio

- Versió HTML: https://postext.dev/ca/docs/document-format-videos
- Última actualització: 2026-11-11
- Temps de lectura: 10 min
- Altres idiomes: [en](https://postext.dev/en/docs/document-format-videos.md), [es](https://postext.dev/es/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 poques paraules

Aquesta pàgina explica els vídeos d'un llibre. Un vídeo pot venir de YouTube o de Vimeo, o ser un fitxer propi. Es cita en el text com una imatge i té una numeració pròpia, com les figures i les taules. En paper i en PDF mostra un fotograma amb una marca de reproducció i un codi QR que obre el vídeo. La versió web i els llibres electrònics el reprodueixen. Al llibre en 3D, un clic sobre el fotograma reprodueix el vídeo a la mateixa pàgina, i continua mentre passa el full.

Un vídeo és un recurs, com una imatge: es declara una vegada, es cita en el text i flota fins al primer espai lliure després de la referència. Les referències, la numeració, la col·locació i l'ajust del text s'expliquen a [Format del document: imatges i taules](https://postext.dev/ca/docs/document-format-resources.md); el que segueix és propi dels vídeos.

> [Vídeos als llibres: un codi QR en paper, un reproductor en pantalla i una pel·lícula a la pàgina](https://youtu.be/Ke9ldA2RYWg) · 4:11

## Vídeos

Un recurs de **vídeo** (`kind: 'video'`) és un vídeo de YouTube o de Vimeo, o un vídeo propi: un fitxer desat dins del llibre (MP4, WebM) o un vídeo en una adreça web, sigui un fitxer en un servidor o un **flux HLS** (una llista de reproducció `.m3u8`). Es col·loca, té peu, flota i es cita com una imatge, i es numera en una seqüència pròpia: el tipus integrat `video` imprimeix *Vídeo 1.1*, *Vídeo 1.2*… al costat de *Figura 1.1* i *Taula 1.1* (vegeu [Configuració › Tipus de recurs](https://postext.dev/ca/docs/configuration-resources.md#tipus-de-recurs)). Cada sortida el mostra com pot:

| Sortida | Què mostra |
| --- | --- |
| Canvas, PDF | La **portada**, un fotograma del vídeo, amb una marca de reproducció i un codi QR que obre el vídeo ([Configuració › Estil de vídeo](https://postext.dev/ca/docs/configuration-resources.md#estil-de-vídeo)). Al PDF la portada també és un enllaç al vídeo. |
| Folio | La portada, tal com s'imprimeix. Un clic a sobre reprodueix el vídeo **a la mateixa pàgina**, i el vídeo continua mentre el full passa (vegeu [Vídeos a les pàgines de Folio](https://postext.dev/ca/docs/document-format-videos.md#vídeos-a-les-pàgines-de-folio), més avall). Els vídeos de YouTube i de Vimeo només mostren la portada. |
| Visor HTML | El **reproductor** del vídeo: el de YouTube o el de Vimeo, o el reproductor HTML5 del navegador per a un fitxer o una adreça. Safari i les versions recents de Chrome reprodueixen un flux HLS per si mateixos; en els altres navegadors, l'aplicació amfitriona hi afegeix un reproductor com hls.js, com fa el Sandbox. Amb `videoStyle.html: 'poster'`, mostra en lloc del reproductor la portada impresa. |
| EPUB | Un fitxer es reprodueix al reproductor del mateix sistema de lectura, empaquetat dins del llibre o carregat des de la seva adreça de producció. Un vídeo de YouTube o de Vimeo es mostra com la seva portada, enllaçada amb el vídeo: un EPUB no pot inserir el reproductor d'una pàgina web. Un flux HLS també es mostra com la portada enllaçada: una llista HLS no és cap tipus de mitjà que un EPUB pugui reproduir. Si el sistema de lectura executa scripts, els fitxers d'una mateixa pàgina o capítol segueixen `player.exclusive`: quan en comença un, es posen en pausa els que no es poden reproduir alhora. |

```ts
const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: 'The keeper explains the lamp.',
  altText: 'A lighthouse keeper beside the lamp',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // es reprodueix des de 0:30; l'enllaç imprès també hi comença
  },
};
```

El text cita un vídeo com cita una figura: `:ref{id="keeper-talk"}` imprimeix *Vídeo 1.1* i fa flotar la portada al primer espai lliure després de la referència, i `::resource{id="keeper-talk"}` amb `placement.position: 'here'` la posa en línia. Els camps de `Resource.video` (`ResourceVideo`):

| Camp | Tipus | Significat |
| --- | --- | --- |
| `source` | `'youtube'` · `'vimeo'` · `'file'` | D'on es reprodueix el vídeo: una pàgina de YouTube o de Vimeo, o un vídeo propi (`'file'`), pujat o en una adreça. |
| `url` | `string` | YouTube o Vimeo: l'adreça del vídeo, en qualsevol forma (una pàgina de visualització, `youtu.be`, Shorts, un enllaç d'inserció, `youtube-nocookie.com`; una pàgina de Vimeo, una pàgina de canal o un enllaç ocult amb el seu hash). En un fitxer: la seva **adreça de producció**, on el trobarà el llibre publicat. Un vídeo propi sense fitxer es reprodueix des d'aquesta adreça: un MP4 o un WebM en un servidor, o un flux HLS (`…/master.m3u8`). |
| `fileId`, `format` | `string` | En un fitxer: el vídeo pujat, desat a part com un mapa de bits, i el seu format: `'mp4'`, `'webm'`, `'ogv'`, `'mov'` o `'hls'` per a un flux HLS. Sense format, es dedueix de l'extensió de l'adreça (`.m3u8` és `'hls'`) i, si no, és `'mp4'`. |
| `poster` | `{ fileId, format, width, height }` | El fotograma de portada, un mapa de bits. |
| `width`, `height`, `duration` | `number` | La mida del fotograma del vídeo en px (que dona la proporció quan no hi ha portada) i la durada en segons. |
| `posterTime` | `number` | El segon del fitxer amb el fotograma que fa de portada, desat perquè es pugui tornar a triar. |
| `start`, `end` | `number` | Reprodueix des del segon `start` fins al segon `end`. El codi QR i l'enllaç del PDF també comencen a `start`. |
| `player` | `VideoPlayerOptions` | Les opcions de reproductor d'aquest vídeo, aplicades per sobre de `videoStyle.player`. |

**La portada.** Es compon a l'amplada del seu espai (o a la fracció `placement.width` d'aquest espai), amb la seva proporció i sigui quina sigui la mida en píxels: un fotograma de la mida d'una pantalla s'amplia en lloc d'imprimir-se petit. Com un mapa de bits, pot tenir una [zona segura](https://postext.dev/ca/docs/document-format-resources.md#zona-segura) i seguir `placement.align`. Un vídeo sense portada imprimeix un requadre fosc amb la proporció del vídeo (16:9 si no se'n sap res) i les marques a sobre, i genera l'avís de contingut `videoWithoutPoster`. Al Sandbox, la portada d'un vídeo de YouTube o de Vimeo es baixa de la plataforma en introduir-ne l'adreça, i la d'un fitxer és un fotograma que tries dins del vídeo.

**L'adreça.** El codi QR i l'enllaç del PDF obren la pàgina del vídeo, `https://youtu.be/<id>` o `https://vimeo.com/<id>`, des de `start`. Un fitxer no té pàgina: obren la seva adreça de producció, que és també d'on es reprodueix un vídeo sense fitxer propi (un MP4 en un servidor, un flux HLS). Sense adreça, la versió impresa no porta codi QR ni enllaç (`videoWithoutUrl`), i una sortida HTML o EPUB que no inclogui el fitxer mostra la portada. Una adreça de YouTube o de Vimeo que no correspon a cap vídeo d'aquesta plataforma genera `videoUrlInvalid`, i es mostra la portada en lloc d'un reproductor.

**Els reproductors.** Les opcions de reproductor (controls, botó de baixada, pantalla completa, menú de velocitat, imatge en imatge, enviament a una altra pantalla, reproducció automàtica, començar sense so, repetició, precàrrega, insercions amb més privadesa) es fixen per a tot el llibre a `videoStyle.player` i per a un sol vídeo a `video.player`; cada reproductor respecta les que pot (vegeu [Configuració › Estil de vídeo](https://postext.dev/ca/docs/configuration-resources.md#estil-de-vídeo)). El backend HTML rep la URL reproduïble d'un fitxer amb l'opció `resourceVideoUrl(fileId)`, igual que rep les imatges amb `resourceImageUrl`, i, si no n'hi ha, fa servir l'adreça de producció. La seva opció `videos: { files, streams, hls }` tria entre reproductor i portada per a cada origen, per sobre de `videoStyle.html` (`hls`, un vídeo que es reprodueix des d'una adreça HLS, segueix `files` si no s'indica); l'escriptor EPUB la fa servir. Un `<video>` que reprodueix una adreça HLS porta `data-pt-hls`, perquè l'aplicació amfitriona hi pugui afegir un reproductor en els navegadors sense suport propi per a HLS (Safari i les versions recents de Chrome el reprodueixen directament). En un llibre de dreta a esquerra, el reproductor i les marques de la portada es tornen a invertir com una imatge, perquè el codi QR es pugui llegir.

**Al VDT.** El bloc de recurs d'un vídeo té `kind: 'video'`, la portada com a `fileId` / `format` (es dibuixa com un mapa de bits) i `video` (`VDTResourceVideo`): l'enllaç `link` al qual s'envia el lector, l'`embedUrl` de YouTube o de Vimeo amb les opcions de reproductor aplicades, el `fileId` d'un fitxer, el `mimeType` d'un vídeo propi (del seu fitxer o només de la seva adreça, `application/vnd.apple.mpegurl` per a HLS), l'interval `start` / `end`, el `player` resolt, `linkPoster`, `html`, i les marques `playMark` i `qr` (els mòduls del QR com a files de `'0'` / `'1'`), amb rectangles relatius a l'angle superior esquerre del cos. Una aplicació amfitriona que dibuixi els vídeos pel seu compte disposa de les funcions que exporta `postext`: `parseVideoUrl`, `videoWatchUrl`, `resourceVideoLink`, `videoEmbedUrl`, `videoEmbedAllow`, `videoElementAttributes`, `mediaFragment`, `videoMimeType`, `videoFormatOfUrl`, `resourceVideoFormat`, `isHlsMimeType`, `HLS_MIME_TYPE`, `youtubePosterUrls`, `encodeQr`, `layoutVideo`, `playMarkTriangle` i `qrModuleRuns`.

**En un paquet.** Un `.postext` conté el fitxer (`resources/<id>.mp4`) i la portada (`resources/<id>.poster.jpg`): l'entrada del manifest els indica a `file` i `poster`, dona la mida de la portada a `width` / `height` i desa la resta a `video`, sense identificadors de fitxer. `bundleVideoUrl(bundle)` és el resolutor `resourceVideoUrl` sobre els fitxers d'un paquet. Un vídeo que es reprodueix només des d'una adreça no porta cap fitxer: la seva entrada només té la portada. En un paquet bilingüe, una llengua pot donar a un vídeo la seva pròpia `poster` i el seu propi `video` (un altre muntatge, a la seva adreça) a `localized[…].resources`.

### Vídeos a les pàgines de Folio

Al [llibre en 3D](https://postext.dev/ca/docs/configuration-html-folio-epub.md#un-llibre-en-3d-postext-folio), un vídeo propi es reprodueix a la pàgina on està imprès. Un clic a la portada l'engega allà mateix, faci el que faci el punter sobre el llibre (passar pàgines, orbitar la vista o seleccionar text): el shader de la pàgina dibuixa els fotogrames del vídeo damunt de la portada, de manera que la imatge es doblega i es corba amb el paper mentre el full passa, i el vídeo no s'atura durant el gir. Un clic sobre un vídeo en marxa el posa en pausa, un clic sobre un vídeo en pausa el reprèn, i la barra d'espai o la tecla de retorn fan el mateix amb el primer vídeo de la doble pàgina oberta. Si s'engega un altre vídeo, el que s'estava reproduint s'atura (i torna a la portada), i un vídeo s'atura quan el llibre queda quiet en una doble pàgina on ja no apareix, o quan arriba al seu `end`. Damunt d'un vídeo que es pot reproduir, el punter es converteix en una mà; un arrossegament que comença sobre el vídeo continua passant la pàgina o girant la vista. Un vídeo que s'ha de reproduir sol (`video.player.autoplay`) s'engega la primera vegada que el llibre queda quiet a la seva doble pàgina, un cop el llibre s'ha estabilitzat (també si l'aplicació amfitriona el compon per etapes), i no es torna a engegar mai més en aquell visor.

Un vídeo que es pot reproduir alhora que d'altres (`video.player.exclusive: false`, des de postext 1.18) canvia les dues regles. Quan s'engega, només s'aturen els vídeos exclusius, de manera que se'n poden reproduir diversos alhora; si s'engega un vídeo exclusiu, també s'atura. Amb `autoplay`, comença sense so cada vegada que el llibre s'atura a la seva doble pàgina, i s'atura quan es passa a una altra: els bucles sense so (`loop`) d'una pàgina es reprodueixen junts cada vegada que el lector hi arriba.

- **Què es reprodueix.** Un fitxer (l'aplicació amfitriona converteix el seu `fileId` en una URL amb l'opció `videoUrl`; al Sandbox, una URL d'objecte) o, si no n'hi ha, la seva adreça: MP4, WebM o un flux HLS. Un flux HLS es reprodueix amb [hls.js](https://github.com/video-dev/hls.js) en qualsevol navegador que tingui Media Source Extensions (es carrega en la primera reproducció; és una dependència *peer* opcional de `postext-folio`), limitat a la variant més propera a la mida que té la imatge a la pantalla, de manera que una imatge de pocs centenars de píxels d'alçada no demana mai una variant 4K; sense Media Source Extensions, el reprodueix el suport HLS del mateix navegador. Les peticions porten un paràmetre `pt-cors` propi, perquè la memòria cau del navegador no doni mai una còpia que un altre reproductor hagi baixat sense CORS. YouTube i Vimeo es reprodueixen en iframes, que WebGL no pot dibuixar: un clic a la portada passa la pàgina com a qualsevol altre lloc.
- **Lectures des d'un altre origen.** WebGL només dibuixa un vídeo si el servidor en permet la lectura (CORS, `Access-Control-Allow-Origin`). Un vídeo que no es pot llegir es queda en portada, i `onVideo` rep `error`.
- **So.** El clic permet que el vídeo es reprodueixi amb so; si el navegador encara no ho permet, sona silenciat. Un vídeo que s'engega sol té so si el lector ja ha fet clic o ha escrit a la pàgina (haver-hi arribat passant pàgines també compta); si no, comença sense so, i un clic a sobre li activa el so abans que el clic següent el posi en pausa. `video.player.muted` l'engega sense so, `loop` el torna a reproduir, i `start` / `end` delimiten el fragment que es reprodueix.
- **A qualsevol pàgina.** La imatge es dibuixa on la col·loca la composició: girada en un recurs girat, dreta en una pàgina vertical i sense invertir en un llibre de dreta a esquerra, igual que la portada. Si la portada es retalla dins de la seva [zona segura](https://postext.dev/ca/docs/document-format-resources.md#zona-segura), el vídeo es retalla de la mateixa manera.
- **Sense WebGL2**, o amb menys moviment, el vídeo es reprodueix en un `<video>` HTML posat damunt de la pàgina.

```ts
const book = createFolioFromDocument(container, doc, {
  // La URL reproduïble d'un vídeo pujat (una URL d'objecte sobre els seus bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();
```

`videos: false` ho desactiva. `toggleVideoAt({ page, x, y })` fa el mateix que un clic en aquell punt, i `pageVideoSpots(page, doc)` llista on és cada vídeo d'una pàgina, per a una aplicació amfitriona que dibuixi els seus propis controls.

Dues receptes del Receptari inclouen vídeos: la núm. 131, [Programa de cineclub amb codis QR a les portades](https://postext.dev/ca/cookbook/film-club-video-qr.md), imprimeix cada pel·lícula com una targeta de títol amb la marca de reproducció i un codi QR, i la núm. 132, [Full de pràctiques amb vídeos per a la pantalla i l'EPUB](https://postext.dev/ca/cookbook/pendulum-lab-video-players.md), fixa les opcions de reproductor de l'edició HTML i empaqueta els seus propis vídeos en un EPUB de maquetació fixa.

## Exemples al Receptari

### Vídeos

- [Núm. 131 Programa de cineclub amb codis QR a les portades](https://postext.dev/ca/cookbook/film-club-video-qr.md)
- [Núm. 132 Full de pràctiques amb vídeos per a la pantalla i l'EPUB](https://postext.dev/ca/cookbook/pendulum-lab-video-players.md)
- [Núm. 136 Un diari viu amb fotos que es mouen](https://postext.dev/ca/cookbook/living-newspaper-video-loops.md)
