Multimédia : rendition, clip multimédia et paramètres d'écran

En un coup d’œil

Le module Multimedia modélise une rendition PDF et ses paramètres multimédias sous forme d’objets-valeurs immuables. Chaque objet valide ses invariants ISO 32000-2 dans son constructeur et se sérialise sous la forme du dictionnaire PDF correspondant. L’action rendition du module Navigation référence le résultat.

Portée : modèle objet de rendition uniquement

Ce module fournit le modèle objet de rendition : l’encodeur typé des dictionnaires ISO 32000-2 §13.2 Rendition, MediaClip et paramètres multimédias. L’action rendition de bout en bout pour annotation Screen (la surface §12.5.6.18 / §13 qui lie une rendition à une annotation Screen pour la lecture) n’est pas encore prise en charge ni vérifiée dans cette version. Les types d’annotation multimédia obsolètes (3D, RichMedia, Sound, Movie ; voir ISO 32000-2 §12.5.2) sont eux aussi hors périmètre. Décris et construis les objets structurels ci-dessous ; ne pars pas du principe qu’une action d’annotation Screen pourra être jouée.

Installation

composer require nextpdf/core:^3

Vue d’ensemble conceptuelle

Une rendition PDF décrit un élément multimédia jouable — contenu audio, vidéo ou clip interactif — et les conditions dans lesquelles une visionneuse le lit. ISO 32000-2 §13.2 définit le modèle de rendition et d’objet multimédia. Ce module est l’encodeur typé de ce modèle, avec validation. Chaque classe est un objet-valeur final readonly : elle reçoit ses entrées dans son constructeur, applique les règles structurelles de la spécification, puis émet une chaîne de dictionnaire PDF via toDictionary(). Elle ne lit aucun média et n’incorpore aucune donnée de fichier : elle produit le dictionnaire que le Writer sérialise.

Rendition est la racine du modèle. Une rendition multimédia (/MR) porte un MediaClip ainsi que des paramètres optionnels de lecture et d’écran. Une rendition de sélecteur (/SR) porte une liste ordonnée de références vers des renditions de repli. Le constructeur applique les exclusions mutuelles de la spécification : un /MR exige un clip et rejette les références de sélecteur, tandis qu’un /SR rejette les entrées de clip, de lecture et d’écran. Une rendition invalide ne peut donc pas être construite.

MediaClip représente les données multimédias ou l’une de leurs sections. Le sous-type section permet à une rendition de lire un sous-intervalle sans copier les données. MediaPlayInfo et MediaScreenInfo portent respectivement les paramètres de lecture (/P) et la présentation à l’écran (/SP). Toutes deux exposent isEmpty() afin qu’un appelant puisse omettre l’entrée lorsque la spécification recommande l’omission plutôt que l’émission d’un dictionnaire vide. MediaCriteria porte les ensembles d’exigences à respecter impérativement (/MH) et au mieux (/BE), avec une échappatoire extras pour les entrées que la surface typée ne modélise pas. L’ensemble du module est @since 2.3.0.

Surface d’API

Classe	Membres clés	Rôle
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	Objet rendition /MR ou /SR (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Objet de données / section de clip multimédia (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	Paramètres de lecture /P (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	Paramètres d’écran /SP (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	Ensembles d’exigences /MH et /BE (@since 2.3.0)

Lance composer docs:generate-api-php -- --module=Multimedia pour obtenir la table PHPDoc complète.

Exemple de code — Démarrage rapide

Construis une rendition multimédia pour un clip vidéo incorporé.

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

Exemple de code — Production

Construis une rendition de sélecteur qui suit une chaîne de repli ordonnée, en séparant explicitement les critères à respecter impérativement et les critères à appliquer au mieux.

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

Cas limites & pièges

• Une rendition /MR sans MediaClip lève une exception dans le constructeur — c’est une règle de la spécification, pas un avertissement à l’exécution. Construis-la avec le clip.
• Une rendition /SR rejette les entrées de clip, de lecture et d’écran. Mélanger les deux formes de rendition est une erreur de programmation, détectée lors de la construction.
• MediaPlayInfo::isEmpty() et MediaScreenInfo::isEmpty() existent pour que tu puisses omettre un /P ou un /SP vide. Émettre un dictionnaire vide là où la spécification recommande l’omission est structurellement valide mais inutile — vérifie isEmpty().
• Un nom /N de rendition ne doit pas contenir d’octet NUL ; le constructeur le rejette.
• Les selectorRefs sont des numéros d’objet indirect, chacun >= 1. Le module émet les références ; c’est au Writer de les résoudre vers les objets correspondants.

Performance

Chaque appel à toDictionary() construit une chaîne en temps linéaire sur un ensemble fixe d’entrées — à l’échelle de la microseconde, sans E/S. Le profil de reproductibilité est bitwise : le même objet-valeur émet toujours les mêmes octets de dictionnaire. La charge de référence par défaut reste largement dans le budget de 1500 ms de temps mural / 64 Mo de pic mémoire. Les dictionnaires multimédias restent petits par rapport aux médias incorporés qu’ils référencent.

Notes de sécurité

Ce module émet une structure de dictionnaire ; il n’incorpore ni ne transmet de données multimédias. La spécification de fichier incorporé référencée par un MediaClip est produite par la surface de pièces jointes de Navigation, qui borne et valide les octets incorporés. Traite tout nom de fichier multimédia ou nom de rendition issu d’une saisie utilisateur comme du texte non fiable. Le constructeur rejette les octets NUL mais ne contrôle pas le contenu sémantique d’une chaîne valide. Consulte le modèle de menace du moteur dans /modules/core/security/.

Conformité

Les dictionnaires que ce module émet suivent le modèle de rendition et d’objet multimédia de l’ISO 32000-2 §13.2, y compris les entrées de données et de section de clip multimédia. Les correspondances d’entrées par table sont documentées directement dans src/Multimedia/ par rapport aux numéros de table du §13.2 et couvertes par tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Ce sont des faits d’implémentation, pas une déclaration de conformité PDF 2.0 de bout en bout ; la conformité du document complet est validée par les suites oracle et golden décrites dans /modules/core/conformance/.

Voir aussi

• Module Navigation — l’action rendition qui référencerait ces objets (action rendition d’annotation Screen pas encore prise en charge ; voir la note de portée ci-dessus).
• Module Writer — sérialise les dictionnaires émis.
• Vue d’ensemble de la conformité
• Modèle de sécurité du moteur