Multimedia: Rendition-, Media-Clip- und Screen-Parameter

Auf einen Blick

Das Multimedia-Modul bildet PDF-Renditions und ihre Medienparameter als unveränderliche Value Objects ab. Jedes Objekt validiert die ISO 32000-2-Invarianten im Konstruktor und serialisiert sich selbst in das entsprechende PDF-Dictionary. Die Rendition-Action des Navigation-Moduls referenziert das Ergebnis.

Geltungsbereich: nur das Rendition-Objektmodell

Dieses Modul ist das Rendition-Objektmodell — der typisierte Encoder für die Rendition-, MediaClip- und Medienparameter-Dictionaries nach ISO 32000-2 §13.2. Die End-to-End-Rendition-Action der Screen-Annotation (die §12.5.6.18- / §13-Schnittstelle, die eine Rendition zur Wiedergabe an eine Screen-Annotation bindet) wird in diesem Release noch nicht unterstützt oder verifiziert. Die veralteten Medien-Annotationstypen (3D, RichMedia, Sound, Movie; siehe ISO 32000-2 §12.5.2) liegen ebenfalls außerhalb des Geltungsbereichs. Verwenden Sie die nachfolgenden Strukturobjekte zum Beschreiben und Erstellen; verlassen Sie sich nicht auf eine abspielbare Screen-Annotation-Action.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Eine PDF-Rendition beschreibt ein abspielbares Medienelement — Audio, Video oder einen interaktiven Clip — sowie die Bedingungen, unter denen ein Viewer es abspielt. ISO 32000-2 §13.2 definiert das Rendition- und Medienobjektmodell. Dieses Modul ist der typisierte, validierende Encoder für dieses Modell. Jede Klasse ist ein final readonly Value Object: Sie nimmt ihre Einträge im Konstruktor entgegen, erzwingt dort die strukturellen Regeln der Spezifikation und gibt über toDictionary() einen PDF-Dictionary-String aus. Das Modul spielt keine Medien ab und bettet keine Dateidaten ein — es erzeugt nur das Dictionary, das der Writer serialisiert.

Rendition bildet die Wurzel. Eine Media-Rendition (/MR) enthält einen MediaClip sowie optionale Play- und Screen-Parameter. Eine Selector-Rendition (/SR) enthält eine geordnete Liste von Fallback-Rendition-Referenzen. Der Konstruktor erzwingt die gegenseitigen Ausschlussregeln der Spezifikation — eine /MR erfordert einen Clip und lehnt Selector-Referenzen ab, eine /SR lehnt Clip-, Play- und Screen-Einträge ab — sodass eine ungültige Rendition nicht konstruiert werden kann.

MediaClip steht für die Mediendaten oder einen Abschnitt davon. Der Section-Subtype ermöglicht einer Rendition, einen Teilbereich abzuspielen, ohne die Daten zu kopieren. MediaPlayInfo und MediaScreenInfo enthalten die Play-Parameter (/P) und die Screen-Darstellung (/SP). Beide stellen isEmpty() bereit, damit ein Aufrufer den Eintrag weglassen kann, wenn die Spezifikation das empfiehlt, statt ein leeres Dictionary auszugeben. MediaCriteria enthält die zwingend einzuhaltenden (/MH) und die nach bestem Bemühen geltenden (/BE) Anforderungssätze mit extras als Ausweichpfad für Einträge, die die typisierte Schnittstelle nicht modelliert. Das gesamte Modul ist @since 2.3.0.

API-Oberfläche

Klasse	Wichtige Member	Rolle
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	/MR- oder /SR-Rendition-Objekt (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Media-Clip-Daten- / Section-Objekt (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	/P-Play-Parameter (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	/SP-Screen-Parameter (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	/MH- und /BE-Anforderungssätze (@since 2.3.0)

Führen Sie composer docs:generate-api-php -- --module=Multimedia aus, um die vollständige PHPDoc-Tabelle zu erhalten.

Codebeispiel — Schnellstart

Erstellen Sie eine Media-Rendition für einen eingebetteten 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();

Codebeispiel — Produktion

Erstellen Sie eine Selector-Rendition mit geordneter Fallback-Kette, bei der die zwingend einzuhaltenden und die nach bestem Bemühen geltenden Kriterien explizit getrennt sind.

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

Grenzfälle & Fallstricke

• Eine /MR-Rendition ohne MediaClip löst im Konstruktor eine Ausnahme aus — dies ist eine Spezifikationsregel, keine Laufzeitwarnung. Konstruieren Sie sie mit dem Clip.
• Eine /SR-Rendition lehnt Clip-, Play- und Screen-Einträge ab. Das Vermischen der beiden Rendition-Formen ist ein Programmierfehler, der während der Konstruktion abgefangen wird.
• MediaPlayInfo::isEmpty() und MediaScreenInfo::isEmpty() sind dafür vorgesehen, dass Sie ein leeres /P oder /SP weglassen können. Das Ausgeben eines leeren Dictionarys dort, wo die Spezifikation das Weglassen empfiehlt, ist strukturell gültig, aber unnötig — prüfen Sie isEmpty().
• Ein /N-Name einer Rendition darf kein NUL-Byte enthalten; der Konstruktor lehnt ihn ab.
• selectorRefs sind indirekte Objektnummern, jeweils >= 1. Das Modul gibt die Referenzen aus; ihre Auflösung zu konkreten Objekten ist Aufgabe des Writers.

Performance

Jeder Aufruf von toDictionary() baut linear einen String aus einer festen Menge von Einträgen auf — im Mikrosekundenbereich, ohne I/O. Das Reproduzierbarkeitsprofil ist bitwise: Dasselbe Value Object gibt stets dieselben Dictionary-Bytes aus. Die Standard-Referenzlast liegt deutlich innerhalb des Budgets von 1500 ms Laufzeit / 64 MB Spitzenwert. Multimedia-Dictionaries sind klein im Verhältnis zu den eingebetteten Medien, die sie referenzieren.

Sicherheitshinweise

Dieses Modul gibt Dictionary-Struktur aus; es bettet keine Mediendaten ein und überträgt keine. Die Embedded-File-Specification, die ein MediaClip referenziert, wird von der Dateianhangsschnittstelle des Navigation-Moduls erzeugt, die die eingebetteten Bytes begrenzt und validiert. Behandeln Sie jeden Mediendateinamen oder Rendition-Namen, der aus Benutzereingaben stammt, als nicht vertrauenswürdigen Text. Der Konstruktor lehnt NUL-Bytes ab, prüft aber nicht den semantischen Inhalt eines gültigen Strings. Siehe das Bedrohungsmodell der Engine unter /modules/core/security/.

Konformität

Die von diesem Modul ausgegebenen Dictionaries folgen dem Rendition- und Medienobjektmodell in ISO 32000-2 §13.2, einschließlich der Media-Clip-Daten- und Section-Einträge. Die Zuordnungen der einzelnen Tabelleneinträge sind in src/Multimedia/ inline mit Bezug auf die §13.2-Tabellennummern dokumentiert und werden durch tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest) abgedeckt. Dies sind Implementierungsfakten, keine Aussage über die End-to-End-PDF-2.0-Konformität; die Konformität des gesamten Dokuments wird durch die Oracle- und Golden-Suiten validiert, die in /modules/core/conformance/ beschrieben sind.

Siehe auch

• Navigation-Modul — die Rendition-Action, die diese Objekte referenzieren würde (Screen-Annotation-Rendition-Action noch nicht unterstützt; siehe den Geltungsbereichshinweis oben).
• Writer-Modul — serialisiert die ausgegebenen Dictionaries.
• Konformitätsüberblick
• Sicherheitsmodell der Engine