Đa phương tiện: các tham số rendition, media clip và màn hình

Tổng quan nhanh

Mô-đun Multimedia mô hình hóa một rendition của Portable Document Format (PDF) và các tham số media tương ứng dưới dạng các value object bất biến. Mỗi object kiểm tra các bất biến ISO 32000-2 của chính nó trong constructor, rồi tự tuần tự hóa thành từ điển PDF tương ứng. Hành động rendition của mô-đun Navigation sẽ tham chiếu đến từ điển đó.

Phạm vi: chỉ mô hình object rendition

Mô-đun này cung cấp mô hình object rendition: bộ mã hóa có định kiểu cho các từ điển Rendition / MediaClip / tham số media của ISO 32000-2 §13.2. Hành động rendition Screen-annotation đầu cuối (bề mặt §12.5.6.18 / §13 ràng buộc một rendition với một chú thích màn hình để phát) chưa được hỗ trợ hoặc kiểm chứng trong bản phát hành này. Các loại chú thích media đã ngừng dùng (3D, RichMedia, Sound, Movie; xem ISO 32000-2 §12.5.2) cũng nằm ngoài phạm vi. Hãy dùng các object cấu trúc bên dưới để mô tả và xây dựng mô hình; đừng dựa vào một hành động Screen-annotation có thể phát được.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Một rendition PDF mô tả media có thể phát, chẳng hạn như âm thanh, video hoặc một clip tương tác, cùng các điều kiện để trình xem phát media đó. ISO 32000-2 §13.2 định nghĩa mô hình rendition và media-object. Mô-đun này là bộ mã hóa có định kiểu, kèm kiểm tra hợp lệ cho mô hình đó. Mỗi class là một value object final readonly: class nhận các mục trong constructor, thực thi ngay tại đó các quy tắc cấu trúc của đặc tả, rồi phát ra một chuỗi từ điển PDF từ toDictionary(). Nó không phát media và không nhúng dữ liệu tệp. Nó tạo ra từ điển để Writer tuần tự hóa.

Rendition là gốc. Một Media Rendition (/MR) mang theo một MediaClip cùng các tham số phát và màn hình tùy chọn. Một Selector Rendition (/SR) mang theo danh sách có thứ tự gồm các tham chiếu rendition dự phòng. Constructor thực thi các điều kiện loại trừ lẫn nhau của đặc tả: một /MR yêu cầu clip và từ chối các tham chiếu selector, còn một /SR từ chối các mục clip, play và screen. Nhờ vậy, không thể tạo ra một rendition không hợp lệ.

MediaClip đại diện cho dữ liệu media hoặc một phần dữ liệu đó. Subtype section cho phép một rendition phát một khoảng con mà không cần sao chép dữ liệu. MediaPlayInfo và MediaScreenInfo mang các tham số phát (/P) và phần trình bày màn hình (/SP). Cả hai đều cung cấp isEmpty() để bạn có thể bỏ qua mục đó khi đặc tả khuyến nghị bỏ qua thay vì dùng một từ điển rỗng. MediaCriteria mang các bộ yêu cầu must-honour (/MH) và best-effort (/BE), cùng một lối thoát extras cho các mục mà bề mặt định kiểu không mô hình hóa. Toàn bộ mô-đun là @since 2.3.0.

Bề mặt API

Class	Thành viên chính	Vai trò
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	/MR hoặc /SR — object rendition (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Object dữ liệu / section media clip (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	/P tham số phát (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	/SP tham số màn hình (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	/MH và /BE — các bộ yêu cầu (@since 2.3.0)

Chạy composer docs:generate-api-php -- --module=Multimedia để tạo bảng PHPDoc hoàn chỉnh.

Mã mẫu — bắt đầu nhanh

Tạo một media rendition cho video clip được nhúng.

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

Mã mẫu — môi trường sản xuất

Tạo một selector rendition theo chuỗi dự phòng có thứ tự, đồng thời tách rõ các tiêu chí must-honour và 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();

Trường hợp đặc biệt & điểm cần lưu ý

• Một rendition /MR không có MediaClip sẽ ném ngoại lệ trong constructor. Đây là quy tắc của đặc tả, không phải cảnh báo lúc chạy. Hãy tạo nó cùng với clip.
• Một rendition /SR từ chối các mục clip, play và screen. Trộn lẫn hai dạng rendition là một lỗi lập trình, bị bắt khi tạo.
• Hãy dùng MediaPlayInfo::isEmpty() và MediaScreenInfo::isEmpty() để bỏ qua một /P hoặc /SP rỗng. Việc phát ra một từ điển rỗng ở nơi đặc tả khuyến nghị bỏ qua vẫn hợp lệ về mặt cấu trúc nhưng lãng phí; hãy kiểm tra isEmpty().
• Tên /N của rendition không được chứa byte NUL. Constructor từ chối nó.
• selectorRefs là các số object gián tiếp, mỗi số >= 1. Mô-đun phát ra các tham chiếu; việc phân giải chúng thành object thực là nhiệm vụ của Writer.

Hiệu năng

Mỗi lần gọi toDictionary() đều xây dựng tuyến tính một chuỗi từ tập mục cố định. Nó chạy ở quy mô micro giây và không thực hiện input/output (I/O) nào. Hồ sơ khả năng tái lập là bitwise: cùng một value object luôn phát ra cùng các byte từ điển. Khối lượng công việc tham chiếu mặc định nằm gọn trong ngân sách 1500 ms thời gian thực / 64 MB đỉnh. Các từ điển multimedia nhỏ so với media được nhúng mà chúng tham chiếu.

Ghi chú bảo mật

Mô-đun này phát ra cấu trúc từ điển; nó không nhúng hoặc truyền dữ liệu media. Bề mặt đính kèm tệp của Navigation tạo ra đặc tả tệp nhúng mà một MediaClip tham chiếu, đồng thời giới hạn và kiểm tra hợp lệ các byte được nhúng. Hãy coi mọi tên tệp media hoặc tên rendition đến từ đầu vào của người dùng là văn bản không đáng tin cậy. Constructor từ chối các byte NUL nhưng không kiểm duyệt nội dung ngữ nghĩa của một chuỗi hợp lệ. Xem mô hình mối đe dọa của engine trong /modules/core/security/.

Tuân thủ

Các từ điển mà mô-đun này phát ra tuân theo mô hình rendition và media-object trong ISO 32000-2 §13.2, bao gồm các mục dữ liệu và section của media-clip. Ánh xạ mục theo từng bảng được ghi tài liệu trực tiếp trong src/Multimedia/, đối chiếu với các số bảng §13.2, và được bao phủ bởi tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Đây là các dữ kiện triển khai, không phải tuyên bố về sự tuân thủ PDF 2.0 đầu cuối; chỉ các bộ oracle và golden được mô tả trong /modules/core/conformance/ mới kiểm chứng sự tuân thủ toàn tài liệu.

Xem thêm

• Mô-đun Navigation — hành động rendition sẽ tham chiếu đến các object này. Hành động rendition Screen-annotation chưa được hỗ trợ; xem ghi chú phạm vi ở trên.
• Mô-đun Writer — tuần tự hóa các từ điển được phát ra.
• Tổng quan về tuân thủ
• Mô hình bảo mật của engine