# 文書形式：動画

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

- HTML版: https://postext.dev/ja/docs/document-format-videos
- 最終更新: 2026-11-11
- 読了時間: 10分
- 他の言語: [en](https://postext.dev/en/docs/document-format-videos.md), [es](https://postext.dev/es/docs/document-format-videos.md), [ca](https://postext.dev/ca/docs/document-format-videos.md), [de](https://postext.dev/de/docs/document-format-videos.md), [fr](https://postext.dev/fr/docs/document-format-videos.md), [it](https://postext.dev/it/docs/document-format-videos.md), [pt](https://postext.dev/pt/docs/document-format-videos.md), [zh](https://postext.dev/zh/docs/document-format-videos.md), [ar](https://postext.dev/ar/docs/document-format-videos.md)

## かんたんな説明

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

動画は画像と同じリソースです。一度宣言し、本文で参照すると、参照のあとの最初の空いた場所にフロートします。参照、番号付け、配置、回り込みについては[文書形式：画像と表](https://postext.dev/ja/docs/document-format-resources.md)で説明しています。ここからは動画に固有の内容です。

> [あなたの本に、動画を：紙には QR コード、画面にはプレーヤー、ページの上には映画。Postext で](https://youtu.be/CbuCU0w3H3U) · 5:09

## 動画

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

| 出力 | 表示されるもの |
| --- | --- |
| Canvas、PDF | 動画の1フレームである**ポスター画像**に、再生マークと動画を開くQRコードを重ねて表示します（[設定 › 動画スタイル](https://postext.dev/ja/docs/configuration-resources.md#動画スタイル)）。PDFでは、ポスター画像は動画へのリンクにもなります。 |
| Folio | 印刷物と同じポスター画像を表示します。クリックすると動画は**そのページの上で**再生され、丁をめくっている間も再生が続きます（後述の[Folioのページで再生する動画](https://postext.dev/ja/docs/document-format-videos.md#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本を再生すると、同時に再生しないほかの動画が一時停止します。 |

```ts
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'`）で、自前の動画はアップロードしたものでもアドレスにあるものでもかまいません。 |
| `url` | `string` | YouTubeまたはVimeo：動画のアドレス。形式は問いません（視聴ページ、`youtu.be`、ショート、埋め込みリンク、`youtube-nocookie.com`。Vimeoのページ、チャンネルのページ、ハッシュ付きの限定公開リンク）。ファイル：その**公開先のアドレス**、つまり公開された本がファイルを見つける場所。ファイルのない自前の動画は、このアドレスから再生されます。サーバー上のMP4やWebM、あるいはHLSストリーム（`…/master.m3u8`）です。 |
| `fileId`, `format` | `string` | ファイル：アップロードした動画（ビットマップと同じく本体とは別に保存されます）とその形式。形式は`'mp4'`、`'webm'`、`'ogv'`、`'mov'`、HLSストリームなら`'hls'`です。形式を指定しなければアドレスの拡張子で決まり（`.m3u8`は`'hls'`）、それもなければ`'mp4'`になります。 |
| `poster` | `{ fileId, format, width, height }` | ポスター画像のフレーム（ビットマップ）。 |
| `width`, `height`, `duration` | `number` | 動画のフレームサイズ（px。ポスター画像がない場合は縦横比として使います）と長さ（秒）。 |
| `posterTime` | `number` | ファイルのどの秒のフレームをポスター画像にしたか。選び直せるように保存されます。 |
| `start`, `end` | `number` | `start`秒から`end`秒まで再生します。QRコードとPDFのリンクも`start`から始まります。 |
| `player` | `VideoPlayerOptions` | この動画のプレーヤーオプション。`videoStyle.player`の上に重ねて適用されます。 |

**ポスター画像**。その位置の行長（またはその`placement.width`の割合）で、ピクセルサイズにかかわらず自身の縦横比で組まれます。画面サイズのフレームは、小さく印刷されるのではなく拡大されます。ビットマップと同じく[セーフエリア](https://postext.dev/ja/docs/document-format-resources.md#セーフエリア)を指定でき、`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`で設定します。各プレーヤーは対応できる範囲でこれに従います（[設定 › 動画スタイル](https://postext.dev/ja/docs/configuration-resources.md#動画スタイル)を参照）。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の本](https://postext.dev/ja/docs/configuration-html-folio-epub.md#3dの本postext-folio)では、自前の動画は、それが印刷されているページの上で再生されます。ポスター画像をクリックすると、ポインターが本に対して何をするモード（ページをめくる、視点を回す、テキストを選択する）であっても、その場で再生が始まります。ページのシェーダーがポスター画像の上に動画のフレームを描くので、丁をめくると映像も紙と一緒にしなって丸まり、めくっている間も再生は続きます。再生中の動画をクリックすると一時停止し、一時停止中の動画をクリックすると再開します。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](https://github.com/video-dev/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`は再生する部分を決めます。
- **どのページでも**。映像はレイアウトが置いた場所に、ポスター画像と同じように描かれます。回転したリソースでは回転し、縦組みのページでは正立し、右から左の本では左右反転されません。[セーフエリア](https://postext.dev/ja/docs/document-format-resources.md#セーフエリア)の範囲内で切り抜かれたポスター画像は、動画も同じように切り抜きます。
- **WebGL2がない場合**、または動きを減らす設定の場合は、ページの上に重ねたHTMLの`<video>`で再生されます。

```ts
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コードを刷った映画クラブのプログラム](https://postext.dev/ja/cookbook/film-club-video-qr.md)」は、映画ごとに再生マークとQRコードの付いたタイトルカードを刷ります。No. 132「[画面とEPUBで動画が再生される実験シート](https://postext.dev/ja/cookbook/pendulum-lab-video-players.md)」は、HTML版のプレーヤーオプションを設定し、自前の動画を固定レイアウトのEPUBに同梱します。

## レシピ集の例

### 動画

- [No. 131 ポスター画像にQRコードを刷った映画クラブのプログラム](https://postext.dev/ja/cookbook/film-club-video-qr.md)
- [No. 132 画面とEPUBで動画が再生される実験シート](https://postext.dev/ja/cookbook/pendulum-lab-video-players.md)
- [No. 136 写真が動く、生きている新聞](https://postext.dev/ja/cookbook/living-newspaper-video-loops.md)
