# Formato del documento: video

> Le risorse video: YouTube, Vimeo, file tuoi e stream HLS, che cosa mostra ogni uscita, i campi di un video, il poster e l’indirizzo, i player, il VDT e i bundle, e i video che si riproducono sulle pagine di Folio

- Versione HTML: https://postext.dev/it/docs/document-format-videos
- Ultimo aggiornamento: 2026-11-11
- Tempo di lettura: 9 min
- Altre lingue: [en](https://postext.dev/en/docs/document-format-videos.md), [es](https://postext.dev/es/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), [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)

## In breve

Questa pagina riguarda i video di un libro. Un video può venire da YouTube o da Vimeo, oppure essere un file tuo. Lo citi nel testo come un’immagine, e ha una numerazione propria, come le figure e le tabelle. Su carta e nel PDF mostra un fotogramma fermo con un segno di riproduzione e un codice QR che apre il video. La vista web e gli e-book lo riproducono. Nel libro 3D un clic sul fotogramma avvia il video sulla pagina stessa, e continua mentre la pagina gira.

Un video è una risorsa come un’immagine: si dichiara una volta, si cita nel testo e flotta fino al primo spazio libero dopo il rimando. Rimandi, numerazione, collocazione e testo intorno alle immagini sono spiegati in [Formato del documento: immagini e tabelle](https://postext.dev/it/docs/document-format-resources.md); quel che segue riguarda solo i video.

> [Video nei tuoi libri: codice QR su carta, lettore sullo schermo e film sulla pagina, con Postext](https://youtu.be/zPR_kTn9qoE) · 4:13

## Video

Una risorsa **video** (`kind: 'video'`) è un video di YouTube o Vimeo, oppure un video tuo: un file conservato nel libro (MP4, WebM) o uno a un indirizzo web, un file su un server o uno **stream HLS** (una playlist `.m3u8`). Viene collocato, dotato di didascalia, fatto flottare e citato come un’immagine, e numerato in una sequenza propria: il tipo integrato `video` stampa *Video 1.1*, *Video 1.2*… accanto a *Figura 1.1* e *Tabella 1.1* (vedi [Configurazione › Tipi di risorsa](https://postext.dev/it/docs/configuration-resources.md#tipi-di-risorsa)). Ogni output lo mostra come può:

| Output | Che cosa mostra |
| --- | --- |
| Canvas, PDF | Il **poster**, un fotogramma del video, con un simbolo di riproduzione e un codice QR che apre il video ([Configurazione › Stile dei video](https://postext.dev/it/docs/configuration-resources.md#stile-dei-video)). Nel PDF il poster è anche un link al video. |
| Folio | Il poster, come stampato. Un clic sul poster riproduce il video **sulla pagina stessa**, e la riproduzione continua mentre il foglio gira (vedi [Video sulle pagine di Folio](https://postext.dev/it/docs/document-format-videos.md#video-sulle-pagine-di-folio) più sotto). I video di YouTube e Vimeo restano poster. |
| Visualizzatore HTML | Il **player** del video: quello di YouTube o di Vimeo, oppure il player HTML5 del browser per un file o un indirizzo. Uno stream HLS viene riprodotto in modo nativo in Safari e nelle versioni recenti di Chrome; altrove l’applicazione ospite collega un player come hls.js, come fa la Sandbox. Con `videoStyle.html: 'poster'` mostra invece il poster stampato. |
| EPUB | Un file viene riprodotto nel player del sistema di lettura, incluso nel libro o letto dal suo indirizzo di produzione. Un video di YouTube o Vimeo è il suo poster, con un link al video: un EPUB non può incorporare il player di una pagina web. Anche uno stream HLS è il suo poster con link: una playlist HLS non è un tipo di media che un EPUB possa riprodurre. Dove il sistema di lettura esegue script, i file di una stessa pagina o di uno stesso capitolo rispettano `player.exclusive`: avviarne uno mette in pausa gli altri che non si riproducono insieme a esso. |

```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,                                // plays from 0:30; the printed link starts there too
  },
};
```

Il testo cita un video come cita una figura: `:ref{id="keeper-talk"}` stampa *Video 1.1* e fa flottare il poster nel primo spazio libero dopo il rimando, e `::resource{id="keeper-talk"}` con `placement.position: 'here'` lo compone in linea. I campi di `Resource.video` (`ResourceVideo`):

| Campo | Tipo | Significato |
| --- | --- | --- |
| `source` | `'youtube'` · `'vimeo'` · `'file'` | Da dove viene riprodotto il video: una pagina di YouTube o Vimeo, oppure un video tuo (`'file'`), caricato o a un indirizzo. |
| `url` | `string` | YouTube o Vimeo: l’indirizzo del video, in qualsiasi forma (una pagina di visione, `youtu.be`, Shorts, un link di incorporamento, `youtube-nocookie.com`; una pagina Vimeo, una pagina di canale o un link non in elenco con il suo hash). Un file: il suo **indirizzo di produzione**, dove il libro pubblicato lo troverà. Un video tuo senza un file proprio viene riprodotto da questo indirizzo: un MP4 o un WebM su un server, oppure uno stream HLS (`…/master.m3u8`). |
| `fileId`, `format` | `string` | Un file: il video caricato, conservato fuori banda come una bitmap, e il suo formato: `'mp4'`, `'webm'`, `'ogv'`, `'mov'`, oppure `'hls'` per uno stream HLS. Senza formato lo indica l’estensione dell’indirizzo (`.m3u8` è `'hls'`), altrimenti `'mp4'`. |
| `poster` | `{ fileId, format, width, height }` | Il fotogramma del poster, una bitmap. |
| `width`, `height`, `duration` | `number` | La dimensione del fotogramma del video in px (le sue proporzioni quando non c’è un poster) e la durata in secondi. |
| `posterTime` | `number` | Il secondo del fotogramma di un file usato come poster, conservato per poterlo scegliere di nuovo. |
| `start`, `end` | `number` | Riproduce da `start` a `end` secondi. Anche il codice QR e il link del PDF partono da `start`. |
| `player` | `VideoPlayerOptions` | Le opzioni del player di questo video, sovrapposte a `videoStyle.player`. |

**Il poster.** Viene composto alla giustezza del suo spazio (o alla frazione `placement.width` di essa), nelle sue proporzioni, qualunque sia la sua dimensione in pixel: un fotogramma a dimensione di schermo viene ingrandito invece di essere stampato piccolo. Come una bitmap, può avere una [zona sicura](https://postext.dev/it/docs/document-format-resources.md#zona-sicura) e seguire `placement.align`. Un video senza poster stampa un riquadro scuro nelle proporzioni del video (16:9 quando nulla le indica) con le sue sovrimpressioni, e genera l’avviso di contenuto `videoWithoutPoster`. Nella Sandbox il poster di un video di YouTube o Vimeo viene scaricato dalla piattaforma quando ne inserisci l’indirizzo, e quello di un file è un fotogramma che scegli nel video.

**L’indirizzo.** Il codice QR e il link del PDF aprono la pagina del video, `https://youtu.be/<id>` o `https://vimeo.com/<id>`, a partire da `start`. Un file non ha una pagina: aprono il suo indirizzo di produzione, che è anche l’indirizzo da cui viene riprodotto un video senza un file proprio (un MP4 su un server, uno stream HLS). Senza indirizzo, la stampa non ha codice QR né link (`videoWithoutUrl`), e un output HTML o EPUB che non contiene il file mostra il poster. Un indirizzo di YouTube o Vimeo che non indica nessun video di quella piattaforma genera `videoUrlInvalid`; al posto di un player viene mostrato il poster.

**I player.** Le opzioni del player (controlli, pulsante di download, schermo intero, menu della velocità, picture in picture, trasmissione, riproduzione automatica, avvio senza audio, ripetizione, precaricamento, incorporamenti con privacy avanzata) si impostano per l’intero libro in `videoStyle.player` e per un singolo video in `video.player`; ogni player rispetta ciò che può (vedi [Configurazione › Stile dei video](https://postext.dev/it/docs/configuration-resources.md#stile-dei-video)). Il backend HTML prende l’URL riproducibile di un file tramite l’opzione `resourceVideoUrl(fileId)`, come prende le immagini tramite `resourceImageUrl`, e in sua assenza ripiega sull’indirizzo di produzione. La sua opzione `videos: { files, streams, hls }` sceglie tra player e poster per ogni sorgente, prevalendo su `videoStyle.html` (`hls`, un video riprodotto da un indirizzo HLS, segue `files` se non è impostato); la usa il generatore di EPUB. Un `<video>` che riproduce un indirizzo HLS porta `data-pt-hls`, così un’applicazione ospite può dargli un player nei browser senza HLS nativo (Safari e le versioni recenti di Chrome lo riproducono così com’è). In un libro da destra a sinistra il player e le sovrimpressioni del poster vengono raddrizzati come un’immagine, così il codice QR resta leggibile.

**Nel VDT.** Il blocco di risorsa di un video ha `kind: 'video'`, il suo poster come `fileId` / `format` (disegnato come una bitmap) e `video` (`VDTResourceVideo`): il `link` a cui viene mandato chi legge, l’`embedUrl` di YouTube o Vimeo con le opzioni del player applicate, il `fileId` di un file, il `mimeType` di un video tuo (del suo file o del solo indirizzo, `application/vnd.apple.mpegurl` per HLS), l’intervallo `start` / `end`, il `player` risolto, `linkPoster`, `html` e le sovrimpressioni `playMark` e `qr` (i moduli del QR come righe di `'0'` / `'1'`), con rettangoli relativi all’angolo in alto a sinistra del corpo. Un’applicazione ospite che disegna da sé i video può usare le funzioni esportate da `postext`: `parseVideoUrl`, `videoWatchUrl`, `resourceVideoLink`, `videoEmbedUrl`, `videoEmbedAllow`, `videoElementAttributes`, `mediaFragment`, `videoMimeType`, `videoFormatOfUrl`, `resourceVideoFormat`, `isHlsMimeType`, `HLS_MIME_TYPE`, `youtubePosterUrls`, `encodeQr`, `layoutVideo`, `playMarkTriangle` e `qrModuleRuns`.

**In un pacchetto.** Un `.postext` contiene un file (`resources/<id>.mp4`) e il poster (`resources/<id>.poster.jpg`): la voce del manifest li indica in `file` e `poster`, dà la dimensione del poster in `width` / `height` e conserva il resto in `video` senza gli id dei file. `bundleVideoUrl(bundle)` è la funzione di risoluzione `resourceVideoUrl` sui file di un pacchetto. Un video riprodotto solo da un indirizzo non contiene file: la sua voce ha soltanto il poster. In un pacchetto bilingue una lingua può dare a un video il proprio `poster` e il proprio `video` (un altro montaggio, al suo indirizzo) in `localized[…].resources`.

### Video sulle pagine di Folio

Nel [libro 3D](https://postext.dev/it/docs/configuration-html-folio-epub.md#un-libro-in-3d-postext-folio) un video tuo si riproduce sulla pagina su cui è stampato. Un clic sul poster lo avvia lì, qualunque cosa faccia il puntatore sul libro (girare le pagine, ruotare la vista o selezionare il testo): lo shader della pagina disegna i fotogrammi del video sopra il poster, così l’immagine si piega e si incurva con la carta mentre il foglio gira, e la riproduzione continua durante la girata. Un clic su un video in riproduzione lo mette in pausa, un clic su uno in pausa lo riprende, e Spazio o Invio fanno lo stesso per il primo video della doppia pagina aperta. Avviare un altro video ferma quello in riproduzione (che torna al suo poster), e un video si ferma quando il libro si posa su una doppia pagina che non lo mostra più, oppure al suo `end`. Il puntatore diventa una mano sopra un video che può riprodurre; un trascinamento che parte da un video gira comunque la pagina o la vista. Un video impostato per partire da solo (`video.player.autoplay`) si avvia da sé la prima volta che il libro si posa sulla sua doppia pagina, una volta che il libro si è assestato (anche quando l’applicazione ospite lo impagina a passi), e mai più in quel visualizzatore.

Un video che si riproduce insieme agli altri (`video.player.exclusive: false`, da postext 1.18) cambia entrambe le regole. Avviarlo ferma solo i video esclusivi, quindi più video di questo tipo si riproducono insieme; avviare un video esclusivo ferma anche questi. Con `autoplay` parte, senza audio, ogni volta che il libro si posa sulla sua doppia pagina, e si ferma quando la doppia pagina viene girata: i loop muti (`loop`) di una pagina partono insieme ogni volta che chi legge ci arriva.

- **Che cosa si riproduce.** Un file (l’applicazione ospite trasforma il suo `fileId` in un URL con l’opzione `videoUrl`, un object URL nella Sandbox) oppure, in sua assenza, il suo indirizzo: MP4, WebM o uno stream HLS. Uno stream HLS si riproduce con [hls.js](https://github.com/video-dev/hls.js) ovunque il browser abbia le Media Source Extensions (caricato alla prima riproduzione; una dipendenza peer facoltativa di `postext-folio`), limitato alla variante più vicina alla dimensione dell’immagine sullo schermo, così un’immagine alta poche centinaia di pixel non scarica mai una variante 4K; in alternativa si usa l’HLS del browser. Le sue richieste portano una query `pt-cors` propria, così la cache del browser non restituisce mai loro una copia scaricata da un altro player senza CORS. YouTube e Vimeo si riproducono in iframe, che WebGL non può disegnare: un clic sul loro poster gira la pagina come in qualsiasi altro punto.
- **Letture da altre origini.** WebGL disegna un video solo quando il suo server consente la lettura (CORS, `Access-Control-Allow-Origin`). Un video che non si può leggere resta un poster, e `onVideo` riceve `error`.
- **Audio.** Il clic consente al video di partire con l’audio; se il browser lo rifiuta, il video parte comunque senza audio. Un video che parte da solo ha l’audio una volta che chi legge ha fatto clic o digitato sulla pagina (arrivarci girando le pagine conta); prima parte senza audio, e un clic su di esso attiva l’audio prima che il clic successivo lo metta in pausa. `video.player.muted` lo avvia senza audio, `loop` lo riproduce di nuovo, e `start` / `end` indicano la parte che viene riprodotta.
- **Su ogni pagina.** L’immagine viene disegnata dove la colloca l’impaginazione: ruotata con una risorsa ruotata, diritta su una pagina verticale e non specchiata in un libro da destra a sinistra, come il poster. Un poster ritagliato entro la sua [zona sicura](https://postext.dev/it/docs/document-format-resources.md#zona-sicura) ritaglia il video allo stesso modo.
- **Senza WebGL2**, o con il movimento ridotto, il video si riproduce in un `<video>` HTML sovrapposto alla pagina.

```ts
const book = createFolioFromDocument(container, doc, {
  // An uploaded video's playable URL (an object URL over its bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();
```

`videos: false` lo disattiva. `toggleVideoAt({ page, x, y })` fa ciò che fa un clic in quel punto, e `pageVideoSpots(page, doc)` elenca dove si trova ogni video su una pagina, per un’applicazione ospite che disegna i propri controlli.

Due ricette del Ricettario compongono video: la Nº 131, [Un programma di cineclub con codici QR sui poster](https://postext.dev/it/cookbook/film-club-video-qr.md), stampa ogni film come un cartello con il titolo, un simbolo di riproduzione e un codice QR, e la Nº 132, [Una scheda di laboratorio i cui filmati si riproducono sullo schermo e nell’EPUB](https://postext.dev/it/cookbook/pendulum-lab-video-players.md), imposta le opzioni del player per l’edizione HTML e include i propri filmati in un EPUB a layout fisso.

## Esempi nel Ricettario

### Video

- [Nº 131 Il programma di un cineclub con QR code sui poster](https://postext.dev/it/cookbook/film-club-video-qr.md)
- [Nº 132 Una scheda di laboratorio con video su schermo e in EPUB](https://postext.dev/it/cookbook/pendulum-lab-video-players.md)
- [Nº 136 Un giornale vivente con le immagini in movimento](https://postext.dev/it/cookbook/living-newspaper-video-loops.md)
