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

Merged
AL
12h ago
+607-80

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. #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 #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.