# Formato do documento: vídeos

> Os recursos de vídeo: YouTube, Vimeo, arquivos seus e streams HLS, o que cada saída mostra, os campos de um vídeo, o pôster e o endereço, os players, o VDT e os pacotes, e os vídeos que tocam nas páginas do Folio

- Versão HTML: https://postext.dev/pt/docs/document-format-videos
- Última atualização: 2026-11-11
- Tempo de leitura: 9 min
- Outros idiomas: [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), [it](https://postext.dev/it/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)

## Em poucas palavras

Esta página trata dos vídeos de um livro. Um vídeo pode vir do YouTube ou do Vimeo, ou ser um arquivo seu. Você o cita no texto como uma imagem, e ele tem numeração própria, como as figuras e as tabelas. No papel e no PDF ele mostra um quadro parado com uma marca de reprodução e um código QR que abre o vídeo. A visualização web e os livros digitais o reproduzem. No livro 3D, um clique no quadro toca o vídeo na própria página, e ele continua tocando enquanto a folha vira.

Um vídeo é um recurso, como uma imagem: é declarado uma vez, citado no texto e flutuado até o primeiro espaço livre depois da referência. Referências, numeração, posicionamento e contorno de texto são explicados em [Formato do documento: imagens e tabelas](https://postext.dev/pt/docs/document-format-resources.md); o que vem a seguir é próprio dos vídeos.

> [Vídeos nos seus livros: um código QR no papel, um player na tela e um filme na página, com o Postext](https://youtu.be/0hU88AWEKmk) · 4:11

## Vídeos

Um recurso de **vídeo** (`kind: 'video'`) é um vídeo do YouTube ou do Vimeo, ou um vídeo seu: um arquivo guardado no livro (MP4, WebM) ou um que está num endereço da web, seja um arquivo num servidor ou um **stream HLS** (uma playlist `.m3u8`). Ele é posicionado, legendado, flutuado e citado como uma imagem, e numerado numa sequência própria: o tipo integrado `video` imprime *Vídeo 1.1*, *Vídeo 1.2*… ao lado de *Figura 1.1* e *Tabela 1.1* (veja [Configuração › Tipos de recurso](https://postext.dev/pt/docs/configuration-resources.md#tipos-de-recurso)). Cada saída o mostra como pode:

| Saída | O que mostra |
| --- | --- |
| Canvas, PDF | O **pôster**, um quadro do vídeo, com uma marca de reprodução e um código QR que abre o vídeo ([Configuração › Estilo de vídeo](https://postext.dev/pt/docs/configuration-resources.md#estilo-de-vídeo)). No PDF, o pôster também é um link para o vídeo. |
| Folio | O pôster, tal como impresso. Um clique nele reproduz o vídeo **na própria página**, e ele continua tocando enquanto a folha vira (veja [Vídeos nas páginas do Folio](https://postext.dev/pt/docs/document-format-videos.md#vídeos-nas-páginas-do-folio) mais abaixo). Os vídeos do YouTube e do Vimeo continuam sendo pôsteres. |
| Visualizador HTML | O **player** do vídeo: o do YouTube ou do Vimeo, ou o player HTML5 do navegador para um arquivo ou um endereço. Um stream HLS toca nativamente no Safari e nas versões recentes do Chrome; nos demais, o aplicativo hospedeiro anexa um player como o hls.js, como faz o Sandbox. Com `videoStyle.html: 'poster'`, mostra o pôster impresso no lugar do player. |
| EPUB | Um arquivo toca no player do próprio sistema de leitura, empacotado no livro ou lido do endereço de produção. Um vídeo do YouTube ou do Vimeo vira o pôster dele, com link para o vídeo: um EPUB não pode incorporar o player de uma página da web. Um stream HLS também vira o pôster com link: uma playlist HLS não é um tipo de mídia que um EPUB possa reproduzir. Onde o sistema de leitura executa scripts, os arquivos de uma mesma página ou capítulo respeitam `player.exclusive`: iniciar um pausa os outros com os quais ele não toca junto. |

```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,                                // toca a partir de 0:30; o link impresso também começa aí
  },
};
```

O texto cita um vídeo como cita uma figura: `:ref{id="keeper-talk"}` imprime *Vídeo 1.1* e faz o pôster flutuar para o primeiro espaço livre depois da referência, e `::resource{id="keeper-talk"}` com `placement.position: 'here'` o coloca no fluxo do texto. Os campos de `Resource.video` (`ResourceVideo`):

| Campo | Tipo | Significado |
| --- | --- | --- |
| `source` | `'youtube'` · `'vimeo'` · `'file'` | De onde o vídeo é reproduzido: uma página do YouTube ou do Vimeo, ou um vídeo seu (`'file'`), enviado ou num endereço. |
| `url` | `string` | YouTube ou Vimeo: o endereço do vídeo, em qualquer forma (uma página de exibição, `youtu.be`, Shorts, um link de incorporação, `youtube-nocookie.com`; uma página do Vimeo, uma página de canal ou um link não listado com o hash). Um arquivo: o **endereço de produção**, onde o livro publicado vai encontrá-lo. Um vídeo seu sem arquivo próprio toca a partir desse endereço: um MP4 ou WebM num servidor, ou um stream HLS (`…/master.m3u8`). |
| `fileId`, `format` | `string` | Um arquivo: o vídeo enviado, guardado à parte como um bitmap, e o formato: `'mp4'`, `'webm'`, `'ogv'`, `'mov'`, ou `'hls'` para um stream HLS. Sem formato, a extensão do endereço o indica (`.m3u8` é `'hls'`); se não, `'mp4'`. |
| `poster` | `{ fileId, format, width, height }` | O quadro do pôster, um bitmap. |
| `width`, `height`, `duration` | `number` | O tamanho do quadro do vídeo em px (a proporção dele quando não há pôster) e a duração em segundos. |
| `posterTime` | `number` | O segundo do arquivo cujo quadro serve de pôster, guardado para poder ser escolhido de novo. |
| `start`, `end` | `number` | Reproduz de `start` a `end` segundos. O código QR e o link do PDF também começam em `start`. |
| `player` | `VideoPlayerOptions` | As opções de player deste vídeo, aplicadas por cima de `videoStyle.player`. |

**O pôster.** Ele é composto na medida do espaço (ou na fração `placement.width` dela), na proporção própria, seja qual for o tamanho dele em pixels: um quadro do tamanho de uma tela é ampliado em vez de sair impresso pequeno. Como um bitmap, pode ter uma [área segura](https://postext.dev/pt/docs/document-format-resources.md#área-segura) e seguir `placement.align`. Um vídeo sem pôster imprime uma caixa escura na proporção do vídeo (16:9 quando nada a indica) com as sobreposições e gera um aviso de conteúdo `videoWithoutPoster`. No Sandbox, o pôster de um vídeo do YouTube ou do Vimeo é buscado na plataforma quando o endereço é digitado, e o de um arquivo é um quadro que você escolhe no vídeo.

**O endereço.** O código QR e o link do PDF abrem a página do vídeo, `https://youtu.be/<id>` ou `https://vimeo.com/<id>`, a partir de `start`. Um arquivo não tem página: eles abrem o endereço de produção dele, que é também de onde toca um vídeo sem arquivo próprio (um MP4 num servidor, um stream HLS). Sem endereço, a impressão fica sem código QR e sem link (`videoWithoutUrl`), e uma saída HTML ou EPUB que não carrega o arquivo mostra o pôster. Um endereço do YouTube ou do Vimeo que não aponta para nenhum vídeo da plataforma gera `videoUrlInvalid`; o pôster aparece no lugar de um player.

**Os players.** As opções de player (controles, botão de download, tela cheia, menu de velocidade, picture-in-picture, transmissão para outra tela, reprodução automática, início sem som, repetição, pré-carregamento, incorporações com privacidade reforçada) são definidas para o livro inteiro em `videoStyle.player` e para um vídeo em `video.player`; cada player respeita o que consegue (veja [Configuração › Estilo de vídeo](https://postext.dev/pt/docs/configuration-resources.md#estilo-de-vídeo)). O renderizador HTML recebe a URL reproduzível de um arquivo pela opção `resourceVideoUrl(fileId)`, assim como recebe as imagens por `resourceImageUrl`, e na falta dela usa o endereço de produção. A opção `videos: { files, streams, hls }` dele escolhe entre player e pôster por origem, por cima de `videoStyle.html` (`hls`, um vídeo reproduzido a partir de um endereço HLS, segue `files` se não for definido); o gerador de EPUB a utiliza. Um `<video>` que reproduz um endereço HLS leva `data-pt-hls`, para que um aplicativo hospedeiro possa lhe dar um player nos navegadores sem HLS nativo (o Safari e as versões recentes do Chrome o reproduzem como está). Num livro da direita para a esquerda, o player e as sobreposições do pôster são desespelhados como uma imagem, para que o código QR possa ser lido.

**No VDT.** O bloco de recurso de um vídeo tem `kind: 'video'`, o pôster como `fileId` / `format` (desenhado como um bitmap) e `video` (`VDTResourceVideo`): o `link` para onde o leitor é levado, o `embedUrl` do YouTube ou do Vimeo com as opções de player aplicadas, o `fileId` de um arquivo, o `mimeType` de um vídeo seu (do arquivo ou apenas do endereço, `application/vnd.apple.mpegurl` para HLS), o intervalo `start` / `end`, o `player` resolvido, `linkPoster`, `html` e as sobreposições `playMark` e `qr` (os módulos do QR como linhas de `'0'` / `'1'`), com retângulos relativos ao canto superior esquerdo do corpo. Um aplicativo hospedeiro que desenhe os vídeos por conta própria pode usar os auxiliares que o `postext` exporta: `parseVideoUrl`, `videoWatchUrl`, `resourceVideoLink`, `videoEmbedUrl`, `videoEmbedAllow`, `videoElementAttributes`, `mediaFragment`, `videoMimeType`, `videoFormatOfUrl`, `resourceVideoFormat`, `isHlsMimeType`, `HLS_MIME_TYPE`, `youtubePosterUrls`, `encodeQr`, `layoutVideo`, `playMarkTriangle` e `qrModuleRuns`.

**Num pacote.** Um `.postext` carrega o arquivo (`resources/<id>.mp4`) e o pôster (`resources/<id>.poster.jpg`): a entrada do manifesto os indica em `file` e `poster`, informa o tamanho do pôster em `width` / `height` e guarda o resto em `video`, sem os ids de arquivo. `bundleVideoUrl(bundle)` é o resolvedor `resourceVideoUrl` sobre os arquivos de um pacote. Um vídeo reproduzido apenas a partir de um endereço não carrega arquivo: a entrada dele tem só o pôster. Num pacote bilíngue, um idioma pode dar a um vídeo `poster` e `video` próprios (outra edição, no próprio endereço) em `localized[…].resources`.

### Vídeos nas páginas do Folio

No [livro 3D](https://postext.dev/pt/docs/configuration-html-folio-epub.md#um-livro-em-3d-postext-folio), um vídeo seu toca na página em que está impresso. Um clique no pôster o inicia ali, seja qual for a função do ponteiro no livro (virar páginas, girar a vista ou selecionar texto): o shader da página desenha os quadros do vídeo sobre o pôster, de modo que a imagem se dobra e se curva com o papel enquanto a folha vira, e continua tocando durante a virada. Um clique num vídeo em reprodução o pausa, um clique num vídeo pausado o retoma, e Espaço ou Enter fazem o mesmo com o primeiro vídeo da página dupla aberta. Iniciar outro vídeo interrompe o que está tocando (ele volta ao pôster), e um vídeo para quando o livro se acomoda numa página dupla que já não o mostra, ou ao chegar ao `end`. O ponteiro vira uma mão sobre um vídeo que pode ser reproduzido; um arrasto que começa sobre ele continua virando a página ou a vista. Um vídeo configurado para tocar sozinho (`video.player.autoplay`) começa por conta própria na primeira vez que o livro se acomoda na página dupla dele, depois que o livro se estabiliza (inclusive quando um aplicativo hospedeiro o diagrama em etapas), e nunca mais nesse visualizador.

Um vídeo que toca junto com os outros (`video.player.exclusive: false`, desde o postext 1.18) muda as duas regras. Iniciá-lo interrompe apenas os vídeos exclusivos, de modo que vários vídeos desse tipo tocam ao mesmo tempo; iniciar um vídeo exclusivo também o interrompe. Com `autoplay`, ele começa sem som cada vez que o livro se acomoda na página dupla dele e para quando a página dupla é virada: os loops silenciosos (`loop`) de uma página rodam juntos toda vez que o leitor chega a ela.

- **O que toca.** Um arquivo (o aplicativo hospedeiro converte o `fileId` numa URL com a opção `videoUrl`; no Sandbox, uma URL de objeto) ou, na falta dele, o endereço: MP4, WebM ou um stream HLS. Um stream HLS toca pelo [hls.js](https://github.com/video-dev/hls.js) onde o navegador tiver Media Source Extensions (carregado na primeira reprodução; uma peer dependency opcional do `postext-folio`), limitado à variante mais próxima do tamanho da imagem na tela, para que uma imagem de algumas centenas de pixels de altura nunca puxe uma variante 4K; o HLS do próprio navegador é a alternativa. As requisições dele levam uma query `pt-cors` própria, para que o cache do navegador nunca lhes entregue uma cópia que outro player buscou sem CORS. O YouTube e o Vimeo tocam em iframes, que o WebGL não consegue desenhar: um clique no pôster deles vira a página como em qualquer outro ponto.
- **Leituras entre origens.** O WebGL só desenha um vídeo quando o servidor permite a leitura (CORS, `Access-Control-Allow-Origin`). Um vídeo que não pode ser lido continua sendo um pôster, e `onVideo` recebe `error`.
- **Som.** O clique permite que o vídeo toque com som; um navegador que ainda assim recuse o recebe sem som. Um vídeo que começa sozinho tem som depois que o leitor clicou ou digitou na página (virar até ela conta); antes disso, começa sem som, e um clique nele ativa o som antes que o clique seguinte o pause. `video.player.muted` o inicia sem som, `loop` o reproduz de novo, e `start` / `end` delimitam o trecho que toca.
- **Em qualquer página.** A imagem é desenhada onde o layout a coloca: girada com um recurso girado, em pé numa página vertical e sem espelhamento num livro da direita para a esquerda, como o pôster. Um pôster recortado dentro da [área segura](https://postext.dev/pt/docs/document-format-resources.md#área-segura) recorta o vídeo da mesma forma.
- **Sem WebGL2**, ou com movimento reduzido, o vídeo toca num `<video>` HTML sobreposto à página.

```ts
const book = createFolioFromDocument(container, doc, {
  // A URL reproduzível de um vídeo enviado (uma URL de objeto sobre os seus bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();
```

`videos: false` desativa isso. `toggleVideoAt({ page, x, y })` faz o que um clique naquele ponto faria, e `pageVideoSpots(page, doc)` lista onde fica cada vídeo numa página, para um aplicativo hospedeiro que desenhe os próprios controles.

Duas receitas das Receitas compõem vídeos: a Nº 131, [Um programa de cineclube com códigos QR nos pôsteres](https://postext.dev/pt/cookbook/film-club-video-qr.md), imprime cada filme como um cartão de título com uma marca de reprodução e um código QR, e a Nº 132, [Uma ficha de laboratório cujos clipes tocam na tela e no EPUB](https://postext.dev/pt/cookbook/pendulum-lab-video-players.md), define as opções de player da edição HTML e empacota os próprios clipes num EPUB de layout fixo.

## Exemplos nas Receitas

### Vídeos

- [Nº 131 Programa de cineclube com QR codes nos pôsteres](https://postext.dev/pt/cookbook/film-club-video-qr.md)
- [Nº 132 Roteiro de laboratório com vídeos na tela e no EPUB](https://postext.dev/pt/cookbook/pendulum-lab-video-players.md)
- [Nº 136 Um jornal vivo com fotos que se mexem](https://postext.dev/pt/cookbook/living-newspaper-video-loops.md)
