Skip to content

feat(author): check a video's and a recording's bytes, and read an mp4's index (#218) - #228

Merged
alekswebnet merged 3 commits into
mainfrom
feat/media-bytes
Nov 18, 2026
Merged

alekswebnet merged 3 commits into
mainfrom
feat/media-bytes

Conversation

@alekswebnet

@alekswebnet alekswebnet commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Part of #218: items 1 and 2. Step 4 of #219's plan, before the MCP server is announced. Item 3, the verifier, follows as a PR of its own.

What changes

  • A video's and a recording's container is read, as a picture's size is: an mp4 or an m4a by its index, after ftyp or an older file's moov, mdat, free or wide, any other by its first bytes (WebM, Ogg, WAV, MP3 by a frame header a decoder takes). A file that is none of what its field takes is a problem. A web page gets its own message, for the issue's case, a wiki's file page at an address ending .mp4, which built and passed the verifier before:
    …/wiki/File:clip.mp4 is a web page, not a video: give the address of the file itself
  • An mp4's index is read, in Node and on the build page alike:
    • no index to read is a problem ("is the file whole?");
    • no sound, no picture, or HEVC is a note, since a silent video can be meant. h5p-author: a source with media can build, pass the verifier and not play: check a video's and a recording's bytes #218 left HEVC and no picture as "a problem or a warning, to decide": both are notes here, and either can become a problem;
    • its length holds an Interactive Video's times. An interaction that starts past the end, a bookmark, an end screen or startVideoAt past it, is a problem. An interaction that only ends past it is not: it shows to the end. No time is named in a list an item of which was refused, since its indices are no longer the source's.
  • The normalizer exports the walk as @missing-elements/h5p-normalize/mp4, mp4Info(read, size), browser-safe like ./crc32. Its faststart now walks top-level atoms through the same code. It reads atoms' 8-byte headers and a few small atoms, each field within its atom, never a byte of the media; it stops at the index, or for the faststart at a fragment, and gives up past 10,000 atoms at one level, so a file of tiny atoms costs neither memory nor time.
  • Docs: design/author.md, both READMEs, docs/compatibility.md. design/normalize.md is left alone, since an uncommitted edit of it waits on main.

Testing

  • normalize: 9 new tests in mp4.test.ts: the length and tracks, the index before and after the media, a 64-bit header, no length, no byte of the media read, a header cut short, a file with no index or an index with no header, a fragmented file and a file of 20,000 tiny atoms, a file that is no mp4. The faststart tests pass unchanged on the shared walk.
  • author: 221 tests, 4 of them new:
    • the issue's wiki page, a local page named .mp4, an mp3 that is not one, a cut mp4, a UTF-16 page named .mp3, which passed for an MP3 frame before;
    • the notes: no sound, no picture, HEVC; an older mp4 with no ftyp builds;
    • Interactive Video's times, refused, within the length built, and none named after a refused item;
    • the page's build in Chromium, reading the index from a File.
  • skills: every type file's example still builds. The demo's clip, every video's sample, has no sound, the case that opened h5p-author: a source with media can build, pass the verifier and not play: check a video's and a recording's bytes #218, so that one note is allowed there.

Release

normalize 1.4.0, for ./mp4, comes before the author release that uses it: the author's dependency is workspace:^, so it publishes as ^1.4.0. With #227 the order is normalize 1.4.0, author 0.12.0, verify 1.6.0, then h5p-mcp 0.1.0.


Summary by cubic

Verifies a video's and a recording's bytes when building, so a web page at an address that ends .mp4, which built and passed the verifier before, is now refused as not being a video. Reads an mp4's index, in Node and on the build page alike, for its length and what its tracks hold, and holds an Interactive Video's times to that length: an interaction, bookmark, end screen, or startVideoAt past the end is refused, while an interaction that ends past it shows to the end.

Details

  • A file that is none of its field's containers — MP4/M4A by ftyp or by its index, WebM, Ogg, MP3 by an ID3 tag or a decoder's frame header, WAV — is a problem; so is an mp4 with no index to read.
  • No sound, no picture, or HEVC is a note, not a problem, since a silent video can be meant.
  • No Interactive Video time is named in a list an item of which was refused, since its indices are no longer the source's.
  • @missing-elements/h5p-normalize/mp4 exports mp4Info(read, size), browser-safe, while normalizeArchive remains Node only; the faststart walks top-level atoms through the same code, reading atoms' headers and a few small atoms, never the media, stopping at the index or a fragment, and giving up past 10,000 atoms at one level.

Written for commit 23b44b7. Summary will update on new commits.

View guided diff Turn on auto-fix

…4's index (#218)

- A video's or a recording's first bytes name its container (MP4/M4A,
  WebM, Ogg, MP3, WAV); one that is none its field takes is refused,
  a web page at an address ending .mp4 by name.
- An mp4's index, read through the normalizer's walk in Node and on the
  build page: none to read is a problem; no sound, no picture or HEVC a
  note; its length holds an Interactive Video's times.
- normalize exports the walk as ./mp4 (mp4Info), browser-safe; its
  faststart walks top-level atoms through the same code.

Part of #218, items 1 and 2.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found across 21 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/author/lib/types.mjs">

<violation number="1" location="packages/author/lib/types.mjs:469">
P2: The interaction index in this message is the generated-list index. When an earlier interaction was refused, the list is shorter, so the path can name the wrong interaction. Skip or map the index for lists the generator shortened, as `build.mjs` already does for other problems.</violation>
</file>

<file name="packages/author/README.md">

<violation number="1" location="packages/author/README.md:70">
P3: `mp4Info` can return a readable index with `duration: undefined`, and `videoTimes` skips timing checks in that case. Qualify this statement as applying only when the index supplies a duration.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

const list = (/** @type {unknown} */ value) => (Array.isArray(value) ? value : [])
const assets = params.interactiveVideo.assets
list(assets?.interactions).forEach((interaction, i) => {
if (late(interaction?.duration?.from)) report(`${path}.interactiveVideo.assets.interactions[${i}].duration`, `starts at ${interaction.duration.from} s, after ${end}`)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The interaction index in this message is the generated-list index. When an earlier interaction was refused, the list is shorter, so the path can name the wrong interaction. Skip or map the index for lists the generator shortened, as build.mjs already does for other problems.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/author/lib/types.mjs, line 469:

<comment>The interaction index in this message is the generated-list index. When an earlier interaction was refused, the list is shorter, so the path can name the wrong interaction. Skip or map the index for lists the generator shortened, as `build.mjs` already does for other problems.</comment>

<file context>
@@ -447,6 +447,35 @@ const interactiveVideo = {
+  const list = (/** @type {unknown} */ value) => (Array.isArray(value) ? value : [])
+  const assets = params.interactiveVideo.assets
+  list(assets?.interactions).forEach((interaction, i) => {
+    if (late(interaction?.duration?.from)) report(`${path}.interactiveVideo.assets.interactions[${i}].duration`, `starts at ${interaction.duration.from} s, after ${end}`)
+  })
+  for (const key of ['bookmarks', 'endscreens']) {
</file context>

Comment thread packages/normalize/lib/mp4.mjs Resolved
Comment thread packages/normalize/lib/mp4.mjs Resolved
Comment thread packages/author/lib/media.mjs Resolved
Comment thread packages/normalize/tests/mp4.test.ts Resolved
Comment thread design/author.md Resolved
Comment thread packages/normalize/lib/mp4.mjs Resolved
Comment thread packages/author/lib/media.mjs Resolved
Comment thread design/author.md Resolved
Comment thread packages/author/README.md Outdated
optional `copyright`. Each is copied into the package with its type and, for a picture, its size.
A video or a recording is read from its first bytes, and one that is not what its field takes, a
web page at a file's address among them, is refused; an mp4's index says whether it has sound,
and how long it is, past which an Interactive Video's times are refused. The package is then

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: mp4Info can return a readable index with duration: undefined, and videoTimes skips timing checks in that case. Qualify this statement as applying only when the index supplies a duration.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/author/README.md, line 70:

<comment>`mp4Info` can return a readable index with `duration: undefined`, and `videoTimes` skips timing checks in that case. Qualify this statement as applying only when the index supplies a duration.</comment>

<file context>
@@ -64,8 +64,11 @@ What `params` takes is what H5P's editor would let an author save in the same fo
+  optional `copyright`. Each is copied into the package with its type and, for a picture, its size.
+  A video or a recording is read from its first bytes, and one that is not what its field takes, a
+  web page at a file's address among them, is refused; an mp4's index says whether it has sound,
+  and how long it is, past which an Interactive Video's times are refused. The package is then
+  laid out to stream, media stored and an mp4's index first. A YouTube, Vimeo,
   Panopto or Echo360 address stays where it is, if it is one H5P.Video plays: a Short's is taken
</file context>
Suggested change
and how long it is, past which an Interactive Video's times are refused. The package is then
and, when it provides a duration, the build refuses Interactive Video starts, bookmarks, end screens and `startVideoAt` values past it. The package is then

- normalize's walk reads an atom's 8-byte header, and 8 more only for a
  64-bit size, so no media byte is read; stops at the index (mp4Info) or
  a fragment (faststart); gives up past 10,000 atoms at one level, so a
  file of tiny atoms costs neither memory nor time.
- Fields are read within their atom; an index without an mvhd is none.
- The author takes an mp4 by its index, whatever atom comes first, as
  the normalizer reads it; an MP3 by a frame header a decoder takes, so a
  UTF-16 page, FF FE, is a page and not an MP3.
- No Interactive Video time is named in a list an item of which was
  refused: its indices are not the source's.
- Tests for each; the wording cubic found unclear.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 9 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/normalize/README.md Resolved
Comment thread design/author.md Resolved
Comment thread design/author.md Resolved
normalizeArchive is the part that is Node only; an mp4 is read by its
index after ftyp or an older file's moov, mdat, free or wide; no time is
named in a list where an item was refused.
@alekswebnet
alekswebnet merged commit 9edd854 into main Nov 18, 2026
18 of 19 checks passed
@alekswebnet
alekswebnet deleted the feat/media-bytes branch November 18, 2026 11:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant