feat: @dcmjs-org/video — MP4 wrapping, image datasets, and the video event source

[awatson1978]

This is the assembly PR for the video package: it brings release/1.0-beta-video into 1.0-beta, carrying PRs #576, #578, #581 and #583 on top of the core engine branch, each individually reviewed with its own plain-English description. Like the other assemblies (#542, #543, #575, #577, #584), it's open as a draft on purpose — please don't merge it yet; the landing order and the trunk overlap (details below) mean the assemblies should go in deliberately, not as soon as they're green.

What this is in plain terms. @dcmjs-org/video gets video and camera imagery into DICOM without re-encoding. Its header parsers (parseJpegInfo, parseMp4Info) read the geometry and timing DICOM needs — rows, columns, frame count, frame rate, codec profile — straight from the JPEG or MP4 bytes, without decoding a single pixel, so the compressed stream can travel verbatim into encapsulated PixelData. encapsulateVideo wraps an MP4's H.264 stream into a Video Photographic Image instance and extractEncapsulatedVideo recovers it byte-identically. buildImageDataset goes the other way for already-decoded pixels, producing a conformant image instance. And createVideoEventSource is the streaming path: MP4 to contract events, one fragment in memory at a time, feeding any event-stream sink. The package imports only @dcmjs-org/core and @dcmjs-org/parser — never legacy.

A worked example, both directions — run on this branch, output verbatim.

Creating: an MP4 becomes a complete Part 10 file, streamed one fragment at a time (the header parsers recover the geometry; nothing is re-encoded):

import { createVideoEventSource } from "./packages/video/src/index.js";
import { StreamingPart10Writer } from "@dcmjs-org/generator";
import fs from "fs";

const mp4 = fs.readFileSync("clip.mp4"); // the run below used the suite's synthetic MP4

const source = await createVideoEventSource(mp4, { PatientName: "FOX^JANE" });
source.info; // { rows: 48, columns: 64, numberOfFrames: 12, frameRate: 60,
             //   transferSyntaxUID: "1.2.840.10008.1.2.4.104.1", codec: "avc1" }

const writer = new StreamingPart10Writer();
await source.run(writer);
const part10 = writer.toArrayBuffer(); // 2,588 bytes for the 1,665-byte test clip
fs.writeFileSync("clip.dcm", Buffer.from(part10));

Reading: the Part 10 file comes back through the engine, and the original MP4 comes out byte-identical:

import { fromPart10, NaturalizedListener } from "@dcmjs-org/parser";
import { extractEncapsulatedVideo } from "./packages/video/src/index.js";

const listener = new NaturalizedListener();
await fromPart10(part10, listener);

const ds = listener.result;
ds.SOPClassUID;     // "1.2.840.10008.5.1.4.1.1.77.1.4.1" (Video Photographic Image)
ds.NumberOfFrames;  // 12
ds.CineRate;        // 60

const { bytes } = extractEncapsulatedVideo(ds);
// bytes === the original MP4 (verified: 1,665 of 1,665 bytes equal)

The buffered pair works the same way without the event stream: encapsulateVideo(mp4, attrs) gives the naturalized dataset directly, and extractEncapsulatedVideo recovers the stream from any dataset however it was read.

What's in it. Four PRs, in the order they landed:

• feat(video): scaffold @dcmjs-org/video with the JPEG and MP4 header parsers #576 — the scaffold and the header parsers. The @dcmjs-org/video package (publishable, MIT, 0.0.0 like its siblings), jpegInfo.js and mp4Info.js with the synthetic-MP4 test factory (makeTinyMp4), the ported mp4Info suite, and a brand-new jpegInfo suite — v2 never had one.
• feat(video): port buildImageDataset with the encapsulated frame-count fix #578 — buildImageDataset. The decoded-pixels-to-instance builder with its 21-test suite.
• feat(video): port the buffered video encapsulation layer #581 — the buffered encapsulation layer. encapsulateVideo / extractEncapsulatedVideo and the fragment helpers, with their 8-test suite.
• feat(video): port the video event source, legacy-free #583 — the video event source. createVideoEventSource, reworked legacy-free: v2's datasetToDict (a legacy import) is replaced by a ~29-line local helper producing the plain {meta, dict} shape the parser's fromDataSet accepts.

The three review findings fixed here, from the PR #512 review map — each regression was written against the ported-but-unfixed code and observed failing first:

• Finding 9 (HIGH, feat(video): scaffold @dcmjs-org/video with the JPEG and MP4 header parsers #576). parseJpegInfo's scan guard checked only 4 bytes of headroom while the SOF parse reads 10, so a truncated JPEG silently returned wrong geometry (the review's exact vector — FF D8 FF C0 00 11 08 01 E0 02 — came back as columns 512 instead of failing). Truncation now throws.
• Finding 10 (HIGH, feat(video): port buildImageDataset with the encapsulated frame-count fix #578). buildImageDataset never derived NumberOfFrames from the encapsulated fragment list — a three-frame encapsulation produced a dataset with no NumberOfFrames at all. The frame list is now the ground truth: it fills the default and an explicit mismatch throws.
• Finding 15 (MED, feat(video): scaffold @dcmjs-org/video with the JPEG and MP4 header parsers #576). parseMp4Info's stts fallback trusted the box's raw entry count, so a malformed file claiming 0xFFFFFF entries blocked the thread for tens of seconds and fabricated a frame count. The entry count is now bounded by the box's own size; the regression asserts the malformed file is rejected fast.

One open question for maintainers, raised in #576 and deliberately not fixed: 12-bit extended-sequential JPEG currently yields BitsAllocated 12, but PS3.5 allows only 8 or 16 (correct would be BitsAllocated 16 with BitsStored 12). It's a ~5-line fix in buildImageDataset if you agree.

Test evidence. 913 tests across 75 suites on this branch — 901 passing, 12 skipped (the pre-existing skips), zero failures, on Node 22 and 24. The package itself is 57 tests in 5 suites, including the new jpegInfo suite and the finding regressions. CI is green at the branch tip 58dba59: tests, lint/format, audit. One honest gap, declared in #576: every MP4 in the suite is synthetic (makeTinyMp4) — no real-world camera file exercises the box parser yet. Adding one later means a DATACITATION row and a license check, like every committed fixture.

Test usage. From the repo root:

npx jest packages/video --testTimeout 60000

Expected: 5 suites, 57 tests, all passing in a few seconds.

GitHub issues. None map directly — the historical backlog has no video-area issues (video support itself arrived with the 1.0 rewrite). The three fixes above trace to the #512 review map rather than filed issues.

The numbers. The package is +2,100 lines under packages/video/ (about two-thirds verbatim v2 port, declared per-PR; the hand-written remainder is the three fixes, their regressions, the new jpegInfo suite, and the legacy-free rework of the event source) across 4 PRs and their conventional commits, merged (not squashed) so the release tooling sees each one. The raw diff against 1.0-beta is much larger because this branch is cut from the core engine tip (e5f46e4) — it carries the whole core trunk that draft #542 also carries. Whichever assembly merges first absorbs that trunk, and this diff shrinks to just the video package.

Breaking changes. None — this is a new package; nothing under the existing src/ surface changes here. Within the port itself: truncated JPEGs and malformed MP4s that previously produced silently-wrong values now throw, and encapsulated multi-frame datasets gain the NumberOfFrames attribute they were always supposed to carry.

Still to come: the DicomEventStream facade factories (fromVideo, fromVideoStream, toVideo, fromImage) land with the media wave, which also carries the review's finding 14 (the lazy source-promise fix) — that wave touches the shared facade file, so it sequences after the three bulk-data packages rather than inside any one of them.

🤖 Generated with Claude Code