跳到主要内容

章 5.5 · 篇 II · 工艺

文档格式:视频

视频资源:YouTube、Vimeo、你自己的文件和HLS流,各种输出显示什么,视频的字段、封面与网址,播放器,VDT与资源包,以及在Folio页面上播放的视频

更新于 2026-11-116分钟所属章节: 5 文档格式enescadefritptzhjaar

简单来说

本页讲书中的视频。视频可以来自YouTube或Vimeo,也可以是你自己的文件。你在正文里像引用图片一样引用它,它和图、表一样有自己的编号。在纸上和PDF里,它显示为一帧画面,带一个播放标记和一个能打开视频的二维码。网页视图和电子书会播放它。在3D书本里,点一下画面,视频就在这一页上播放,翻页时也不会停。

视频和图片一样是资源:声明一次,在正文中引用,并浮动到引用之后第一个空位。引用、编号、位置和文字绕排的规则见文档格式:图片与表格;下面只讲视频特有的内容。

书中的视频:用 Postext 在纸上印二维码,在屏幕上放播放器,在页面上播放影片在 YouTube 上观看 (在新标签页中打开) · 按下播放后才会从 YouTube 加载播放器。

#视频

视频资源(kind: 'video')是一段YouTube或Vimeo视频,或者你自己的视频:保存在书中的文件(MP4、WebM),或者位于某个网址的视频,即服务器上的文件或HLS流(.m3u8播放列表)。它像图片一样放置、加题注、浮动和引用,并单独编号:内置的video类型印出Video 1.1、Video 1.2……,与Figure 1.1和Table 1.1并列(中文文档中为视频1-1,见配置 › 资源类型)。各种输出按各自的能力显示它:

输出显示的内容
Canvas、PDF封面,即视频中的一帧,上面有播放标记和一个打开视频的二维码(配置 › 视频样式)。在PDF中,封面同时是指向视频的链接。
Folio封面,与印刷版相同。点击封面,视频就在页面上播放,翻动这一叶时也不停(见下文Folio视图中的视频)。YouTube和Vimeo视频仍只显示封面。
HTML阅读器视频的播放器:YouTube或Vimeo的播放器,文件或网址则用浏览器的HTML5播放器。HLS流在Safari和较新的Chrome中可以直接播放;在其他浏览器中,由宿主接上hls.js之类的播放器,沙盒就是这样做的。设置videoStyle.html: 'poster'时改为显示印刷封面。
EPUB文件在阅读系统自己的播放器中播放,文件打包在书中,或从正式发布地址读取。YouTube或Vimeo视频显示为封面,链接到视频:EPUB不能嵌入网页的播放器。HLS流同样显示为带链接的封面:HLS播放列表不属于EPUB可以播放的媒体类型。如果阅读系统运行脚本,同一页面或章节中的文件遵守player.exclusive:开始播放一段,会暂停不与它同时播放的其他视频。
const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: '看守人讲解灯具。',
  altText: '灯塔看守人站在灯旁',
  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,                                // 从0:30开始播放;印出的链接也从这里开始
  },
};

正文引用视频的方式与引用图相同::ref{id="keeper-talk"}印出Video 1.1,并把封面浮动到该引用之后的第一个空位;::resource{id="keeper-talk"}配合placement.position: 'here'则把它行内嵌入。Resource.video(ResourceVideo)的字段:

字段类型含义
source'youtube' · 'vimeo' · 'file'视频从哪里播放:YouTube或Vimeo的页面,或者你自己的视频('file'),上传的文件或某个网址均可。
urlstringYouTube或Vimeo:视频的地址,任何形式均可(观看页、youtu.be、Shorts、嵌入链接、youtube-nocookie.com;Vimeo的视频页、频道页,或带哈希的不公开链接)。文件:它的正式发布地址,即出版后的书找到它的位置。自己的视频如果没有上传文件,就从这个地址播放:服务器上的MP4或WebM,或者HLS流(…/master.m3u8)。
fileId、formatstring文件:上传的视频,像位图一样在带外存储,以及它的格式:'mp4'、'webm'、'ogv'、'mov',HLS流则为'hls'。不写格式时由地址的扩展名判断(.m3u8即'hls'),否则为'mp4'。
poster{ fileId, format, width, height }封面帧,一张位图。
width、height、durationnumber视频画面的px尺寸(没有封面时用它的宽高比)和以秒计的时长。
posterTimenumber文件中用作封面的那一帧所在的秒数,保留下来以便重新选取。
start、endnumber从第start秒播放到第end秒。二维码和PDF链接也从start开始。
playerVideoPlayerOptions这个视频的播放器选项,覆盖在videoStyle.player之上。

封面。封面按所在空位的行长(或其placement.width比例)排版,保持自身的宽高比,与像素尺寸无关:屏幕大小的帧会被放大,而不是印得很小。和位图一样,它可以带安全区,也遵循placement.align。没有封面的视频印出一个按视频宽高比(没有说明时为16:9)的深色方框,上面照样有叠加元素,并发出videoWithoutPoster内容警告。在沙盒中,填入YouTube或Vimeo视频的地址时会从平台获取封面;文件的封面则是你在视频中选取的一帧。

地址。二维码和PDF链接打开视频的页面,即https://youtu.be/<id>或https://vimeo.com/<id>,从start开始。文件没有页面,所以打开它的正式发布地址;没有自带文件的视频(服务器上的MP4、HLS流)也从这个地址播放。没有这个地址时,印刷版既没有二维码也没有链接(videoWithoutUrl),不携带文件的HTML或EPUB输出则显示封面。YouTube或Vimeo地址不指向该平台的任何视频时,发出videoUrlInvalid,并以封面代替播放器。

播放器。播放器选项(控件、下载按钮、全屏、倍速菜单、画中画、投屏、自动播放、静音开始、循环、预加载、增强隐私的嵌入)在videoStyle.player中为全书设定,在video.player中为单个视频设定;每种播放器支持它能支持的那些(见配置 › 视频样式)。HTML后端通过resourceVideoUrl(fileId)选项取得文件可播放的URL,就像通过resourceImageUrl取得图片一样,没有时退回正式发布地址。它的videos: { files, streams, hls }选项按来源在播放器和封面之间选择,优先于videoStyle.html(hls指从HLS地址播放的视频,不设置时随files);EPUB写入器就使用这个选项。播放HLS地址的<video>带有data-pt-hls,宿主可以据此在不能原生播放HLS的浏览器中为它接上播放器(Safari和较新的Chrome直接就能播放)。在从右到左的书中,播放器和封面上的叠加元素像图片一样转回来,使二维码能被读出。

在VDT中。视频的资源块带有kind: 'video',以fileId / format表示它的封面(像位图一样绘制),还有video(VDTResourceVideo):读者被引向的link、应用了播放器选项的YouTube或Vimeo embedUrl、文件的fileId、自己的视频的mimeType(取自它的文件,或仅取自它的地址;HLS为application/vnd.apple.mpegurl)、start / end范围、解析后的player、linkPoster、html,以及叠加元素playMark和qr(二维码模块表示为由'0' / '1'组成的行),各矩形相对于主体的左上角。自己绘制视频的宿主可以使用postext导出的函数:parseVideoUrl、videoWatchUrl、resourceVideoLink、videoEmbedUrl、videoEmbedAllow、videoElementAttributes、mediaFragment、videoMimeType、videoFormatOfUrl、resourceVideoFormat、isHlsMimeType、HLS_MIME_TYPE、youtubePosterUrls、encodeQr、layoutVideo、playMarkTriangle和qrModuleRuns。

在文件包中。.postext携带视频文件(resources/<id>.mp4)和封面(resources/<id>.poster.jpg):清单条目在file和poster中写明它们,在width / height中给出封面的尺寸,其余内容放在不含文件id的video中。bundleVideoUrl(bundle)是基于文件包中文件的resourceVideoUrl解析函数。只从网址播放的视频不携带文件,它的条目中只有封面。在双语文件包中,一种语言可以在localized[…].resources中给视频指定自己的poster和video(另一个剪辑版本,放在它自己的地址)。

#Folio视图中的视频

在3D书本中,你自己的视频就在印着它的那一页上播放。无论指针在书上做什么(翻页、转动视角还是选择文字),点击封面,视频就在那里开始播放:页面的着色器把视频画面画在封面之上,所以翻动这一叶时,画面随纸张一起弯曲卷起,翻页过程中也照常播放。点击正在播放的视频会暂停,再点击则继续;空格键或回车键对打开的跨页上的第一个视频起同样的作用。开始播放另一个视频时,正在播放的那个会停止,回到封面;书停在不再显示某个视频的跨页上,或播到它的end时,这个视频也会停止。指针移到可以播放的视频上时变成手形;从视频上开始的拖动仍然翻页或转动视角。设为自动播放的视频(video.player.autoplay)在书第一次停在它的跨页上、且书已经稳定下来之后(包括宿主分几步排版的情况)自动开始播放,在这个查看器中不会再自动播放第二次。

与其他视频同时播放的视频(video.player.exclusive: false,postext 1.18起)改变了这两条规则。开始播放它只会停止独占的视频,因此几段这样的视频可以同时播放;开始播放独占的视频也会让它停止。设了autoplay时,书每次停在它所在的跨页上,它都静音开始,翻走时停止:一页上无声的循环片段(loop)在读者每次翻到这一页时一起播放。

  • 能播放什么。 文件(宿主用videoUrl选项把它的fileId换成URL,沙盒中是一个对象URL),没有文件时则用它的地址:MP4、WebM或HLS流。只要浏览器支持Media Source Extensions,HLS流就通过hls.js播放(在第一次播放时加载;它是postext-folio的可选对等依赖),清晰度以最接近画面在屏幕上尺寸的那一档为上限,所以几百像素高的画面不会去拉取4K版本;浏览器自带的HLS播放作为后备。这些请求带有专用的pt-cors查询参数,这样浏览器缓存就不会把另一个播放器在没有CORS的情况下取得的副本交给它们。YouTube和Vimeo在iframe中播放,WebGL无法绘制iframe,所以点击它们的封面和点击页面其他地方一样会翻页。
  • 跨源读取。 只有视频所在的服务器允许读取时(CORS,Access-Control-Allow-Origin),WebGL才能绘制它。无法读取的视频仍显示为封面,onVideo会收到error。
  • 声音。 点击之后视频带声音播放;仍然拒绝的浏览器则让它静音播放。自动开始的视频,要等读者在页面上点击或按过键(翻到这一页也算)才有声音;在此之前它静音开始,点击它会先打开声音,再点击一次才暂停。video.player.muted让它静音开始,loop让它循环播放,start / end给出播放的片段。
  • 在每一种页面上。 画面画在版面安排的位置:资源转向时它也转向,在竖排页面上保持正立,在从右到左的书中不作镜像,都和封面一样。封面按安全区裁切时,视频也以同样的方式裁切。
  • 没有WebGL2,或要求减少动画时,视频在叠放于页面之上的HTML <video>中播放。
const book = createFolioFromDocument(container, doc, {
  // 上传视频可播放的URL(基于其字节的对象URL)。
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();

videos: false关闭这项功能。toggleVideoAt({ page, x, y })的作用与在该处点击相同;pageVideoSpots(page, doc)列出一页上每个视频的位置,供自己绘制控件的宿主使用。

排版食谱中有两篇用到视频:第131号封面印有二维码的电影俱乐部节目单把每部影片印成带播放标记和二维码的片名卡;第132号视频在屏幕和EPUB里都能播放的实验报告单为HTML版设定播放器选项,并把自己的视频片段打包进固定版式EPUB。

#排版食谱中的示例

用到本页内容的食谱,每道列在最贴切的小节下。每道食谱都把页面和完整脚本并排展示。