コンテンツにスキップ
NextPDF

マルチメディア：rendition、メディアクリップ、スクリーンパラメーター

概要

「概要」という見出しのセクション

マルチメディアモジュールは、PDF の rendition とそのメディアパラメーターを、イミュータブルな値オブジェクトとしてモデル化します。各オブジェクトはコンストラクターで ISO 32000-2 の不変条件を検証し、対応する PDF ディクショナリーへシリアライズします。ナビゲーションモジュールの rendition アクションは、その結果を参照します。

インストール

「インストール」という見出しのセクション
Terminal window
composer require nextpdf/core:^3

概念の概要

「概念の概要」という見出しのセクション

PDF の rendition は、再生可能なメディア（音声、動画、インタラクティブクリップ）と、ビューアーがそれを再生する条件を記述します。ISO 32000-2 §13.2 は、rendition とメディアオブジェクトのモデルを定義しています。このモジュールは、そのモデルに対応する、型付きで検証を行うエンコーダーです。すべてのクラスは final readonly の値オブジェクトです。コンストラクターでエントリーを受け取り、仕様の構造ルールをそこで強制し、toDictionary() から PDF ディクショナリー文字列を生成します。メディアの再生も、ファイルデータの埋め込みも行いません。Writer がシリアライズするディクショナリーを生成するだけです。

Rendition がルートです。Media Rendition (/MR) は、MediaClip と、オプションの再生パラメーターおよびスクリーンパラメーターを保持します。Selector Rendition (/SR) は、フォールバック用の rendition 参照を順序付きリストとして保持します。コンストラクターは、仕様上の相互排他を強制します。/MR はクリップを必須とし、セレクター参照を拒否します。/SR はクリップ、再生、スクリーンの各エントリーを拒否します。これにより、無効な rendition は構築できません。

MediaClip は、メディアデータまたはその一区間を表します。section サブタイプを使うと、rendition はデータをコピーせずに部分範囲を再生できます。MediaPlayInfo と MediaScreenInfo は、再生パラメーター (/P) とスクリーン表示 (/SP) を保持します。どちらも isEmpty() を公開しているため、仕様が空のディクショナリー生成ではなく省略を推奨している場合、呼び出し側はそのエントリーを省略できます。MediaCriteria は、必須遵守 (/MH) とベストエフォート (/BE) の要件セットを保持し、型付きサーフェスがモデル化しないエントリー用に extras エスケープハッチを備えています。モジュール全体が @since 2.3.0 です。

API サーフェス

「API サーフェス」という見出しのセクション
クラス主なメンバー役割
Rendition__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR/MR または /SR rendition オブジェクト (@since 2.3.0)
MediaClip__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTIONメディアクリップの data / section オブジェクト (@since 2.3.0)
MediaPlayInfotoDictionary(), isEmpty()/P 再生パラメーター (@since 2.3.0)
MediaScreenInfotoDictionary(), isEmpty()/SP スクリーンパラメーター (@since 2.3.0)
MediaCriteriatoDictionary(), isEmpty()/MH および /BE の要件セット (@since 2.3.0)

完全な PHPDoc テーブルについては composer docs:generate-api-php -- --module=Multimedia を実行してください。

コードサンプル — クイックスタート

「コードサンプル — クイックスタート」という見出しのセクション

埋め込み動画クリップ用の media rendition を構築します。

<?php


declare(strict_types=1);


require_once __DIR__ . '/../vendor/autoload.php';


use NextPDF\Multimedia\MediaClip;
use NextPDF\Multimedia\Rendition;


$clip = new MediaClip(
    subtype: MediaClip::SUBTYPE_DATA,
    dataRef: 42, // indirect object number of the embedded file specification
);


$rendition = new Rendition(
    subtype: Rendition::SUBTYPE_MEDIA,
    name: 'Intro Video',
    clip: $clip,
);


$dictionary = $rendition->toDictionary();

コードサンプル — 本番環境

「コードサンプル — 本番環境」という見出しのセクション

必須遵守とベストエフォートの基準を明示的に分けたうえで、順序付きチェーンによってフォールバックする selector rendition を構築します。

<?php


declare(strict_types=1);


require_once __DIR__ . '/../vendor/autoload.php';


use NextPDF\Multimedia\MediaCriteria;
use NextPDF\Multimedia\Rendition;


// Preferred rendition first, degraded fallback second.
$selector = new Rendition(
    subtype: Rendition::SUBTYPE_SELECTOR,
    name: 'Adaptive Media',
    mustHonour: new MediaCriteria(/* strict /MH requirements */),
    bestEffort: new MediaCriteria(/* soft /BE requirements */),
    selectorRefs: [51, 52], // indirect rendition object numbers, in evaluation order
);


$dictionary = $selector->toDictionary();

エッジケースと注意点

「エッジケースと注意点」という見出しのセクション
  • MediaClip を持たない /MR rendition は、コンストラクターで例外をスローします。これはランタイム警告ではなく、仕様上のルールです。クリップを指定して構築してください。
  • /SR rendition は、クリップ、再生、スクリーンの各エントリーを拒否します。2 つの rendition 形状を混在させることはプログラミングエラーであり、構築時に検出されます。
  • MediaPlayInfo::isEmpty() と MediaScreenInfo::isEmpty() があるため、空の /P や /SP を省略できます。仕様が省略を推奨している箇所で空のディクショナリーを生成することは、構造的には有効ですが無駄です。isEmpty() を確認してください。
  • rendition の /N 名には NUL バイトを含めてはなりません。コンストラクターはそれを拒否します。
  • selectorRefs は間接オブジェクト番号であり、それぞれ >= 1 です。このモジュールは参照を生成します。それらを実際のオブジェクトへ解決するのは Writer の役割です。

パフォーマンス

「パフォーマンス」という見出しのセクション

各 toDictionary() 呼び出しは、固定されたエントリー集合に対する線形の文字列構築であり、マイクロ秒スケールで I/O はありません。再現性プロファイルは bitwise です。同じ値オブジェクトは常に同じディクショナリーバイトを生成します。デフォルトの参照ワークロードは、1500 ms のウォール時間 / 64 MB のピークという予算に十分収まっています。マルチメディアディクショナリーは、参照先の埋め込みメディアに比べて小さなものです。

セキュリティに関する注意

「セキュリティに関する注意」という見出しのセクション

このモジュールはディクショナリー構造を生成します。メディアデータの埋め込みや送信は行いません。MediaClip が参照する埋め込みファイル仕様は、ナビゲーションのファイル添付サーフェスによって生成され、そこで埋め込みバイトの範囲が制限され、検証されます。ユーザー入力に由来するメディアファイル名や rendition 名は、信頼できないテキストとして扱ってください。コンストラクターは NUL バイトを拒否しますが、有効な文字列の意味的内容までは検査しません。エンジンの脅威モデルについては /modules/core/security/ を参照してください。

準拠

「準拠」という見出しのセクション

このモジュールが生成するディクショナリーは、media-clip の data エントリーと section エントリーを含め、ISO 32000-2 §13.2 の rendition とメディアオブジェクトのモデルに従います。テーブルごとのエントリーマッピングは、§13.2 のテーブル番号に対応する形で src/Multimedia/ 内にインラインで文書化されており、tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest) によって検証されています。これらは実装上の事実であり、エンドツーエンドの PDF 2.0 準拠を表明するものではありません。ドキュメント全体の準拠は、/modules/core/conformance/ に記載されているオラクルおよびゴールデンスイートによって検証されます。

関連情報

「関連情報」という見出しのセクション