Multimedya: işleme, medya klibi ve ekran parametreleri

Bir bakışta

Multimedya modülü, bir PDF işlemesini ve bu işlemenin medya parametrelerini değişmez değer nesneleri olarak modeller. Her nesne, kurucuda ilgili ISO 32000-2 değişmezlerini doğrular, ardından kendini eşleşen PDF sözlüğüne serileştirir. Navigation modülünün işleme eylemi bu sözlüğe başvurur.

Kapsam: yalnızca işleme nesne modeli

Bu modül işleme nesne modelini sağlar: ISO 32000-2 §13.2 Rendition / MediaClip / medya parametresi sözlükleri için tipli kodlayıcı. Uçtan uca Screen-annotation işleme eylemi (bir işlemeyi oynatmak üzere bir ekran ek açıklamasına bağlayan §12.5.6.18 / §13 yüzeyi) bu sürümde henüz desteklenmiyor veya doğrulanmış değil. Kullanımdan kaldırılmış medya ek açıklama türleri (3D, RichMedia, Sound, Movie; bkz. ISO 32000-2 §12.5.2) de kapsam dışıdır. Modeli tanımlayıp oluşturmak için aşağıdaki yapısal nesneleri kullanın; oynatılabilir bir Screen-annotation eylemine güvenmeyin.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Bir PDF işlemesi, ses, video veya etkileşimli klip gibi oynatılabilir medyayı ve bir görüntüleyicinin bunu hangi koşullarda oynatacağını tanımlar. ISO 32000-2 §13.2, işleme ve medya nesnesi modelini tanımlar. Bu modül, söz konusu model için tipli ve doğrulama yapan bir kodlayıcıdır. Her sınıf bir final readonly değer nesnesidir: girdileri kurucuda kabul eder, spesifikasyonun yapısal kurallarını burada uygular ve toDictionary() ile bir PDF sözlüğü dizesi üretir. Medyayı oynatmaz ve dosya verisini gömmez. Writer’ın serileştireceği sözlüğü üretir.

Rendition kök nesnedir. Bir medya işlemesi (/MR), bir MediaClip ile isteğe bağlı oynatma ve ekran parametrelerini taşır. Bir seçici işlemesi (/SR), sıralı yedek işleme başvuruları listesini taşır. Kurucu, spesifikasyonun karşılıklı dışlama kurallarını uygular: bir /MR klip gerektirir ve seçici başvurularını reddeder; bir /SR ise klip, oynatma ve ekran girdilerini reddeder. Böylece geçersiz bir işleme oluşturulamaz.

MediaClip, medya verisini veya bunun bir bölümünü temsil eder. Bölüm alt türü, bir işlemenin veriyi kopyalamadan verinin bir alt aralığını oynatmasına olanak tanır. MediaPlayInfo ve MediaScreenInfo oynatma parametrelerini (/P) ve ekran sunumunu (/SP) taşır. Her ikisi de isEmpty() yöntemini sunar; böylece spesifikasyon boş bir sözlük yerine atlamayı önerdiğinde girdiyi atlayabilirsiniz. MediaCriteria, uyulması zorunlu (/MH) ve mümkünse uyulacak (/BE) gereksinim kümelerini taşır; tipli yüzeyin modellemediği girdiler için bir extras kaçış noktası içerir. Modülün tamamı @since 2.3.0 sürümünden itibaren kullanılabilir.

API yüzeyi

Sınıf	Önemli üyeler	Rol
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	/MR veya /SR işleme nesnesi (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	Medya klibi veri / bölüm nesnesi (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	/P oynatma parametreleri (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	/SP ekran parametreleri (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	/MH ve /BE gereksinim kümeleri (@since 2.3.0)

Tam PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Multimedia komutunu çalıştırın.

Kod örneği — hızlı başlangıç

Gömülü bir video klibi için bir medya işlemesi oluşturun.

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

Kod örneği — üretim

Sıralı bir yedek zincirini izleyen ve uyulması zorunlu ölçütlerle mümkünse uyulacak ölçütleri açıkça ayıran bir seçici işlemesi oluşturun.

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

Sınır durumları ve tuzaklar

• Bir /MR işlemesi, MediaClip içermediğinde kurucuda bir istisna fırlatır. Bu, çalışma zamanı uyarısı değil, bir spesifikasyon kuralıdır. Bunu bir klip ile oluşturun.
• Bir /SR işlemesi klip, oynatma ve ekran girdilerini reddeder. İki işleme biçimini karıştırmak, oluşturma sırasında yakalanan bir programlama hatasıdır.
• Boş bir girdiyi atlamak için MediaPlayInfo::isEmpty() ve MediaScreenInfo::isEmpty() yöntemlerini kullanın; bu, boş bir /P veya /SP üretmenizi önler. Spesifikasyonun atlamayı önerdiği yerde boş bir sözlük üretmek yapısal olarak geçerlidir ama gereksizdir; isEmpty() denetimini yapın.
• Bir işlemenin /N adı NUL baytı içermemelidir. Kurucu bunu reddeder.
• selectorRefs, her biri >= 1 olan dolaylı nesne numaralarıdır. Modül başvuruları üretir; bunları canlı nesnelere çözümlemek Writer’ın işidir.

Performans

Her toDictionary() çağrısı, sabit bir girdi kümesinden bir dizeyi doğrusal olarak oluşturur. Mikrosaniye ölçeğinde çalışır ve hiçbir input/output (I/O) işlemi gerçekleştirmez. Yeniden üretilebilirlik profili bitwise şeklindedir: aynı değer nesnesi her zaman aynı sözlük baytlarını üretir. Varsayılan referans iş yükü, 1500 ms duvar süresi / 64 MB tepe bellek bütçesinin oldukça içinde kalır. Multimedya sözlükleri, başvurdukları gömülü medyaya kıyasla küçüktür.

Güvenlik notları

Bu modül sözlük yapısını üretir; medya verisini gömmez veya iletmez. Navigation’ın dosya eki yüzeyi, bir MediaClip nesnesinin başvurduğu gömülü dosya belirtimini üretir ve gömülü baytları sınırlandırıp doğrular. Kullanıcı girdisinden gelen medya dosya adlarını veya işleme adlarını güvenilmez metin olarak değerlendirin. Kurucu NUL baytlarını reddeder ancak geçerli bir dizenin anlamsal içeriğini denetlemez. /modules/core/security/ içindeki motor tehdit modeline bakın.

Uygunluk

Bu modülün ürettiği sözlükler, medya klibi verisi ve bölüm girdileri dahil olmak üzere ISO 32000-2 §13.2 içindeki işleme ve medya nesnesi modelini izler. Tablo bazındaki girdi eşlemeleri, §13.2 tablo numaralarına karşı src/Multimedia/ içinde satır içi olarak belgelenmiştir ve tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest) tarafından kapsanmaktadır. Bunlar uygulamaya ilişkin gerçeklerdir; uçtan uca PDF 2.0 uygunluğu beyanı değildir. /modules/core/conformance/ içinde açıklanan oracle ve golden paketleri tam belge uygunluğunu doğrular.

Ayrıca bakınız

• Navigation modülü — bu nesnelere başvuracak işleme eylemi. Screen-annotation işleme eylemi henüz desteklenmiyor; yukarıdaki kapsam notuna bakın.
• Writer modülü — üretilen sözlükleri serileştirir.
• Uygunluk genel bakışı
• Motor güvenlik modeli