Multimedia: rendition, media clip e parametri dello schermo

In sintesi

Il modulo Multimedia modella le rendition PDF e i relativi parametri multimediali come value object immutabili. Ogni oggetto convalida nel costruttore le proprie invarianti ISO 32000-2 e si serializza nel dizionario PDF corrispondente. L’azione di rendition del modulo Navigation fa riferimento all’output prodotto.

Ambito: solo modello a oggetti della rendition

Questo modulo è il modello a oggetti della rendition: l’encoder tipizzato per i dizionari ISO 32000-2 §13.2 Rendition / MediaClip / dei parametri multimediali. L’azione di rendition end-to-end per l’annotazione Screen (la superficie §12.5.6.18 / §13 che collega una rendition a un’annotazione Screen per la riproduzione) non è ancora supportata né verificata in questa release. Anche i tipi di annotazione multimediale deprecati (3D, RichMedia, Sound, Movie; vedere ISO 32000-2 §12.5.2) restano fuori ambito. Descrivere e costruire soltanto gli oggetti strutturali riportati sotto; non fare affidamento su un’azione Screen-annotation riproducibile.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Una rendition PDF descrive un elemento multimediale riproducibile, ad esempio audio, video o una clip interattiva, e le condizioni in cui un visualizzatore lo riproduce. ISO 32000-2 §13.2 definisce il modello a oggetti della rendition e del media. Questo modulo fornisce l’encoder tipizzato e convalidato per quel modello. Ogni classe è un value object final readonly: riceve le proprie voci nel costruttore, vi applica le regole strutturali della specifica ed emette una stringa di dizionario PDF da toDictionary(). Non riproduce media e non incorpora dati di file: produce il dizionario che il Writer serializza.

Rendition è la radice. Una Media Rendition (/MR) contiene un MediaClip e parametri opzionali di riproduzione e dello schermo. Una Selector Rendition (/SR) contiene un elenco ordinato di riferimenti a rendition di fallback. Il costruttore applica le esclusioni reciproche previste dalla specifica: una /MR richiede una clip e rifiuta i riferimenti del selettore; una /SR rifiuta le voci di clip, riproduzione e schermo. In questo modo non è possibile costruire una rendition non valida.

MediaClip rappresenta il dato multimediale o una sua sezione. Il sottotipo sezione consente a una rendition di riprodurre un sottointervallo senza copiare i dati. MediaPlayInfo e MediaScreenInfo contengono i parametri di riproduzione (/P) e di presentazione a schermo (/SP). Entrambi espongono isEmpty(), così il chiamante può omettere la voce quando la specifica raccomanda l’omissione anziché emettere un dizionario vuoto. MediaCriteria contiene gli insiemi di requisiti obbligatori (/MH) e best-effort (/BE), con una via di fuga extras per le voci che la superficie tipizzata non modella. L’intero modulo è @since 2.3.0.

Superficie API

Classe	Membri chiave	Ruolo
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	Oggetto rendition /MR o /SR (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Oggetto dati / sezione del media clip (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	Parametri di riproduzione /P (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	Parametri dello schermo /SP (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	Insiemi di requisiti /MH e /BE (@since 2.3.0)

Per la tabella PHPDoc completa, eseguire composer docs:generate-api-php -- --module=Multimedia.

Esempio di codice — Avvio rapido

Costruire una media rendition per una clip video incorporata.

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

Esempio di codice — Produzione

Costruire una selector rendition con fallback lungo una catena ordinata, mantenendo esplicitamente separati i criteri obbligatori e best-effort.

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

Casi limite e insidie

• Una rendition /MR senza un MediaClip solleva un’eccezione nel costruttore: è una regola della specifica, non un avviso a runtime. Costruirla con la clip.
• Una rendition /SR rifiuta le voci di clip, riproduzione e schermo. Mescolare le due forme di rendition è un errore di programmazione, rilevato in fase di costruzione.
• MediaPlayInfo::isEmpty() e MediaScreenInfo::isEmpty() esistono per poter omettere un /P o /SP vuoto. Emettere un dizionario vuoto quando la specifica raccomanda l’omissione è strutturalmente valido ma dispendioso: controllare isEmpty().
• Il nome /N di una rendition non deve contenere un byte NUL; il costruttore lo rifiuta.
• Gli elementi di selectorRefs sono numeri di oggetto indiretto, ciascuno >= 1. Il modulo emette i riferimenti; risolverli in oggetti effettivi è compito del Writer.

Prestazioni

Ogni chiamata a toDictionary() costruisce una stringa in modo lineare su un insieme fisso di voci: richiede microsecondi e non esegue I/O. Il profilo di riproducibilità è bitwise: lo stesso value object emette sempre gli stessi byte di dizionario. Il workload di riferimento predefinito rientra ampiamente nel budget di 1500 ms wall / 64 MB di picco. I dizionari multimediali sono piccoli rispetto al contenuto multimediale incorporato a cui fanno riferimento.

Note sulla sicurezza

Questo modulo emette la struttura del dizionario; non incorpora né trasmette dati multimediali. La specifica del file incorporato a cui un MediaClip fa riferimento è prodotta dalla superficie degli allegati file del modulo Navigation, che delimita e convalida i byte incorporati. Trattare qualsiasi nome di file multimediale o nome di rendition proveniente da input utente come testo non attendibile. Il costruttore rifiuta i byte NUL ma non verifica il contenuto semantico di una stringa valida. Vedere il modello di minaccia del motore in /modules/core/security/.

Conformità

I dizionari emessi da questo modulo seguono il modello a oggetti della rendition e del media in ISO 32000-2 §13.2, comprese le voci di dati e di sezione del media clip. Le mappature delle voci per tabella sono documentate inline in src/Multimedia/ con riferimento ai numeri di tabella §13.2 e coperte da tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Si tratta di dettagli di implementazione, non di un’attestazione di conformità PDF 2.0 end-to-end; la conformità dell’intero documento è convalidata dalle suite oracle e golden descritte in /modules/core/conformance/.

Vedere anche

• Modulo Navigation — l’azione di rendition che farebbe riferimento a questi oggetti (azione di rendition Screen-annotation non ancora supportata; vedere la nota sull’ambito sopra).
• Modulo Writer — serializza i dizionari emessi.
• Panoramica della conformità
• Modello di sicurezza del motore