Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -143,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
Expand Down
5 changes: 3 additions & 2 deletions design/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 5 additions & 2 deletions design/normalize.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,12 @@
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
Comment thread
alekswebnet marked this conversation as resolved.
Resolved
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:
Expand Down
4 changes: 2 additions & 2 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
6 changes: 3 additions & 3 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
alekswebnet marked this conversation as resolved.
Resolved

A page has two limits that Node does not:

Expand Down
27 changes: 24 additions & 3 deletions packages/author/lib/browser.mjs
Original file line number Diff line number Diff line change
@@ -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'
Expand All @@ -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
Comment thread
alekswebnet marked this conversation as resolved.
Resolved
* 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`.
*/

Expand Down Expand Up @@ -126,6 +127,25 @@ function pageMedia(files) {
}
}

/**
* 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. 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
* @returns {Promise<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
// 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<ArrayBuffer>} */ (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
Expand Down Expand Up @@ -171,7 +191,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)
await writer.add(`content/${item.name}`, new BlobReader(file), { passThrough: true, compressionMethod: 0, uncompressedSize: file.size, crc32: await crcOf(file) })
}
})
return {
Expand Down
14 changes: 13 additions & 1 deletion packages/author/scripts/check-pack-published.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -54,6 +56,16 @@ 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 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)
}
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) {
Expand Down
12 changes: 12 additions & 0 deletions packages/author/tests/browser/page.test.ts
Original file line number Diff line number Diff line change
@@ -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'
Expand Down Expand Up @@ -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' }]
})
Expand Down
7 changes: 7 additions & 0 deletions packages/normalize/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
Loading