Перейти к содержимому
NextPDF

Мультимедиа: параметры rendition, медиаклипа и экрана

Кратко

Заголовок раздела «Кратко»

Модуль Multimedia моделирует rendition в формате Portable Document Format (PDF) и связанные медиапараметры как неизменяемые объекты-значения. Каждый объект проверяет инварианты ISO 32000-2 в конструкторе, а затем сериализуется в соответствующий словарь PDF. Действие rendition из модуля Navigation ссылается на этот словарь.

Установка

Заголовок раздела «Установка»
Окно терминала
composer require nextpdf/core:^3

Концептуальный обзор

Заголовок раздела «Концептуальный обзор»

В PDF rendition описывает воспроизводимый медиаконтент — например, аудио, видео или интерактивный клип — и условия, при которых средство просмотра запускает его воспроизведение. ISO 32000-2 §13.2 определяет модель rendition и медиаобъектов. Этот модуль — типизированный кодировщик этой модели с проверками. Каждый класс — объект-значение final readonly: он принимает записи в конструкторе, применяет структурные правила спецификации и выдаёт строку словаря PDF из toDictionary(). Модуль не воспроизводит медиаконтент и не встраивает данные файлов. Он формирует словарь, который затем сериализует модуль 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Объект данных / фрагмента медиаклипа (@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.

Пример кода — быстрый старт

Заголовок раздела «Пример кода — быстрый старт»

Создайте 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();

Граничные случаи и подводные камни

Заголовок раздела «Граничные случаи и подводные камни»
  • Rendition /MR без MediaClip выбрасывает исключение в конструкторе. Это требование спецификации, а не предупреждение времени выполнения. Создавайте его сразу с клипом.
  • Rendition /SR отклоняет записи клипа, воспроизведения и экрана. Смешивание двух форм rendition — ошибка программирования, которая обнаруживается при создании.
  • Используйте MediaPlayInfo::isEmpty() и MediaScreenInfo::isEmpty(), чтобы опустить пустой /P или /SP. Создание пустого словаря там, где спецификация рекомендует пропустить запись, структурно допустимо, но расточительно; проверяйте isEmpty().
  • Имя rendition /N не должно содержать байт NUL. Конструктор отклоняет такое имя.
  • selectorRefs — это номера косвенных объектов, каждый >= 1. Модуль выдаёт ссылки; их разрешение в реальные объекты — это задача модуля Writer.

Производительность

Заголовок раздела «Производительность»

Каждый вызов toDictionary() линейно строит строку из фиксированного набора записей. Он выполняется за микросекунды и не выполняет операций ввода-вывода input/output (I/O). Профиль воспроизводимости — bitwise: один и тот же объект-значение всегда выдаёт одни и те же байты словаря. Эталонная нагрузка по умолчанию с большим запасом укладывается в бюджет 1500 ms по времени / 64 MB по пиковой памяти. Словари Multimedia малы по сравнению со встроенным медиаконтентом, на который они ссылаются.

Замечания по безопасности

Заголовок раздела «Замечания по безопасности»

Этот модуль выдаёт структуру словаря; он не встраивает и не передаёт медиаданные. Поверхность файловых вложений модуля Navigation формирует спецификацию встроенного файла, на которую ссылается MediaClip, а также ограничивает и проверяет встроенные байты. Рассматривайте любое имя медиафайла или имя rendition из пользовательского ввода как недоверенный текст. Конструктор отклоняет байты NUL, но не проверяет смысловое содержимое допустимой строки. См. модель угроз движка в /modules/core/security/.

Соответствие

Заголовок раздела «Соответствие»

Словари, выдаваемые этим модулем, следуют модели rendition и медиаобъектов из ISO 32000-2 §13.2, включая записи данных и фрагментов медиаклипа. Сопоставления записей с таблицами задокументированы непосредственно в src/Multimedia/ с привязкой к номерам таблиц §13.2 и покрыты tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Это факты реализации, а не заявление о сквозном соответствии PDF 2.0; наборы oracle и golden, описанные в /modules/core/conformance/, проверяют соответствие на уровне всего документа.

См. также

Заголовок раздела «См. также»