Multimedia: rendition, media clip และพารามิเตอร์ screen

ภาพรวมโดยย่อ

โมดูล Multimedia จำลอง rendition ของ Portable Document Format (PDF) และพารามิเตอร์สื่อที่เกี่ยวข้องในรูปแบบ value object ที่เปลี่ยนแปลงไม่ได้ แต่ละ object ตรวจสอบ invariant ตาม ISO 32000-2 ใน constructor แล้วจึง serialize ตัวเองเป็น PDF dictionary ที่ตรงกัน rendition action ของโมดูล Navigation จะอ้างอิง dictionary นั้น

ขอบเขต: เฉพาะ object model ของ rendition เท่านั้น

โมดูลนี้ให้บริการ object model ของ rendition: encoder แบบมีชนิดข้อมูลสำหรับ dictionary ของ Rendition / MediaClip / media-parameter ตาม ISO 32000-2 §13.2 action ของ rendition แบบ Screen-annotation ที่ทำงานครบทั้งกระบวนการ (ส่วนใน §12.5.6.18 / §13 ซึ่งผูก rendition เข้ากับ screen annotation เพื่อเล่นสื่อ) ยังไม่รองรับหรือยังไม่ได้รับการตรวจสอบ ในรุ่นนี้ ชนิด media annotation ที่เลิกใช้แล้ว (3D, RichMedia, Sound, Movie; ดู ISO 32000-2 §12.5.2) อยู่นอกขอบเขตเช่นกัน ใช้ object เชิงโครงสร้างด้านล่างเพื่ออธิบายและสร้าง model เท่านั้น อย่าพึ่งพา Screen-annotation action ที่เล่นสื่อได้

การติดตั้ง

composer require nextpdf/core:^3

ภาพรวมเชิงแนวคิด

PDF rendition อธิบายสื่อที่เล่นได้ เช่น เสียง วิดีโอ หรือคลิปแบบโต้ตอบ รวมถึงเงื่อนไขที่โปรแกรมดูจะใช้เล่นสื่อนั้น ISO 32000-2 §13.2 กำหนด model ของ rendition และ media-object โมดูลนี้คือ encoder แบบมีชนิดข้อมูลพร้อมการตรวจสอบความถูกต้องสำหรับ model นั้น ทุกคลาสเป็น value object แบบ final readonly: รับ entry ใน constructor บังคับใช้กฎเชิงโครงสร้างของข้อกำหนด ณ จุดนั้น และส่งออกสตริง PDF dictionary จาก toDictionary() โมดูลนี้ไม่เล่นสื่อและไม่ฝังข้อมูลไฟล์ แต่สร้าง dictionary เพื่อให้ Writer นำไป serialize

Rendition คือรากของ Media Rendition (/MR) ซึ่งมี MediaClip และพารามิเตอร์ play กับ screen ที่เป็นทางเลือก Selector Rendition (/SR) มีรายการอ้างอิง rendition สำรองตามลำดับ constructor บังคับใช้เงื่อนไขที่แยกกันโดยเด็ดขาดตามข้อกำหนด: /MR ต้องมี clip และปฏิเสธการอ้างอิง selector ส่วน /SR ปฏิเสธ entry ของ clip, play และ screen จึงไม่สามารถสร้าง rendition ที่ไม่ถูกต้องได้

MediaClip แทนข้อมูลสื่อหรือส่วนหนึ่งของข้อมูลสื่อนั้น subtype แบบ section ช่วยให้ rendition เล่นช่วงย่อยได้โดยไม่ต้องคัดลอกข้อมูล MediaPlayInfo และ MediaScreenInfo เก็บพารามิเตอร์การเล่น (/P) และการนำเสนอบนหน้าจอ (/SP) ทั้งสองเปิดเผย isEmpty() เพื่อให้ละ entry ได้เมื่อข้อกำหนดแนะนำให้ละไว้ แทนที่จะใช้ dictionary ว่างเปล่า MediaCriteria เก็บชุดข้อกำหนดแบบต้องปฏิบัติตาม (/MH) และแบบพยายามอย่างดีที่สุด (/BE) พร้อมช่องทางสำรอง extras สำหรับ entry ที่ส่วนต่อประสานแบบมีชนิดข้อมูลไม่ได้จำลองไว้ ทั้งโมดูลนี้เป็น @since 2.3.0 ทั้งหมด

ส่วนต่อประสาน API

คลาส	สมาชิกหลัก	บทบาท
Rendition	__construct(...), toDictionary(), SUBTYPE_MEDIA, SUBTYPE_SELECTOR	/MR หรือ /SR object rendition (@since 2.3.0)
MediaClip	__construct(...), toDictionary(), SUBTYPE_DATA, SUBTYPE_SECTION	object ข้อมูล media clip / section (@since 2.3.0)
MediaPlayInfo	toDictionary(), isEmpty()	/P พารามิเตอร์การเล่น (@since 2.3.0)
MediaScreenInfo	toDictionary(), isEmpty()	/SP พารามิเตอร์ screen (@since 2.3.0)
MediaCriteria	toDictionary(), isEmpty()	/MH และ /BE ชุดข้อกำหนด (@since 2.3.0)

รัน composer docs:generate-api-php -- --module=Multimedia เพื่อสร้างตาราง PHPDoc แบบเต็ม

ตัวอย่างโค้ด — เริ่มต้นใช้งานอย่างรวดเร็ว

สร้าง media rendition สำหรับคลิปวิดีโอแบบฝัง

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

ตัวอย่างโค้ด — ระดับ Production

สร้าง selector rendition ที่ทำงานตามลำดับสายโซ่สำรอง และแยกเกณฑ์แบบต้องปฏิบัติตามออกจากเกณฑ์แบบพยายามอย่างดีที่สุดอย่างชัดเจน

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

กรณีขอบและข้อควรระวัง

• rendition แบบ /MR ที่ไม่มี MediaClip จะโยน exception ใน constructor นี่คือกฎตามข้อกำหนด ไม่ใช่คำเตือนขณะรันไทม์ ให้สร้าง rendition นั้นพร้อม clip
• rendition แบบ /SR ปฏิเสธ entry ของ clip, play และ screen การผสม rendition ทั้งสองรูปแบบเข้าด้วยกันเป็นข้อผิดพลาดในการเขียนโปรแกรมที่ตรวจพบขณะสร้าง object
• ใช้ MediaPlayInfo::isEmpty() และ MediaScreenInfo::isEmpty() เพื่อละ /P หรือ /SP ที่ว่างเปล่า การส่งออก dictionary ว่างเปล่าในจุดที่ข้อกำหนดแนะนำให้ละไว้นั้นถูกต้องเชิงโครงสร้างแต่สิ้นเปลือง ให้ตรวจสอบด้วย isEmpty() เสมอ
• ชื่อ /N ของ rendition ต้องไม่มีไบต์ NUL constructor จะปฏิเสธชื่อดังกล่าว
• selectorRefs เป็นหมายเลข indirect object โดยแต่ละค่า >= 1 โมดูลนี้ส่งออกการอ้างอิง ส่วนการแปลงการอ้างอิงเหล่านั้นเป็น object จริงเป็นหน้าที่ของ Writer

ประสิทธิภาพ

การเรียก toDictionary() แต่ละครั้งสร้างสตริงแบบเชิงเส้นจากชุด entry ที่คงที่ ทำงานในระดับไมโครวินาทีและไม่ทำงาน input/output (I/O) ใด ๆ โปรไฟล์การทำซ้ำได้เป็นแบบ bitwise: value object เดียวกันจะส่งออกไบต์ของ dictionary ที่เหมือนกันเสมอ ภาระงานอ้างอิงค่าเริ่มต้นอยู่ภายในงบประมาณ 1500 ms wall / 64 MB peak อย่างสบาย dictionary ของ Multimedia มีขนาดเล็กเมื่อเทียบกับสื่อแบบฝังที่ dictionary เหล่านั้นอ้างอิงถึง

หมายเหตุด้านความปลอดภัย

โมดูลนี้ส่งออกโครงสร้าง dictionary เท่านั้น ไม่ได้ฝังหรือส่งข้อมูลสื่อ ส่วนต่อประสาน file-attachment ของ Navigation สร้าง embedded file specification ที่ MediaClip อ้างอิงถึง และจำกัดขอบเขตกับตรวจสอบความถูกต้องของไบต์ที่ฝังไว้ ให้ถือว่าชื่อไฟล์สื่อหรือชื่อ rendition ใด ๆ ที่มาจากอินพุตของผู้ใช้เป็นข้อความที่ไม่น่าเชื่อถือ constructor ปฏิเสธไบต์ NUL แต่ไม่ได้ตรวจสอบเนื้อหาเชิงความหมายของสตริงที่ถูกต้อง ดู threat model ของเอนจินประกอบได้ที่ /modules/core/security/

ความสอดคล้องตามข้อกำหนด

dictionary ที่โมดูลนี้ส่งออกเป็นไปตาม model ของ rendition และ media-object ใน ISO 32000-2 §13.2 รวมถึง entry ของ media-clip data และ section การจับคู่ entry ในแต่ละตารางได้รับการบันทึกไว้แบบ inline ใน src/Multimedia/ โดยเทียบกับหมายเลขตารางใน §13.2 และครอบคลุมโดย tests/Unit/Multimedia/ (RenditionTest, MediaClipTest, MediaCriteriaTest, MediaPlayInfoTest, MediaScreenInfoTest) รายการเหล่านี้เป็นข้อเท็จจริงเชิงการพัฒนา ไม่ใช่การประกาศความสอดคล้อง PDF 2.0 แบบครบทั้งกระบวนการ ชุด oracle และ golden ที่อธิบายไว้ใน /modules/core/conformance/ เป็นตัวตรวจสอบความสอดคล้องของเอกสารทั้งฉบับ

ดูเพิ่มเติม

• โมดูล Navigation — rendition action ที่จะอ้างอิง object เหล่านี้ rendition action แบบ Screen-annotation ยังไม่รองรับ ดูหมายเหตุเรื่องขอบเขตด้านบน
• โมดูล Writer — serialize dictionary ที่ส่งออก
• ภาพรวมความสอดคล้องตามข้อกำหนด
• โมเดลความปลอดภัยของเอนจิน