Multimídia: rendition, media clip e parâmetros de tela

Visão geral

O módulo Multimedia modela uma rendition do Portable Document Format (PDF) e seus parâmetros de mídia como value objects imutáveis. Cada objeto valida os invariantes do ISO 32000-2 no construtor e, em seguida, serializa a própria representação no dicionário PDF correspondente. A ação de rendition do módulo Navigation referencia esse dicionário.

Escopo: apenas o modelo de objetos de rendition

Este módulo fornece o modelo de objetos de rendition: o codificador tipado para os dicionários Rendition / MediaClip / media-parameter do ISO 32000-2 §13.2. A ação de rendition de Screen-annotation de ponta a ponta (a superfície da §12.5.6.18 / §13 que vincula uma rendition a uma anotação de tela para reprodução) ainda não é suportada nem verificada nesta versão. Os tipos obsoletos de anotação de mídia (3D, RichMedia, Sound, Movie; consulte o ISO 32000-2 §12.5.2) também ficam fora do escopo. Use os objetos estruturais abaixo para descrever e construir o modelo; não conte com uma ação de Screen-annotation reproduzível.

Instalação

composer require nextpdf/core:^3

Visão conceitual

Uma rendition de PDF descreve mídia reproduzível, como áudio, vídeo ou um clipe interativo, e as condições em que um visualizador a reproduz. A §13.2 do ISO 32000-2 define o modelo de rendition e de objeto de mídia. Este módulo é o codificador tipado e o validador desse modelo. Toda classe é um value object final readonly: ela aceita entradas no construtor, aplica ali as regras estruturais da especificação e emite uma string de dicionário PDF a partir de toDictionary(). Ela não reproduz mídia nem incorpora dados de arquivo. Ela produz o dicionário que o Writer serializa.

Rendition é a raiz. Uma Media Rendition (/MR) carrega um MediaClip e parâmetros opcionais de reprodução e de tela. Uma Selector Rendition (/SR) carrega uma lista ordenada de referências de rendition de fallback. O construtor aplica as exclusões mútuas da especificação: um /MR exige um clip e rejeita referências de seletor, enquanto um /SR rejeita entradas de clip, reprodução e tela. Com isso, uma rendition inválida não pode ser construída.

MediaClip representa os dados de mídia ou uma seção desses dados. O subtipo de seção permite que uma rendition reproduza um subintervalo sem copiar os dados. MediaPlayInfo e MediaScreenInfo carregam os parâmetros de reprodução (/P) e a apresentação na tela (/SP). Ambos expõem isEmpty() para que você possa omitir a entrada quando a especificação recomendar a omissão em vez de um dicionário vazio. MediaCriteria carrega os conjuntos de requisitos obrigatórios (/MH) e de melhor esforço (/BE), com a válvula de escape extras para entradas que a superfície tipada não modela. O módulo inteiro é @since 2.3.0.

Superfície da API

Classe	Membros principais	Papel
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	/MR ou /SR objeto de rendition (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Objeto de dados / seção de media clip (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	/P parâmetros de reprodução (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	/SP parâmetros de tela (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	/MH e /BE conjuntos de requisitos (@since 2.3.0)

Execute composer docs:generate-api-php -- --module=Multimedia para gerar a tabela completa de PHPDoc.

Exemplo de código — Início rápido

Construa uma media rendition para um clipe de vídeo incorporado.

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

Exemplo de código — Produção

Construa uma selector rendition que segue uma cadeia ordenada de fallback e separa explicitamente os critérios obrigatórios dos critérios de melhor esforço.

<?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 extremos e pegadinhas

• Uma rendition /MR sem um MediaClip lança uma exceção no construtor. Esta é uma regra da especificação, não um aviso em tempo de execução. Construa a rendition com o clip.
• Uma rendition /SR rejeita entradas de clip, reprodução e tela. Misturar os dois formatos de rendition é um erro de programação detectado na construção.
• Use MediaPlayInfo::isEmpty() e MediaScreenInfo::isEmpty() para omitir um /P ou /SP vazio. Emitir um dicionário vazio quando a especificação recomenda a omissão é estruturalmente válido, mas desperdiça recursos; verifique isEmpty().
• O nome /N de uma rendition não deve conter um byte NUL. O construtor o rejeita.
• selectorRefs são números de objeto indireto, cada um >= 1. O módulo emite as referências; resolvê-las para objetos ativos é tarefa do Writer.

Desempenho

Cada chamada de toDictionary() constrói uma string linearmente a partir de um conjunto fixo de entradas. Ela é executada na escala de microssegundos e não realiza nenhuma operação de input/output (I/O). O perfil de reprodutibilidade é bitwise: o mesmo value object sempre emite os mesmos bytes de dicionário. A carga de trabalho de referência padrão fica bem dentro do orçamento de 1500 ms de tempo de parede / 64 MB de pico. Os dicionários de multimídia são pequenos em comparação com a mídia incorporada que eles referenciam.

Notas de segurança

Este módulo emite a estrutura de dicionário; ele não incorpora nem transmite dados de mídia. A superfície de anexo de arquivo do Navigation produz a especificação de arquivo incorporado que um MediaClip referencia, além de limitar e validar os bytes incorporados. Trate qualquer nome de arquivo de mídia ou nome de rendition vindo de entrada do usuário como texto não confiável. O construtor rejeita bytes NUL, mas não examina o conteúdo semântico de uma string válida. Consulte o modelo de ameaças do motor em /modules/core/security/.

Conformidade

Os dicionários emitidos por este módulo seguem o modelo de rendition e de objeto de mídia da §13.2 do ISO 32000-2, incluindo as entradas de dados e de seção de media-clip. Os mapeamentos de entradas por tabela estão documentados inline em src/Multimedia/ em relação aos números de tabela da §13.2 e cobertos por tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Esses são fatos de implementação, não uma declaração de conformidade PDF 2.0 de ponta a ponta; o oráculo e as suítes golden descritas em /modules/core/conformance/ validam a conformidade do documento completo.

Veja também

• Módulo Navigation — a ação de rendition que referenciaria esses objetos. A ação de rendition de Screen-annotation ainda não é suportada; consulte a nota de escopo acima.
• Módulo Writer — serializa os dicionários emitidos.
• Visão geral de conformidade
• Modelo de segurança do motor