跳到內容
NextPDF

多媒體：呈現、媒體片段與螢幕參數

速覽

標題為「速覽」的區段

多媒體模組會將 PDF 呈現及其媒體參數建模為不可變值物件。每個物件都會在建構式中驗證自身的 ISO 32000-2 不變量，並序列化為對應的 PDF 字典。導覽模組的呈現動作會參考這些結果。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/core:^3

概念總覽

標題為「概念總覽」的區段

PDF 呈現描述一段可播放的媒體——音訊、視訊或互動式片段——以及檢視器播放該媒體的條件。ISO 32000-2 §13.2 定義了呈現與媒體物件模型。本模組是該模型的型別化驗證編碼器。每個類別都是 final readonly 值物件：它會在建構式中接收各個項目，於此強制套用規格的結構規則，並從 toDictionary() 輸出一個 PDF 字典字串。它並不播放媒體，也不內嵌檔案資料，而是產生 Writer 用來序列化的字典。

Rendition 是根節點。媒體呈現（/MR）攜帶一個 MediaClip，以及選用的播放與螢幕參數。選擇器呈現（/SR）攜帶一份依序排列的後備呈現參考清單。建構式會強制套用規格的互斥規則——/MR 必須有片段且拒絕選擇器參考，/SR 拒絕片段、播放與螢幕項目——因此無法建構出無效的呈現。

MediaClip 是媒體資料或其中的一段。區段子類型讓呈現得以播放某個子範圍，而無需複製資料。MediaPlayInfo 與 MediaScreenInfo 攜帶播放參數（/P）與螢幕呈現（/SP）。兩者都公開了 isEmpty()，因此當規格建議省略而非輸出一個空字典時，呼叫方可以省略該項目。MediaCriteria 攜帶必須遵守（/MH）與盡力而為（/BE）的需求集合，並以 extras 作為逸出口，容納型別化介面尚未建模的項目。整個模組為 @since 2.3.0。

API 介面

標題為「API 介面」的區段
類別主要成員角色
Rendition__construct(...)、toDictionary()、SUBTYPE_MEDIA、SUBTYPE_SELECTOR/MR 或 /SR 呈現物件（@since 2.3.0）
MediaClip__construct(...)、toDictionary()、SUBTYPE_DATA、SUBTYPE_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）

請執行 composer docs:generate-api-php -- --module=Multimedia 取得完整的 PHPDoc 表格。

程式碼範例——快速上手

標題為「程式碼範例——快速上手」的區段

替內嵌的視訊片段建構一個媒體呈現。

<?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();

程式碼範例——正式環境

標題為「程式碼範例——正式環境」的區段

建構一個選擇器呈現，使其透過一條有序的後備鏈依序降級，並明確區分必須遵守與盡力而為的準則。

<?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 呈現會在建構式中擲出例外——這是規格要求，而非執行期警告。建構時請一併提供片段。
  • 一個 /SR 呈現會拒絕片段、播放與螢幕項目。混用這兩種呈現型態是一種程式設計錯誤，會在建構時被攔截。
  • MediaPlayInfo::isEmpty() 與 MediaScreenInfo::isEmpty() 用來讓你省略空的 /P 或 /SP。在規格建議省略之處輸出一個空字典，結構上有效但浪費——請檢查 isEmpty()。
  • 呈現的 /N 名稱不得包含 NUL 位元組；建構式會拒絕它。
  • selectorRefs 是間接物件編號，每個皆 >= 1。本模組輸出這些參考；將它們解析為實際物件則是 Writer 的工作。

效能

標題為「效能」的區段

每次 toDictionary() 呼叫都是針對一組固定項目進行線性字串建構——微秒等級，且無 I/O。重現性設定檔為 bitwise：相同的值物件永遠輸出相同的字典位元組。預設參考工作負載穩定落在 1500 ms 牆鐘/64 MB 峰值的預算之內。相較於多媒體所參考的內嵌媒體，這些字典都很小。

安全性注意事項

標題為「安全性注意事項」的區段

本模組輸出字典結構；它並不內嵌或傳輸媒體資料。MediaClip 所參考的內嵌檔案規格，是由導覽的檔案附件介面所產生，該介面會限定並驗證內嵌的位元組。請將任何來自使用者輸入的媒體檔名或呈現名稱視為不可信任文字。建構式會拒絕 NUL 位元組，但並不審查有效字串的語意內容。請參閱 /modules/core/security/ 中的引擎威脅模型。

符合性

標題為「符合性」的區段

本模組輸出的字典遵循 ISO 32000-2 §13.2 中的呈現與媒體物件模型，包括媒體片段資料與區段項目。各表格的逐項對應已內嵌記錄於 src/Multimedia/，對照 §13.2 表格編號，並由 tests/Unit/Multimedia/（RenditionTest、MediaClipTest、MediaCriteriaTest、MediaPlayInfoTest、MediaScreenInfoTest）所驗證。這些是實作事實，而非端對端 PDF 2.0 符合性的聲明；完整文件的符合性是由 /modules/core/conformance/ 中所述的 oracle 與黃金套件驗證。

另請參閱

標題為「另請參閱」的區段