跳转到内容
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 与黄金套件验证。

另请参阅

标题为“另请参阅”的章节