@bubo-squared/gyroview 0.1.0

package/dist/packages/core/src/application/playback/probeDecoding.js

@@ -0,0 +1,168 @@
+import { hasErrorCode, messageOf } from "../../shared/errors/GyroViewError.js";
+import { Deferred } from "../../shared/async/Deferred.js";
+//#region ../../packages/core/src/application/playback/probeDecoding.ts
+var DECODES = {
+	verdict: "decodes",
+	detail: void 0
+};
+var NO_KEY_FRAME = {
+	verdict: "no-key-frame",
+	detail: "the track has no key frame"
+};
+var NO_FRAME_OUT = {
+	verdict: "decode-failed",
+	detail: "the decoder accepted the first key frame but produced no picture"
+};
+var TIMED_OUT = {
+	verdict: "timed-out",
+	detail: "the decoder produced no picture before the deadline"
+};
+var KEY_FRAME_LATE = {
+	verdict: "key-frame-late",
+	detail: "the first key frame did not arrive before the deadline"
+};
+/**
+* Use case: find out before playback whether this platform decodes the recording, by decoding the
+* first key frame of every frame source. The decoder port's `isSupported` alone is not trusted:
+* platforms answer yes and then fail, and hardware decoders can stall, hence the real decode under
+* a deadline. The host resolves `deadline` once the probe has taken too long (the core has no
+* timers); sources still undecided then report `timed-out`, or `key-frame-late` while their key
+* frame was still being read, and their decoders are closed. A track that cannot be read rejects
+* the probe with its own failure, and the other sources' decoders are closed then, not at the
+* deadline.
+*/
+async function probeDecoding(frameSources, decoderPort, deadline) {
+	const probes = frameSources.map((track) => new SourceProbe(track, decoderPort));
+	try {
+		const sources = await Promise.all(probes.map((probe) => probeFrameSource(probe, deadline)));
+		return {
+			canDecode: sources.every((source) => source.verdict === "decodes"),
+			sources
+		};
+	} finally {
+		for (const probe of probes) probe.close();
+	}
+}
+async function probeFrameSource(probe, deadline) {
+	try {
+		const outcome = await Promise.race([probe.run(), afterDeadline(deadline, probe)]);
+		return {
+			track: probe.track.description,
+			...outcome
+		};
+	} finally {
+		probe.close();
+	}
+}
+async function afterDeadline(deadline, probe) {
+	await deadline.promise;
+	return probe.outcomeAtDeadline;
+}
+/**
+* One frame source's probe: owns the decoder it opens so a deadline can close it from outside.
+* Closed while its decoder works, it settles as timed out; a key frame read that never answers
+* keeps its run pending until the track itself is let go, since track reads take no signal.
+*/
+var SourceProbe = class {
+	track;
+	decoderPort;
+	decoder;
+	/**
+	* The outcome the open decoder reports into, settled by a close as well.
+	*/
+	firstOutcome;
+	isClosed = false;
+	isReadingKeyFrame = false;
+	constructor(track, decoderPort) {
+		this.track = track;
+		this.decoderPort = decoderPort;
+	}
+	/**
+	* What a deadline passing now says: the network did not bring the key frame in time, or the
+	* platform did not answer or decode it in time.
+	*/
+	get outcomeAtDeadline() {
+		return this.isReadingKeyFrame ? KEY_FRAME_LATE : TIMED_OUT;
+	}
+	/**
+	* The decoder's answers make the verdict; a failure to read the track rejects as it is, since
+	* a connection that dropped is no codec's fault. A probe closed meanwhile reads no key frame and
+	* opens no decoder: decoders are few on some platforms, and the next load may need them.
+	*/
+	async run() {
+		const configuration = await this.track.decoderConfiguration();
+		if (!await this.decoderPort.isSupported(configuration)) return unsupported(configuration);
+		if (this.isClosed) return TIMED_OUT;
+		this.isReadingKeyFrame = true;
+		const keyPacket = await this.track.firstKeyPacket();
+		this.isReadingKeyFrame = false;
+		return keyPacket ? await this.decodeFirst(configuration, keyPacket) : NO_KEY_FRAME;
+	}
+	close() {
+		this.isClosed = true;
+		this.decoder?.close();
+		this.decoder = void 0;
+		this.firstOutcome?.resolve(TIMED_OUT);
+	}
+	async decodeFirst(configuration, keyPacket) {
+		if (this.isClosed) return TIMED_OUT;
+		const first = new Deferred();
+		this.firstOutcome = first;
+		const decoder = await this.openDecoder(configuration, first);
+		if (decoder === void 0) return first.promise;
+		this.decoder = decoder;
+		this.decodeInto(decoder, keyPacket, first);
+		return first.promise;
+	}
+	/**
+	* A decoder that reports into `first`; undefined, the outcome reported there, when the port
+	* refuses one or the probe was closed while it was being made.
+	*/
+	async openDecoder(configuration, first) {
+		try {
+			const decoder = await this.decoderPort.create(configuration, {
+				onFrame: (frame) => {
+					frame.close();
+					first.resolve(DECODES);
+				},
+				onError: (error) => {
+					first.resolve(failedWith(error));
+				}
+			});
+			if (!this.isClosed) return decoder;
+			decoder.close();
+			first.resolve(TIMED_OUT);
+		} catch (error) {
+			first.resolve(failedWith(error));
+		}
+	}
+	/**
+	* Decodes the key frame and forces its picture out of decoders that buffer. A decoder that
+	* refuses the packet (one that is no real key frame), or a flush that ends without a picture,
+	* is a failure.
+	*/
+	async decodeInto(decoder, keyPacket, first) {
+		try {
+			decoder.decode(keyPacket);
+			await decoder.flush();
+			first.resolve(NO_FRAME_OUT);
+		} catch (error) {
+			first.resolve(failedWith(error));
+		}
+	}
+};
+function unsupported(configuration) {
+	return {
+		verdict: "unsupported-configuration",
+		detail: `${configuration.codec} at ${configuration.codedWidth}x${configuration.codedHeight} is not supported here`
+	};
+}
+function failedWith(error) {
+	const message = messageOf(error);
+	return {
+		verdict: hasErrorCode(error, "codec-unsupported") ? "unsupported-configuration" : "decode-failed",
+		detail: message
+	};
+}
+//#endregion
+export { probeDecoding };

package/dist/packages/core/src/application/recording/frameTimesOf.js

@@ -0,0 +1,22 @@
+import { planFrameTimes } from "../../domain/motion/timing/resolveFrameTimes.js";
+//#region ../../packages/core/src/application/recording/frameTimesOf.ts
+/**
+* Frame times for a frame source. The exposure record costs one small read and is always at
+* hand; the track's own timestamps are fetched only when the domain says the answer depends on
+* them, since walking the sample table is the costly part. Undefined when even nominal spacing
+* is impossible (no frame rate).
+*/
+async function frameTimesOf(recording, frameSource, timeline) {
+	const { info } = recording;
+	const [frameCount, exposureRecord] = await Promise.all([frameSource.frameCount(), recording.readExposureRecord()]);
+	const plan = planFrameTimes({
+		...timeline,
+		frameCount,
+		frameRate: info.frameRate,
+		readoutTime: info.readoutTime,
+		exposureRecord
+	}, info.preferredFrameTimeSource);
+	return plan.needsTrackTimestamps ? plan.resolveWith(await frameSource.sampleTimestamps()) : plan.resolved;
+}
+//#endregion
+export { frameTimesOf };

package/dist/packages/core/src/application/recording/inspectLayout.js

@@ -0,0 +1,21 @@
+import { readTrailer } from "../../domain/format/trailer/readTrailer.js";
+import { trailerWrapperOf } from "../../domain/format/boxes/BoxLayout.js";
+import { scanBoxes } from "../../domain/format/boxes/scanBoxes.js";
+//#region ../../packages/core/src/application/recording/inspectLayout.ts
+/**
+* Use case: map out a file's structure, box by box and record by record.
+*/
+async function inspectLayout(source) {
+	const fileSize = await source.size();
+	const [boxes, trailer] = await Promise.all([scanBoxes(source, fileSize), readTrailer(source, fileSize)]);
+	return {
+		fileSize,
+		boxes,
+		trailerWrapper: trailerWrapperOf(boxes),
+		trailerVersion: trailer.footer.version,
+		trailerPayloadStart: trailer.payloadStart,
+		records: trailer.records.toSorted((left, right) => left.id - right.id)
+	};
+}
+//#endregion
+export { inspectLayout };

package/dist/packages/core/src/application/recording/inspectRecording.js

@@ -0,0 +1,124 @@
+import { hasErrorCode, messageOf } from "../../shared/errors/GyroViewError.js";
+import { microseconds, microsecondsToSeconds } from "../../shared/units/time.js";
+import { magnitudeOf } from "../../shared/math/Vector3.js";
+import { readRecording } from "./readRecording.js";
+import { inspectLayout } from "./inspectLayout.js";
+//#region ../../packages/core/src/application/recording/inspectRecording.ts
+var GRAVITY_SAMPLE_COUNT = 1e3;
+/**
+* Reads what a recording's file holds without playing it: the layout of its boxes and trailer,
+* the info record, the calibration and summaries of the gyro and exposure records. A gyro layout
+* it cannot tell is reported in the result, since telling it is what an inspection is for; a
+* file that is not a recording rejects as `readRecording` does.
+*/
+async function inspectRecording(source) {
+	const [layout, recording] = await Promise.all([inspectLayout(source), readRecording(source)]);
+	const gyro = await gyroOf(recording);
+	const exposure = await exposureOf(recording, gyro);
+	return {
+		...summarizeStructure(layout),
+		info: recording.info,
+		calibration: summarizeCalibration(recording),
+		calibrationWarnings: recording.calibration.warnings,
+		gyro,
+		exposure
+	};
+}
+function summarizeStructure(layout) {
+	return {
+		fileSize: layout.fileSize,
+		boxes: layout.boxes.map((box) => ({
+			type: box.type,
+			offset: box.range.offset,
+			size: box.range.length
+		})),
+		trailerWrapper: layout.trailerWrapper,
+		trailerVersion: layout.trailerVersion,
+		payloadStart: layout.trailerPayloadStart,
+		records: layout.records.map((record) => ({
+			id: record.id,
+			format: record.format,
+			offset: record.payload.offset,
+			size: record.payload.length
+		}))
+	};
+}
+function summarizeCalibration(recording) {
+	const { calibration } = recording.calibration;
+	return calibration === void 0 ? void 0 : {
+		version: calibration.version,
+		canvas: [calibration.canvas.width, calibration.canvas.height],
+		lenses: calibration.lenses.map((lens) => ({
+			lensIndex: lens.lensIndex,
+			model: lens.model.kind,
+			principalPoint: [lens.model.principalPoint.x, lens.model.principalPoint.y],
+			orientationDegrees: [
+				lens.orientation.yaw,
+				lens.orientation.pitch,
+				lens.orientation.roll
+			],
+			translationMetres: lens.translation
+		}))
+	};
+}
+function summarizeGyro(gyro) {
+	const { track, layout, strayBytes, damagedSamples, mendedStamps } = gyro;
+	const leading = Math.min(GRAVITY_SAMPLE_COUNT, track.length);
+	let magnitudeSum = 0;
+	for (let index = 0; index < leading; index += 1) magnitudeSum += magnitudeOf(track.sampleAt(index).acceleration);
+	const span = track.isEmpty ? 0 : track.sampleAt(track.length - 1).captureTime - track.sampleAt(0).captureTime;
+	return {
+		layout,
+		samples: track.length,
+		strayBytes,
+		damagedSamples,
+		mendedStamps,
+		spanSeconds: microsecondsToSeconds(microseconds(span)),
+		meanIntervalUs: track.meanSampleInterval,
+		meanAccelerationMagnitudeG: leading > 0 ? magnitudeSum / leading : void 0
+	};
+}
+function summarizeExposure(exposure, firstEncodedFrame) {
+	let shutterSum = 0;
+	for (let index = 0; index < exposure.length; index += 1) shutterSum += exposure.entryAt(index).shutterTime;
+	const hasEntries = exposure.length > 0;
+	return {
+		entries: exposure.length,
+		firstCaptureTimeUs: hasEntries ? exposure.entryAt(0).captureTime : void 0,
+		lastCaptureTimeUs: hasEntries ? exposure.entryAt(exposure.length - 1).captureTime : void 0,
+		meanShutterTimeSeconds: hasEntries ? shutterSum / exposure.length : void 0,
+		firstEncodedFrameEntry: firstEncodedFrame
+	};
+}
+/**
+* The gyro summary, or why the record cannot be read: a camera the inspector has not seen is the
+* case it exists for, so an undecidable layout is reported, not fatal.
+*/
+async function gyroOf(recording) {
+	try {
+		const gyro = await recording.readGyroRecord();
+		return gyro === void 0 ? void 0 : summarizeGyro(gyro);
+	} catch (error) {
+		if (!hasErrorCode(error, "unsupported-gyro-record")) throw error;
+		return { unreadable: messageOf(error) };
+	}
+}
+/**
+* The exposure summary; damaged when the trailer lists a record that did not parse, and not read
+* where the gyro layout cannot be told (its stamps are in the gyro's unit).
+*/
+async function exposureOf(recording, gyro) {
+	if (!recording.listsExposureRecord) return void 0;
+	if (gyro !== void 0 && "unreadable" in gyro) return { unread: "gyro layout unknown" };
+	const exposure = await recording.readExposureRecord();
+	return exposure ? summarizeExposure(exposure, await firstEncodedFrameEntry(exposure, recording)) : { damaged: true };
+}
+/**
+* The exposure entry of the first encoded frame; unknown without a capture clock.
+*/
+async function firstEncodedFrameEntry(exposure, recording) {
+	const clock = await recording.captureClock();
+	return clock === void 0 ? void 0 : exposure.indexAtOrAfter(clock.firstFrameCaptureTime);
+}
+//#endregion
+export { inspectRecording };

package/dist/packages/core/src/application/recording/locateOtherLensFile.js

@@ -0,0 +1,18 @@
+import { RecordingFileName } from "../../domain/format/naming/RecordingFileName.js";
+import { fileNameOfUrl, splitUrl } from "../../shared/text/urlPath.js";
+//#region ../../packages/core/src/application/recording/locateOtherLensFile.ts
+/**
+* Use case: the URL of the other lens's file of a split-file recording, if the server has one.
+*/
+async function locateOtherLensFile(recordingUrl, locator) {
+	const name = RecordingFileName.parse(fileNameOfUrl(recordingUrl));
+	if (!name) return void 0;
+	const candidate = siblingUrl(recordingUrl, name.otherLensName());
+	return await locator.exists(candidate) ? candidate : void 0;
+}
+function siblingUrl(url, fileName) {
+	const { path, suffix } = splitUrl(url);
+	return `${path.slice(0, path.lastIndexOf("/") + 1)}${encodeURIComponent(fileName)}${suffix}`;
+}
+//#endregion
+export { locateOtherLensFile };

package/dist/packages/core/src/application/recording/motionOf.js

@@ -0,0 +1,39 @@
+import { imuFrameFor } from "../../domain/motion/imu/ImuFrame.js";
+import { OrientationTrack } from "../../domain/motion/orientation/OrientationTrack.js";
+//#region ../../packages/core/src/application/recording/motionOf.ts
+var NO_GYRO_WARNING = "the recording has no gyro record; stabilization is unavailable";
+/**
+* Integrates the gyro record when there is one. A camera whose IMU frame has never been measured
+* still gets stabilization, with a warning, because the aligned guess is right for some cameras
+* and the ranking test can confirm it later.
+*/
+async function motionOf(recording, clock) {
+	const gyro = await recording.readGyroRecord();
+	if (!gyro) return {
+		setup: void 0,
+		warnings: [NO_GYRO_WARNING]
+	};
+	const imuFrame = imuFrameFor(recording.info);
+	const orientations = OrientationTrack.integrate({
+		gyro: gyro.track,
+		clock,
+		frame: imuFrame
+	});
+	const warnings = [...unverifiedWarningsOf(imuFrame, recording), ...damageWarningsOf(gyro)];
+	return {
+		setup: {
+			orientations,
+			imuFrame
+		},
+		warnings
+	};
+}
+function damageWarningsOf(gyro) {
+	return [...gyro.damagedSamples > 0 ? [`damaged gyro samples left out of stabilization: ${gyro.damagedSamples}`] : [], ...gyro.mendedStamps > 0 ? [`gyro stamps off their neighbours mended: ${gyro.mendedStamps}`] : []];
+}
+function unverifiedWarningsOf(imuFrame, recording) {
+	if (imuFrame.isVerified) return [];
+	return [`the IMU frame of ${recording.info.model ?? "this camera"} has not been verified on a recording; stabilization may misbehave`];
+}
+//#endregion
+export { motionOf };

package/dist/packages/core/src/application/recording/readRecording.js

@@ -0,0 +1,31 @@
+import { selectCalibration } from "../../domain/format/calibration/selectCalibration.js";
+import { readInfoRecord } from "../../domain/format/info/readInfoRecord.js";
+import { TrailerRecords } from "../../domain/format/records/TrailerRecords.js";
+import { readTrailer } from "../../domain/format/trailer/readTrailer.js";
+import { CaptureClock } from "../../domain/motion/timing/CaptureClock.js";
+//#region ../../packages/core/src/application/recording/readRecording.ts
+/**
+* Use case: open a source and read everything needed to describe the recording, with the
+* minimum of I/O: one size lookup, the trailer's table of contents, then the info record. The
+* file's box structure is left to `inspectLayout`. A missing calibration is reported, not
+* fatal; stitching checks for it. The large records are read when asked for.
+*/
+async function readRecording(source) {
+	const fileSize = await source.size();
+	const trailer = await readTrailer(source, fileSize);
+	const info = await readInfoRecord(source, trailer);
+	const records = new TrailerRecords(source, trailer, info);
+	return {
+		info,
+		calibration: selectCalibration(info.calibration),
+		listsExposureRecord: records.listsExposure,
+		captureClock: async () => {
+			const origin = await records.firstFrameCaptureTime();
+			return origin === void 0 ? void 0 : new CaptureClock(origin, info.gyroOffset);
+		},
+		readGyroRecord: () => records.readGyro(),
+		readExposureRecord: () => records.readExposure()
+	};
+}
+//#endregion
+export { readRecording };

package/dist/packages/core/src/application/recording/timeRecording.js

@@ -0,0 +1,57 @@
+import { hasErrorCode, messageOf } from "../../shared/errors/GyroViewError.js";
+import { seconds } from "../../shared/units/time.js";
+import { frameTimesOf } from "./frameTimesOf.js";
+import { motionOf } from "./motionOf.js";
+//#region ../../packages/core/src/application/recording/timeRecording.ts
+var TIMING_UNAVAILABLE = "frame timing and stabilization are unavailable";
+var NO_CLOCK_WARNING = `the recording has no capture clock; ${TIMING_UNAVAILABLE}`;
+var NO_FRAME_SOURCE_WARNING = `the recording has no frame source to time; ${TIMING_UNAVAILABLE}`;
+var NO_FRAME_TIMES_WARNING = "no frame timing source is usable; frames are timed by their track timestamps";
+/**
+* Relates the recording to video time: the capture clock, the frame times of its first frame
+* source (all sources share the camera clock) and the camera's orientation for stabilization.
+*/
+async function timeRecording(recording, frameSource) {
+	try {
+		return await timeByTheClock(recording, frameSource);
+	} catch (error) {
+		if (!hasErrorCode(error, "unsupported-gyro-record")) throw error;
+		return withoutTiming([`${messageOf(error)}; ${TIMING_UNAVAILABLE}`]);
+	}
+}
+async function timeByTheClock(recording, frameSource) {
+	const recordingClock = await recording.captureClock();
+	if (!recordingClock) return withoutTiming([NO_CLOCK_WARNING]);
+	if (!frameSource) return withoutTiming([NO_FRAME_SOURCE_WARNING]);
+	const timeline = await timelineOf(recordingClock, frameSource);
+	const [frames, motion] = await Promise.all([frameTimesOf(recording, frameSource, timeline), motionOf(recording, timeline.clock)]);
+	return {
+		frameTimes: frames?.frameTimes,
+		frameTimeSource: frames?.source,
+		motion: motion.setup,
+		warnings: [...frames?.warnings ?? [NO_FRAME_TIMES_WARNING], ...motion.warnings]
+	};
+}
+/**
+* Where the frame source's frames lie in time: the first shows where the first key packet does
+* (a track without one does not decode), and the rest follow at that packet's duration, the
+* cameras recording at a constant rate.
+*/
+async function timelineOf(recordingClock, frameSource) {
+	const firstKey = await frameSource.firstKeyPacket();
+	const hasDuration = firstKey !== void 0 && firstKey.duration > 0;
+	return {
+		clock: recordingClock.withFirstFrameAt(firstKey?.timestamp ?? seconds(0)),
+		frameDuration: hasDuration ? firstKey.duration : void 0
+	};
+}
+function withoutTiming(warnings) {
+	return {
+		frameTimes: void 0,
+		frameTimeSource: void 0,
+		motion: void 0,
+		warnings
+	};
+}
+//#endregion
+export { timeRecording };

package/dist/packages/core/src/application/stabilization/StabilizingFrameSink.js

@@ -0,0 +1,31 @@
+import { OffStabilization } from "../../domain/motion/stabilization/stabilizers.js";
+//#region ../../packages/core/src/application/stabilization/StabilizingFrameSink.ts
+/**
+* Use case: before every presentation, looks up the camera's orientation at the frame's
+* exposure and tells the sink how to turn the picture for the current stabilization mode.
+*/
+var StabilizingFrameSink = class {
+	parts;
+	stabilizer = new OffStabilization();
+	constructor(parts) {
+		this.parts = parts;
+	}
+	setStabilizer(stabilizer) {
+		this.stabilizer = stabilizer;
+	}
+	present(presentation) {
+		const time = this.exposureTimeOf(presentation);
+		const orientation = this.parts.orientations.orientationAt(time);
+		this.parts.sink.setStabilization(this.stabilizer.nextRotation(orientation, time));
+		this.parts.sink.present(presentation);
+	}
+	/**
+	* The frame's mid-exposure time, or its track timestamp when there are no frame times to say.
+	*/
+	exposureTimeOf(presentation) {
+		const { timestamp } = presentation.pair;
+		return this.parts.frameTimes?.midExposureAt(timestamp) ?? timestamp;
+	}
+};
+//#endregion
+export { StabilizingFrameSink };

package/dist/packages/core/src/domain/format/boxes/BoxLayout.js

@@ -0,0 +1,7 @@
+import { BoxType } from "./boxConstants.js";
+//#region ../../packages/core/src/domain/format/boxes/BoxLayout.ts
+function trailerWrapperOf(boxes) {
+	return boxes.some((box) => box.type === BoxType.Insta360Trailer) ? "inst-box" : "bare";
+}
+//#endregion
+export { trailerWrapperOf };

package/dist/packages/core/src/domain/format/boxes/boxConstants.js

@@ -0,0 +1,16 @@
+//#region ../../packages/core/src/domain/format/boxes/boxConstants.ts
+/**
+* The box types the player looks for. `inst` is Insta360's wrapper around the trailer on newer
+* firmware; older firmware appends the trailer bare, outside any box.
+*/
+var BoxType = { Insta360Trailer: "inst" };
+/**
+* Four printable ASCII characters, which is what every real box type looks like. Anything else
+* at a box boundary means the boxes have ended and raw trailer bytes follow.
+*/
+var PLAUSIBLE_BOX_TYPE = /^[ -~]{4}$/u;
+function isPlausibleBoxType(type) {
+	return PLAUSIBLE_BOX_TYPE.test(type);
+}
+//#endregion
+export { BoxType, isPlausibleBoxType };

package/dist/packages/core/src/domain/format/boxes/scanBoxes.js

@@ -0,0 +1,59 @@
+import { hasErrorCode } from "../../../shared/errors/GyroViewError.js";
+import { ByteReader } from "../../../shared/binary/ByteReader.js";
+import { ByteRange } from "../../../shared/binary/ByteRange.js";
+import { isPlausibleBoxType } from "./boxConstants.js";
+//#region ../../packages/core/src/domain/format/boxes/scanBoxes.ts
+/**
+* Walks the top-level boxes of a file with one small read per box, and stops at the first bytes
+* that do not form a box header, where a bare trailer begins. `fileSize` is passed in so the
+* caller can share one size lookup between several readers of the same source.
+*/
+async function scanBoxes(source, fileSize) {
+	const boxes = [];
+	let offset = 0;
+	while (offset + 8 <= fileSize) {
+		const box = await readBoxAt(source, offset, fileSize);
+		if (!box) break;
+		boxes.push(box);
+		offset = box.range.end;
+	}
+	return boxes;
+}
+async function readBoxAt(source, offset, fileSize) {
+	const headerLength = Math.min(16, fileSize - offset);
+	const header = new ByteReader(await source.read(ByteRange.of(offset, headerLength)));
+	const type = header.asciiAt(4, 4);
+	if (!isPlausibleBoxType(type)) return void 0;
+	const resolved = resolveSize(header, offset, fileSize);
+	if (!resolved) return void 0;
+	const { size, headerSize } = resolved;
+	return size >= headerSize && offset + size <= fileSize ? {
+		type,
+		range: ByteRange.of(offset, size)
+	} : void 0;
+}
+/**
+* Undefined when the header declares a large size that is not a safe integer: real boxes never
+* do, so those bytes are trailer data, not a box.
+*/
+function resolveSize(header, offset, fileSize) {
+	const declared = header.uint32BeAt(0);
+	if (declared === 1 && header.length >= 16) return largeSize(header);
+	return {
+		size: declared === 0 ? fileSize - offset : declared,
+		headerSize: 8
+	};
+}
+function largeSize(header) {
+	try {
+		return {
+			size: header.uint64BeAt(8),
+			headerSize: 16
+		};
+	} catch (error) {
+		if (hasErrorCode(error, "binary-unsafe-integer")) return void 0;
+		throw error;
+	}
+}
+//#endregion
+export { scanBoxes };

package/dist/packages/core/src/domain/format/calibration/CalibrationVersion.js

@@ -0,0 +1,13 @@
+//#region ../../packages/core/src/domain/format/calibration/CalibrationVersion.ts
+/**
+* Which calibration string a set was read from, in increasing order of fidelity: `offset` (1),
+* `offset_v2` (2) and `offset_v3` (3). The versioned strings declare theirs in the high bits of
+* their version word (the X5 recordings; insta360-rs docs); the legacy one declares none.
+*/
+var CalibrationVersion = {
+	Legacy: 1,
+	Polynomial: 2,
+	Mei: 3
+};
+//#endregion
+export { CalibrationVersion };

package/dist/packages/core/src/domain/format/calibration/layouts/CalibrationStringLayout.js

@@ -0,0 +1,34 @@
+import { degrees } from "../../../../shared/units/angle.js";
+//#region ../../packages/core/src/domain/format/calibration/layouts/CalibrationStringLayout.ts
+function eulerDegrees(yaw, pitch, roll) {
+	return {
+		yaw: degrees(yaw),
+		pitch: degrees(pitch),
+		roll: degrees(roll)
+	};
+}
+/**
+* For the versioned strings (v2, v3): what is wrong with a version word that does not declare
+* `expected` in its high bits, if anything.
+*/
+function versionWordMismatch(versionWord, expected) {
+	const declared = versionWord >>> 16;
+	return declared === expected ? void 0 : `declares version ${declared}`;
+}
+/**
+* For the versioned strings: the canvas the first lens block declares at the given token
+* positions; an empty canvas when there is no block.
+*/
+function canvasOfFirstBlock(blocks, widthToken, heightToken) {
+	const [first] = blocks;
+	return first ? {
+		width: first(widthToken),
+		height: first(heightToken)
+	} : EMPTY_CANVAS;
+}
+var EMPTY_CANVAS = {
+	width: 0,
+	height: 0
+};
+//#endregion
+export { canvasOfFirstBlock, eulerDegrees, versionWordMismatch };