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
3 changes: 1 addition & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
182 changes: 97 additions & 85 deletions README.md

Large diffs are not rendered by default.

5 changes: 3 additions & 2 deletions design/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
5 changes: 3 additions & 2 deletions design/licensing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
7 changes: 4 additions & 3 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
116 changes: 116 additions & 0 deletions packages/player/README.md
Original file line number Diff line number Diff line change
@@ -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
<h5p-player src="https://host.example/course.h5p"></h5p-player>
```

```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.
14 changes: 6 additions & 8 deletions packages/player/scripts/prepack.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Loading