# صيغة المستند: مقاطع الفيديو

> موارد الفيديو: يوتيوب وفيميو وملفاتك الخاصة وبث HLS، وما يعرضه كل مُخرَج، وحقول الفيديو، وصورة الغلاف والعنوان، والمشغّلات، وشجرة VDT والحِزم، ومقاطع الفيديو التي تعمل على صفحات Folio

- نسخة HTML: https://postext.dev/ar/docs/document-format-videos
- آخر تحديث: 2026-11-11
- مدة القراءة: 9 دقائق
- لغات أخرى: [en](https://postext.dev/en/docs/document-format-videos.md), [es](https://postext.dev/es/docs/document-format-videos.md), [ca](https://postext.dev/ca/docs/document-format-videos.md), [de](https://postext.dev/de/docs/document-format-videos.md), [fr](https://postext.dev/fr/docs/document-format-videos.md), [it](https://postext.dev/it/docs/document-format-videos.md), [pt](https://postext.dev/pt/docs/document-format-videos.md), [zh](https://postext.dev/zh/docs/document-format-videos.md), [ja](https://postext.dev/ja/docs/document-format-videos.md)

## باختصار

تتناول هذه الصفحة مقاطع الفيديو في الكتاب. قد يأتي الفيديو من يوتيوب أو فيميو، وقد يكون ملفًّا خاصًّا بك. تحيل إليه في النص كما تحيل إلى الصورة، وله ترقيم خاص به كالأشكال والجداول. وفي الورق وفي PDF يظهر لقطةً ثابتة عليها علامة تشغيل ورمز QR يفتح الفيديو. ويعمل الفيديو في عرض الويب وفي الكتب الإلكترونية. وفي الكتاب ثلاثي الأبعاد تكفي نقرة على اللقطة ليعمل الفيديو على الصفحة نفسها، ويستمر في العمل أثناء قلب الورقة.

الفيديو مورد كالصورة: يُعرَّف مرة واحدة، ويُحال إليه في النص، ويطفو إلى أول موضع شاغر بعد الإحالة إليه. وتشرح صفحة [صيغة المستند: الصور والجداول](https://postext.dev/ar/docs/document-format-resources.md) الإحالات والترقيم والموضع والتفاف النص؛ وما يلي خاص بالفيديو.

> [مقاطع الفيديو في كتبك: رمز QR على الورق، ومشغّل على الشاشة، وفيلم على الصفحة، بـPostext](https://youtu.be/wqv0ioospSo) · 4:41

## مقاطع الفيديو

مورد **الفيديو** (`kind: 'video'`) مقطع على يوتيوب أو فيميو، أو فيديو خاص بك: ملف محفوظ في الكتاب (MP4 أو WebM)، أو فيديو على عنوان ويب، ملفًّا على خادم أو **بثًّا بصيغة HLS** (قائمة تشغيل `.m3u8`). يُوضع ويُكتب له تعليق ويطفو ويُحال إليه كما تُعامَل الصورة، ويُرقَّم في تسلسل خاص به: يطبع النوع المدمج `video` *فيديو 1-1* و*فيديو 1-2*… بجانب *شكل 1-1* و*جدول 1-1* (انظر [الإعدادات › أنواع الموارد](https://postext.dev/ar/docs/configuration-resources.md#أنواع-الموارد)). ويعرضه كل نوع من المخرجات بما يستطيع:

| المخرجات | ما يعرضه |
| --- | --- |
| Canvas وPDF | **الغلاف**، وهو إطار من الفيديو، وعليه علامة تشغيل ورمز QR يفتح الفيديو ([الإعدادات › نمط الفيديو](https://postext.dev/ar/docs/configuration-resources.md#نمط-الفيديو)). وفي PDF يكون الغلاف أيضًا رابطًا إلى الفيديو. |
| Folio | الغلاف كما يُطبع. والنقر عليه يشغّل الفيديو **على الصفحة نفسها**، ويستمر تشغيله والورقة تنقلب (انظر [مقاطع الفيديو على صفحات Folio](https://postext.dev/ar/docs/document-format-videos.md#مقاطع-الفيديو-على-صفحات-folio) أدناه). أما مقاطع يوتيوب وفيميو فتبقى أغلفة. |
| عارض HTML | **مشغّل** الفيديو: مشغّل يوتيوب أو فيميو، أو مشغّل HTML5 في المتصفح للملف أو للعنوان. ويُشغَّل بثّ HLS مباشرةً في Safari وفي الإصدارات الحديثة من Chrome؛ وفي غيرهما يربط المضيف به مشغّلًا مثل hls.js، كما يفعل Sandbox. ومع `videoStyle.html: 'poster'` يعرض الغلاف المطبوع بدلًا منه. |
| EPUB | يُشغَّل الملف في مشغّل نظام القراءة نفسه، محزومًا في الكتاب أو مقروءًا من عنوان نشره. أما فيديو يوتيوب أو فيميو فيظهر غلافُه مربوطًا بالفيديو، لأن EPUB لا يجوز له أن يضمّن مشغّل صفحة ويب. وبثّ HLS كذلك يظهر غلافًا مربوطًا بالفيديو، لأن قائمة تشغيل HLS ليست من أنواع الوسائط التي يجوز لـEPUB تشغيلها. وإذا كان نظام القراءة يشغّل النصوص البرمجية التزمت ملفات الصفحة الواحدة أو الفصل الواحد بـ`player.exclusive`: تشغيل أحدها يوقف مؤقتًا ما لا يعمل إلى جانبه. |

```ts
const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: 'الحارس يشرح المصباح.',
  altText: 'حارس منارة بجانب المصباح',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // plays from 0:30; the printed link starts there too
  },
};
```

يحيل النص إلى الفيديو كما يحيل إلى الشكل: `:ref{id="keeper-talk"}` يطبع *فيديو 1-1* ويجعل الغلاف يطفو إلى أول موضع شاغر بعد الإحالة، و`::resource{id="keeper-talk"}` مع `placement.position: 'here'` يضعه داخل التدفق. وهذه حقول `Resource.video` (`ResourceVideo`):

| الحقل | النوع | المعنى |
| --- | --- | --- |
| `source` | `'youtube'` · `'vimeo'` · `'file'` | مصدر تشغيل الفيديو: صفحة على يوتيوب أو فيميو، أو فيديو خاص بك (`'file'`)، مرفوعًا أو على عنوان. |
| `url` | `string` | يوتيوب أو فيميو: عنوان الفيديو بأي صيغة (صفحة مشاهدة، أو `youtu.be`، أو Shorts، أو رابط تضمين، أو `youtube-nocookie.com`؛ أو صفحة على فيميو، أو صفحة قناة، أو رابط غير مُدرج مع رمز التجزئة الخاص به). الملف: **عنوان نشره**، أي المكان الذي سيجده فيه الكتاب المنشور. والفيديو الخاص بك الذي لا ملف له يُشغَّل من هذا العنوان: ملف MP4 أو WebM على خادم، أو بثّ HLS (`…/master.m3u8`). |
| `fileId`، `format` | `string` | الملف: الفيديو المرفوع، مخزّنًا خارج المستند كالصورة النقطية، وصيغته: `'mp4'` أو `'webm'` أو `'ogv'` أو `'mov'`، أو `'hls'` لبثّ HLS. وحين لا تُذكر الصيغة يدلّ عليها امتداد العنوان (`.m3u8` تعني `'hls'`)، وإلا فهي `'mp4'`. |
| `poster` | `{ fileId, format, width, height }` | إطار الغلاف، وهو صورة نقطية. |
| `width`، `height`، `duration` | `number` | حجم إطار الفيديو بـpx (ومنه نسبة أبعاده حين لا يكون له غلاف) وطوله بالثواني. |
| `posterTime` | `number` | الثانية التي أُخذ منها إطار الغلاف في الملف، تُحفظ ليمكن اختياره من جديد. |
| `start`، `end` | `number` | يُشغَّل من الثانية `start` إلى الثانية `end`. ويبدأ رمز QR ورابط PDF من `start` أيضًا. |
| `player` | `VideoPlayerOptions` | خيارات مشغّل هذا الفيديو، تُطبَّق فوق `videoStyle.player`. |

**الغلاف.** يُنضَّد بعرض موضعه (أو بالكسر `placement.width` منه)، بنسبة أبعاده، أيًّا كان حجمه بالبكسل: فالإطار بحجم الشاشة يُكبَّر بدل أن يُطبع صغيرًا. ويمكن أن تكون له، كالصورة النقطية، [منطقة آمنة](https://postext.dev/ar/docs/document-format-resources.md#المنطقة-الآمنة) وأن يتبع `placement.align`. والفيديو الذي بلا غلاف يُطبع مربعًا داكنًا بنسبة أبعاد الفيديو (16:9 حين لا يُعرف غيرها) وعليه علامة التشغيل ورمز QR، ويظهر تحذير المحتوى `videoWithoutPoster`. وفي Sandbox يُجلب غلاف فيديو يوتيوب أو فيميو من المنصة عند إدخال عنوانه، أما غلاف الملف فإطار تختاره من الفيديو.

**العنوان.** يفتح رمز QR ورابط PDF صفحة الفيديو، `https://youtu.be/<id>` أو `https://vimeo.com/<id>`، بدءًا من `start`. أما الملف فلا صفحة له، فيفتحان عنوان نشره، وهو أيضًا المكان الذي يُشغَّل منه الفيديو الذي لا ملف له (ملف MP4 على خادم، أو بثّ HLS). ومن دون هذا العنوان لا يكون في المطبوع رمز QR ولا رابط (`videoWithoutUrl`)، وتعرض مخرجات HTML أو EPUB التي لا تتضمّن الملفَ الغلافَ. والعنوان على يوتيوب أو فيميو الذي لا يشير إلى فيديو من تلك المنصة يظهر له التحذير `videoUrlInvalid`، ويُعرض الغلاف مكان المشغّل.

**المشغّلات.** تُضبط خيارات المشغّل (أدوات التحكم، وزر التنزيل، وملء الشاشة، وقائمة السرعة، وصورة داخل صورة، والإرسال إلى شاشة، والتشغيل التلقائي، والبدء دون صوت، والتكرار، والتحميل المسبق، والتضمين مع خصوصية معزَّزة) للكتاب كله في `videoStyle.player`، ولفيديو واحد في `video.player`؛ ويراعي كل مشغّل ما يستطيع منها (انظر [الإعدادات › نمط الفيديو](https://postext.dev/ar/docs/configuration-resources.md#نمط-الفيديو)). ويتلقى مُخرِج HTML عنوان URL القابل للتشغيل لكل ملف عبر الخيار `resourceVideoUrl(fileId)`، كما يتلقى الصور عبر `resourceImageUrl`، ويعود إلى عنوان النشر حين لا يجده. ويختار خياره `videos: { files, streams, hls }` بين المشغّل والغلاف لكل مصدر، متقدّمًا على `videoStyle.html` (و`hls`، أي الفيديو المُشغَّل من عنوان HLS، يتبع `files` ما لم يُضبط)؛ ويستعمله كاتب EPUB. ولعنصر `<video>` الذي يشغّل عنوان HLS السمة `data-pt-hls`، ليستطيع المضيف أن يعطيه مشغّلًا في المتصفحات التي لا تدعم HLS بنفسها (أما Safari والإصدارات الحديثة من Chrome فتشغّله كما هو). وفي كتاب يُقرأ من اليمين إلى اليسار لا يُعكس المشغّل ولا ما يُطبع فوق الغلاف، كما لا تُعكس الصورة، فيبقى رمز QR مقروءًا.

**في VDT.** لكتلة مورد الفيديو `kind: 'video'`، وغلافها في `fileId` / `format` (يُرسم كالصورة النقطية)، و`video` (`VDTResourceVideo`): الرابط `link` الذي يُرسَل إليه القارئ، و`embedUrl` ليوتيوب أو فيميو بعد تطبيق خيارات المشغّل، و`fileId` للملف، و`mimeType` للفيديو الخاص بك (لملفه أو لعنوانه وحده، و`application/vnd.apple.mpegurl` لبثّ HLS)، والمجال `start` / `end`، و`player` النهائي، و`linkPoster`، و`html`، والطبقتان `playMark` و`qr` (وحدات رمز QR صفوفًا من `'0'` / `'1'`)، بمستطيلات تُقاس من الزاوية العليا اليسرى لجسم المورد. والمضيف الذي يرسم مقاطع الفيديو بنفسه يجد الدوال التي يصدّرها `postext`: `parseVideoUrl` و`videoWatchUrl` و`resourceVideoLink` و`videoEmbedUrl` و`videoEmbedAllow` و`videoElementAttributes` و`mediaFragment` و`videoMimeType` و`videoFormatOfUrl` و`resourceVideoFormat` و`isHlsMimeType` و`HLS_MIME_TYPE` و`youtubePosterUrls` و`encodeQr` و`layoutVideo` و`playMarkTriangle` و`qrModuleRuns`.

**في الحزمة.** يتضمّن ملف `.postext` ملفَّ الفيديو (`resources/<id>.mp4`) والغلاف (`resources/<id>.poster.jpg`): يذكرهما مدخل البيان (manifest) في `file` و`poster`، ويعطي حجم الغلاف في `width` / `height`، ويحفظ الباقي في `video` بلا معرّفات ملفات. و`bundleVideoUrl(bundle)` هي دالة الحلّ `resourceVideoUrl` على ملفات الحزمة. والفيديو المُشغَّل من عنوان وحده لا ملف له: ليس في مدخله إلا الغلاف. وفي الحزمة ثنائية اللغة يمكن أن تعطي لغةٌ الفيديو غلافها `poster` وفيديوها `video` الخاصّين بها (نسخة أخرى من المقطع، على عنوانها الخاص) في `localized[…].resources`.

### مقاطع الفيديو على صفحات Folio

في [الكتاب ثلاثي الأبعاد](https://postext.dev/ar/docs/configuration-html-folio-epub.md#كتاب-ثلاثي-الأبعاد-postext-folio) يُشغَّل الفيديو الخاص بك على الصفحة المطبوع عليها. ويبدأ النقر على الغلاف تشغيله هناك، أيًّا كان ما يفعله المؤشر على الكتاب (قلب الصفحات، أو تدوير المنظر، أو تحديد النص): يرسم مظلِّل (shader) الصفحة إطارات الفيديو فوق الغلاف، فتنثني الصورة وتلتفّ مع الورق حين تُقلب الورقة، ويستمر التشغيل أثناء القلب. والنقر على فيديو يعمل يوقفه مؤقتًا، والنقر على فيديو متوقف يستأنفه، ويفعل مفتاح المسافة أو Enter الشيء نفسه لأول فيديو في الصفحتين المفتوحتين. وتشغيل فيديو آخر يوقف الفيديو العامل (فيعود إلى غلافه)، ويتوقف الفيديو حين يستقر الكتاب على صفحتين متقابلتين لم تعودا تعرضانه، أو عند بلوغه `end`. ويصير المؤشر يدًا فوق فيديو يمكنه تشغيله؛ والسحب الذي يبدأ عليه يقلب الصفحة أو يدير المنظر مع ذلك. والفيديو المضبوط ليبدأ وحده (`video.player.autoplay`) يبدأ تشغيله تلقائيًا أول مرة يستقر فيها الكتاب على صفحتيه، بعد أن يهدأ الكتاب (ويدخل في ذلك المضيف الذي يُخرجه على مراحل)، ولا يبدأ وحده بعدها أبدًا في أداة العرض تلك.

الفيديو الذي يعمل إلى جانب غيره (`video.player.exclusive: false`، منذ postext 1.18) يغيّر القاعدتين. تشغيله لا يوقف إلا المقاطع الحصرية، فتعمل عدة مقاطع من هذا النوع معًا؛ وتشغيل فيديو حصري يوقفه هو أيضًا. ومع `autoplay` يبدأ صامتًا كلما استقر الكتاب على صفحتيه المتقابلتين، ويتوقف حين تُقلبان: فتعمل المقاطع الصامتة المتكررة (`loop`) في الصفحة معًا كلما وصل إليها القارئ.

- **ما يُشغَّل.** الملف (يحوّل المضيف `fileId` الخاص به إلى عنوان URL بالخيار `videoUrl`، وهو في Sandbox عنوان كائن object URL)، أو عنوانه إن لم يكن له ملف: MP4 أو WebM أو بثّ HLS. ويُشغَّل بثّ HLS عبر [hls.js](https://github.com/video-dev/hls.js) حيثما توفرت في المتصفح امتدادات مصدر الوسائط (Media Source Extensions)، ويُحمَّل عند أول تشغيل (وهو تبعية نظيرة اختيارية لـ`postext-folio`)، مقصورًا على النسخة الأقرب إلى حجم الصورة على الشاشة، فلا تجلب صورة لا يتجاوز ارتفاعها بضع مئات من البكسلات نسخةً بدقة 4K؛ ويبقى دعم HLS المدمج في المتصفح بديلًا احتياطيًا. ولطلباته معامل استعلام خاصّ بها، `pt-cors`، فلا تعطيها ذاكرة التخزين المؤقت في المتصفح نسخة جلبها مشغّل آخر دون CORS. أما يوتيوب وفيميو فيُشغَّلان في إطارات iframe لا يستطيع WebGL رسمها: فالنقر على غلافهما يقلب الصفحة كما في أي موضع آخر.
- **القراءة من مصدر آخر.** لا يرسم WebGL الفيديو إلا حين يسمح خادمه بقراءته (CORS، `Access-Control-Allow-Origin`). والفيديو الذي لا تمكن قراءته يبقى غلافًا، ويتلقّى `onVideo` الحالة `error`.
- **الصوت.** يسمح النقر بتشغيل الفيديو بصوته؛ والمتصفح الذي يرفض ذلك مع هذا يشغّله دون صوت. والفيديو الذي يبدأ وحده يكون بصوته متى نقر القارئ على الصفحة أو كتب فيها (والانتقال إليها بالقلب يُحتسب)؛ وقبل ذلك يبدأ دون صوت، والنقر عليه يعيد إليه صوته قبل أن توقفه النقرة التالية مؤقتًا. ويبدأ `video.player.muted` التشغيل دون صوت، ويعيده `loop` من أوله، ويحدّد `start` / `end` الجزء الذي يُشغَّل.
- **على كل صفحة.** تُرسم الصورة حيث يضعها الإخراج: مُدارةً مع المورد المُدار، وقائمةً على الصفحة العمودية، وغير معكوسة في الكتاب الذي يُقرأ من اليمين إلى اليسار، كالغلاف تمامًا. والغلاف المقصوص داخل [منطقته الآمنة](https://postext.dev/ar/docs/document-format-resources.md#المنطقة-الآمنة) يُقصّ الفيديو بالطريقة نفسها.
- **دون WebGL2**، أو مع تقليل الحركة، يُشغَّل الفيديو في عنصر HTML `<video>` موضوع فوق الصفحة.

```ts
const book = createFolioFromDocument(container, doc, {
  // An uploaded video's playable URL (an object URL over its bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();
```

ويعطّل `videos: false` هذه الميزة. وتفعل `toggleVideoAt({ page, x, y })` ما تفعله النقرة في ذلك الموضع، وتسرد `pageVideoSpots(page, doc)` مواضع مقاطع الفيديو في الصفحة، للمضيف الذي يرسم أدوات تحكّمه بنفسه.

وصفتان في دليل الوصفات تضعان مقاطع فيديو: الوصفة رقم 131، [برنامج نادٍ سينمائي برموز QR على الأغلفة](https://postext.dev/ar/cookbook/film-club-video-qr.md)، تطبع كل فيلم بطاقةَ عنوان عليها علامة التشغيل ورمز QR، والوصفة رقم 132، [ورقة تجربة تُعرض مقاطعها على الشاشة وفي EPUB](https://postext.dev/ar/cookbook/pendulum-lab-video-players.md)، تضبط خيارات المشغّل في نسخة HTML وتحزم مقاطعها في EPUB ثابت التخطيط.

## أمثلة في دليل الوصفات

### مقاطع الفيديو

- [رقم 131 برنامج نادٍ سينمائي برموز QR على الأغلفة](https://postext.dev/ar/cookbook/film-club-video-qr.md)
- [رقم 132 ورقة تجربة تُعرض مقاطعها على الشاشة وفي EPUB](https://postext.dev/ar/cookbook/pendulum-lab-video-players.md)
- [رقم 136 صحيفة حيّة تتحرك صورها](https://postext.dev/ar/cookbook/living-newspaper-video-loops.md)
