Capítol 5.5 · Part II · L'ofici
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
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; el que segueix és propi dels vídeos.
#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). 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). 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, 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., 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. |
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 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). 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, 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
fileIden 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 en qualsevol navegador que tingui Media Source Extensions (es carrega en la primera reproducció; és una dependència peer opcional depostext-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àmetrept-corspropi, 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, ionVideoreperror. - 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.mutedl'engega sense so,loopel torna a reproduir, istart/enddelimiten 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, 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.
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, 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, 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
Receptes que fan servir el que explica aquesta pàgina, cadascuna sota la secció a què respon millor. Cada recepta mostra les seves pàgines al costat de l’script complet.



