Multimedia: parametry obiektu rendition, klipu medialnego i ekranu

W skrócie

Moduł Multimedia odwzorowuje obiekt rendition w formacie Portable Document Format (PDF) oraz jego parametry medialne jako niezmienne obiekty wartości. Każdy obiekt w konstruktorze sprawdza własne niezmienniki zgodne z ISO 32000-2, a następnie serializuje się do odpowiedniego słownika PDF. Akcja rendition w module Navigation odwołuje się do tego słownika.

Zakres: tylko model obiektowy rendition

Ten moduł udostępnia model obiektowy rendition: typowany koder dla słowników Rendition / MediaClip / parametrów medialnych z ISO 32000-2 §13.2. Pełna akcja rendition dla adnotacji typu Screen (interfejs z §12.5.6.18 / §13, który wiąże obiekt rendition z adnotacją ekranową na potrzeby odtwarzania) nie jest jeszcze obsługiwana ani zweryfikowana w tym wydaniu. Przestarzałe typy adnotacji medialnych (3D, RichMedia, Sound, Movie; zobacz ISO 32000-2 §12.5.2) również są poza zakresem. Użyj poniższych obiektów strukturalnych, aby opisać i zbudować model; nie polegaj na odtwarzalnej akcji adnotacji typu Screen.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Obiekt rendition w PDF opisuje odtwarzalne media, takie jak dźwięk, wideo lub interaktywny klip, oraz warunki, w których przeglądarka je odtwarza. ISO 32000-2 §13.2 definiuje model obiektu rendition i obiektu medialnego. Ten moduł zapewnia typowany, walidujący koder dla tego modelu. Każda klasa jest obiektem wartości final readonly: przyjmuje wpisy w konstruktorze, egzekwuje w nim reguły strukturalne specyfikacji i emituje ciąg słownika PDF w metodzie toDictionary(). Nie odtwarza mediów ani nie osadza danych plików. Tworzy słownik serializowany później przez moduł Writer.

Rendition jest obiektem głównym. Media Rendition (/MR) zawiera obiekt MediaClip oraz opcjonalne parametry odtwarzania i ekranu. Selector Rendition (/SR) zawiera uporządkowaną listę odwołań do zapasowych obiektów rendition. Konstruktor wymusza wzajemne wykluczenia opisane w specyfikacji: /MR wymaga klipu i odrzuca odwołania selektora, natomiast /SR odrzuca wpisy klipu, odtwarzania i ekranu. W rezultacie nie można utworzyć nieprawidłowego obiektu rendition.

MediaClip reprezentuje dane medialne lub ich fragment. Podtyp section pozwala obiektowi rendition odtworzyć podzakres bez kopiowania danych. MediaPlayInfo oraz MediaScreenInfo zawierają parametry odtwarzania (/P) oraz prezentację na ekranie (/SP). Oba udostępniają metodę isEmpty(), dzięki czemu można pominąć wpis, gdy specyfikacja zaleca pominięcie zamiast pustego słownika. MediaCriteria zawiera zestawy wymagań bezwzględnych (/MH) i najlepszego dostępnego rezultatu (/BE), wraz z mechanizmem extras dla wpisów, których typowany interfejs nie modeluje. Cały moduł jest oznaczony @since 2.3.0.

Interfejs API

Klasa	Kluczowe składowe	Rola
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	Obiekt rendition /MR lub /SR (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Obiekt danych lub fragmentu klipu medialnego (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	Parametry odtwarzania /P (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	Parametry ekranu /SP (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	Zestawy wymagań /MH i /BE (@since 2.3.0)

Uruchom composer docs:generate-api-php -- --module=Multimedia, aby wygenerować pełną tabelę PHPDoc.

Przykład kodu — szybki start

Zbuduj obiekt media rendition dla osadzonego klipu wideo.

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

Przykład kodu — środowisko produkcyjne

Zbuduj obiekt selector rendition, który używa uporządkowanego łańcucha zapasowego i jawnie rozdziela kryteria bezwzględne oraz najlepszego dostępnego rezultatu.

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

Przypadki brzegowe i pułapki

• Obiekt rendition /MR bez MediaClip zgłasza wyjątek w konstruktorze. Jest to reguła specyfikacji, a nie ostrzeżenie czasu wykonania. Utwórz go wraz z klipem.
• Obiekt rendition /SR odrzuca wpisy klipu, odtwarzania i ekranu. Mieszanie tych dwóch postaci obiektu rendition jest błędem programistycznym wychwytywanym podczas tworzenia obiektu.
• Użyj MediaPlayInfo::isEmpty() oraz MediaScreenInfo::isEmpty(), aby pominąć puste /P lub /SP. Emitowanie pustego słownika tam, gdzie specyfikacja zaleca pominięcie, jest strukturalnie prawidłowe, ale rozrzutne; sprawdź isEmpty().
• Nazwa /N obiektu rendition nie może zawierać bajtu NUL. Konstruktor ją odrzuca.
• selectorRefs to numery obiektów pośrednich, każdy >= 1. Moduł emituje odwołania; za ich rozwiązywanie do działających obiektów odpowiada moduł Writer.

Wydajność

Każde wywołanie toDictionary() buduje ciąg liniowo na podstawie stałego zestawu wpisów. Działa w skali mikrosekund i nie wykonuje żadnych operacji wejścia/wyjścia (I/O). Profil powtarzalności to bitwise: ten sam obiekt wartości zawsze emituje te same bajty słownika. Domyślne obciążenie referencyjne pozostaje z dużym zapasem w ramach budżetu 1500 ms czasu rzeczywistego / 64 MB szczytowego zużycia pamięci. Słowniki multimedialne są małe w stosunku do osadzonych mediów, do których się odwołują.

Uwagi dotyczące bezpieczeństwa

Ten moduł emituje strukturę słownika; nie osadza ani nie przesyła danych medialnych. Interfejs załączników plików w module Navigation tworzy specyfikację osadzonego pliku, do której odwołuje się MediaClip, oraz ogranicza i sprawdza osadzone bajty. Każdą nazwę pliku medialnego lub nazwę obiektu rendition pochodzącą z danych wejściowych użytkownika traktuj jako niezaufany tekst. Konstruktor odrzuca bajty NUL, ale nie weryfikuje semantycznej zawartości prawidłowego ciągu. Model zagrożeń silnika znajdziesz w /modules/core/security/.

Zgodność

Słowniki emitowane przez ten moduł są zgodne z modelem obiektu rendition i obiektu medialnego z ISO 32000-2 §13.2, włącznie z wpisami danych i fragmentów klipu medialnego. Odwzorowania wpisów dla poszczególnych tabel są udokumentowane bezpośrednio w kodzie w src/Multimedia/ względem numerów tabel z §13.2 i pokryte przez tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Są to fakty implementacyjne, a nie deklaracja kompleksowej zgodności z PDF 2.0; pełną zgodność dokumentu weryfikują zestawy oracle i golden opisane w /modules/core/conformance/.

Zobacz także

• Moduł Navigation — akcja rendition, która odwoływałaby się do tych obiektów. Akcja rendition dla adnotacji typu Screen nie jest jeszcze obsługiwana; zobacz uwagę o zakresie powyżej.
• Moduł Writer — serializuje emitowane słowniki.
• Przegląd zgodności
• Model bezpieczeństwa silnika