From c41678c8a85ab01001bb95a2d7fb27b534354445 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Fri, 20 Nov 2026 11:49:29 +0200 Subject: [PATCH 1/3] feat(normalize, author): the page's build moves an mp4's index to the front, by the normalizer's plan (#218) --- design/author.md | 4 +- design/layout.md | 5 +- design/normalize.md | 4 +- docs/compatibility.md | 4 +- packages/author/README.md | 6 +- packages/author/lib/browser.mjs | 30 +++- packages/author/tests/browser/page.test.ts | 12 ++ packages/normalize/README.md | 7 + packages/normalize/lib/mp4-faststart.mjs | 136 +-------------- packages/normalize/lib/mp4.mjs | 155 +++++++++++++++++- .../normalize/tests/mp4-faststart.test.ts | 22 +++ 11 files changed, 243 insertions(+), 142 deletions(-) diff --git a/design/author.md b/design/author.md index a6b0f4d8..7326c2c0 100644 --- a/design/author.md +++ b/design/author.md @@ -82,7 +82,9 @@ text to the content check's rules, and `apps/skills` plays every example untrust not take is refused (a video takes MP4, WebM and Ogg; a recording MP3, M4A, WAV, Ogg and WebM): a web page at an address that ends `.mp4`, as a wiki's file page or a share link answers, built and passed the verifier before (#218). An mp4's index is read through the normalizer's - `mp4Info`, the walk its faststart uses, in Node and on a page alike. No index to read is a + `mp4Info`, the walk its faststart uses, in Node and on a page alike, and on a page the index is + moved to the front by the normalizer's plan, `faststartPlan`, the file made of the given one's + slices and the rewritten index (#218, item 5). No index to read is a problem. Where the index lists tracks, no sound or no picture is a note, a silent video being one an author can mean, and so is HEVC. Where it gives a length, that holds an Interactive Video's times (`videoTimes`): a start, a bookmark or an end screen past the end is refused, an diff --git a/design/layout.md b/design/layout.md index 8cb5e1e2..268210c9 100644 --- a/design/layout.md +++ b/design/layout.md @@ -24,8 +24,9 @@ packages/runtime/ the H5P core vendored at a commit (vendor/h5p-core/) and and the `finished` rule are bundled into it; l10n/ the core's strings packages/libraries/ the library pack: parts/ an archive per library and its index, libraries.h5p the whole pack; committed, built by `pnpm libraries` -packages/normalize/ the package rewriter: lib/normalize.mjs the policy, mp4-faststart.mjs the - remux, zip-writer.mjs the zip writer, mp4.mjs what an MP4's index says +packages/normalize/ the package rewriter: lib/normalize.mjs the policy, mp4.mjs what an MP4's + index says and the remux's plan, mp4-faststart.mjs that plan over a file, + zip-writer.mjs the zip writer packages/verify/ a package played headless (lib/verify.mjs) and in a browser (lib/preview.mjs); lib/serve.mjs what both share, which the extension bundles packages/author/ a playable .h5p from a short source: lib/build.mjs both builds, node.mjs diff --git a/design/normalize.md b/design/normalize.md index 1f52dbb6..97d488a1 100644 --- a/design/normalize.md +++ b/design/normalize.md @@ -4,7 +4,9 @@ deflated, non-faststart video, applied where it belongs: to the package, by whoever publishes it. It is its own package, `packages/normalize`, published as `@missing-elements/h5p-normalize` so that a publisher runs it with `npx` and needs no checkout: `lib/normalize.mjs` holds the policy, -`lib/mp4-faststart.mjs` the remux and `lib/zip-writer.mjs` the output side; `bin/h5p-normalize.mjs` +`lib/mp4.mjs` the remux's plan (`faststartPlan`, exported as `./mp4`, which h5p-author's page build +runs on a `Blob`), `lib/mp4-faststart.mjs` that plan over a range of a file, and +`lib/zip-writer.mjs` the output side; `bin/h5p-normalize.mjs` is the command. Its documented API is `normalizeArchive`, with `formatBytes` and `archiveFingerprint` re-exported, so the other modules stay free to change; the demo's content build and h5p-author's Node build are the callers in this repository. Its `prepublishOnly` runs its diff --git a/docs/compatibility.md b/docs/compatibility.md index 5c56d738..47dc7f04 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -122,8 +122,8 @@ with the specification is a conformance fix. The command's options, and `normalizeArchive()`, `formatBytes()` and `archiveFingerprint()`, with their types, `crc32()` from `@missing-elements/h5p-normalize/crc32`, which embed and h5p-author take -through a range, and `mp4Info()` from `@missing-elements/h5p-normalize/mp4`, which h5p-author takes -the same way. The content of a package it rewrites never changes. How it lays out the zip may change in a minor, as +through a range, and `mp4Info()` and `faststartPlan()` from `@missing-elements/h5p-normalize/mp4`, +which h5p-author takes the same way. The content of a package it rewrites never changes. How it lays out the zip may change in a minor, as long as the player streams the result at least as well. ### The verifier, `@missing-elements/h5p-verify` diff --git a/packages/author/README.md b/packages/author/README.md index c763b2b0..176c79c9 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -379,9 +379,9 @@ const { blob, notes } = await buildPackage(source, { libraries, files: { 'volga. - `fetch`: for media named by web address. - Media go in after the content and stored, each with its size and CRC in the header in front of it, as the player reads them on a host without `Range`; the libraries carried for an H5P site's - upload check come after them, as in Node. An mp4 goes in as it was given. Moving its index to the - front, so that it starts before the whole file has arrived, is the normalizer's job, which runs - in Node: `npx @missing-elements/h5p-normalize@latest course.h5p`. + upload check come after them, as in Node. An mp4's or an m4a's index is moved to the front, as + the normalizer moves it in Node, so that it starts before the whole file has arrived: the file is + made of slices of the one given and the rewritten index, and the media are never copied. A page has two limits that Node does not: diff --git a/packages/author/lib/browser.mjs b/packages/author/lib/browser.mjs index 4b2eddac..b94ffa7c 100644 --- a/packages/author/lib/browser.mjs +++ b/packages/author/lib/browser.mjs @@ -1,5 +1,6 @@ import { BlobReader, BlobWriter, ZipWriter } from '@zip.js/zip.js' import { crc32 } from '@missing-elements/h5p-normalize/crc32' +import { faststartPlan } from '@missing-elements/h5p-normalize/mp4' import { packLibrariesIn } from '@missing-elements/h5p-offline-player/plan' import { composePackage, sourceOf, typeNames, writePackage } from './build.mjs' import { MediaStore } from './media.mjs' @@ -16,8 +17,8 @@ export * from './core.mjs' * package comes back as a `Blob`, its media stored with their sizes and CRC in their local headers, * as embed's SCORM writer stores its entries since #92, so that the player reads each one's size * off its header on a host without `Range`, and before the libraries carried for an H5P site's - * upload check, as Node's build lays them out. An mp4 goes in as it was given: moving its index to - * the front is the normalizer's, which runs in Node. It needs a secure context, https, localhost or + * upload check, as Node's build lays them out. An mp4's or an m4a's index is moved to the front, as + * the normalizer does in Node, by its plan (#218). It needs a secure context, https, localhost or * a Tauri window, for `crypto.subtle` and `crypto.randomUUID`. */ @@ -126,6 +127,28 @@ function pageMedia(files) { } } +/** The files the normalizer lays out with their index first, by extension, as it tells them. */ +const ISO_MEDIA = /\.(?:mp4|m4v|m4a|mov)$/i + +/** + * A stored video or recording laid out to stream, its index (`moov`) in front of its media, as + * Node's build lays it out through the normalizer (#218): by the normalizer's own plan + * (`faststartPlan`), made of the given file's slices and the rewritten index, so that no byte of + * the media is copied. A file of another kind, or one the plan leaves as it is, is the file given. + * @param {Blob} blob + * @param {string} name its name in the package + * @returns {Promise} + */ +async function laidOut(blob, name) { + if (!ISO_MEDIA.test(name)) return blob + const read = async (/** @type {number} */ offset, /** @type {number} */ length) => new Uint8Array(await blob.slice(offset, offset + length).arrayBuffer()) + const plan = await faststartPlan(read, blob.size) + if (plan.status !== 'moved') return blob + // The rewritten index is a copy of its own, over an ArrayBuffer, as a Blob takes it. + const parts = plan.pieces.map((piece) => ('bytes' in piece ? /** @type {Uint8Array} */ (piece.bytes) : blob.slice(piece.start, piece.end))) + return new Blob(parts, { type: blob.type }) +} + /** * A `Blob`'s CRC-32, read as a stream. * @param {Blob} blob @@ -171,7 +194,8 @@ export async function buildPackage(input, options) { await writePackage(writer, built, pack, async () => { for (const item of media.files) { // Stored, its size and CRC in its local header: written into a stream, zip.js would put them in a descriptor after it. - await writer.add(`content/${item.name}`, new BlobReader(item.from), { passThrough: true, compressionMethod: 0, uncompressedSize: item.from.size, crc32: await crcOf(item.from) }) + const file = await laidOut(item.from, item.name) + await writer.add(`content/${item.name}`, new BlobReader(file), { passThrough: true, compressionMethod: 0, uncompressedSize: file.size, crc32: await crcOf(file) }) } }) return { diff --git a/packages/author/tests/browser/page.test.ts b/packages/author/tests/browser/page.test.ts index 15ce8376..74657cfd 100644 --- a/packages/author/tests/browser/page.test.ts +++ b/packages/author/tests/browser/page.test.ts @@ -1,3 +1,4 @@ +import { BlobReader, type FileEntry, Uint8ArrayWriter, ZipReader } from '@zip.js/zip.js' import { pack } from '@missing-elements/h5p-libraries/install' import { describe, expect, it } from 'vitest' import { commands } from 'vitest/browser' @@ -90,6 +91,17 @@ describe('the build in a page', () => { }) const built = await buildPackage(source(5), { libraries, files: { 'clip.mp4': clip } }) expect(built.notes.filter(({ path }) => path.endsWith('.path'))).toEqual([{ path: 'params.interactiveVideo.video.files[0].path', message: 'clip.mp4 has no sound' }]) + // Stored with its index first, as Node's build lays it out, and its CRC that of what is stored. + const reader = new ZipReader(new BlobReader(built.blob), { checkSignature: true }) + try { + const entry = (await reader.getEntries()).find(each => each.filename === 'content/videos/clip.mp4') as FileEntry + const stored = await entry.getData(new Uint8ArrayWriter()) + const text = new TextDecoder('latin1').decode(stored) + expect(entry.compressionMethod).toBe(0) + expect(stored.length).toBe(clip.size) + expect(text.indexOf('moov')).toBeGreaterThan(0) + expect(text.indexOf('moov')).toBeLessThan(text.indexOf('mdat')) + } finally { await reader.close() } await expect(buildPackage(source(40), { libraries, files: { 'clip.mp4': clip } })).rejects.toMatchObject({ problems: [{ path: 'params.interactiveVideo.assets.interactions[0].duration', message: 'starts at 40 s, after the video ends at 30 s' }] }) diff --git a/packages/normalize/README.md b/packages/normalize/README.md index 9dde571c..ef9c91e9 100644 --- a/packages/normalize/README.md +++ b/packages/normalize/README.md @@ -65,6 +65,13 @@ length in seconds, and each track's kind and codec. `read(offset, length)` gives fewer at its end, so it runs on a file in Node or a `Blob` in a page. It reads atoms' headers and a few small atoms, never the media. +`faststartPlan(read, size)`, from the same module, is how the normalizer moves an mp4's index in +front of its media: `{ status, detail, pieces, size }`, `status` `moved`, `already` or `skipped`, +and `pieces` the output in order, each a range of the file (`{ start, end }`) or the rewritten index +(`{ bytes }`). Only the index is read whole. On a page, a `Blob` of the pieces, the ranges as +slices, is the file laid out to stream; the media are never copied. A file it does not understand +is `skipped`, its one piece the whole file. + Why deflated video cannot stream: the demo's [normalize page](https://github.com/missing-elements/h5p-toolkit/blob/main/apps/demo/demo/normalize.html). diff --git a/packages/normalize/lib/mp4-faststart.mjs b/packages/normalize/lib/mp4-faststart.mjs index 3b7b423d..a802d608 100644 --- a/packages/normalize/lib/mp4-faststart.mjs +++ b/packages/normalize/lib/mp4-faststart.mjs @@ -1,22 +1,10 @@ /** - * Moves an mp4's `moov` atom in front of its `mdat`, so a player can decode the first frame from - * the first few hundred kilobytes instead of after the last byte. A remux, not a re-encode: the - * only bytes that change are the chunk offset tables (`stco` / `co64`) inside `moov`, which - * shift by the length of `moov` itself because `moov` now sits in front of the data they point - * into. The same thing `qt-faststart` and `ffmpeg -movflags +faststart` do. - * - * Works on a range of an open file rather than on a buffer: the video may be a stored entry read - * in place in the source archive, or an inflated copy in a temp file, and neither is loaded - * whole. Only `moov` — a few megabytes at most — is read into memory, because it is rewritten. + * Moves an mp4's `moov` atom in front of its `mdat` in a range of an open file: the video may be + * a stored entry read in place in the source archive, or an inflated copy in a temp file, and + * neither is loaded whole. The plan is `faststartPlan`'s, in `mp4.mjs`, which a page runs on a + * `Blob` too; this gives it the file's bytes and reads the pieces it names. */ -import { formatBytes } from './format.mjs' -import { topLevelAtoms } from './mp4.mjs' - -/** Atoms whose children hold the chunk offset tables. Nothing under any other branch does. */ -const CONTAINERS = new Set(['trak', 'mdia', 'minf', 'stbl']) - -/** Larger than any real index; a `moov` past this is a malformed file, and is left alone. */ -const MAX_MOOV_SIZE = 256 * 1024 * 1024 +import { faststartPlan } from './mp4.mjs' const READ_CHUNK = 1024 * 1024 @@ -41,57 +29,14 @@ const READ_CHUNK = 1024 * 1024 * @returns {Promise} */ export async function planFaststart(file, base, size) { - /** @type {Piece[]} */ - const identity = [{ start: base, end: base + size }] - /** @param {string} detail */ - const skipped = (detail) => ({ status: /** @type {const} */ ('skipped'), detail, pieces: identity, size }) - // The media file's own bytes, never past its end: it may be a range of a larger file. const read = async (/** @type {number} */ offset, /** @type {number} */ length) => { const buffer = Buffer.alloc(Math.max(0, Math.min(length, size - offset))) await readExact(file, buffer, base + offset) return buffer } - // As far as a fragment, which says the file streams as it is, however many follow. - const atoms = await topLevelAtoms(read, size, 'moof') - if (!atoms) return skipped('not an ISO media file') - if (atoms.some((atom) => atom.type === 'moof')) return skipped('fragmented mp4, already streamable') - - const moov = atoms.find((atom) => atom.type === 'moov') - const mdat = atoms.find((atom) => atom.type === 'mdat') - if (!moov) return skipped('no moov atom') - if (!mdat) return skipped('no mdat atom') - if (moov.offset < mdat.offset) { - return { status: 'already', detail: 'moov already precedes mdat', pieces: identity, size } - } - if (moov.size > MAX_MOOV_SIZE) return skipped('moov is implausibly large') - - const moovBytes = Buffer.alloc(moov.size) - await readExact(file, moovBytes, base + moov.offset) - - // Where a byte ends up once `moov` is lifted out from behind `mdat` and dropped in front of it: - // anything before `mdat` stays put, anything from `mdat` up to `moov` moves back by `moov`'s - // length, and anything after `moov` loses it in front and gains it behind, so does not move. - /** @param {number} position */ - const shift = (position) => (position >= mdat.offset && position < moov.offset ? moov.size : 0) - - const problem = patchChunkOffsets(moovBytes, moov.headerSize, moov.size, shift) - if (problem) return skipped(problem) - - /** @type {Piece[]} */ - const pieces = [ - { start: base, end: base + mdat.offset }, - { bytes: moovBytes }, - { start: base + mdat.offset, end: base + moov.offset }, - { start: base + moov.offset + moov.size, end: base + size } - ].filter((piece) => 'bytes' in piece || piece.end > piece.start) - - return { - status: 'moved', - detail: `moov was behind ${formatBytes(moov.offset - mdat.offset)} of mdat`, - pieces, - size - } + const plan = await faststartPlan(read, size) + return { ...plan, pieces: plan.pieces.map((piece) => ('bytes' in piece ? piece : { start: base + piece.start, end: base + piece.end })) } } /** @@ -117,73 +62,6 @@ export async function* readPieces(file, pieces) { } } -/** - * Walks the atoms between `start` and `end` inside `moov`, descending into the containers that - * lead to sample tables, and adds `shift(offset)` to every chunk offset it finds. Any other - * absolute position it knows of — `saio` — makes the file one it will not move. Returns a - * reason where the table cannot be rewritten, `null` on success. - * - * @param {Buffer} moov - * @param {number} start - * @param {number} end - * @param {(position: number) => number} shift - * @returns {string | null} - */ -function patchChunkOffsets(moov, start, end, shift) { - let position = start - - while (position + 8 <= end) { - let atomSize = moov.readUInt32BE(position) - const type = moov.toString('latin1', position + 4, position + 8) - let headerSize = 8 - - if (atomSize === 1) { - if (position + 16 > end) return 'truncated atom inside moov' - atomSize = Number(moov.readBigUInt64BE(position + 8)) - headerSize = 16 - } else if (atomSize === 0) { - atomSize = end - position - } - if (atomSize < headerSize || position + atomSize > end) return 'malformed atom inside moov' - - if (type === 'cmov') return 'compressed moov is not supported' - // Common Encryption keeps the offsets of its per-sample data in `saio`, and in a file that is - // not fragmented those are absolute file positions, like the chunk offsets. Moving `moov` - // without rewriting them would leave a protected video that can no longer be decrypted, so - // such a file is left as it was. - if (type === 'saio') return 'encrypted sample data (saio) is not supported' - - if (CONTAINERS.has(type)) { - const problem = patchChunkOffsets(moov, position + headerSize, position + atomSize, shift) - if (problem) return problem - } else if (type === 'stco' || type === 'co64') { - const body = position + headerSize - const wide = type === 'co64' - const entrySize = wide ? 8 : 4 - if (body + 8 > position + atomSize) return `truncated ${type}` - const count = moov.readUInt32BE(body + 4) // after the version and flags word - if (body + 8 + count * entrySize > position + atomSize) return `${type} claims more entries than it holds` - - for (let index = 0; index < count; index++) { - const at = body + 8 + index * entrySize - if (wide) { - const offset = moov.readBigUInt64BE(at) - moov.writeBigUInt64BE(offset + BigInt(shift(Number(offset))), at) - } else { - const offset = moov.readUInt32BE(at) - const moved = offset + shift(offset) - if (moved > 0xffffffff) return 'a chunk offset would outgrow stco; the file needs co64' - moov.writeUInt32BE(moved, at) - } - } - } - - position += atomSize - } - - return null -} - /** * Fills `buffer` from `position`, or throws: a short read here means the file changed under us. * @param {import('node:fs/promises').FileHandle} file diff --git a/packages/normalize/lib/mp4.mjs b/packages/normalize/lib/mp4.mjs index bb09ce5d..b273e3cc 100644 --- a/packages/normalize/lib/mp4.mjs +++ b/packages/normalize/lib/mp4.mjs @@ -2,8 +2,11 @@ * An ISO media file, an mp4's or an m4a's, read by its atoms: where they are, and what its index * (`moov`) says of it. Through a `read(offset, length)` that gives fewer bytes at the file's end, * so it runs wherever the bytes are, a file in Node or a `Blob` on a page. Only atoms' headers and - * a few small atoms are read: never the media, nor the index's tables. + * a few small atoms are read: never the media, nor the index's tables, but where the index is moved + * in front of the media (`faststartPlan`), which reads it whole to rewrite its chunk offsets. */ +import { formatBytes } from './format.mjs' + /** * @typedef {(offset: number, length: number) => Promise} Read the file's bytes from an @@ -166,3 +169,153 @@ async function trackOf(read, trak) { const codec = await textIn(read, stsd, 12, 4) return { kind: KINDS[handler] ?? 'other', codec } } + +/** Atoms whose children hold the chunk offset tables. Nothing under any other branch does. */ +const CONTAINERS = new Set(['trak', 'mdia', 'minf', 'stbl']) + +/** Larger than any real index; a `moov` past this is a malformed file, and is left alone. */ +const MAX_MOOV_SIZE = 256 * 1024 * 1024 + +/** + * @typedef {{ start: number, end: number } | { bytes: Uint8Array }} Piece a range of the media + * file, end exclusive, or literal bytes + * + * @typedef {object} FaststartPlan + * @property {'moved' | 'already' | 'skipped'} status + * @property {string} detail why, in words + * @property {Piece[]} pieces the output in order; the whole file when nothing moved + * @property {number} size the output length, always the input's + */ + +/** + * How to lay an mp4 out with its index (`moov`) in front of its media (`mdat`), so that a player + * decodes the first frame from the first few hundred kilobytes instead of after the last byte. A + * remux, not a re-encode: the only bytes that change are the chunk offset tables (`stco`, `co64`) + * inside `moov`, which shift by its length, since it now sits in front of the data they point + * into: what `qt-faststart` and `ffmpeg -movflags +faststart` do. Only `moov`, a few megabytes at + * most, is read into memory; the rest is ranges of the file. So it runs wherever the bytes are: a + * range of a file in Node, as the normalizer's faststart, or a `Blob` on a page, whose slices are + * the ranges, as the author's build page lays out a video it stores. + * + * Never throws over content: a file that is no ISO media file, or one whose structure this does + * not understand, comes back `skipped`, with the input as its output. + * @param {Read} read + * @param {number} size the file's length + * @returns {Promise} + */ +export async function faststartPlan(read, size) { + /** @type {Piece[]} */ + const identity = [{ start: 0, end: size }] + /** @param {string} detail */ + const skipped = (detail) => ({ status: /** @type {const} */ ('skipped'), detail, pieces: identity, size }) + + // As far as a fragment, which says the file streams as it is, however many follow. + const atoms = await topLevelAtoms(read, size, 'moof') + if (!atoms) return skipped('not an ISO media file') + if (atoms.some((atom) => atom.type === 'moof')) return skipped('fragmented mp4, already streamable') + + const moov = atoms.find((atom) => atom.type === 'moov') + const mdat = atoms.find((atom) => atom.type === 'mdat') + if (!moov) return skipped('no moov atom') + if (!mdat) return skipped('no mdat atom') + if (moov.offset < mdat.offset) { + return { status: 'already', detail: 'moov already precedes mdat', pieces: identity, size } + } + if (moov.size > MAX_MOOV_SIZE) return skipped('moov is implausibly large') + + const whole = await read(moov.offset, moov.size) + if (whole.length < moov.size) throw new Error(`Unexpected end of file at ${moov.offset + whole.length}`) + // A copy: a read may hand back a view of bytes it keeps, which are not this to change. + const index = new Uint8Array(whole) + + // Where a byte ends up once `moov` is lifted out from behind `mdat` and dropped in front of it: + // anything before `mdat` stays put, anything from `mdat` up to `moov` moves back by `moov`'s + // length, and anything after `moov` loses it in front and gains it behind, so does not move. + /** @param {number} position */ + const shift = (position) => (position >= mdat.offset && position < moov.offset ? moov.size : 0) + + const problem = patchChunkOffsets(index, moov.headerSize, moov.size, shift) + if (problem) return skipped(problem) + + /** @type {Piece[]} */ + const pieces = [ + { start: 0, end: mdat.offset }, + { bytes: index }, + { start: mdat.offset, end: moov.offset }, + { start: moov.offset + moov.size, end: size } + ].filter((piece) => 'bytes' in piece || piece.end > piece.start) + + return { + status: 'moved', + detail: `moov was behind ${formatBytes(moov.offset - mdat.offset)} of mdat`, + pieces, + size + } +} + +/** + * Walks the atoms between `start` and `end` inside `moov`, descending into the containers that + * lead to sample tables, and adds `shift(offset)` to every chunk offset it finds. Any other + * absolute position it knows of, `saio`, makes the file one it will not move. Returns a reason + * where the table cannot be rewritten, `null` on success. + * @param {Uint8Array} moov + * @param {number} start + * @param {number} end + * @param {(position: number) => number} shift + * @returns {string | null} + */ +function patchChunkOffsets(moov, start, end, shift) { + const view = new DataView(moov.buffer, moov.byteOffset, moov.byteLength) + let position = start + + while (position + 8 <= end) { + let atomSize = view.getUint32(position) + const type = ascii(moov.subarray(position + 4, position + 8)) + let headerSize = 8 + + if (atomSize === 1) { + if (position + 16 > end) return 'truncated atom inside moov' + atomSize = Number(view.getBigUint64(position + 8)) + headerSize = 16 + } else if (atomSize === 0) { + atomSize = end - position + } + if (atomSize < headerSize || position + atomSize > end) return 'malformed atom inside moov' + + if (type === 'cmov') return 'compressed moov is not supported' + // Common Encryption keeps the offsets of its per-sample data in `saio`, and in a file that is + // not fragmented those are absolute file positions, like the chunk offsets. Moving `moov` + // without rewriting them would leave a protected video that can no longer be decrypted, so + // such a file is left as it was. + if (type === 'saio') return 'encrypted sample data (saio) is not supported' + + if (CONTAINERS.has(type)) { + const problem = patchChunkOffsets(moov, position + headerSize, position + atomSize, shift) + if (problem) return problem + } else if (type === 'stco' || type === 'co64') { + const body = position + headerSize + const wide = type === 'co64' + const entrySize = wide ? 8 : 4 + if (body + 8 > position + atomSize) return `truncated ${type}` + const count = view.getUint32(body + 4) // after the version and flags word + if (body + 8 + count * entrySize > position + atomSize) return `${type} claims more entries than it holds` + + for (let index = 0; index < count; index++) { + const at = body + 8 + index * entrySize + if (wide) { + const offset = view.getBigUint64(at) + view.setBigUint64(at, offset + BigInt(shift(Number(offset)))) + } else { + const offset = view.getUint32(at) + const moved = offset + shift(offset) + if (moved > 0xffffffff) return 'a chunk offset would outgrow stco; the file needs co64' + view.setUint32(at, moved) + } + } + } + + position += atomSize + } + + return null +} diff --git a/packages/normalize/tests/mp4-faststart.test.ts b/packages/normalize/tests/mp4-faststart.test.ts index 8a00c610..6f8859c4 100644 --- a/packages/normalize/tests/mp4-faststart.test.ts +++ b/packages/normalize/tests/mp4-faststart.test.ts @@ -3,6 +3,7 @@ import { tmpdir } from 'node:os' import { join } from 'node:path' import { describe, expect, it } from 'vitest' import { planFaststart, readPieces } from '../lib/mp4-faststart.mjs' +import { faststartPlan } from '../lib/mp4.mjs' import { atom, atomsIn, chunkOffsets, concat, findAtom, sampleMp4, stco, u32s } from './helpers/mp4' async function withFile(bytes: Uint8Array, run: (file: Awaited>) => Promise): Promise { @@ -117,3 +118,24 @@ describe('planFaststart', () => { } }) }) + +describe('faststartPlan', () => { + it('lays out bytes held in memory as the faststart lays out a file, and leaves the bytes it read as they were', async () => { + const sample = sampleMp4() + const original = sample.bytes.slice() + // A read that hands back views of the bytes it holds, as a page reading a Blob's slices need not. + const read = async (offset: number, length: number) => sample.bytes.subarray(offset, Math.min(offset + length, sample.bytes.length)) + const plan = await faststartPlan(read, sample.bytes.length) + expect(plan.status).toBe('moved') + const laid = concat(plan.pieces.map((piece) => ('bytes' in piece ? piece.bytes : sample.bytes.subarray(piece.start, piece.end)))) + const fromFile = await withFile(sample.bytes, async (file) => assemble(file, await planFaststart(file, 0, sample.bytes.length))) + expect(laid).toEqual(fromFile) + expect(types(laid)).toEqual(['ftyp', 'free', 'moov', 'mdat']) + expect(sample.bytes).toEqual(original) + + for (const bytes of [sampleMp4({ faststart: true }).bytes, new TextEncoder().encode('')]) { + const left = await faststartPlan(async (offset, length) => bytes.subarray(offset, offset + length), bytes.length) + expect(left.pieces).toEqual([{ start: 0, end: bytes.length }]) + } + }) +}) From bd7780a9bf35d2e894af8da8591eb0f55a919af3 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Fri, 20 Nov 2026 12:04:24 +0200 Subject: [PATCH 2/3] fix(normalize, author): a nested index is left alone, the page asks the plan of every file, and the publish check holds the normalizer's version (#218) --- design/author.md | 3 ++- design/normalize.md | 3 ++- packages/author/lib/browser.mjs | 13 +++++-------- .../author/scripts/check-pack-published.mjs | 12 +++++++++++- packages/normalize/lib/mp4-faststart.mjs | 11 +++-------- packages/normalize/lib/mp4.mjs | 14 +++++++++++--- packages/normalize/tests/mp4-faststart.test.ts | 18 ++++++++++++++++++ 7 files changed, 52 insertions(+), 22 deletions(-) diff --git a/design/author.md b/design/author.md index 7326c2c0..7ddef4a1 100644 --- a/design/author.md +++ b/design/author.md @@ -145,7 +145,8 @@ text to the content check's rules, and `apps/skills` plays every example untrust needs no project set up; `--libraries` names another `parts/` folder. Each part is checked against the index's SHA-256 before it is read. `prepublishOnly` refuses while that version is not on npm with this checkout's index (`scripts/check-pack-published.mjs`, which checks the player it pins - and the normalizer's `./crc32` too). + and the normalizer's `./crc32` too, and holds the normalizer's version to 1.5.0, the first with + the `faststartPlan` the page's build imports, #218). - **The player's library rules, not copies of them** (#106, the owner's rule: reuse what another package has). Which libraries content names, an addon's patterns and which parts of the pack a package needs are the player's: the build plans with `planPack` from the player's `./plan`. Two diff --git a/design/normalize.md b/design/normalize.md index 97d488a1..9bc6d5b5 100644 --- a/design/normalize.md +++ b/design/normalize.md @@ -8,7 +8,8 @@ a publisher runs it with `npx` and needs no checkout: `lib/normalize.mjs` holds runs on a `Blob`), `lib/mp4-faststart.mjs` that plan over a range of a file, and `lib/zip-writer.mjs` the output side; `bin/h5p-normalize.mjs` is the command. Its documented API is `normalizeArchive`, with `formatBytes` and -`archiveFingerprint` re-exported, so the other modules stay free to change; the demo's content +`archiveFingerprint` re-exported, and two entries a page takes too: `./crc32`, and `./mp4` with +`mp4Info` and `faststartPlan` (docs/compatibility.md). The other modules stay free to change; the demo's content build and h5p-author's Node build are the callers in this repository. Its `prepublishOnly` runs its typecheck and tests, and its `prepack` copies the root LICENSE in. Five things about it that the code does not say by itself: diff --git a/packages/author/lib/browser.mjs b/packages/author/lib/browser.mjs index b94ffa7c..ae5bd41e 100644 --- a/packages/author/lib/browser.mjs +++ b/packages/author/lib/browser.mjs @@ -127,20 +127,17 @@ function pageMedia(files) { } } -/** The files the normalizer lays out with their index first, by extension, as it tells them. */ -const ISO_MEDIA = /\.(?:mp4|m4v|m4a|mov)$/i - /** * A stored video or recording laid out to stream, its index (`moov`) in front of its media, as * Node's build lays it out through the normalizer (#218): by the normalizer's own plan * (`faststartPlan`), made of the given file's slices and the rewritten index, so that no byte of - * the media is copied. A file of another kind, or one the plan leaves as it is, is the file given. + * the media is copied. Every file is asked of the plan, which tells an mp4 or an m4a by its first + * eight bytes and leaves any other file, and one with its index first already, as it is: no list + * of extensions is kept here beside the normalizer's. * @param {Blob} blob - * @param {string} name its name in the package * @returns {Promise} */ -async function laidOut(blob, name) { - if (!ISO_MEDIA.test(name)) return blob +async function laidOut(blob) { const read = async (/** @type {number} */ offset, /** @type {number} */ length) => new Uint8Array(await blob.slice(offset, offset + length).arrayBuffer()) const plan = await faststartPlan(read, blob.size) if (plan.status !== 'moved') return blob @@ -194,7 +191,7 @@ export async function buildPackage(input, options) { await writePackage(writer, built, pack, async () => { for (const item of media.files) { // Stored, its size and CRC in its local header: written into a stream, zip.js would put them in a descriptor after it. - const file = await laidOut(item.from, item.name) + const file = await laidOut(item.from) await writer.add(`content/${item.name}`, new BlobReader(file), { passThrough: true, compressionMethod: 0, uncompressedSize: file.size, crc32: await crcOf(file) }) } }) diff --git a/packages/author/scripts/check-pack-published.mjs b/packages/author/scripts/check-pack-published.mjs index 46dc6184..78e08358 100644 --- a/packages/author/scripts/check-pack-published.mjs +++ b/packages/author/scripts/check-pack-published.mjs @@ -7,7 +7,9 @@ * not install either, and one pinned to a player published before `./plan` existed would install * and fail on its first import, so the version on npm has to export it. And the normalizer, a * range from the version packages/normalize has, whose `./crc32` the page's build imports (#108): - * that version has to be on npm with it, or a page's build fails on its first import. + * that version has to be on npm with it, or a page's build fails on its first import. The page's + * build also imports `faststartPlan` from its `./mp4` (#218), which npm's record of a version does + * not list, so the version itself is held to the first that has it. */ import { readFile } from 'node:fs/promises' import { resolve } from 'node:path' @@ -54,6 +56,14 @@ if (!(await published.json()).exports?.['./plan']) { console.log(`[player] @missing-elements/h5p-offline-player@${player} is published, and exports ./plan`) const normalize = await versionOf('normalize') +// The first with `faststartPlan` in `./mp4`. The range published is from packages/normalize's +// version, so one below this would let the author install beside a normalizer without it. +const NORMALIZER_FLOOR = [1, 5, 0] +const [major, minor, patch] = normalize.split('.').map(Number) +if (major === NORMALIZER_FLOOR[0] && (minor < NORMALIZER_FLOOR[1] || (minor === NORMALIZER_FLOOR[1] && patch < NORMALIZER_FLOOR[2]))) { + console.error(`[normalize] packages/normalize is ${normalize}, and the page's build imports faststartPlan from its ./mp4, new in ${NORMALIZER_FLOOR.join('.')}: bump the normalizer to that, publish it, and publish the author package against it.`) + process.exit(1) +} const normalizer = await served(`https://registry.npmjs.org/@missing-elements%2fh5p-normalize/${normalize}`, `@missing-elements/h5p-normalize@${normalize}`, { until }) stopUnlessAnswered(normalizer, `@missing-elements/h5p-normalize@${normalize} on npm`) if (!normalizer.ok) { diff --git a/packages/normalize/lib/mp4-faststart.mjs b/packages/normalize/lib/mp4-faststart.mjs index a802d608..b57e9341 100644 --- a/packages/normalize/lib/mp4-faststart.mjs +++ b/packages/normalize/lib/mp4-faststart.mjs @@ -9,14 +9,9 @@ import { faststartPlan } from './mp4.mjs' const READ_CHUNK = 1024 * 1024 /** - * @typedef {{ start: number, end: number } | { bytes: Uint8Array }} Piece - * Either a range of the source file — absolute positions, end exclusive — or literal bytes. - * - * @typedef {object} FaststartPlan - * @property {'moved' | 'already' | 'skipped'} status - * @property {string} detail why, in words - * @property {Piece[]} pieces the output in order; the input itself when nothing moved - * @property {number} size the output length, always equal to the input length + * @typedef {import('./mp4.mjs').Piece} Piece here a range of the source file, absolute positions, + * or literal bytes + * @typedef {import('./mp4.mjs').FaststartPlan} FaststartPlan */ /** diff --git a/packages/normalize/lib/mp4.mjs b/packages/normalize/lib/mp4.mjs index b273e3cc..364feef8 100644 --- a/packages/normalize/lib/mp4.mjs +++ b/packages/normalize/lib/mp4.mjs @@ -7,7 +7,6 @@ */ import { formatBytes } from './format.mjs' - /** * @typedef {(offset: number, length: number) => Promise} Read the file's bytes from an * offset, fewer at its end @@ -176,6 +175,13 @@ const CONTAINERS = new Set(['trak', 'mdia', 'minf', 'stbl']) /** Larger than any real index; a `moov` past this is a malformed file, and is left alone. */ const MAX_MOOV_SIZE = 256 * 1024 * 1024 +/** + * Deeper than the containers of a real index nest, which is four, `trak` to `stbl`: an index made + * of containers inside containers, as only a crafted file has, is left alone before the walk + * through it runs out of stack. + */ +const MAX_DEPTH = 8 + /** * @typedef {{ start: number, end: number } | { bytes: Uint8Array }} Piece a range of the media * file, end exclusive, or literal bytes @@ -262,9 +268,11 @@ export async function faststartPlan(read, size) { * @param {number} start * @param {number} end * @param {(position: number) => number} shift + * @param {number} [depth] how many containers deep `start` is * @returns {string | null} */ -function patchChunkOffsets(moov, start, end, shift) { +function patchChunkOffsets(moov, start, end, shift, depth = 0) { + if (depth > MAX_DEPTH) return 'containers nested deeper than an index has' const view = new DataView(moov.buffer, moov.byteOffset, moov.byteLength) let position = start @@ -290,7 +298,7 @@ function patchChunkOffsets(moov, start, end, shift) { if (type === 'saio') return 'encrypted sample data (saio) is not supported' if (CONTAINERS.has(type)) { - const problem = patchChunkOffsets(moov, position + headerSize, position + atomSize, shift) + const problem = patchChunkOffsets(moov, position + headerSize, position + atomSize, shift, depth + 1) if (problem) return problem } else if (type === 'stco' || type === 'co64') { const body = position + headerSize diff --git a/packages/normalize/tests/mp4-faststart.test.ts b/packages/normalize/tests/mp4-faststart.test.ts index 6f8859c4..7564a3ea 100644 --- a/packages/normalize/tests/mp4-faststart.test.ts +++ b/packages/normalize/tests/mp4-faststart.test.ts @@ -120,6 +120,24 @@ describe('planFaststart', () => { }) describe('faststartPlan', () => { + it('leaves alone an index of containers nested deeper than a real one, however deep, and one just as deep as a real one is moved', async () => { + // A hundred thousand `trak` atoms, each holding the next: a walk into every one runs out of stack. + const levels = 100_000 + const nested = new Uint8Array(levels * 8) + const view = new DataView(nested.buffer) + for (let level = 0; level < levels; level++) { + view.setUint32(level * 8, nested.length - level * 8) + nested.set(new TextEncoder().encode('trak'), level * 8 + 4) + } + const crafted = concat([atom('ftyp', u32s(1)), atom('mdat', new Uint8Array(8)), atom('moov', nested)]) + const plan = await faststartPlan(async (offset, length) => crafted.subarray(offset, offset + length), crafted.length) + expect(plan).toMatchObject({ status: 'skipped', detail: 'containers nested deeper than an index has', pieces: [{ start: 0, end: crafted.length }] }) + + const real = concat([atom('ftyp', u32s(1)), atom('mdat', new Uint8Array(8)), atom('moov', atom('trak', atom('mdia', atom('minf', atom('stbl', stco([16]))))))]) + expect((await faststartPlan(async (offset, length) => real.subarray(offset, offset + length), real.length)).status).toBe('moved') + }) + + it('lays out bytes held in memory as the faststart lays out a file, and leaves the bytes it read as they were', async () => { const sample = sampleMp4() const original = sample.bytes.slice() From 2af58de0c2aa68a70c1d9d36b1217eb885be37a2 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Fri, 20 Nov 2026 12:11:59 +0200 Subject: [PATCH 3/3] fix(normalize, author): the normalizer's floor holds for any version below it, and the file plan says its positions (#218) --- packages/author/scripts/check-pack-published.mjs | 6 ++++-- packages/normalize/lib/mp4-faststart.mjs | 10 ++++++---- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/packages/author/scripts/check-pack-published.mjs b/packages/author/scripts/check-pack-published.mjs index 78e08358..bdffadba 100644 --- a/packages/author/scripts/check-pack-published.mjs +++ b/packages/author/scripts/check-pack-published.mjs @@ -59,8 +59,10 @@ const normalize = await versionOf('normalize') // The first with `faststartPlan` in `./mp4`. The range published is from packages/normalize's // version, so one below this would let the author install beside a normalizer without it. const NORMALIZER_FLOOR = [1, 5, 0] -const [major, minor, patch] = normalize.split('.').map(Number) -if (major === NORMALIZER_FLOOR[0] && (minor < NORMALIZER_FLOOR[1] || (minor === NORMALIZER_FLOOR[1] && patch < NORMALIZER_FLOOR[2]))) { +const parts = normalize.split('.').map((/** @type {string} */ part) => Number.parseInt(part, 10)) +// The first part that differs decides, and a version that is no three numbers is below any. +const differs = NORMALIZER_FLOOR.findIndex((floor, i) => parts[i] !== floor) +if (differs !== -1 && !(parts[differs] > NORMALIZER_FLOOR[differs])) { console.error(`[normalize] packages/normalize is ${normalize}, and the page's build imports faststartPlan from its ./mp4, new in ${NORMALIZER_FLOOR.join('.')}: bump the normalizer to that, publish it, and publish the author package against it.`) process.exit(1) } diff --git a/packages/normalize/lib/mp4-faststart.mjs b/packages/normalize/lib/mp4-faststart.mjs index b57e9341..e3d24bc0 100644 --- a/packages/normalize/lib/mp4-faststart.mjs +++ b/packages/normalize/lib/mp4-faststart.mjs @@ -9,9 +9,11 @@ import { faststartPlan } from './mp4.mjs' const READ_CHUNK = 1024 * 1024 /** - * @typedef {import('./mp4.mjs').Piece} Piece here a range of the source file, absolute positions, - * or literal bytes - * @typedef {import('./mp4.mjs').FaststartPlan} FaststartPlan + * @typedef {{ start: number, end: number } | { bytes: Uint8Array }} Piece a range of the open + * file, absolute positions in it, end exclusive, or literal bytes: where `faststartPlan`'s + * ranges are counted from the media file's start, these have `base` added + * @typedef {Omit & { pieces: Piece[] }} FaststartPlan + * `faststartPlan`'s, its pieces positions in the open file */ /** @@ -21,7 +23,7 @@ const READ_CHUNK = 1024 * 1024 * @param {import('node:fs/promises').FileHandle} file * @param {number} base where the media file starts within `file` * @param {number} size its length - * @returns {Promise} + * @returns {Promise} its ranges absolute positions in `file`, for `readPieces` */ export async function planFaststart(file, base, size) { // The media file's own bytes, never past its end: it may be a range of a larger file.