Pular para o conteúdo principal

Capítulo 5.5 · Parte II · O ofício

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

Atualizado 2026-11-119 minNo capítulo 5 Formato do documentoenescadefritptzhjaar

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; 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 PostextAssistir no YouTube (abre em uma nova aba) · O player é carregado do YouTube quando você aperta o play.

#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). Cada saída o mostra como pode:

SaídaO que mostra
Canvas, PDFO 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). No PDF, o pôster também é um link para o vídeo.
FolioO 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 mais abaixo). Os vídeos do YouTube e do Vimeo continuam sendo pôsteres.
Visualizador HTMLO 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.
EPUBUm 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.
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):

CampoTipoSignificado
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.
urlstringYouTube 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, formatstringUm 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, durationnumberO tamanho do quadro do vídeo em px (a proporção dele quando não há pôster) e a duração em segundos.
posterTimenumberO segundo do arquivo cujo quadro serve de pôster, guardado para poder ser escolhido de novo.
start, endnumberReproduz de start a end segundos. O código QR e o link do PDF também começam em start.
playerVideoPlayerOptionsAs 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 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). 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, 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 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 recorta o vídeo da mesma forma.
  • Sem WebGL2, ou com movimento reduzido, o vídeo toca num <video> HTML sobreposto à página.
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, 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, define as opções de player da edição HTML e empacota os próprios clipes num EPUB de layout fixo.

#Exemplos nas Receitas

Receitas que usam o que esta página explica, cada uma sob a seção que mais lhe corresponde. Cada receita mostra as páginas ao lado do script completo.