Multimedia: parámetros de representación, clips multimedia y pantalla

De un vistazo

El módulo Multimedia modela representaciones PDF y sus parámetros multimedia como objetos de valor inmutables. Cada objeto valida en el constructor sus invariantes de ISO 32000-2 y se serializa como el diccionario PDF correspondiente. La acción de representación del módulo Navigation hace referencia al resultado.

Alcance: solo el modelo de objetos de representación

Este módulo es el modelo de objetos de representación: el codificador tipado de los diccionarios Rendition / MediaClip / de parámetros multimedia de ISO 32000-2 §13.2. La acción de representación de extremo a extremo para la anotación de pantalla (la superficie de §12.5.6.18 / §13 que vincula una representación a una anotación de pantalla para su reproducción) todavía no está admitida ni verificada en esta versión. Los tipos de anotación multimedia obsoletos (3D, RichMedia, Sound, Movie; véase ISO 32000-2 §12.5.2) también quedan fuera del alcance. Describir y construir los objetos estructurales que se indican a continuación; no depender de una acción de anotación de pantalla reproducible.

Instalación

composer require nextpdf/core:^3

Visión conceptual general

Una representación PDF describe contenido multimedia reproducible —audio, vídeo, un clip interactivo— y las condiciones en las que un visor lo reproduce. ISO 32000-2 §13.2 define el modelo de representaciones y objetos multimedia. Este módulo es el codificador y validador tipado de ese modelo. Cada clase es un objeto de valor final readonly: recibe sus entradas en el constructor, aplica ahí las reglas estructurales de la especificación y emite desde toDictionary() una cadena con el diccionario PDF. No reproduce contenido multimedia ni incrusta datos de archivo: produce el diccionario que serializa el Writer.

Rendition es el objeto raíz. Una representación multimedia (/MR) contiene un MediaClip y parámetros opcionales de reproducción y pantalla. Una representación de selector (/SR) contiene una lista ordenada de referencias a representaciones alternativas. El constructor hace cumplir las exclusiones mutuas de la especificación: una /MR requiere un clip y rechaza las referencias de selector, mientras que una /SR rechaza las entradas de clip, reproducción y pantalla, de modo que no es posible construir una representación no válida.

MediaClip representa los datos multimedia o una sección de ellos. El subtipo de sección permite que una representación reproduzca un subrango sin copiar los datos. MediaPlayInfo y MediaScreenInfo contienen los parámetros de reproducción (/P) y la presentación en pantalla (/SP). Ambos exponen isEmpty() para que el código llamador pueda omitir la entrada cuando la especificación recomienda omitirla en lugar de emitir un diccionario vacío. MediaCriteria contiene los conjuntos de requisitos de cumplimiento obligatorio (/MH) y de mejor esfuerzo (/BE), con extras como vía de escape para las entradas que la superficie tipada no modela. Todo el módulo es @since 2.3.0.

Superficie de la API

Clase	Miembros clave	Función
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	Objeto de representación /MR o /SR (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Objeto de datos / sección del clip multimedia (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	Parámetros de reproducción /P (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	Parámetros de pantalla /SP (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	Conjuntos de requisitos /MH y /BE (@since 2.3.0)

Ejecutar composer docs:generate-api-php -- --module=Multimedia para obtener la tabla completa de PHPDoc.

Ejemplo de código: inicio rápido

Construir una representación multimedia para un clip de vídeo incrustado.

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

Ejemplo de código: producción

Construir una representación de selector que recurra a una cadena ordenada de alternativas, con los criterios de cumplimiento obligatorio y de mejor esfuerzo separados de forma explícita.

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

Casos límite y aspectos a tener en cuenta

• Una representación /MR sin un MediaClip lanza una excepción en el constructor: es una regla de la especificación, no una advertencia en tiempo de ejecución. Construirla con el clip.
• Una representación /SR rechaza las entradas de clip, reproducción y pantalla. Mezclar las dos formas de representación es un error de programación que se detecta durante la construcción.
• MediaPlayInfo::isEmpty() y MediaScreenInfo::isEmpty() permiten omitir un /P o /SP vacío. Emitir un diccionario vacío cuando la especificación recomienda la omisión es estructuralmente válido, pero innecesario: comprobar isEmpty().
• El nombre /N de una representación no debe contener un byte NUL; el constructor lo rechaza.
• Los selectorRefs son números de objeto indirecto, cada uno >= 1. El módulo emite las referencias; resolverlas a objetos reales es tarea del Writer.

Rendimiento

Cada llamada a toDictionary() construye linealmente una cadena sobre un conjunto fijo de entradas: del orden de microsegundos y sin E/S. El perfil de reproducibilidad es bitwise: el mismo objeto de valor siempre emite los mismos bytes de diccionario. La carga de trabajo de referencia predeterminada queda holgadamente dentro del presupuesto de 1500 ms de tiempo real / 64 MB de pico. Los diccionarios multimedia son pequeños en comparación con el contenido multimedia incrustado al que hacen referencia.

Notas de seguridad

Este módulo emite estructuras de diccionario; no incrusta ni transmite datos multimedia. La especificación de archivo incrustado a la que hace referencia un MediaClip la produce la superficie de adjuntos de archivos del módulo Navigation, que acota y valida los bytes incrustados. Tratar cualquier nombre de archivo multimedia o nombre de representación procedente de la entrada del usuario como texto no confiable. El constructor rechaza los bytes NUL, pero no examina el contenido semántico de una cadena válida. Consultar el modelo de amenazas del motor en /modules/core/security/.

Conformidad

Los diccionarios que emite este módulo siguen el modelo de representaciones y objetos multimedia de ISO 32000-2 §13.2, incluidas las entradas de datos y de sección del clip multimedia. Las asignaciones de entradas por tabla están documentadas en el propio código de src/Multimedia/ con respecto a los números de tabla de §13.2, y se prueban en tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Se trata de hechos de implementación, no de una declaración de conformidad PDF 2.0 de extremo a extremo; la conformidad del documento completo se valida mediante el oráculo y las suites de referencia descritos en /modules/core/conformance/.

Véase también

• Módulo Navigation: la acción de representación que haría referencia a estos objetos (la acción de representación de la anotación de pantalla todavía no se admite; véase la nota sobre el alcance anterior).
• Módulo Writer: serializa los diccionarios emitidos.
• Visión general de la conformidad
• Modelo de seguridad del motor