Em poucas palavras
Um roteiro de aula prática de física com dois vídeos curtos de um pêndulo. No papel, cada vídeo é uma imagem parada com um código para escanear; na tela e no livro digital, o vídeo roda na página.
O que você vai compor
O roteiro 4.2 de Bench Physics, uma apostila A4 para alunos de 16 a 18 anos, sobre o período de um pêndulo. Uma faixa cor de ferrugem traz o título e os campos para nome, turma e data. No pé da primeira página, dois vídeos do mesmo pêndulo, solto a partir de 10° e de 80°, ficam lado a lado. No papel, cada vídeo é o primeiro quadro, com um sinal de play e um QR code que abre o MP4. Na edição de tela ao lado das páginas, e no EPUB que o pen gera, os mesmos dois recursos rodam no próprio player de vídeo do leitor. A segunda página traz o procedimento, uma tabela para preencher, os períodos exatos calculados pelo código e quatro questões com caixas para as respostas.
Esta receita responde a
- Como a edição HTML e o EPUB reproduzem os vídeos do livro, e como oculto o botão de download?
- Como coloco um vídeo em um livro impresso para que o leitor possa abri-lo a partir da página?
A resposta curta
const clip = (id, file, poster, caption, altText) => ({
id, typeId: 'video', kind: 'video', createdAt: 0, updatedAt: 0, caption: t(caption),
note: t({ en: '8.00 s, 25 frames per second · Postext Cookbook, CC BY 4.0',
es: '8,00 s, 25 fotogramas por segundo · Postext Cookbook, CC BY 4.0' }),
altText: t(altText), placement: { position: 'bottom', span: 'column' },
video: { source: 'file', fileId: file, format: 'mp4', width: 640, height: 360, duration: 8,
url: asset(file), // the production address: printed as the QR code, linked from the PDF
poster: { fileId: poster, format: 'jpeg', width: 640, height: 360 }, // the first frame
},
});
const videoStyle = {
playMark: { shape: 'rounded', position: 'top-left', size: mm(7), inset: mm(3),
background: col('ink'), color: col('paper') },
qr: { position: 'bottom-right', size: mm(19), inset: mm(2.5), // 111 characters: 45 modules
color: col('ink'), background: col('paper'), radius: mm(1) },
// The HTML5 player of a file honours every option. download: false writes
// controlslist="nodownload": it hides the button, and the file stays at its address.
player: { download: false, loop: true, muted: true, preload: 'auto',
pictureInPicture: false, remotePlayback: false },
};
const clips = [
clip('small', 'pendulum-small.mp4', 'pendulum-small-poster.jpg',
{ en: 'Released from rest at 10°.', es: 'Soltado desde el reposo a 10°.' },
{ en: 'A rust bob on a dark string hangs a few degrees off the vertical, under a short bar.',
es: 'Una lenteja roja cuelga de un hilo oscuro a pocos grados de la vertical.' }),
clip('large', 'pendulum-large.mp4', 'pendulum-large-poster.jpg',
{ en: 'Released from rest at 80°.', es: 'Soltado desde el reposo a 80°.' },
{ en: 'The same pendulum pulled out almost level with its pivot, a pale arc below it.',
es: 'El mismo péndulo, casi a la altura de su eje, sobre un arco pálido.' }),
];
Ingredientes
- Funcionalidades
- Capas de vídeo: marca de reprodução e código QRVídeos como recursosExportação para EPUBEdição de leitura em HTMLUm projeto mais simples para a telaTabelas a partir de dadosEstilo de tabelaBoxesBoxes aninhadosEspaço vertical explícitoAberturas desenhadasAtributos de títuloTextos, fios e caixas nos designs de páginaCabeços e fóliosCabeços por tipo de páginaTipos de recurso personalizadosPaleta de cores semânticaFontes incorporadas ao PDF
- Também usa
- Citações que posicionam as figurasFiguras exatamente aquiFigura e Tabela no seu idiomaFaixa de capítulo em largura totalEstilos de parágrafoExportação para PDFFiguras e tabelas como recursosSobrescritos e subscritos
- Tipografia
- Source Serif 4, Red Hat Display, Red Hat Mono (SIL OFL 1.1)
- Materiais
pendulum-large-poster.jpgpendulum-large.mp4pendulum-small-poster.jpgpendulum-small.mp4- Video 1: a pendulum 1 m long released from 10°, 8 s at 25 frames per second, rendered from an RK4 solution of the pendulum equation (1 ms steps) with Python and encoded with ffmpeg (Postext Cookbook, CC BY 4.0)
- Video 2: the same pendulum released from 80°, rendered and encoded the same way (Postext Cookbook, CC BY 4.0)
- The first frame of Video 1, its printed poster (Postext Cookbook, CC BY 4.0)
- The first frame of Video 2, its printed poster (Postext Cookbook, CC BY 4.0)
Preparo
#1 · Dê a cada vídeo um endereço de produção e um arquivo
O código é a resposta curta logo acima. Um vídeo seu tem dois endereços. video.url é onde o livro publicado vai encontrá-lo: o QR code o imprime e o PDF liga o pôster do vídeo a ele, por isso aqui ele é o endereço do vídeo no jsDelivr, que um celular já consegue abrir hoje. video.fileId identifica o arquivo em si, guardado à parte como um bitmap, para as saídas que podem levá-lo junto ou reproduzi-lo de outro lugar (veja Formato do documento › Vídeos). As opções do player em videoStyle.player valem para todos os vídeos: rodam em loop, começam sem som, carregam inteiros (27 e 61 KB) e não oferecem download, picture-in-picture nem transmissão para outra tela, de modo que os vídeos ficam na folha.
#2 · Diagrame a edição de tela a partir do mesmo original
const [PANE_W, PANE_H] = [400, 640]; // px
const screen = {
page: { width: px(PANE_W), height: px(PANE_H), dpi: 122, // so the 9.4 pt text is 16 px
margins: { top: px(28), bottom: px(28), left: px(22), right: px(22), mirror: false } },
layout: { layoutType: 'single' }, bodyText: { textAlign: 'left' }, // ragged in a narrow pane
headings: { levels: [{ level: 1, span: 'column', breakBefore: { enabled: false },
fontSize: px(28), lineHeight: px(32), fontWeight: 800, marginBottom: px(16),
advancedDesign: { enabled: false } }] }, // the title alone: the band and fields are print's
header: { elements: [] }, footer: { elements: [] } };
A edição de tela fica na configuração, em htmlViewer.overrides, que o canvas e o PDF ignoram. A 122 dpi, cada medida dada em pontos sai cerca de um quarto maior do que a 96, por isso o texto de 9,4 pt aparece com 16 px no painel, e as legendas, os boxes e as tabelas crescem junto. A abertura mantém o título e deixa de lado a faixa e os campos, que são coisa do papel.
#3 · Reproduza os vídeos no painel
// A shadow root keeps the page's styles out, so the pane shows the lines as they were measured.
const pane = desk.querySelector('#screen').attachShadow({ mode: 'open' });
pane.innerHTML = renderToHtml(buildDocument({ markdown, resources },
applyHtmlViewerOverrides(config())), { mode: 'single', padding: 0, background: '#ffffff',
resourceImageUrl: imageUrl, // the posters, until a clip plays
resourceVideoUrl: (fileId) => asset(fileId) }); // the file each <video> plays: the asset here
const top = (el) => el.getBoundingClientRect().top; // open the pane on the first player
pane.host.scrollTop = top(pane.querySelector('video')) - top(pane.host) - 48;
renderToHtml compõe cada recurso de vídeo como um <video> do HTML5 com as opções do player como atributos: controls, muted, loop, playsinline, preload="auto", disablepictureinpicture, disableremoteplayback e controlslist="nodownload". Este último só esconde o botão. Quem tiver o endereço ainda consegue salvar o arquivo, de modo que trate isso como arrumação da interface, não como proteção. resourceVideoUrl entrega ao renderizador um endereço reproduzível para cada fileId, como resourceImageUrl faz com os pôsteres dos vídeos. Aqui ele é o arquivo publicado; um site que guarda os envios em outro lugar devolve a própria URL, ou uma URL de blob com os bytes. Sem ele, o player recorre a video.url, e sem nenhum dos dois o painel mostra o pôster.
#4 · Empacote os vídeos num EPUB de layout fixo
const bytesOf = async (url) => new Uint8Array(await (await fetch(url)).arrayBuffer());
const media = new Map(await Promise.all(clips.map(async ({ video }) =>
[video.fileId, { bytes: await bytesOf(asset(video.fileId)), mediaType: 'video/mp4' }])));
// Every face as bytes (gotcha: epub-embeds-given-fonts): the files loadFonts loaded, latin
// for each face and greek for the text face, limited to the Greek block and listed after
// latin, so a reading system tries it first for θ and π.
const faces = Object.entries(FONTS).flatMap(([family, specs]) => specs.map((spec) =>
({ family, weight: parseInt(spec, 10), style: spec.endsWith('i') ? 'italic' : 'normal' })));
const fonts = await Promise.all([...faces.map((face) => [face, 'latin']),
...faces.filter(({ family }) => family === TEXT)
.map((face) => [{ ...face, unicodeRange: 'U+0370-03FF' }, 'greek'])]
.map(async ([face, subset]) => ({ ...face, format: 'woff2', bytes: await bytesOf(
`https://cdn.jsdelivr.net/npm/@fontsource/${fontsourceId(face.family)}@5/files/`
+ `${fontsourceId(face.family)}-${subset}-${face.weight}-${face.style}.woff2`) })));
const epub = await renderToEpub([doc], { layout: 'fixed', fonts,
metadata: { title: doc.metadata.title, creators: ['Postext Cookbook'], language: LANG,
rights: 'CC BY 4.0', modified: new Date('2026-10-05T00:00:00Z') }, // the same bytes each run
// The clips as video/mp4 and the posters as pictures; the book packs both under media/.
resourceBytes: (fileId) => media.get(fileId)
?? { bytes: imageBytes(fileId), mediaType: 'image/jpeg' },
});
A folha é montada em torno de dois vídeos lado a lado e de caixas vazias para escrever, por isso o layout fixo a preserva: cada página como foi impressa, com um player onde estava o pôster do vídeo. Um EPUB refluível também reproduziria os vídeos, um embaixo do outro na largura do texto. resourceBytes responde video/mp4 para cada vídeo e um JPEG para cada pôster, e o gerador os guarda em media/ e images/. O EPUB mantém só os atributos que o esquema conhece (controls, autoplay, muted, loop, playsinline, preload), por isso o botão de download e o resto ficam por conta do sistema de leitura. O arquivo passa no EPUBCheck sem erros nem avisos.
#5 · Componha θ e π no canvas, no PDF e no EPUB
A Source Serif 4 guarda as letras gregas num arquivo próprio do Fontsource, greek, ao lado do latin. kitFonts(FONTS) encontra letras gregas no texto e carrega esse arquivo para cada fonte da família, e o fontsourceProvider o incorpora ao PDF junto com o arquivo latin em cada fonte que compõe θ ou π, de modo que essas duas letras não exigem código nenhum. O EPUB incorpora só as fontes que o pen lhe entrega, por isso o passo 4 lista os arquivos greek da fonte do texto depois dos latin, cada um limitado ao bloco grego pelo unicodeRange.
#6 · Calcule a tabela no código
// The arithmetic-geometric mean gives the elliptic integral K of the exact period in a few steps.
const T0 = 2 * Math.PI * Math.sqrt(1 / 9.81); // s: L = 1 m, g = 9.81 m/s²
const agm = (a, b) => (Math.abs(a - b) < 1e-15 ? a : agm((a + b) / 2, Math.sqrt(a * b)));
const period = (degrees) => T0 / agm(1, Math.cos((degrees * Math.PI) / 360));
const num = (x, digits) => x.toFixed(digits).replace('.', t({ en: '.', es: ',' }));
const cell = (content, align = 'right') => ({ content, align, verticalAlign: 'middle' });
const table = (id, caption, head, rows, columnWidths) => ({ id, typeId: 'table', kind: 'table',
createdAt: 0, updatedAt: 0, caption: t(caption), placement: { position: 'here' },
table: { model: { headerRowCount: 1, columnWidths, rows: [head.map((h, i) =>
({ ...cell(h, i ? 'right' : 'left'), isHeader: true })), ...rows] } } });
const periods = table('periods', { en: 'Exact periods of a pendulum 1.00 m long.',
es: 'Periodos exactos de un péndulo de 1,00 m.' },
['Amplitude|Amplitud', 'T (s)', 'T/T~0~', 'Longer by|Aumento'].map((h) =>
t({ en: h.split('|')[0], es: h.split('|').at(-1) })),
[5, 10, 20, 30, 45, 60, 80, 90].map((d) => [cell(`${d}°`, 'left'), cell(num(period(d), 3)),
cell(num(period(d) / T0, 3)), cell(`${num((period(d) / T0 - 1) * 100, 2)} %`)]),
[1.2, 1, 1, 1.1]);
const blank = cell(' \n '); // two empty lines: room to write
const data = table('data', { en: 'Your measurements.', es: 'Tus medidas.' },
t({ en: ['Clip', 'Swings in 8 s', 'T (s)'], es: ['Vídeo', 'Oscilaciones en 8 s', 'T (s)'] }),
[10, 80].map((d, i) => [cell(`${t({ en: 'Video', es: 'Vídeo' })} ${i + 1} · ${d}°`, 'left'),
blank, blank]), [1.2, 1.5, 0.8]);
O período exato exige a integral elíptica completa K, e a média aritmético-geométrica a fornece em poucos passos: T = T~0~ / AGM(1, cos ½θ~0~). A tabela imprime três casas decimais com a vírgula decimal do espanhol, e as linhas de 10° e 80° batem com os vídeos: 2,010 s e 2,282 s, 0,2 % e 13,8 % mais longos que T~0~ = 2,006 s. Em 8 s, isso dá pouco menos de quatro oscilações completas no primeiro vídeo e três e meia no segundo.
A receita completa
// ═══ Postext Cookbook · Nº 132 · A lab sheet whose clips play on screen and in the EPUB ════
// https://postext.dev/en/cookbook/pendulum-lab-video-players
// Code: MIT · Text: original (CC BY 4.0) · Clips: rendered in code (CC BY 4.0)
// Fonts: Source Serif 4, Red Hat Display, Red Hat Mono (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocument, buildDocumentWithFonts, prepareFonts, renderPageToCanvas, renderToHtml,
applyHtmlViewerOverrides, registerResourceImage, defaultResourceTypes, resourceVideoLink,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
import { renderToEpub, readEpub } from 'https://esm.sh/postext-epub';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'pendulum-lab-video-players';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { // the clips' own colours: a cream ground, the rust bob, warm black ink
ink: '#22201b', // text, the play mark, the QR modules, table heads
rust: '#a8432b', // the accent: the band, labels, list numbers (the bob's red, darker)
cream: '#f6f1e4', rule: '#cbc2ae', // box fills, a shade deeper than the clips; hairlines
muted: '#68625a', paper: '#ffffff' }; // muted: running heads, notes, prompts
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.rust }) // defaults: rust
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, MONO] = ['Source Serif 4', 'Red Hat Display', 'Red Hat Mono'];
const [TOP, INNER, OUTER, BAND, LEAD] = [22, 20, 17, 84, 13.2]; // mm, A4; LEAD in pt
const px = (value) => ({ value, unit: 'px' }); // the screen edition's sizes
const at = (to, edge, x, y, size) => ({ anchor: { to, edge }, offset: { x, y }, size });
const label = (size, color = 'rust') => ({ fontFamily: MONO, fontSize: pt(size), fontWeight: 600,
letterSpacing: pt(size * 0.16), textTransform: 'uppercase', color: col(color) });
// #region answer: two clips of the book's own: a poster and a QR code, or a player
const clip = (id, file, poster, caption, altText) => ({
id, typeId: 'video', kind: 'video', createdAt: 0, updatedAt: 0, caption: t(caption),
note: t({ en: '8.00 s, 25 frames per second · Postext Cookbook, CC BY 4.0',
es: '8,00 s, 25 fotogramas por segundo · Postext Cookbook, CC BY 4.0' }),
altText: t(altText), placement: { position: 'bottom', span: 'column' },
video: { source: 'file', fileId: file, format: 'mp4', width: 640, height: 360, duration: 8,
url: asset(file), // the production address: printed as the QR code, linked from the PDF
poster: { fileId: poster, format: 'jpeg', width: 640, height: 360 }, // the first frame
},
});
const videoStyle = {
playMark: { shape: 'rounded', position: 'top-left', size: mm(7), inset: mm(3),
background: col('ink'), color: col('paper') },
qr: { position: 'bottom-right', size: mm(19), inset: mm(2.5), // 111 characters: 45 modules
color: col('ink'), background: col('paper'), radius: mm(1) },
// The HTML5 player of a file honours every option. download: false writes
// controlslist="nodownload": it hides the button, and the file stays at its address.
O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)
Variações
#Faça um vídeo começar sozinho
O player de cada vídeo se sobrepõe a videoStyle.player. A reprodução automática sempre começa sem som, como os navegadores exigem.
];
+clips[0].video.player = { autoplay: true }; // the 10° clip starts as the pane opens#Mostre na tela a capa impressa
Com html: 'poster', a edição HTML compõe o pôster do vídeo com o sinal de play e o QR code, com link para o endereço de produção, no lugar do player.
const videoStyle = {
+ html: 'poster',#Use um vídeo do YouTube ou do Vimeo
source: 'youtube' com o endereço do vídeo incorpora o player do YouTube a partir de youtube-nocookie.com (privacy vem ativado por padrão). Esse player aceita menos opções: controles, tela cheia, reprodução automática, sem som e loop; o do Vimeo acrescenta o menu de velocidade e o picture-in-picture, e nenhum dos dois oferece download. Um EPUB não pode incorporar o player de uma página web, por isso lá o vídeo é o pôster com link para ele. As opções e o alcance de cada uma estão em Configuração › Estilo de vídeo.
Erros comuns
Erro comum
renderToEpub incorpora só as fontes que você passa
As fontes carregadas pelo navegador não são arquivos que o postext-epub consiga ler: passe em options.fonts os bytes de cada fonte que as páginas usam (os mesmos arquivos woff2 do Fontsource que a página carregou). Uma fonte que ficar de fora é informada como missingFont, e o sistema de leitura compõe esse texto com uma fonte própria, que em um layout fixo já não cabe nas linhas com que a página foi composta. Incorpore só fontes cuja licença permita. Exportação para EPUB →
Erro comum
Os arquivos do Fontsource cobrem letras, não símbolos
O kit incorpora o arquivo latin do Fontsource de cada fonte e, quando o texto usa esses caracteres, o arquivo latin-ext para č, ł, † e o arquivo greek para α, χ (em uma família que o tenha: Lora e Gelasio não têm), na tela e no PDF. Símbolos como →, ≈, ✓ e ★ não estão em nenhum desses arquivos e somem no PDF: desenhe-os, componha-os como matemática ou escolha uma fonte cujos arquivos os tenham. Fontes incorporadas ao PDF →
Os MP4 estão em H.264. Chrome, Edge, Safari e Firefox os reproduzem, assim como o Chrome for Testing que a captura usa. Um Chromium compilado sem os codecs proprietários, o padrão do projeto de código aberto, não reproduz; codifique os vídeos em WebM (format: 'webm') se isso importar para seus leitores.
Créditos
- Receita
- Ignacio Ferro
- Texto
- Texto original, CC BY 4.0
- Imagens
- Video 1: a pendulum 1 m long released from 10°, 8 s at 25 frames per second, rendered from an RK4 solution of the pendulum equation (1 ms steps) with Python and encoded with ffmpeg · Postext Cookbook · CC BY 4.0
- Video 2: the same pendulum released from 80°, rendered and encoded the same way · Postext Cookbook · CC BY 4.0
- The first frame of Video 1, its printed poster · Postext Cookbook · CC BY 4.0
- The first frame of Video 2, its printed poster · Postext Cookbook · CC BY 4.0
- Fontes
- Source Serif 4 (SIL OFL 1.1) · Red Hat Display (SIL OFL 1.1) · Red Hat Mono (SIL OFL 1.1)
- Código
- MIT, como o Postext
Editar este texto ↗ (abre em uma nova aba)Pasta da receita no GitHub ↗ (abre em uma nova aba)


