本文へスキップ

章 5.5 · 部 II · 技法

文書形式:動画

動画リソース:YouTube、Vimeo、自前のファイルとHLSストリーム、出力ごとの表示、動画のフィールド、ポスター画像とアドレス、プレイヤー、VDTとバンドル、Folioのページで再生する動画

更新日 2026-11-1110分所属する章: 5 文書形式enescadefritptzhjaar

かんたんな説明

このページでは、本の動画を説明します。動画はYouTubeやVimeoのものでも、自前のファイルでもかまいません。本文では画像と同じように参照し、図や表と同じく独自の番号が付きます。紙とPDFでは、再生マークと、動画を開くQRコードの付いた1枚の静止画になります。Web表示と電子書籍では再生できます。3Dの本では、静止画をクリックするとそのページの上で動画が再生され、ページをめくる間も止まりません。

動画は画像と同じリソースです。一度宣言し、本文で参照すると、参照のあとの最初の空いた場所にフロートします。参照、番号付け、配置、回り込みについては文書形式:画像と表で説明しています。ここからは動画に固有の内容です。

あなたの本に、動画を:紙には QR コード、画面にはプレーヤー、ページの上には映画。Postext でYouTube で見る (新しいタブで開きます) · 再生を押すと YouTube からプレーヤーを読み込みます。

#動画

動画リソース(kind: 'video')は、YouTubeまたはVimeoの動画、あるいは自前の動画です。自前の動画は、本に含めたファイル(MP4、WebM)でも、Webのアドレスにあるもの、つまりサーバー上のファイルやHLSストリーム(.m3u8のプレイリスト)でもかまいません。画像と同じように配置、キャプション付け、フロート、参照ができ、独自の系列で番号が付きます。組み込みのvideoの種類は、Figure 1.1やTable 1.1と並んでVideo 1.1、Video 1.2…と表示します(設定 › リソースの種類を参照)。各出力は、それぞれ可能な形で動画を表示します。

出力表示されるもの
Canvas、PDF動画の1フレームであるポスター画像に、再生マークと動画を開くQRコードを重ねて表示します(設定 › 動画スタイル)。PDFでは、ポスター画像は動画へのリンクにもなります。
Folio印刷物と同じポスター画像を表示します。クリックすると動画はそのページの上で再生され、丁をめくっている間も再生が続きます(後述のFolioのページで再生する動画を参照)。YouTubeやVimeoの動画はポスター画像のままです。
HTMLビューアー動画のプレーヤーを表示します。YouTubeやVimeoのプレーヤー、ファイルやアドレスの場合はブラウザーのHTML5プレーヤーです。HLSストリームはSafariと最近のChromeではそのまま再生され、それ以外のブラウザーでは、Sandboxがしているように、ホストがhls.jsなどのプレーヤーを付けます。videoStyle.html: 'poster'を指定すると、代わりに印刷用のポスター画像を表示します。
EPUBファイルは本に同梱されるか公開先のアドレスから読み込まれ、リーディングシステム自身のプレーヤーで再生されます。YouTubeやVimeoの動画は、動画にリンクしたポスター画像になります。EPUBにはWebページのプレーヤーを埋め込めないためです。HLSストリームも、動画にリンクしたポスター画像になります。HLSのプレイリストは、EPUBが再生してよいメディアタイプではないためです。リーディングシステムがスクリプトを実行する場合、同じページや章のファイルはplayer.exclusiveに従います。1本を再生すると、同時に再生しないほかの動画が一時停止します。
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,                                // plays from 0:30; the printed link starts there too
  },
};

本文は図と同じように動画を参照します。:ref{id="keeper-talk"}はVideo 1.1と表示し、参照の後にある最初の空き位置へポスター画像をフロートとして配置します。placement.position: 'here'を指定して::resource{id="keeper-talk"}を書くと、本文中に組まれます。Resource.video(ResourceVideo)の項目は次のとおりです。

項目型意味
source'youtube' · 'vimeo' · 'file'動画の再生元。YouTubeやVimeoのページ、または自前の動画('file')で、自前の動画はアップロードしたものでもアドレスにあるものでもかまいません。
urlstringYouTubeまたはVimeo:動画のアドレス。形式は問いません(視聴ページ、youtu.be、ショート、埋め込みリンク、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, endnumberstart秒からend秒まで再生します。QRコードとPDFのリンクもstartから始まります。
playerVideoPlayerOptionsこの動画のプレーヤーオプション。videoStyle.playerの上に重ねて適用されます。

ポスター画像。その位置の行長(またはそのplacement.widthの割合)で、ピクセルサイズにかかわらず自身の縦横比で組まれます。画面サイズのフレームは、小さく印刷されるのではなく拡大されます。ビットマップと同じくセーフエリアを指定でき、placement.alignに従います。ポスター画像のない動画は、動画の縦横比(指定がなければ16:9)の暗い枠をオーバーレイ付きで印刷し、videoWithoutPosterの内容の警告を出します。Sandboxでは、YouTubeやVimeoの動画のポスター画像はアドレスを入力したときにプラットフォームから取得され、ファイルの場合は動画の中から選んだフレームになります。

アドレス。QRコードとPDFのリンクは、動画のページhttps://youtu.be/<id>またはhttps://vimeo.com/<id>をstartの位置から開きます。ファイルにはページがないので、公開先のアドレスを開きます。ファイルのない動画(サーバー上のMP4、HLSストリーム)も、このアドレスから再生されます。それがない場合、印刷物にはQRコードもリンクも付かず(videoWithoutUrl)、ファイルを含まないHTMLやEPUBの出力はポスター画像を表示します。YouTubeやVimeoのアドレスがそのプラットフォームの動画を指していない場合はvideoUrlInvalidが出て、プレーヤーの代わりにポスター画像が表示されます。

プレーヤー。プレーヤーのオプション(コントロール、ダウンロードボタン、全画面表示、速度メニュー、ピクチャーインピクチャー、キャスト、自動再生、ミュートでの開始、ループ、プリロード、プライバシー強化モードの埋め込み)は、本全体にはvideoStyle.playerで、1つの動画にはvideo.playerで設定します。各プレーヤーは対応できる範囲でこれに従います(設定 › 動画スタイルを参照)。HTMLバックエンドは、画像をresourceImageUrlで受け取るのと同じように、ファイルの再生可能なURLをresourceVideoUrl(fileId)オプションで受け取り、なければ公開先のアドレスを使います。そのvideos: { files, streams, hls }オプションは、videoStyle.htmlに優先して、再生元ごとにプレーヤーかポスター画像かを選びます(hlsはHLSのアドレスから再生する動画のためのもので、指定しなければfilesに従います)。EPUBライターもこれを使います。HLSのアドレスを再生する<video>にはdata-pt-hlsが付くので、HLSにネイティブ対応していないブラウザーでは、ホストがプレーヤーを付けられます(Safariと最近のChromeはそのまま再生します)。右から左の本では、QRコードが読めるように、プレーヤーとポスター画像のオーバーレイは画像と同じく向きが元に戻されます。

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(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の本では、自前の動画は、それが印刷されているページの上で再生されます。ポスター画像をクリックすると、ポインターが本に対して何をするモード(ページをめくる、視点を回す、テキストを選択する)であっても、その場で再生が始まります。ページのシェーダーがポスター画像の上に動画のフレームを描くので、丁をめくると映像も紙と一緒にしなって丸まり、めくっている間も再生は続きます。再生中の動画をクリックすると一時停止し、一時停止中の動画をクリックすると再開します。SpaceキーかEnterキーは、開いている見開きの最初の動画に同じことをします。別の動画を再生すると、再生中の動画は止まってポスター画像に戻ります。動画は、本がその動画の見えない見開きで静止したとき、またはendに達したときにも止まります。再生できる動画の上ではポインターが手の形になります。動画の上から始めたドラッグでも、ページはめくれ、視点は回ります。ひとりでに再生するよう設定した動画(video.player.autoplay)は、本が初めてその見開きで静止したときに、本の状態が落ち着くのを待って(レイアウトを段階的に進めるホストの場合も含めて)ひとりでに再生を始めます。そのビューアーで2度目に自動再生されることはありません。

ほかの動画と同時に再生する動画(video.player.exclusive: false、postext 1.18以降)では、この2つの決まりが変わります。再生を始めても止まるのは排他的な動画だけなので、こうした動画は何本でも同時に再生されます。排他的な動画を再生すると、こちらも止まります。autoplayを付けると、本がその見開きで止まるたびに無音で始まり、見開きがめくられると止まります。ページ上の無音のループ(loop)は、読者がそのページを開くたびにいっしょに流れます。

  • 再生されるもの。ファイル(ホストがvideoUrlオプションでそのfileIdをURLに変えます。SandboxではオブジェクトURLです)、ファイルがなければそのアドレスで、MP4、WebM、HLSストリームのいずれかです。HLSストリームは、ブラウザーにMedia Source Extensionsがあればどこでもhls.jsを通して再生されます(最初の再生時に読み込まれます。postext-folioの省略可能なピア依存関係です)。画面上の映像の大きさに最も近いバリアントまでに抑えるので、高さ数百ピクセルの映像のために4Kのバリアントを読み込むことはありません。ブラウザー自身のHLSは、その代わりの手段として使われます。そのリクエストには専用のpt-corsクエリーが付くので、ほかのプレーヤーがCORSなしで取得したコピーをブラウザーのキャッシュが返すことはありません。YouTubeとVimeoはiframeの中で再生され、iframeはWebGLでは描けないので、そのポスター画像をクリックしても、ほかの場所と同じくページがめくれるだけです。
  • クロスオリジンの読み込み。WebGLが動画を描けるのは、動画のサーバーが読み込みを許可している場合(CORS、Access-Control-Allow-Origin)だけです。読み込めない動画はポスター画像のままで、onVideoはerrorを受け取ります。
  • 音声。クリックによって、動画は音声付きで再生できるようになります。それでもブラウザーが拒んだ場合は、ミュートで再生されます。ひとりでに再生を始める動画は、読者がページ上でクリックかキー入力をした後なら(そのページまでめくったことも数えます)音声付きで再生されます。それより前はミュートで始まり、動画をクリックすると、まずミュートが解除され、次のクリックで一時停止します。video.player.mutedはミュートで再生を始め、loopは繰り返し再生し、start / endは再生する部分を決めます。
  • どのページでも。映像はレイアウトが置いた場所に、ポスター画像と同じように描かれます。回転したリソースでは回転し、縦組みのページでは正立し、右から左の本では左右反転されません。セーフエリアの範囲内で切り抜かれたポスター画像は、動画も同じように切り抜きます。
  • WebGL2がない場合、または動きを減らす設定の場合は、ページの上に重ねたHTMLの<video>で再生されます。
const book = createFolioFromDocument(container, doc, {
  // An uploaded video's playable URL (an object URL over its bytes).
  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)はページ上の各動画の位置を一覧にします。独自のコントロールを描くホストのためのものです。

レシピ集の2つのレシピが動画を組んでいます。No. 131「ポスター画像にQRコードを刷った映画クラブのプログラム」は、映画ごとに再生マークとQRコードの付いたタイトルカードを刷ります。No. 132「画面とEPUBで動画が再生される実験シート」は、HTML版のプレーヤーオプションを設定し、自前の動画を固定レイアウトのEPUBに同梱します。

#レシピ集の例

このページの内容を使うレシピを、いちばん近い節ごとにまとめました。どのレシピもページとスクリプト全体を並べて見せます。