epub

EPUB — 電子書籍の作成、抽出、エンリッチメント

EPUB 2 および EPUB 3 ファイルの高度な取り扱いに対応します。EPUB ファイルの読み込み、書き込み、編集、検証、知識の抽出ができます。EPUB の全領域を網羅する、5 つの Python CLI スクリプトと5 つの詳細なリファレンスが付属しています。

使用しないケース

• EPUB 以外のドキュメント — Word、PDF、プレーンな Markdown、ウェブページの変換タスクは、ここにあるどのスクリプトにも該当しません。EPUB 以外のファイルに EPUB ツールを無理に適用せず、ドキュメント処理用のスキルに振り分けてください。
• DRM で保護された電子書籍 — これらのスクリプトは標準の OCF／EPUB コンテナーを読み書きしますが、デジタル著作権管理を解除したり回避したりすることはありません。
• Mobi／AZW／Kindle ネイティブ形式 — まず専用のコンバーターを使用してください。このスキルでは、Amazon 独自のコンテナーの読み書きはできません。

EPUB 形式の基本

EPUB ファイルは、特定の内部構造を持つ ZIP アーカイブ（Open Container Format、OCF）です。W3C EPUB 3.3 標準では「3 つのプレーン」モデルが採用されています。

プレーン	内容	主なルール
マニフェスト	すべてのリソース（XHTML、画像、CSS、フォント）	すべてのファイルを OPF の <manifest> に記載する必要があります
スパイン	直線的な読み上げ順	デフォルトでは XHTML／SVG のみです。それ以外の種類にはフォールバックが必要です
コンテンツ	ドキュメントに埋め込まれたリソース	コアメディアタイプは保証されています。それ以外のタイプにはフォールバックが必要です

パッケージドキュメント（content.opf）には、メタデータ（Dublin Core）、マニフェスト（すべてのリソース）、スパイン（読み上げ順）が格納されます。EPUB3 ではナビゲーションに XHTML の nav ドキュメントを使用し、EPUB2 では .ncx XML を使用します。互換性のため、両方を共存させることもできます。

重要なルール： mimetype は ZIP の最初のエントリーに配置し、非圧縮で保存する必要があります。すべてのコンテンツドキュメントは整形式の XML（HTML5 ではなく XHTML）でなければなりません。レンダリングに使用するすべてのファイルをマニフェストに記載する必要があります。構造の詳細については、references/epub-format-internals.md を参照してください。

選択表 — 使用するスクリプト

タスク	スクリプト	備考
構造、メタデータ、マニフェスト、スパイン、目次を確認する	epub-info	JSON 出力。簡潔な出力には --summary を使用
読み上げ順のクリーンなテキストを抽出する	epub-text	章ごと、または単一ファイルで出力
最小構成の有効な EPUB を一から作成する	epub-scaffold	依存関係は不要
事実、引用、定義、論点を抽出する	epub-extract-knowledge	ヒューリスティックまたは LLM モード（環境変数を自動検出）
EPUB 仕様に照らして検証する	epub-validate	EPUBCheck または Python によるフォールバック
EPUB を編集する（メタデータ、章、スパイン、CSS）	epub-edit	v2 の主力機能 — 8 つのサブコマンド、非侵襲的
画像を抽出する	epub-images	一覧表示、またはディレクトリに抽出
複数の EPUB を一括処理する	epub-batch	glob パターンを使って既存のスクリプトを実行
EPUB2 → EPUB3 に変換する	epub-convert	NAV を追加し、NS を更新して、NCX を保持
構造上の問題を診断して修復する	epub-repair	よくある検証エラーを自動修正

スクリプト

すべてのスクリプトは、このスキルのディレクトリを基準とする scripts/ にあります。各スクリプトは cli-builder の規約に従います。機械処理用の --json、実行内容を事前確認する --dry-run に対応し、非対話型で、エラーは stderr に出力します。フラグの詳細を確認するには --help を実行してください。

epub-info — 構造とメタデータのダンプ

scripts/epub-info book.epub --json
scripts/epub-info book.epub --summary      # compact manifest
scripts/epub-info book.epub --dry-run      # preview

出力内容：EPUB のバージョン、メタデータ（タイトル、著者、言語、識別子）、マニフェスト（id／href／media-type を含む全項目）、スパイン（読み上げ順）、目次（階層構造）。--summary を指定すると、マニフェストの出力が id＋href＋media-type に簡略化されます。

epub-text — クリーンなテキストの抽出

scripts/epub-text book.epub                           # plain text to stdout
scripts/epub-text book.epub --json                    # JSON with chapter array
scripts/epub-text book.epub --chapters                # one .txt per chapter
scripts/epub-text book.epub --output book.txt         # single file
scripts/epub-text book.epub --format markdown         # markdown output

スパイン順のコンテンツドキュメントからテキストを抽出します。HTML タグを除去し、段落構造を保持します。beautifulsoup4 が必要です。スパインの直線的な順序を尊重し、読み上げ順に含まれるドキュメントのみを処理します。

epub-scaffold — EPUB をゼロから作成

scripts/epub-scaffold --title "My Book" --author "Jane Doe"
scripts/epub-scaffold --title "Novel" --author "Me" --chapters 12 --output novel.epub
scripts/epub-scaffold --title "Guide" --author "Me" --cover cover.jpg
scripts/epub-scaffold --title "Guide" --author "Me" --cover cover.jpg --toc-hidden --dry-run

すべてのコンテンツを OEBPS/ 内に配置した有効な EPUB3 を作成します。Apple Books との互換性に必要です。外部依存関係はなく、Python 標準ライブラリのみを使用します。

表紙の処理： --cover を指定すると、スキャフォールドが自動的に次の処理を行います。

• 画像を OEBPS/Images/cover.{ext} にコピーします
• OEBPS/Text/cover.xhtml を生成します。これは、表示領域全体に適用される CSS を備えた XHTML ラッパーページです
• 表紙ページをスパインの最初の項目として追加します
• ライブラリのサムネイル用に、元画像に properties="cover-image" を設定します

これは、表紙を画像への直接参照ではなく、スパイン内の XHTML ページにする必要があるという Apple Books の要件に準拠しています（画像を直接参照すると、空白ページとして表示されます）。

ナビゲーションの表示： --toc-hidden を指定すると、ナビゲーションのスパイン項目に linear="no" が設定され、読書の流れから非表示になります（アプリ内蔵の目次ブラウザーからは引き続きアクセスできます）。デフォルトは --toc-visible で、ナビゲーションがページとして表示されます。

CSS： Apple Books に対応したタイポグラフィを備えた OEBPS/Styles/default.css が付属します。非推奨の page-break-before は使用せず、余白には body の margin: 0（空白部分には padding を使用）、適切な見出し階層、レスポンシブなスタイルを採用しています。

表紙画像に関するガイダンス： --cover フラグには、既存の画像ファイルを指定できます。ユーザーが表紙画像を持っていない場合は、エージェントの image_gen 機能を使って生成することを提案してください。表紙の XHTML および CSS の規約については、references/apple-books-compatibility.md を参照してください。

epub-cover — 既存の EPUB に表紙を追加

scripts/epub-cover wrap book.epub --image cover.png --output with-cover.epub
scripts/epub-cover wrap book.epub --image cover.png --in-place

マニフェスト内に表紙画像がすでにある EPUB に、表紙の XHTML ラッパーページを追加します。画像は存在するものの、Apple Books で表示されない場合に使用します。epublib が必要です。

epub-extract-knowledge — ナレッジ抽出パイプライン

# LLM mode — set env vars first (see references below), then run without flags:
scripts/epub-extract-knowledge book.epub --format json
scripts/epub-extract-knowledge book.epub --format atoms
scripts/epub-extract-knowledge book.epub --format memory

# Force heuristic mode (ignore env vars):
scripts/epub-extract-knowledge book.epub --no-llm --format json

# Custom prompt override:
scripts/epub-extract-knowledge book.epub --prompt "Extract all definitions" --format json

EPUB のコンテンツから、事実、定義、要点、論拠などのナレッジを抽出します。モードは 2 種類あり、自動選択されます。

• LLM モード（自動検出）： EPUB_LLM_URL と EPUB_LLM_KEY の環境変数が設定されている場合、章のテキストと抽出プロンプトを指定して、設定済みの LLM を呼び出します。高品質で構造化された知見を生成します。LLM の呼び出しに失敗した場合は、ヒューリスティック方式にフォールバックします。
• ヒューリスティックモード（フォールバック）： 環境変数が設定されていない場合、または --no-llm が渡された場合、パターンマッチング（見出し、強調マーカー、定義表現、段落の密度）を使って、ナレッジを含む箇所を特定します。LLM は不要です。

出力形式：json（構造化された JSON をそのまま出力）、atoms（Obsidian の Vault 用アトムテンプレート）、memory（エージェントの永続化に適したキーと値のエントリー）。環境変数の設定規約、ナレッジタイプの検出テーブル、LLM プロンプトの設計、プラットフォームごとの出力先オプションについては、 references/llm-config-and-extraction.md を読み込んでください。

epub-edit — EPUB のピンポイント編集（v2）

scripts/epub-edit info book.epub --json
scripts/epub-edit metadata book.epub --title "New Title" --output out.epub
scripts/epub-edit add-chapter book.epub --content new.xhtml --after chapter3 --output out.epub
scripts/epub-edit remove-chapter book.epub --id chapter5 --output out.epub
scripts/epub-edit reorder-spine book.epub --order chapter3,chapter1,chapter2 --dry-run
scripts/epub-edit rename-resource book.epub --from Images/old.jpg --to Images/new.jpg
scripts/epub-edit inject-css book.epub --css dark.css --output out.epub
scripts/epub-edit update-manifest book.epub --output out.epub

epublib を介して、既存の EPUB を侵襲性の低い方法で編集します。編集機能全体を網羅する 8 つのサブコマンドを備えています。元のファイルは上書きせず、デフォルトでは --output out.epub に出力します。変更を確定するには --in-place を使用してください。すべてのサブコマンドで --json と --dry-run を使用できます。

epub-images — 画像の抽出

scripts/epub-images book.epub --list --json           # list all images
scripts/epub-images book.epub --extract images/       # extract all to directory
scripts/epub-images book.epub --type cover --extract .  # cover image only

epub-batch — 複数ファイルの処理

scripts/epub-batch extract-text "books/*.epub" --output texts/
scripts/epub-batch validate "books/*.epub" --json
scripts/epub-batch metadata "books/*.epub" --set-author "Author" --output-dir fixed/
scripts/epub-batch info "books/*.epub" --json

epub-convert — EPUB2 から EPUB3 への変換

scripts/epub-convert old.epub --output new-v3.epub
scripts/epub-convert old.epub --validate --json

epub-repair — 診断と修復

scripts/epub-repair broken.epub --diagnose --json     # list fixable issues
scripts/epub-repair broken.epub --output fixed.epub   # auto-fix

epub-validate — 構造検証

scripts/epub-validate book.epub --json
scripts/epub-validate book.epub --dry-run

最初に EPUBCheck（Java JAR）を試し、信頼性の高い検証を行います。利用できない場合は、純粋な Python による構造チェックにフォールバックします。チェック項目は、mimetype の位置・圧縮・内容、container.xml の解析可能性、OPF スキーマ、マニフェストの完全性、スパイン参照の整合性、必須メタデータ、NAV ドキュメントの有無です。

機能の検出とパイプラインの構築

複数ステップの EPUB パイプラインを実行する前に、エージェントプラットフォームで利用できるツールを確認してください。このスキルは移植可能であり、具体的なパイプラインの構成はハーネスの機能によって異なります。手順は、ツール（ファイル書き込み、ウェブアクセス、サブエージェント、cron、永続メモリ、ベクトル DB、Vault、LLM）を列挙し、パイプラインの各段階（取り込み → 解析 → 抽出 → 形式化 → 出力先）に分類して、利用可能な要素からパイプラインを構築し、実行前に計画をユーザーに提示することです。

各段階の対応表と、さまざまなプラットフォーム向けのパイプライン例（Vault + RAG を備えたフル機能エージェント、ターミナルのみの最小構成のハーネス、複数ファイルの一括処理）を含む完全な手順については、references/agent-capability-discovery.md を参照してください。

よくあるワークフロー

Markdown ファイルから EPUB を作成する

# 1. Scaffold the EPUB
scripts/epub-scaffold --title "My Book" --author "Me" --chapters 3 --output book.epub

# 2. Use epublib (Python) to inject real content into each chapter
# See references/tutorials-and-guides.md for the editing pattern

EPUB からすべての画像を抽出する

scripts/epub-images book.epub --extract images/

EPUB を編集する

# Update metadata
scripts/epub-edit metadata book.epub --title "New Title" --output revised.epub

# Add a chapter
scripts/epub-edit add-chapter book.epub --content new.xhtml --output expanded.epub

# Inject dark theme
scripts/epub-edit inject-css book.epub --css dark.css --output dark.epub

破損した EPUB を修復する

scripts/epub-repair broken.epub --diagnose --json     # see what's broken
scripts/epub-repair broken.epub --output fixed.epub   # auto-fix

ライブラリからテキストを一括抽出する

scripts/epub-batch extract-text "books/*.epub" --output texts/

EPUB2 を EPUB3 に変換する

scripts/epub-convert old.epub --output old-v3.epub --validate

Apple Books との互換性

macOS/iOS 版 Apple Books は、EPUB 仕様を超える要件を適用します。これらのルールは、macOS 26 でのビルドとテストによって検証されています。要点は、すべてのコンテンツを OEBPS/ 内に配置すること、表紙をスパイン内の XHTML ページにすること（画像をそのままスパイン項目にすると何も表示されません）、本文では margin: 0 を避けて padding を使うこと、非推奨の page-break-before を使わないこと、xmlns:epub は nav ドキュメントにのみ付けること、表紙画像そのものには properties="cover-image" を保持すること、そして linear="no" によってページ（例：nav）をアプリの目次ブラウザーには表示したまま、読書の流れから除外できることです。スパインの順序パターンは次のとおりです。表紙なし（nav → chapters）、表紙のみ（cover-page → nav(linear="no") → chapters）、完全構成（cover-page → nav → chapters。スキャフォールドのデフォルト）。

これらのルールを記憶だけに頼って適用しないでください。Apple Books を対象とする EPUB の作成または修復時は、ルールごとの表、CSS の例、表紙 XHTML テンプレート、検証時の注意点が記載された references/apple-books-compatibility.md を読み込んでください。

注意点

• mimetype の圧縮： Python の zipfile はデフォルトで圧縮します。mimetype エントリーには必ず ZIP_STORED を使用してください。mimetype が圧縮されると、読み取りシステムで問題が発生しても気づきにくいことがあります。
• XHTML ≠ HTML5： コンテンツドキュメントは整形式の XML でなければなりません。自己終了タグが必要です（<br> ではなく <br/>）。xmlns:epub="http://www.idpf.org/2007/ops" を使用してください。
• マニフェストに漏れがないこと： EPUB 内のすべてのファイルを記載する必要があります。マニフェストのエントリーが不足すると、検証に失敗します。画像、CSS、フォントも例外ではありません。
• AGPL の境界： EbookLib は AGPL です。スクリプトは実行時にこれを呼び出しますが、同梱はしません。ユーザー自身が pip でインストールします。このスキルとそのスクリプトは MIT ライセンスです。
• EPUBCheck には Java が必要： 権威あるバリデーターには Java が必要です。代替の Python チェックでは構造上の問題を検出できますが、XHTML スキーマ違反や CSS の妥当性は検証できません。
• スパインはマニフェスト ID を参照する： スパイン内の idref は、マニフェスト内の id と一致する必要があります。参照が壊れていると、EPUB の検証に失敗します。
• ナビゲーションドキュメント： EPUB3 では properties="nav" を持つ NAV が必要です。これがないと、読み取りシステムで目次が表示されないことがあります。
• 言語の指定は必須： <dc:language> と、コンテンツドキュメントの xml:lang／lang 属性の両方が必要です。言語が指定されていない EPUB は無効です。

注意点

• 機能の検出を省略しないでください。 存在しないツールがあると思い込むと、パイプラインが壊れます。構築を始める前に必ず確認してください。
• LLM が利用できると思い込まないでください。 抽出には必ず --no-llm のフォールバックを用意してください。適切に構成された書籍では、ヒューリスティックモードが驚くほどうまく機能します。
• バックアップを取らずに EPUB を直接編集しないでください。 EPUB の編集は外科手術のようなものです。必ず元のファイルを保持してください。
• 同じセッションで同じファイルに EbookLib と epublib を混在させないでください。 メモリモデルが異なり、競合する可能性があります。タスクごとにライブラリを1つ選んでください。
• OPF が OEBPS/content.opf にあると思い込まないでください。 実際のパスを見つけるため、必ず container.xml を読んでください。ルートディレクトリは異なる場合があります。

参考資料

• references/epub-format-internals.md — 構造の詳細なリファレンス（OCF、OPF、XHTML、NCX/NAV、スパイン、3つのプレーン、コアメディアタイプ、EPUB2 と EPUB3）
• references/python-libraries.md — EbookLib と epublib の比較、コード例、使い分け、ライセンスに関する注意事項
• references/spec-and-validation.md — W3C EPUB 3.3 仕様へのアクセス方法、EPUBCheck の使い方、Ace によるアクセシビリティ検証、主な制約の概要
• references/tutorials-and-guides.md — 初心者向けから上級者向けまでのガイド、一般的なワークフロー、OPF の手動編集、一括操作、注意点
• references/agent-capability-discovery.md — エージェントツールを調査するためのプロトコル、抽出パイプラインの構築、各プラットフォームでの実例
• references/fixed-layout-epub.md — 固定レイアウトの検出とプロパティ（rendition:layout、orientation、spread、viewport メタデータ）
• references/accessibility.md — WCAG との整合性、代替テキスト、見出し階層、ARIA ロール、Ace の統合、アクセシビリティメタデータ
• references/media-overlays.md — SMIL 同期、音声とテキストの組み合わせ、スキップ可能性／離脱可能性、マニフェストからの検出
• references/apple-books-compatibility.md — 仕様を超える Apple Books のルール：OEBPS のレイアウト、表紙の XHTML ラッパー、CSS の慣例、スパインのパターン、独自の挙動
• references/llm-config-and-extraction.md — EPUB_LLM_* 環境変数の慣例、LLM とヒューリスティックによる抽出モード、ナレッジタイプの検出、プロンプトの設計、プラットフォームごとの出力先オプション