diff --git a/.gitignore b/.gitignore index ce53c7d..7bc22c4 100644 --- a/.gitignore +++ b/.gitignore @@ -11,8 +11,7 @@ types # reproducible from source. public -# Copied from the repository root by the player's `prepack`, so npm finds them in the package. -packages/player/README.md +# Copied from the repository root by the player's `prepack`, so npm finds it in the package. packages/player/LICENSE # The same for the normalizer, the verifier, the author, the cmi5 wiring and the embed site writer, whose `prepack` copies the LICENSE. packages/normalize/LICENSE diff --git a/README.md b/README.md index 7366caa..3cc060d 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,56 @@ # H5P Toolkit by Missing Elements -[![npm](https://img.shields.io/npm/v/%40missing-elements%2Fh5p-offline-player)](https://www.npmjs.com/package/@missing-elements/h5p-offline-player) -[![licence](https://img.shields.io/npm/l/%40missing-elements%2Fh5p-offline-player)](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE) - -Self-hosted [H5P](https://h5p.org) without an H5P server. One web component plays `.h5p` files -from your own URLs or from disk, on static hosting you control: no Moodle, WordPress or Lumi, no -backend, and no service of ours or H5P Group's between your learners and your content. +Everything you needed an [H5P](https://h5p.org) server for (playing, building, checking, +packaging for an LMS) as static files, command-line tools and agent skills. **[Live player demo](https://h5p-offline-player.vercel.app/)** · +[Build with AI](https://missing-elements.github.io/h5p/build/) · [Offline app](https://h5p-offline-player.vercel.app/app/) · [H5P to SCORM](https://h5p-offline-player.vercel.app/demo/scorm.html) · -[Lovable example](https://embed-h5p-file.lovable.app/) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=MissingElements.h5p-preview) -Version 1 since October 2026; [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) -says what a version number promises. **Every week** a job rebuilds the library pack from the H5P -hub and the interface strings from Moodle's translations, opens a pull request when either -changed, and plays every content type in the pack, trusted and untrusted. - -## Features - -- **Plays the packages people have.** Large ones stream, and exports without their libraries, as - h5p.com and h5p.org make them, play against a [library pack](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) - of the 53 content types the H5P hub serves. -- **Plays packages you did not make** with [`untrusted`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md): none of their - code runs, and their content is checked by a port of H5P's own validator. -- **Reports results you can audit:** xAPI statements that name the - [build of the package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) they came from, [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md), [resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md), and a - [SCORM zip](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms): SCORM 1.2, checked in - Moodle, ILIAS, OpenOLAT, Chamilo, SCORM Cloud and Frappe LMS, or 2004, checked in Moodle and - SCORM Cloud. -- **No tracking:** no account, cookies or telemetry, and nothing it stores leaves the learner's - browser. The library pack comes from jsDelivr unless you serve a copy +The player and the packages around it are at version 1 since October 2026, and +[Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) +says what a version number promises; the author package, the MCP server and the VS Code +extension are 0.x. **Every week** a job rebuilds the library pack from the H5P hub and the +interface strings from Moodle's translations, opens a pull request when either changed, and plays +every content type in the pack, trusted and untrusted. + +## What it does + +| To | Use | +|---|---| +| Play `.h5p` files on your site, from your own URLs or from disk | [``](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/player#readme), a web component | +| Play them from a domain of your own, or hand an LMS a SCORM zip or a cmi5 unit | [`h5p-embed`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#readme), [`h5p-cmi5`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/cmi5#readme) | +| Build an activity of any content type from a prompt or a short JSON source | the [`h5p-author` skill](https://github.com/missing-elements/h5p-toolkit/tree/main/skills/h5p-author), [the build page](https://missing-elements.github.io/h5p/build/), or [`h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) in Claude Desktop | +| Check that a package plays before you hand it over | [`h5p-verify`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/verify#readme) | +| Make a package's video start at once | [`h5p-normalize`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/normalize#readme) | +| Play `.h5p` files with no network, or in your editor | [the offline app](https://h5p-offline-player.vercel.app/app/), [H5P Preview](https://marketplace.visualstudio.com/items?itemName=MissingElements.h5p-preview) for VS Code | + +## Why this one + +- **No H5P server anywhere.** H5P usually runs in Moodle, WordPress or Drupal with its plugin, on + an h5p.com account, or in Lumi on a desktop. Here a `.h5p` plays from a URL on static hosting, + with nothing unzipped, and the tools run on your computer or in your agent. + [The comparison](https://h5p-offline-player.vercel.app/demo/compare.html) goes through + h5p-standalone, Lumi, h5p.com and the plugins. +- **The packages people have.** Exports without their libraries, as h5p.com and h5p.org make + them, play against a library pack of every content type the H5P hub serves, and packages you + did not make play [`untrusted`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md), + with none of their code run. +- **What a model builds is checked.** `h5p-author` writes a package that carries its libraries, + which Moodle accepts as an upload, and `h5p-verify` plays it in the real H5P runtime in a + headless browser before anyone hands it over. +- **Nothing passes through a server of ours:** no account, cookies or telemetry, and the library + pack comes from jsDelivr unless you serve a copy ([privacy](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md)). -- **Works offline, in the content's language:** an installable app, and H5P's own buttons in - English and 56 other languages. -- **Tested in Chromium, Firefox and WebKit** on every change, and in Safari on macOS and iOS by - hand ([browsers](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md#browsers)). -- **Comes with tools:** [`h5p-verify`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/verify.md) checks that a package plays, - [`h5p-normalize`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/streaming-video.md) makes its video stream, and - [`h5p-author`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/author#readme) builds one from a short JSON source, which a - Moodle site accepts as an upload too. [`h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) - brings the build and the check to an app with no shell, such as Claude Desktop. - -It is a player, not an editor, and it stores no results: its events go wherever your page sends -them. Coming from [h5p-standalone](https://github.com/tunapanda/h5p-standalone)? This player -reads the `.h5p` itself, with nothing to unzip, and -[takes its options by the same names](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md). + +It is not an editor: H5P's own editor is not here, so content comes from the tools above or from +an H5P site. Nothing here stores results either: xAPI events go wherever your page sends them. ## Quick start -With Vite or webpack 5; both packages ship TypeScript declarations: +**Play** a package on your site, with Vite or webpack 5: ```bash npm install @missing-elements/h5p-offline-player @missing-elements/h5p-runtime @@ -64,50 +64,39 @@ npm install @missing-elements/h5p-offline-player @missing-elements/h5p-runtime import '@missing-elements/h5p-offline-player' import { runtime } from '@missing-elements/h5p-runtime' -const player = document.querySelector('h5p-player') -player.runtime = runtime -player.addEventListener('xapi', (e) => console.log(e.detail.statement)) +document.querySelector('h5p-player').runtime = runtime ``` -The bundler emits the Service Worker and the runtime (the H5P core, a package of its own because -it is GPL-3.0) as files, so there is nothing to copy. The page must be on `https://` or -`localhost`, and a package from another origin needs CORS headers on its host. A package that -carries its libraries plays as it is; one exported without them, as h5p.com exports, needs -`libraries="pack"`. +A package that carries its libraries plays as it is; one exported without them, as h5p.com +exports, needs `libraries="pack"` on the element. +[Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) +covers pages without a bundler, other bundlers, CORS, and which setup suits packages you did not +make. -Packages you did not make, or a site with signed-in users: play every package `untrusted`, or -embed the player from a domain of its own, as -[Which setup](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md#which-setup) explains. -[Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) also covers a page without a bundler, Rollup and -esbuild, and the one-prompt install on Lovable; -[the element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) lists every attribute, property and event. +**Build** with AI, in Claude Code or another agent that runs commands: -## Documentation +```bash +npx skills add missing-elements/h5p-toolkit --skill h5p-author +``` -- **Set up:** [Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) · - [The element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) · - [Troubleshooting](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/troubleshooting.md) · - [Single-worker hosts and upgrades](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/single-worker.md) · - [Coming from h5p-standalone](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md) -- **Packages:** [Libraries](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) · - [Packages you did not make](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md) · - [Video that cannot stream](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/streaming-video.md) · - [Verifying a package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/verify.md) · - [The frame's CSP](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/frame-csp.md) -- **Results:** [Resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md) · - [Which build a learner completed](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) · - [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md) · - [A SCORM package](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms) -- **Policies:** [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) · - [Privacy and data protection](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md) · - [Accessibility](https://github.com/missing-elements/h5p-toolkit/blob/main/ACCESSIBILITY.md) · - [Security](https://github.com/missing-elements/h5p-toolkit/blob/main/SECURITY.md) +Then ask it for an activity, such as "a five-question quiz on the water cycle, as H5P": it asks +which content type, builds the `.h5p`, checks it and opens it for you to play. In a chat app, +[the build page](https://missing-elements.github.io/h5p/build/) turns what the chat wrote into the +file, in your browser; in Claude Desktop, +[`h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) builds +it onto your disk. + +**Check** a package, with Node 22 or later: + +```bash +npx @missing-elements/h5p-verify@latest course.h5p +``` ## Packages | Package | What it is | |---|---| -| [`@missing-elements/h5p-offline-player`](https://www.npmjs.com/package/@missing-elements/h5p-offline-player) | The `` element and its workers | +| [`@missing-elements/h5p-offline-player`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/player#readme) | The `` element and its workers | | [`@missing-elements/h5p-runtime`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/runtime#readme) | The H5P core the player loads in its frame, GPL-3.0 | | [`@missing-elements/h5p-libraries`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/libraries#readme) | The library pack: the runtime libraries of every content type the H5P hub serves | | [`@missing-elements/h5p-embed`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#readme) | The player page as a static site, and a package as a SCORM zip | @@ -141,8 +130,28 @@ npx skills add missing-elements/h5p-toolkit A chat app takes `h5p-author` as a zip that you upload or attach. Download it from [missing-elements.github.io/h5p/create-with-ai/#install](https://missing-elements.github.io/h5p/create-with-ai/#install), which says where it goes in each app. The zip holds the same h5p-author release as the site's -build page runs. In Claude Desktop, [`h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) -builds onto your disk instead. +build page runs. + +## Documentation + +- **Set up:** [Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) · + [The element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) · + [Troubleshooting](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/troubleshooting.md) · + [Single-worker hosts and upgrades](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/single-worker.md) · + [Coming from h5p-standalone](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md) +- **Packages:** [Libraries](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) · + [Packages you did not make](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md) · + [Video that cannot stream](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/streaming-video.md) · + [Verifying a package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/verify.md) · + [The frame's CSP](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/frame-csp.md) +- **Results:** [Resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md) · + [Which build a learner completed](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) · + [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md) · + [A SCORM package](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms) +- **Policies:** [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) · + [Privacy and data protection](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md) · + [Accessibility](https://github.com/missing-elements/h5p-toolkit/blob/main/ACCESSIBILITY.md) · + [Security](https://github.com/missing-elements/h5p-toolkit/blob/main/SECURITY.md) ## Contributing @@ -154,13 +163,16 @@ the design and the reasons behind it. Report vulnerabilities privately, as ## Licence -The player is MIT ([LICENSE](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE)); -its Service Worker bundles [zip.js](https://github.com/gildas-lormeau/zip.js), BSD-3-Clause -([NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/player/NOTICE.md)). -The H5P runtime the frame loads, the H5P core from [h5p-php-library](https://github.com/h5p/h5p-php-library) -and the script that boots it, is GPL-3.0 and published separately as -[`@missing-elements/h5p-runtime`](https://www.npmjs.com/package/@missing-elements/h5p-runtime); +Every package is MIT ([LICENSE](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE)) +but two. The H5P runtime the player's frame loads, the H5P core from +[h5p-php-library](https://github.com/h5p/h5p-php-library) and the script that boots it, is GPL-3.0 +and published apart as [`@missing-elements/h5p-runtime`](https://www.npmjs.com/package/@missing-elements/h5p-runtime); the player talks to it only over HTTP and `postMessage`, and its [NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/runtime/NOTICE.md) -says what serving it entails. Whether the copyleft reaches the page around the player is a legal -question this README does not answer. +says what serving it entails. The library pack holds H5P's libraries, each under its own licence, +most MIT, as [its list](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/libraries/libraries.txt) +says. What a package bundles keeps its licence too: the player's Service Worker carries +[zip.js](https://github.com/gildas-lormeau/zip.js), BSD-3-Clause +([NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/player/NOTICE.md)). +Whether the copyleft reaches the page around the player is a legal question this README does not +answer. diff --git a/design/build.md b/design/build.md index 869ac29..f52d0ec 100644 --- a/design/build.md +++ b/design/build.md @@ -142,8 +142,9 @@ went; `typecheck` and `prepack` both run it. Three rules, with TypeScript 7: build) so a broken tree cannot ship; the browser suite is left out because it needs an installed Chromium. Firefox, WebKit and the slow browser files run only in CI's weekly run and a run by hand, so before publishing the player, run CI by hand on main (`gh workflow run ci.yml`) and wait for -green. Then `prepack` copies the root README and LICENSE into the package, which is where npm -takes them from. The repository sets no `ignore-scripts`, so `prepublishOnly` runs; pnpm 10 blocks +green. Then `prepack` copies the root LICENSE into the package, which is where npm takes it +from. The player's README is its own, `packages/player/README.md`, since the root one is the +toolkit's front page. The repository sets no `ignore-scripts`, so `prepublishOnly` runs; pnpm 10 blocks dependency scripts by itself. The build deletes `types/` and the TypeScript build info first: `tsc -b` never removes a declaration whose source was deleted. diff --git a/design/licensing.md b/design/licensing.md index fa94236..64bad64 100644 --- a/design/licensing.md +++ b/design/licensing.md @@ -90,8 +90,9 @@ library pack", which nobody sees. Changing that one changes every part's bytes, so every package's `libraries` revision, and every learner's saved state starts over once; it goes with the next pack release that rewrites every part anyway. The VS Code extension and the MCP server, "H5P Author MCP by Missing Elements", were named to the rule from -the start, and so is the README's title, "H5P Toolkit by Missing Elements", which is also the -player's on npm, since `prepack` copies the README. Not decided: the site's address, +the start, and so is the README's title, "H5P Toolkit by Missing Elements". The player's own +README, its page on npm, is titled with the package's name, whose scope names the author. +Not decided: the site's address, `h5p-offline-player.vercel.app`, which names no owner (the policy approves "h5p.terrisblog.com" and refuses "h5pbootcamp.com"), and the tab title "H5P player" of `/embed` and the embed package's page, a generic use. Two limits outweigh any name: the automatic licence covers free, diff --git a/docs/compatibility.md b/docs/compatibility.md index 01c6c37..5c56d73 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -160,9 +160,10 @@ in a major. None is in that state now. ## Browsers The player needs a secure context — https, or `localhost` — with Service Workers, the Cache API, -IndexedDB, Web Locks and `DecompressionStream` for `deflate-raw`. Its browser suite runs on every -change in Chromium, Firefox and WebKit, Playwright's builds of their current releases; Safari on -macOS and iOS is checked by hand. No version floor is published: a package that plays in a current +IndexedDB, Web Locks and `DecompressionStream` for `deflate-raw`. Its browser suite runs in +Chromium on every change, and in Firefox and WebKit every week and before each release of the +player, all three Playwright's builds of their current releases; Safari on macOS and iOS is +checked by hand. No version floor is published: a package that plays in a current browser and not in another that has those features is a bug, and worth reporting. Dropping an engine is a major change. diff --git a/packages/player/README.md b/packages/player/README.md new file mode 100644 index 0000000..b8ea9fb --- /dev/null +++ b/packages/player/README.md @@ -0,0 +1,116 @@ +# @missing-elements/h5p-offline-player + +[![npm](https://img.shields.io/npm/v/%40missing-elements%2Fh5p-offline-player)](https://www.npmjs.com/package/@missing-elements/h5p-offline-player) +[![licence](https://img.shields.io/npm/l/%40missing-elements%2Fh5p-offline-player)](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE) + +Self-hosted [H5P](https://h5p.org) without an H5P server. One web component plays `.h5p` files +from your own URLs or from disk, on static hosting you control: no Moodle, WordPress or Lumi, no +backend, and no service of ours or H5P Group's between your learners and your content. + +**[Live player demo](https://h5p-offline-player.vercel.app/)** · +[Offline app](https://h5p-offline-player.vercel.app/app/) · +[H5P to SCORM](https://h5p-offline-player.vercel.app/demo/scorm.html) · +[Lovable example](https://embed-h5p-file.lovable.app/) · +[VS Code extension](https://marketplace.visualstudio.com/items?itemName=MissingElements.h5p-preview) + +Version 1 since October 2026; [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) +says what a version number promises. **Every week** a job rebuilds the library pack from the H5P +hub and the interface strings from Moodle's translations, opens a pull request when either +changed, and plays every content type in the pack, trusted and untrusted. + +## Features + +- **Plays the packages people have.** Large ones stream, and exports without their libraries, as + h5p.com and h5p.org make them, play against a [library pack](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) + of the 53 content types the H5P hub serves. +- **Plays packages you did not make** with [`untrusted`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md): none of their + code runs, and their content is checked by a port of H5P's own validator. +- **Reports results you can audit:** xAPI statements that name the + [build of the package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) they came from, and [resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md). + With [`h5p-cmi5`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/cmi5#readme), a page holding the player is a + [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md) unit, and [`h5p-embed`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms) writes a package as a SCORM zip: + SCORM 1.2, checked in Moodle, ILIAS, OpenOLAT, Chamilo, SCORM Cloud and Frappe LMS, or 2004, + checked in Moodle and SCORM Cloud. +- **No tracking:** no account, cookies or telemetry, and nothing it stores leaves the learner's + browser. The library pack comes from jsDelivr unless you serve a copy + ([privacy](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md)). +- **Works offline, in the content's language:** an installable app, and H5P's own buttons in + English and 56 other languages. +- **Tested in Chromium** on every change, in Firefox and WebKit every week and before each + release, and in Safari on macOS and iOS by hand ([browsers](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md#browsers)). +- **Part of a toolkit:** [H5P Toolkit by Missing Elements](https://github.com/missing-elements/h5p-toolkit#readme) + also builds packages with AI, checks that they play, makes their video stream and turns them + into SCORM zips. + +It is a player, not an editor, and it stores no results: its events go wherever your page sends +them. Coming from [h5p-standalone](https://github.com/tunapanda/h5p-standalone)? This player +reads the `.h5p` itself, with nothing to unzip, and +[takes its options by the same names](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md). + +## Quick start + +With Vite or webpack 5; both packages ship TypeScript declarations: + +```bash +npm install @missing-elements/h5p-offline-player @missing-elements/h5p-runtime +``` + +```html + +``` + +```js +import '@missing-elements/h5p-offline-player' +import { runtime } from '@missing-elements/h5p-runtime' + +const player = document.querySelector('h5p-player') +player.runtime = runtime +player.addEventListener('xapi', (e) => console.log(e.detail.statement)) +``` + +The bundler emits the Service Worker and the runtime (the H5P core, a package of its own because +it is GPL-3.0) as files, so there is nothing to copy. The page must be on `https://` or +`localhost`, and a package from another origin needs CORS headers on its host. A package that +carries its libraries plays as it is; one exported without them, as h5p.com exports, needs +`libraries="pack"`. + +Packages you did not make, or a site with signed-in users: play every package `untrusted`, or +embed the player from a domain of its own, as +[Which setup](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md#which-setup) explains. +[Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) also covers a page without a bundler, Rollup and +esbuild, and the one-prompt install on Lovable; +[the element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) lists every attribute, property and event. + +## Documentation + +- **Set up:** [Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) · + [The element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) · + [Troubleshooting](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/troubleshooting.md) · + [Single-worker hosts and upgrades](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/single-worker.md) · + [Coming from h5p-standalone](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md) +- **Packages:** [Libraries](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) · + [Packages you did not make](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md) · + [Video that cannot stream](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/streaming-video.md) · + [Verifying a package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/verify.md) · + [The frame's CSP](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/frame-csp.md) +- **Results:** [Resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md) · + [Which build a learner completed](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) · + [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md) · + [A SCORM package](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms) +- **Policies:** [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) · + [Privacy and data protection](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md) · + [Accessibility](https://github.com/missing-elements/h5p-toolkit/blob/main/ACCESSIBILITY.md) · + [Security](https://github.com/missing-elements/h5p-toolkit/blob/main/SECURITY.md) + +## Licence + +The player is MIT ([LICENSE](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE)); +its Service Worker bundles [zip.js](https://github.com/gildas-lormeau/zip.js), BSD-3-Clause +([NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/player/NOTICE.md)). +The H5P runtime the frame loads, the H5P core from [h5p-php-library](https://github.com/h5p/h5p-php-library) +and the script that boots it, is GPL-3.0 and published separately as +[`@missing-elements/h5p-runtime`](https://www.npmjs.com/package/@missing-elements/h5p-runtime); +the player talks to it only over HTTP and `postMessage`, and its +[NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/runtime/NOTICE.md) +says what serving it entails. Whether the copyleft reaches the page around the player is a legal +question this README does not answer. diff --git a/packages/player/scripts/prepack.mjs b/packages/player/scripts/prepack.mjs index 7421250..e82c917 100644 --- a/packages/player/scripts/prepack.mjs +++ b/packages/player/scripts/prepack.mjs @@ -2,17 +2,15 @@ import { copyFile } from 'node:fs/promises' import { resolve } from 'node:path' /** - * Puts the repository's README and LICENSE into the package just before it is packed. npm takes - * both from the package's own folder, and the README is the repository's landing page as well, - * so it lives at the root and is copied here rather than kept twice. The copies are ignored by - * git. The README's one relative link, `LICENSE`, resolves in both places. + * Puts the repository's LICENSE into the package just before it is packed: npm takes it from the + * package's own folder, and it lives at the root, so it is copied here rather than kept twice. The + * copy is ignored by git. The README is the package's own, `README.md` beside this folder: the + * root one is the toolkit's front page, and npm shows this package's. */ const packageDir = resolve(import.meta.dirname, '..') const repositoryRoot = resolve(packageDir, '..', '..') -for (const name of ['README.md', 'LICENSE']) { - await copyFile(resolve(repositoryRoot, name), resolve(packageDir, name)) -} +await copyFile(resolve(repositoryRoot, 'LICENSE'), resolve(packageDir, 'LICENSE')) -console.log('[prepack] README.md and LICENSE copied from the repository root') +console.log('[prepack] LICENSE copied from the repository root')