باختصار
ورقة تجربة في الفيزياء فيها مقطعان قصيران لبندول. على الورق كل مقطع صورة ثابتة ورمز يُمسح بالهاتف؛ وعلى الشاشة وفي الكتاب الإلكتروني يُشغَّل المقطع في الصفحة.
ما الذي ستنضده
التجربة 4.2 من Bench Physics، وهي كراسة تجارب بمقاس A4 لطلاب من 16 إلى 18 عامًا، وموضوعها دور البندول. على شريط بلون الصدأ العنوان وخانات الاسم والمجموعة والتاريخ. وفي أسفل الصفحة الأولى مقطعان للبندول نفسه، أُفلت في أحدهما من 10° وفي الآخر من 80°، متجاوران. على الورق، كل مقطع هو أول لقطة منه مع علامة تشغيل ورمز QR يفتح ملف MP4. وفي نسخة الشاشة بجوار الصفحات، وفي ملف EPUB الذي تكتبه الشيفرة، يُشغَّل المورِدان نفساهما في مشغّل الفيديو لدى القارئ. وفي الصفحة الثانية الخطوات، وجدول يملؤه الطالب، والأدوار الدقيقة التي تحسبها الشيفرة، وأربعة أسئلة لكل منها خانة للإجابة.
تجيب هذه الوصفة عن
- كيف يشغّل إصدار HTML وملف EPUB مقاطع الفيديو في الكتاب، وكيف أخفي زر التنزيل؟
- كيف أضع فيديو في كتاب مطبوع بحيث يستطيع القارئ فتحه من الصفحة؟
الجواب المختصر
const clip = (id, file, poster, caption, altText) => ({
id, typeId: 'video', kind: 'video', createdAt: 0, updatedAt: 0, caption: t(caption),
note: t({ en: '8.00 s, 25 frames per second · Postext Cookbook, CC BY 4.0',
es: '8,00 s, 25 fotogramas por segundo · Postext Cookbook, CC BY 4.0' }),
altText: t(altText), placement: { position: 'bottom', span: 'column' },
video: { source: 'file', fileId: file, format: 'mp4', width: 640, height: 360, duration: 8,
url: asset(file), // the production address: printed as the QR code, linked from the PDF
poster: { fileId: poster, format: 'jpeg', width: 640, height: 360 }, // the first frame
},
});
const videoStyle = {
playMark: { shape: 'rounded', position: 'top-left', size: mm(7), inset: mm(3),
background: col('ink'), color: col('paper') },
qr: { position: 'bottom-right', size: mm(19), inset: mm(2.5), // 111 characters: 45 modules
color: col('ink'), background: col('paper'), radius: mm(1) },
// The HTML5 player of a file honours every option. download: false writes
// controlslist="nodownload": it hides the button, and the file stays at its address.
player: { download: false, loop: true, muted: true, preload: 'auto',
pictureInPicture: false, remotePlayback: false },
};
const clips = [
clip('small', 'pendulum-small.mp4', 'pendulum-small-poster.jpg',
{ en: 'Released from rest at 10°.', es: 'Soltado desde el reposo a 10°.' },
{ en: 'A rust bob on a dark string hangs a few degrees off the vertical, under a short bar.',
es: 'Una lenteja roja cuelga de un hilo oscuro a pocos grados de la vertical.' }),
clip('large', 'pendulum-large.mp4', 'pendulum-large-poster.jpg',
{ en: 'Released from rest at 80°.', es: 'Soltado desde el reposo a 80°.' },
{ en: 'The same pendulum pulled out almost level with its pivot, a pale arc below it.',
es: 'El mismo péndulo, casi a la altura de su eje, sobre un arco pálido.' }),
];
المكونات
- الميزات
- أغلفة الفيديو: علامة التشغيل ورمز QRالفيديو بوصفه موردًاالتصدير إلى EPUBطبعة HTML للقراءةتصميم أبسط للشاشةجداول من البياناتنمط الجدولإطارات التنبيهإطارات متداخلةمسافة عمودية صريحةصفحات افتتاح مصمَّمةسمات العنوانالنصوص والخطوط والمربعات في تصاميم الصفحةالترويسات وأرقام الصفحاتالترويسات بحسب دور الصفحةأنواع موارد مخصّصةلوحة ألوان دلاليةالخطوط المضمَّنة في PDF
- تستخدم أيضًا
- استشهادات تضع الأشكالأشكال في هذا الموضع بالضبط«شكل» و«جدول» بلغتكشريط فصل بعرض الصفحةأنماط الفقراتالتصدير إلى PDFالأشكال والجداول بوصفها مواردالنص المرتفع والمنخفض
- الخطوط
- Source Serif 4, Red Hat Display, Red Hat Mono (SIL OFL 1.1)
- الأصول
pendulum-large-poster.jpgpendulum-large.mp4pendulum-small-poster.jpgpendulum-small.mp4- Video 1: a pendulum 1 m long released from 10°, 8 s at 25 frames per second, rendered from an RK4 solution of the pendulum equation (1 ms steps) with Python and encoded with ffmpeg (Postext Cookbook, CC BY 4.0)
- Video 2: the same pendulum released from 80°, rendered and encoded the same way (Postext Cookbook, CC BY 4.0)
- The first frame of Video 1, its printed poster (Postext Cookbook, CC BY 4.0)
- The first frame of Video 2, its printed poster (Postext Cookbook, CC BY 4.0)
طريقة التحضير
#1 · أعطِ كل مقطع عنوان نشر وملفًا
الشيفرة هي الجواب المختصر أعلاه. للمقطع الخاص عنوانان. video.url هو المكان الذي سيجد فيه الكتابُ المنشور المقطعَ: يطبعه رمز QR ويربط به ملف PDF الصورة، ولذلك هو هنا عنوان المقطع على jsDelivr، وهو عنوان يفتحه الهاتف اليوم. وvideo.fileId يحدّد الملف نفسه، ويُحفظ منفصلًا مثل الصورة النقطية، للمخرجات التي تستطيع حمله أو تشغيله من مكان آخر (انظر صيغة المستند › مقاطع الفيديو). وخيارات videoStyle.player تسري على المقطعين: يتكرران، ويبدآن بلا صوت، ويُحمَّلان كاملين (27 و61 كيلوبايت)، ولا يعرضان تنزيلًا ولا صورة داخل صورة ولا إرسالًا إلى شاشة أخرى، فيبقى المقطع في الورقة.
#2 · أخرِج نسخة الشاشة من الأصل نفسه
const [PANE_W, PANE_H] = [400, 640]; // px
const screen = {
page: { width: px(PANE_W), height: px(PANE_H), dpi: 122, // so the 9.4 pt text is 16 px
margins: { top: px(28), bottom: px(28), left: px(22), right: px(22), mirror: false } },
layout: { layoutType: 'single' }, bodyText: { textAlign: 'left' }, // ragged in a narrow pane
headings: { levels: [{ level: 1, span: 'column', breakBefore: { enabled: false },
fontSize: px(28), lineHeight: px(32), fontWeight: 800, marginBottom: px(16),
advancedDesign: { enabled: false } }] }, // the title alone: the band and fields are print's
header: { elements: [] }, footer: { elements: [] } };
تعيش نسخة الشاشة في الإعدادات تحت htmlViewer.overrides، ولا يقرؤها Canvas ولا ملف PDF. بدقة 122 نقطة في البوصة يخرج كل قياس بالنقاط أكبر بنحو الربع مما يكون عليه بدقة 96، فيُقرأ نص 9.4 نقطة بحجم 16 بكسل في اللوحة، وتكبر معه التعليقات والإطارات والجداول. ويحتفظ الافتتاح بالعنوان ويترك الشريط والخانات، فهي للورق.
#3 · شغّل المقطعين في اللوحة
// A shadow root keeps the page's styles out, so the pane shows the lines as they were measured.
const pane = desk.querySelector('#screen').attachShadow({ mode: 'open' });
pane.innerHTML = renderToHtml(buildDocument({ markdown, resources },
applyHtmlViewerOverrides(config())), { mode: 'single', padding: 0, background: '#ffffff',
resourceImageUrl: imageUrl, // the posters, until a clip plays
resourceVideoUrl: (fileId) => asset(fileId) }); // the file each <video> plays: the asset here
const top = (el) => el.getBoundingClientRect().top; // open the pane on the first player
pane.host.scrollTop = top(pane.querySelector('video')) - top(pane.host) - 48;
تضع renderToHtml كل مورد فيديو في عنصر <video> من HTML5، وتصير خيارات المشغّل سماتٍ له: controls وmuted وloop وplaysinline وpreload="auto" وdisablepictureinpicture وdisableremoteplayback وcontrolslist="nodownload". والسمة الأخيرة تخفي الزر فقط. من يعرف العنوان يستطيع حفظ الملف على أي حال، فهي ترتيب للواجهة وليست حماية. وتزوّد resourceVideoUrl المحرّكَ بعنوان قابل للتشغيل لكل fileId، كما تفعل resourceImageUrl مع الصور. هنا هو الملف المنشور؛ والموقع الذي يحفظ ملفاته في مكان آخر يعيد عنوانه الخاص، أو عنوان blob للبايتات. وبدونها يرجع المشغّل إلى video.url، وبدون الاثنين تعرض اللوحة الصورة.
#4 · احزم المقطعين في EPUB بتخطيط ثابت
const bytesOf = async (url) => new Uint8Array(await (await fetch(url)).arrayBuffer());
const media = new Map(await Promise.all(clips.map(async ({ video }) =>
[video.fileId, { bytes: await bytesOf(asset(video.fileId)), mediaType: 'video/mp4' }])));
// Every face as bytes (gotcha: epub-embeds-given-fonts): the files loadFonts loaded, latin
// for each face and greek for the text face, limited to the Greek block and listed after
// latin, so a reading system tries it first for θ and π.
const faces = Object.entries(FONTS).flatMap(([family, specs]) => specs.map((spec) =>
({ family, weight: parseInt(spec, 10), style: spec.endsWith('i') ? 'italic' : 'normal' })));
const fonts = await Promise.all([...faces.map((face) => [face, 'latin']),
...faces.filter(({ family }) => family === TEXT)
.map((face) => [{ ...face, unicodeRange: 'U+0370-03FF' }, 'greek'])]
.map(async ([face, subset]) => ({ ...face, format: 'woff2', bytes: await bytesOf(
`https://cdn.jsdelivr.net/npm/@fontsource/${fontsourceId(face.family)}@5/files/`
+ `${fontsourceId(face.family)}-${subset}-${face.weight}-${face.style}.woff2`) })));
const epub = await renderToEpub([doc], { layout: 'fixed', fonts,
metadata: { title: doc.metadata.title, creators: ['Postext Cookbook'], language: LANG,
rights: 'CC BY 4.0', modified: new Date('2026-10-05T00:00:00Z') }, // the same bytes each run
// The clips as video/mp4 and the posters as pictures; the book packs both under media/.
resourceBytes: (fileId) => media.get(fileId)
?? { bytes: imageBytes(fileId), mediaType: 'image/jpeg' },
});
تقوم الورقة على مقطعين متجاورين وخانات فارغة للكتابة، ولذلك يحفظها التخطيط الثابت: كل صفحة كما تُطبع، ومشغّل مكان الصورة. والملف القابل لإعادة التدفق يشغّل المقطعين أيضًا، واحدًا تحت الآخر بعرض النص. تجيب resourceBytes بـvideo/mp4 لكل مقطع وبصورة JPEG لكل لقطة، فيحزمها الكاتب تحت media/ وimages/. ولا يحتفظ EPUB إلا بالسمات التي يعرفها مخططه (controls وautoplay وmuted وloop وplaysinline وpreload)، فيُترك زر التنزيل وغيره لنظام القراءة. ويجتاز الملف EPUBCheck بلا أخطاء ولا تحذيرات.
#5 · انضد θ وπ في اللوح وملف PDF وEPUB
يضع Source Serif 4 حروفه اليونانية في ملف مستقل من Fontsource هو greek، إلى جانب latin. فإذا وجدت kitFonts(FONTS) حروفًا يونانية في النص حمّلت هذا الملف لكل وجه من وجوه العائلة، ويضمّنه fontsourceProvider في ملف PDF مع الملف اللاتيني لكل وجه يُنضَد به θ أو π، فلا يحتاج الحرفان إلى شيفرة. ولا يضمّن EPUB إلا الخطوط التي تسلّمه إياها الشيفرة، ولذلك تضيف الخطوة 4 ملفات greek لخط النص بعد الملفات اللاتينية، وكل منها مقصور على الكتلة اليونانية بـunicodeRange الخاص به.
#6 · احسب الجدول في الشيفرة
// The arithmetic-geometric mean gives the elliptic integral K of the exact period in a few steps.
const T0 = 2 * Math.PI * Math.sqrt(1 / 9.81); // s: L = 1 m, g = 9.81 m/s²
const agm = (a, b) => (Math.abs(a - b) < 1e-15 ? a : agm((a + b) / 2, Math.sqrt(a * b)));
const period = (degrees) => T0 / agm(1, Math.cos((degrees * Math.PI) / 360));
const num = (x, digits) => x.toFixed(digits).replace('.', t({ en: '.', es: ',' }));
const cell = (content, align = 'right') => ({ content, align, verticalAlign: 'middle' });
const table = (id, caption, head, rows, columnWidths) => ({ id, typeId: 'table', kind: 'table',
createdAt: 0, updatedAt: 0, caption: t(caption), placement: { position: 'here' },
table: { model: { headerRowCount: 1, columnWidths, rows: [head.map((h, i) =>
({ ...cell(h, i ? 'right' : 'left'), isHeader: true })), ...rows] } } });
const periods = table('periods', { en: 'Exact periods of a pendulum 1.00 m long.',
es: 'Periodos exactos de un péndulo de 1,00 m.' },
['Amplitude|Amplitud', 'T (s)', 'T/T~0~', 'Longer by|Aumento'].map((h) =>
t({ en: h.split('|')[0], es: h.split('|').at(-1) })),
[5, 10, 20, 30, 45, 60, 80, 90].map((d) => [cell(`${d}°`, 'left'), cell(num(period(d), 3)),
cell(num(period(d) / T0, 3)), cell(`${num((period(d) / T0 - 1) * 100, 2)} %`)]),
[1.2, 1, 1, 1.1]);
const blank = cell(' \n '); // two empty lines: room to write
const data = table('data', { en: 'Your measurements.', es: 'Tus medidas.' },
t({ en: ['Clip', 'Swings in 8 s', 'T (s)'], es: ['Vídeo', 'Oscilaciones en 8 s', 'T (s)'] }),
[10, 80].map((d, i) => [cell(`${t({ en: 'Video', es: 'Vídeo' })} ${i + 1} · ${d}°`, 'left'),
blank, blank]), [1.2, 1.5, 0.8]);
يحتاج الدور الدقيق إلى التكامل الإهليلجي التام من النوع الأول K، ويحسبه الوسط الحسابي الهندسي في خطوات قليلة: T = T~0~ / AGM(1, cos ½θ~0~). يطبع الجدول ثلاثة منازل عشرية، بفاصلة عشرية في الطبعة الإسبانية، ويطابق سطرا 10° و80° المقطعين: 2.010 ث و2.282 ث، أي أطول من T~0~ = 2.006 ث بنسبة 0.2 % و13.8 %. وفي 8 ثوانٍ يكمل المقطع الأول ما يقارب أربع تأرجحات كاملة، والثاني ثلاثًا ونصفًا.
الوصفة كاملة
// ═══ Postext Cookbook · Nº 132 · A lab sheet whose clips play on screen and in the EPUB ════
// https://postext.dev/en/cookbook/pendulum-lab-video-players
// Code: MIT · Text: original (CC BY 4.0) · Clips: rendered in code (CC BY 4.0)
// Fonts: Source Serif 4, Red Hat Display, Red Hat Mono (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocument, buildDocumentWithFonts, prepareFonts, renderPageToCanvas, renderToHtml,
applyHtmlViewerOverrides, registerResourceImage, defaultResourceTypes, resourceVideoLink,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
import { renderToEpub, readEpub } from 'https://esm.sh/postext-epub';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'pendulum-lab-video-players';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { // the clips' own colours: a cream ground, the rust bob, warm black ink
ink: '#22201b', // text, the play mark, the QR modules, table heads
rust: '#a8432b', // the accent: the band, labels, list numbers (the bob's red, darker)
cream: '#f6f1e4', rule: '#cbc2ae', // box fills, a shade deeper than the clips; hairlines
muted: '#68625a', paper: '#ffffff' }; // muted: running heads, notes, prompts
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.rust }) // defaults: rust
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, MONO] = ['Source Serif 4', 'Red Hat Display', 'Red Hat Mono'];
const [TOP, INNER, OUTER, BAND, LEAD] = [22, 20, 17, 84, 13.2]; // mm, A4; LEAD in pt
const px = (value) => ({ value, unit: 'px' }); // the screen edition's sizes
const at = (to, edge, x, y, size) => ({ anchor: { to, edge }, offset: { x, y }, size });
const label = (size, color = 'rust') => ({ fontFamily: MONO, fontSize: pt(size), fontWeight: 600,
letterSpacing: pt(size * 0.16), textTransform: 'uppercase', color: col(color) });
// #region answer: two clips of the book's own: a poster and a QR code, or a player
const clip = (id, file, poster, caption, altText) => ({
id, typeId: 'video', kind: 'video', createdAt: 0, updatedAt: 0, caption: t(caption),
note: t({ en: '8.00 s, 25 frames per second · Postext Cookbook, CC BY 4.0',
es: '8,00 s, 25 fotogramas por segundo · Postext Cookbook, CC BY 4.0' }),
altText: t(altText), placement: { position: 'bottom', span: 'column' },
video: { source: 'file', fileId: file, format: 'mp4', width: 640, height: 360, duration: 8,
url: asset(file), // the production address: printed as the QR code, linked from the PDF
poster: { fileId: poster, format: 'jpeg', width: 640, height: 360 }, // the first frame
},
});
const videoStyle = {
playMark: { shape: 'rounded', position: 'top-left', size: mm(7), inset: mm(3),
background: col('ink'), color: col('paper') },
qr: { position: 'bottom-right', size: mm(19), inset: mm(2.5), // 111 characters: 45 modules
color: col('ink'), background: col('paper'), radius: mm(1) },
// The HTML5 player of a file honours every option. download: false writes
// controlslist="nodownload": it hides the button, and the file stays at its address.
يعمل ملف script.js المجمّع كما هو: الصقه في سكربت الوحدة (module) لأي صفحة، أو افتح الوصفة على CodePen. مجلد الوصفة على GitHub ↗ (يفتح في تبويب جديد)
تنويعات
#اجعل مقطعًا يبدأ وحده
يُوضع player الخاص بكل مقطع فوق videoStyle.player. ويبدأ التشغيل التلقائي دائمًا بلا صوت، كما تشترط المتصفحات.
];
+clips[0].video.player = { autoplay: true }; // the 10° clip starts as the pane opens#اعرض الصورة المطبوعة على الشاشة
مع html: 'poster' تضع نسخة HTML الصورة مع علامة التشغيل ورمز QR، مربوطةً بعنوان النشر، مكان المشغّل.
const videoStyle = {
+ html: 'poster',#استعمل فيديو من YouTube أو Vimeo
source: 'youtube' مع عنوان الفيديو يضمّن مشغّل YouTube من youtube-nocookie.com (وprivacy مفعّل افتراضيًا). وهذا المشغّل يلتزم بخيارات أقل: الأزرار، وملء الشاشة، والتشغيل التلقائي، وكتم الصوت، والتكرار؛ ويضيف مشغّل Vimeo قائمة السرعة والصورة داخل الصورة، ولا يعرض أيٌّ منهما التنزيل. ولا يجوز لملف EPUB أن يضمّن مشغّل صفحة ويب، فيكون الفيديو فيه صورته مربوطةً بالفيديو. والخيارات ومدى كل منها في الإعدادات › نمط الفيديو.
أخطاء شائعة
خطأ شائع
لا تضمّن renderToEpub إلا الخطوط التي تمرّرها إليها
الخطوط التي حمّلها المتصفح ليست ملفات تستطيع postext-epub قراءتها: مرّر في options.fonts بايتات كل خط تستخدمه الصفحات (ملفات woff2 نفسها من Fontsource التي حمّلتها الصفحة). يُبلَّغ عن الخط الناقص بتحذير missingFont، ويُنضّد نظام القراءة ذلك النص بخط من عنده، وهو في التخطيط الثابت لا يتسع للأسطر التي نُضّدت بها الصفحة. لا تضمّن إلا الخطوط التي تسمح رخصتها بذلك. التصدير إلى EPUB →
خطأ شائع
ملفات Fontsource تغطي الحروف لا الرموز
تضمّن العُدّة ملف latin من Fontsource لكل خط، ومعه ملف latin-ext للحروف č وł و†، وملف greek للحروف α وχ (في عائلة تضمه: لا يضمه Lora ولا Gelasio)، حين يستعملها النص، على الشاشة وفي PDF. أما رموز مثل → و≈ و✓ و★ فليست في أي من هذه الملفات فتغيب عن PDF: ارسمها، أو اكتبها رياضيات، أو اختر خطًا تضمها ملفاته. الخطوط المضمَّنة في PDF →
ملفا MP4 بترميز H.264. تشغّلهما متصفحات Chrome وEdge وSafari وFirefox، وكذلك Chrome for Testing الذي يستعمله الالتقاط. أما Chromium المبني بلا مرمّزاته المملوكة، وهو الإعداد الافتراضي للمشروع المفتوح، فلا يشغّلهما؛ رمّز المقطعين بصيغة WebM (format: 'webm') إن كان ذلك يهم قرّاءك.
الحقوق
- الوصفة
- Ignacio Ferro
- النص
- نص أصلي, CC BY 4.0
- الصور
- Video 1: a pendulum 1 m long released from 10°, 8 s at 25 frames per second, rendered from an RK4 solution of the pendulum equation (1 ms steps) with Python and encoded with ffmpeg · Postext Cookbook · CC BY 4.0
- Video 2: the same pendulum released from 80°, rendered and encoded the same way · Postext Cookbook · CC BY 4.0
- The first frame of Video 1, its printed poster · Postext Cookbook · CC BY 4.0
- The first frame of Video 2, its printed poster · Postext Cookbook · CC BY 4.0
- الخطوط
- Source Serif 4 (SIL OFL 1.1) · Red Hat Display (SIL OFL 1.1) · Red Hat Mono (SIL OFL 1.1)
- الشيفرة
- MIT، مثل Postext
حرّر هذا الشرح ↗ (يفتح في تبويب جديد)مجلد الوصفة على GitHub ↗ (يفتح في تبويب جديد)


