Multimedia: parameter rendition, klip media, dan layar

Sekilas pandang

Modul Multimedia memodelkan rendition Portable Document Format (PDF) beserta parameter medianya sebagai objek nilai yang tidak dapat diubah. Setiap objek memvalidasi invariannya menurut ISO 32000-2 di dalam konstruktor, lalu menserialisasikannya ke kamus PDF yang sesuai. Aksi rendition di modul Navigation merujuk ke kamus tersebut.

Cakupan: hanya model objek rendition

Modul ini menyediakan model objek rendition: encoder bertipe untuk kamus Rendition / MediaClip / media-parameter ISO 32000-2 §13.2. Aksi rendition end-to-end untuk anotasi Layar (permukaan §12.5.6.18 / §13 yang menautkan sebuah rendition ke anotasi layar untuk pemutaran) belum didukung atau diverifikasi dalam rilis ini. Tipe anotasi media yang sudah usang (3D, RichMedia, Sound, Movie; lihat ISO 32000-2 §12.5.2) juga berada di luar cakupan. Gunakan objek struktural di bawah ini untuk mendeskripsikan dan membangun model; jangan mengandalkan aksi anotasi Layar yang dapat diputar.

Instalasi

composer require nextpdf/core:^3

Tinjauan konseptual

Sebuah rendition PDF mendeskripsikan media yang dapat diputar, seperti audio, video, atau klip interaktif, beserta kondisi yang menyebabkan penampil memutarnya. ISO 32000-2 §13.2 mendefinisikan model rendition dan objek media. Modul ini adalah encoder bertipe yang tervalidasi untuk model tersebut. Setiap kelas adalah objek nilai final readonly: kelas menerima entri melalui konstruktor, menegakkan aturan struktural spesifikasi di sana, dan menghasilkan string kamus PDF dari toDictionary(). Kelas ini tidak memutar media dan tidak menyematkan data berkas. Kelas ini menghasilkan kamus yang diserialisasikan oleh Writer.

Rendition adalah akar modelnya. Sebuah Media Rendition (/MR) membawa MediaClip serta parameter pemutaran dan layar opsional. Sebuah Selector Rendition (/SR) membawa daftar referensi rendition cadangan yang terurut. Konstruktor menegakkan eksklusi yang saling meniadakan sesuai spesifikasi: sebuah /MR mensyaratkan klip dan menolak referensi selektor, sedangkan sebuah /SR menolak entri klip, pemutaran, dan layar. Karena itu, rendition yang tidak valid tidak dapat dibangun.

MediaClip merepresentasikan data media atau sebagian darinya. Subtipe section memungkinkan sebuah rendition memutar subrentang tanpa menyalin data tersebut. MediaPlayInfo dan MediaScreenInfo membawa parameter pemutaran (/P) dan presentasi layar (/SP). Keduanya menyediakan isEmpty() sehingga Anda dapat menghilangkan entri tersebut ketika spesifikasi merekomendasikan agar entri dihilangkan, bukan diisi kamus kosong. MediaCriteria membawa jaringan persyaratan must-honour (/MH) dan best-effort (/BE), dengan jalur keluar extras untuk entri yang tidak dimodelkan oleh permukaan bertipe. Seluruh modul ini memiliki penanda @since 2.3.0.

Permukaan API

Kelas	Anggota utama	Peran
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	Objek rendition /MR atau /SR (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Objek data / section untuk klip media (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	Parameter pemutaran /P (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	Parameter layar /SP (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	Kumpulan persyaratan /MH dan /BE (@since 2.3.0)

Jalankan composer docs:generate-api-php -- --module=Multimedia untuk menghasilkan tabel PHPDoc lengkap.

Contoh kode — Mulai cepat

Bangun media rendition untuk klip video yang disematkan.

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

Contoh kode — Produksi

Bangun selector rendition yang mengikuti rantai cadangan terurut dan memisahkan kriteria must-honour serta best-effort secara eksplisit.

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

Kasus tepi & jebakan

• Rendition /MR tanpa MediaClip melempar eksepsi di dalam konstruktor. Ini adalah aturan spesifikasi, bukan peringatan runtime. Bangun dengan menyertakan klipnya.
• Rendition /SR menolak entri klip, pemutaran, dan layar. Mencampur kedua bentuk rendition itu adalah kesalahan pemrograman yang ditangkap saat konstruksi.
• Gunakan MediaPlayInfo::isEmpty() dan MediaScreenInfo::isEmpty() untuk menghilangkan /P atau /SP yang kosong. Menghasilkan kamus kosong di tempat yang menurut spesifikasi sebaiknya dihilangkan tetap valid secara struktural, tetapi boros; periksa isEmpty().
• Nama rendition /N tidak boleh mengandung bita NUL. Konstruktor akan menolaknya.
• selectorRefs adalah nomor objek tidak langsung, masing-masing >= 1. Modul menghasilkan referensinya; menyelesaikannya menjadi objek aktual adalah tugas Writer.

Performa

Setiap panggilan toDictionary() membangun string secara linear dari sekumpulan entri tetap. Proses ini berjalan pada skala mikrodetik dan tidak melakukan input/output (I/O). Profil reprodusibilitasnya adalah bitwise: objek nilai yang sama selalu menghasilkan bita kamus yang sama. Beban kerja referensi standar tetap jauh di bawah anggaran 1500 ms wall / 64 MB peak. Kamus Multimedia berukuran kecil dibandingkan media tersemat yang dirujuknya.

Catatan keamanan

Modul ini menghasilkan struktur kamus; modul ini tidak menyematkan atau mentransmisikan data media. Permukaan lampiran berkas di Navigation menghasilkan spesifikasi berkas tersemat yang dirujuk oleh MediaClip, serta membatasi dan memvalidasi bita yang tersemat. Perlakukan setiap nama berkas media atau nama rendition dari masukan pengguna sebagai teks yang tidak tepercaya. Konstruktor menolak bita NUL, tetapi tidak memeriksa konten semantik dari string yang valid. Lihat model ancaman mesin di /modules/core/security/.

Konformansi

Kamus yang dihasilkan modul ini mengikuti model rendition dan objek media dalam ISO 32000-2 §13.2, termasuk entri data dan section media-clip. Pemetaan entri per tabel didokumentasikan secara inline di src/Multimedia/ berdasarkan nomor tabel §13.2 dan dicakup oleh tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest). Ini adalah fakta implementasi, bukan pernyataan konformansi PDF 2.0 end-to-end; suite oracle dan golden yang dijelaskan di /modules/core/conformance/ memvalidasi konformansi dokumen secara menyeluruh.

Lihat juga

• Modul Navigation — aksi rendition yang akan merujuk ke objek-objek ini. Aksi rendition anotasi Layar belum didukung; lihat catatan cakupan di atas.
• Modul Writer — menserialisasikan kamus yang dihasilkan.
• Tinjauan konformansi
• Model keamanan mesin