Multimedia: rendition, media-clip en schermparameters

In het kort

De Multimedia-module modelleert een Portable Document Format (PDF)-rendition en de bijbehorende mediaparameters als immutable value objects. Elk object valideert zijn ISO 32000-2-invarianten in de constructor en serialiseert zichzelf vervolgens naar de bijbehorende PDF-dictionary. De rendition-action in de Navigation-module verwijst naar die dictionary.

Reikwijdte: alleen het rendition-objectmodel

Deze module biedt het rendition-objectmodel: de getypeerde encoder voor de ISO 32000-2 §13.2-dictionaries voor Rendition / MediaClip / mediaparameters. De end-to-end rendition-action voor Screen-annotations (het §12.5.6.18 / §13-oppervlak dat een rendition voor afspelen aan een screen-annotation bindt) wordt in deze release nog niet ondersteund of geverifieerd. De verouderde media-annotatietypen (3D, RichMedia, Sound, Movie; zie ISO 32000-2 §12.5.2) vallen eveneens buiten de reikwijdte. Gebruik de structurele objecten hieronder om het model te beschrijven en op te bouwen; vertrouw niet op een afspeelbare Screen-annotation-action.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Een PDF-rendition beschrijft afspeelbare media, zoals audio, video of een interactieve clip, en de voorwaarden waaronder een viewer die afspeelt. ISO 32000-2 §13.2 definieert het rendition- en media-objectmodel. Deze module is de getypeerde, validerende encoder voor dat model. Elke klasse is een final readonly value object: deze accepteert entries in de constructor, dwingt daar de structurele regels van de specificatie af en levert via toDictionary() een PDF-dictionarystring op. De module speelt geen media af en sluit geen bestandsdata in. Ze produceert de dictionary die de Writer serialiseert.

Rendition is de root. Een Media Rendition (/MR) bevat een MediaClip en optionele afspeel- en schermparameters. Een Selector Rendition (/SR) bevat een geordende lijst met fallback-rendition-referenties. De constructor dwingt de wederzijdse uitsluitingen uit de specificatie af: een /MR vereist een clip en weigert selector-referenties, en een /SR weigert clip-, afspeel- en schermentries. Daardoor kan een ongeldige rendition niet worden geconstrueerd.

MediaClip vertegenwoordigt de mediadata of een sectie daarvan. Met het section-subtype kan een rendition een subbereik afspelen zonder de data te kopiëren. MediaPlayInfo en MediaScreenInfo bevatten de afspeelparameters (/P) en de schermpresentatie (/SP). Beide stellen isEmpty() beschikbaar, zodat je de entry kunt weglaten wanneer de specificatie aanraadt om geen lege dictionary te gebruiken. MediaCriteria bevat de must-honour- (/MH) en best-effort- (/BE) vereistensets, met een extras-noodluik voor entries die het getypeerde oppervlak niet modelleert. De volledige module is @since 2.3.0.

API-oppervlak

Klasse	Belangrijkste members	Rol
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	/MR- of /SR-rendition-object (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Media-clip-data- / section-object (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	/P afspeelparameters (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	/SP schermparameters (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	/MH- en /BE-vereistensets (@since 2.3.0)

Voer composer docs:generate-api-php -- --module=Multimedia uit om de volledige PHPDoc-tabel te genereren.

Codevoorbeeld — Snelstart

Bouw een media-rendition voor een ingebedde videoclip.

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

Codevoorbeeld — Productie

Bouw een selector-rendition die een geordende fallback-keten volgt en de must-honour- en best-effort-criteria expliciet scheidt.

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

Randgevallen en valkuilen

• Een /MR-rendition zonder een MediaClip gooit een exception in de constructor. Dit is een regel uit de specificatie, geen runtime-waarschuwing. Construeer de rendition met de clip.
• Een /SR-rendition weigert clip-, afspeel- en schermentries. Het mengen van de twee rendition-vormen is een programmeerfout die bij de constructie wordt opgevangen.
• Gebruik MediaPlayInfo::isEmpty() en MediaScreenInfo::isEmpty() om een lege /P of /SP weg te laten. Een lege dictionary uitgeven wanneer de specificatie aanraadt de entry weg te laten is structureel geldig maar verspillend; controleer isEmpty().
• Een rendition-/N-naam mag geen NUL-byte bevatten. De constructor weigert die.
• selectorRefs zijn indirecte objectnummers, elk >= 1. De module geeft de referenties uit; het oplossen ervan naar live objecten is de taak van de Writer.

Prestaties

Elke toDictionary()-aanroep bouwt lineair een string op uit een vaste set entries. De aanroep draait op microseconde-schaal en voert geen input/output (I/O) uit. Het reproduceerbaarheidsprofiel is bitwise: hetzelfde value object levert altijd dezelfde dictionarybytes op. De standaardreferentie-workload blijft ruim binnen het budget van 1500 ms wall / 64 MB piek. Multimedia-dictionaries zijn klein in verhouding tot de ingebedde media waarnaar ze verwijzen.

Beveiligingsnotities

Deze module geeft dictionarystructuur uit; ze sluit geen mediadata in en verzendt die niet. Het file-attachment-oppervlak van Navigation produceert de embedded file specification waarnaar een MediaClip verwijst, en begrenst en valideert de ingebedde bytes. Behandel elke mediabestandsnaam of rendition-naam uit gebruikersinvoer als niet-vertrouwde tekst. De constructor weigert NUL-bytes, maar controleert de semantische inhoud van een geldige string niet. Zie het threat model van de engine in /modules/core/security/.

Conformiteit

De dictionaries die deze module uitgeeft, volgen het rendition- en media-objectmodel in ISO 32000-2 §13.2, inclusief de media-clip-data- en section-entries. De mappings per tabelentry zijn inline gedocumenteerd in src/Multimedia/ aan de hand van de §13.2-tabelnummers en gedekt door tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Dit zijn implementatiefeiten, geen verklaring van end-to-end PDF 2.0-conformiteit; de oracle- en golden-suites die worden beschreven in /modules/core/conformance/ valideren de conformiteit van het volledige document.

Zie ook

• Navigation-module — de rendition-action die naar deze objecten zou verwijzen. De rendition-action voor Screen-annotations wordt nog niet ondersteund; zie de reikwijdte-opmerking hierboven.
• Writer-module — serialiseert de uitgegeven dictionaries.
• Conformiteitsoverzicht
• Beveiligingsmodel van de engine