멀티미디어: 렌디션, 미디어 클립, 스크린 매개변수

한눈에 보기

멀티미디어 모듈은 PDF 렌디션과 해당 미디어 매개변수를 불변 값 객체로 모델링합니다. 각 객체는 생성자에서 ISO 32000-2 불변식을 검증하고, 자신을 해당 PDF 딕셔너리로 직렬화합니다. Navigation 모듈의 렌디션 액션이 이 결과를 참조합니다.

설치

composer require nextpdf/core:^3

개념 개요

PDF 렌디션은 재생 가능한 미디어 항목(오디오, 비디오, 인터랙티브 클립)과 뷰어가 이를 재생하는 조건을 기술합니다. ISO 32000-2 §13.2가 렌디션 및 미디어 객체 모델을 정의합니다. 이 모듈은 그 모델을 위한 타입 지정 검증 인코더입니다. 모든 클래스는 final readonly 값 객체입니다. 생성자는 엔트리를 받아 그 자리에서 명세의 구조 규칙을 강제하고, toDictionary()에서 PDF 딕셔너리 문자열을 내보냅니다. 이 모듈은 미디어를 재생하지 않으며 파일 데이터를 임베드하지도 않습니다. Writer가 직렬화할 딕셔너리를 생성할 뿐입니다.

Rendition이 루트입니다. 미디어 렌디션(/MR)은 MediaClip과 선택적 재생 및 스크린 매개변수를 담습니다. 선택자 렌디션(/SR)은 순서가 지정된 폴백 렌디션 참조 목록을 담습니다. 생성자는 명세의 상호 배타 규칙을 강제합니다. /MR은 클립을 요구하고 선택자 참조를 거부하며, /SR은 클립, 재생, 스크린 엔트리를 거부합니다. 따라서 유효하지 않은 렌디션은 생성할 수 없습니다.

MediaClip은 미디어 데이터 또는 그 일부 구간입니다. 구간 서브타입은 렌디션이 데이터를 복사하지 않고도 하위 범위를 재생할 수 있게 합니다. MediaPlayInfo와 MediaScreenInfo는 재생 매개변수(/P)와 스크린 프레젠테이션(/SP)을 담습니다. 둘 다 isEmpty()를 제공하므로, 명세가 빈 딕셔너리를 내보내기보다 생략을 권장할 때 호출자가 해당 엔트리를 생략할 수 있습니다. MediaCriteria는 반드시 준수해야 하는(/MH) 요구 사항 집합과 최선 노력(/BE) 요구 사항 집합을 담으며, 타입 지정 표면이 모델링하지 않는 엔트리를 위한 extras 탈출구를 제공합니다. 모듈 전체는 @since 2.3.0입니다.

API 표면

클래스	주요 멤버	역할
`Rendition`	`__construct(...)`, `toDictionary()`, `SUBTYPE_MEDIA`, `SUBTYPE_SELECTOR`	`/MR` 또는 `/SR` 렌디션 객체(`@since 2.3.0`)
`MediaClip`	`__construct(...)`, `toDictionary()`, `SUBTYPE_DATA`, `SUBTYPE_SECTION`	미디어 클립 데이터 / 구간 객체(`@since 2.3.0`)
`MediaPlayInfo`	`toDictionary()`, `isEmpty()`	`/P` 재생 매개변수(`@since 2.3.0`)
`MediaScreenInfo`	`toDictionary()`, `isEmpty()`	`/SP` 스크린 매개변수(`@since 2.3.0`)
`MediaCriteria`	`toDictionary()`, `isEmpty()`	`/MH` 및 `/BE` 요구 사항 집합(`@since 2.3.0`)

전체 PHPDoc 표를 보려면 composer docs:generate-api-php -- --module=Multimedia를 실행하십시오.

코드 샘플 — 빠른 시작

임베드된 비디오 클립용 미디어 렌디션을 빌드합니다.

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

코드 샘플 — 프로덕션

반드시 준수해야 하는 기준과 최선 노력 기준을 명시적으로 분리하고, 순서가 지정된 체인을 따라 폴백하는 선택자 렌디션을 빌드합니다.

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

엣지 케이스 & 함정

/MR 렌디션에 MediaClip이 없으면 생성자에서 예외를 던집니다. 이는 런타임 경고가 아니라 명세 규칙입니다. 클립을 포함해 생성하십시오.
/SR 렌디션은 클립, 재생, 스크린 엔트리를 거부합니다. 두 렌디션 형태를 섞는 것은 프로그래밍 오류이며, 생성 시점에 포착됩니다.
MediaPlayInfo::isEmpty()와 MediaScreenInfo::isEmpty()는 빈 /P 또는 /SP를 생략할 수 있도록 존재합니다. 명세가 생략을 권장하는 곳에서 빈 딕셔너리를 내보내는 것은 구조적으로는 유효하지만 낭비입니다. isEmpty()를 확인하십시오.
렌디션 /N 이름에는 NUL 바이트가 포함되어서는 안 됩니다. 생성자가 이를 거부합니다.
selectorRefs는 간접 객체 번호이며, 각각 >= 1입니다. 모듈은 참조를 내보냅니다. 이를 실제 객체로 해석하는 것은 Writer의 역할입니다.

성능

각 toDictionary() 호출은 고정된 엔트리 집합에 대한 선형 문자열 빌드이며, I/O 없이 마이크로초 단위로 완료됩니다. 재현성 프로파일은 bitwise입니다. 동일한 값 객체는 항상 동일한 딕셔너리 바이트를 내보냅니다. 기본 참조 워크로드는 1500 ms 벽시계 / 64 MB 피크 예산에 충분히 들어맞습니다. 멀티미디어 딕셔너리는 참조하는 임베드된 미디어에 비해 작습니다.

보안 참고 사항

이 모듈은 딕셔너리 구조를 내보냅니다. 미디어 데이터를 임베드하거나 전송하지 않습니다. MediaClip이 참조하는 임베드된 파일 명세는 Navigation 파일 첨부 표면에서 생성되며, 해당 표면이 임베드된 바이트를 제한하고 검증합니다. 사용자 입력에서 비롯된 미디어 파일 이름이나 렌디션 이름은 모두 신뢰할 수 없는 텍스트로 취급하십시오. 생성자는 NUL 바이트를 거부하지만, 유효한 문자열의 의미론적 내용은 검사하지 않습니다. /modules/core/security/의 엔진 위협 모델을 참조하십시오.

적합성

이 모듈이 내보내는 딕셔너리는 ISO 32000-2 §13.2의 렌디션 및 미디어 객체 모델을 따르며, 미디어 클립 데이터 및 구간 엔트리를 포함합니다. 테이블별 엔트리 매핑은 src/Multimedia/에 §13.2 테이블 번호에 대응하여 인라인으로 문서화되어 있으며, tests/Unit/Multimedia/(RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest)에서 실행됩니다. 이는 구현 사실이며 종단 간 PDF 2.0 적합성에 대한 진술이 아닙니다. 전체 문서 적합성은 /modules/core/conformance/에 기술된 오라클 및 골든 스위트로 검증됩니다.