@bubo-squared/gyroview 0.2.0 → 0.3.0

package/dist/packages/adapters/fetch/src/httpRequest.js

@@ -7,9 +7,11 @@ import "../../../core/src/index.js";
 */
 var FIRST_BYTE_RANGE = "bytes=0-0";
 /**
-* The response headers a cross-origin page must be let read, as the fix a CORS failure names.
+* The response headers a cross-origin page must be let read, as the fix a CORS failure names;
+* `ETag` is optional, and tells a recording replaced while it plays more surely than
+* `Last-Modified`, which a page may always read.
 */
-var EXPOSED_HEADERS_ADVICE = "Access-Control-Expose-Headers: Content-Range, Content-Length, Accept-Ranges";
+var EXPOSED_HEADERS_ADVICE = "Access-Control-Expose-Headers: Content-Range, Content-Length, Accept-Ranges, ETag";
 /**
 * What a server must add for a page to read it across origins. A request that carries the
 * visitor's cookies is held to more: the Fetch standard refuses a wildcard origin for it.
@@ -20,7 +22,7 @@ var CREDENTIALED_CORS_ADVICE = `Access-Control-Allow-Origin naming this page's o
 * Browsers keep byte ranges of one URL as a sparse cache entry and revalidate them with
 * conditional requests. A 304 to such a request makes the browser answer from that entry, and
 * Chrome has been seen to hand back an empty body for a range it believed it held (ADR 0013).
-* The demuxer caches what it needs itself, so nothing is lost by leaving the cache out.
+* The download holds what it needs itself, so nothing is lost by leaving the cache out.
 */
 var CACHE_MODE = "no-store";
 /**

package/dist/packages/adapters/fetch/src/index.js

@@ -1,3 +1,5 @@
+import { HttpByteStream } from "./HttpByteStream.js";
 import { HttpRangeSource } from "./HttpRangeSource.js";
+import { HttpResource } from "./HttpResource.js";
 import { HttpResourceLocator } from "./HttpResourceLocator.js";
-export { HttpRangeSource, HttpResourceLocator };
+export { HttpByteStream, HttpRangeSource, HttpResource, HttpResourceLocator };

package/dist/packages/adapters/fetch/src/passingFailures.js

@@ -0,0 +1,24 @@
+import { GyroViewError, hasErrorCode } from "../../../core/src/shared/errors/GyroViewError.js";
+import "../../../core/src/index.js";
+//#region ../../packages/adapters/fetch/src/passingFailures.ts
+/**
+* The failures on the way, which asking again may cure; any other fails the read at once. They
+* are `source-unreadable` errors like any other, so a caller that gets one after the retries
+* cannot tell, and need not: only the retry loop asks.
+*/
+var passingFailures = /* @__PURE__ */ new WeakSet();
+function passing(failure) {
+	passingFailures.add(failure);
+	return failure;
+}
+function isPassing(error) {
+	return error instanceof GyroViewError && passingFailures.has(error);
+}
+/**
+* A request that did not get through for want of a network is worth another try.
+*/
+function passingIfUnreachable(error) {
+	return hasErrorCode(error, "source-unreadable") && error instanceof Error ? passing(new GyroViewError("source-unreadable", error.message, { cause: error.cause })) : error;
+}
+//#endregion
+export { isPassing, passing, passingIfUnreachable };

package/dist/packages/adapters/fetch/src/rangeFailures.js

@@ -0,0 +1,17 @@
+import { GyroViewError } from "../../../core/src/shared/errors/GyroViewError.js";
+import "../../../core/src/index.js";
+import { passing } from "./passingFailures.js";
+//#region ../../packages/adapters/fetch/src/rangeFailures.ts
+/**
+* A body a dropped connection broke off after the headers: the most common way a network fails
+* during long playback, so it is `source-unreadable` as a refused request is, not a bug or a bad
+* file, and worth another try.
+*/
+function brokenOff(url, range, cause) {
+	return passing(new GyroViewError("source-unreadable", `${url} broke off the ${range.length}-byte range at ${range.offset}`, { cause }));
+}
+function truncated(url, received, range) {
+	return new GyroViewError("source-truncated", `${url} returned ${received} bytes for a ${range.length}-byte range at ${range.offset}`);
+}
+//#endregion
+export { brokenOff, truncated };

package/dist/packages/adapters/fetch/src/recordingVersion.js

@@ -0,0 +1,37 @@
+import { contentRangeOf } from "./contentRange.js";
+//#region ../../packages/adapters/fetch/src/recordingVersion.ts
+var HTTP_OK = 200;
+var WEAK_ETAG_PREFIX = /^W\//u;
+function versionOf(response) {
+	const etag = response.headers.get("etag");
+	const lastModified = response.headers.get("last-modified");
+	const size = sizeOf(response);
+	return {
+		...etag !== null && { etag },
+		...lastModified !== null && { lastModified },
+		...size !== void 0 && { size }
+	};
+}
+/**
+* Whether two answers are of one version of the recording, by the ETag where both tell one,
+* else by the Last-Modified and the size; what either does not tell is taken for the same, so
+* a server that tells nothing is never taken for one that changed its file.
+*/
+function isSameVersion(known, seen) {
+	return known.etag !== void 0 && seen.etag !== void 0 ? opaqueTagOf(known.etag) === opaqueTagOf(seen.etag) : isSameWhereTold(known.lastModified, seen.lastModified) && isSameWhereTold(known.size, seen.size);
+}
+/**
+* The tag without its weakness mark: a CDN may weaken a strong ETag it passes on.
+*/
+function opaqueTagOf(etag) {
+	return etag.replace(WEAK_ETAG_PREFIX, "");
+}
+function isSameWhereTold(known, seen) {
+	return known === void 0 || seen === void 0 || known === seen;
+}
+function sizeOf(response) {
+	const size = response.status === HTTP_OK ? Number(response.headers.get("content-length") ?? NaN) : contentRangeOf(response)?.total;
+	return size !== void 0 && Number.isSafeInteger(size) && size > 0 ? size : void 0;
+}
+//#endregion
+export { isSameVersion, versionOf };

package/dist/packages/adapters/mediabunny/src/MediabunnyAudioPackager.js

@@ -0,0 +1,129 @@
+import { GyroViewError } from "../../../core/src/shared/errors/GyroViewError.js";
+import "../../../core/src/index.js";
+import { SegmentChannel } from "./SegmentChannel.js";
+import { EncodedAudioPacketSource, EncodedPacket, Mp4OutputFormat, NullTarget, Output } from "mediabunny";
+//#region ../../packages/adapters/mediabunny/src/MediabunnyAudioPackager.ts
+/**
+* Seconds of audio per media segment: short enough that a seek has sound quickly, long enough
+* that appends stay cheap.
+*/
+var FRAGMENT_DURATION_SECONDS = 1;
+/**
+* Segments (each fragment is two: `moof` and `mdat`) that may wait for the consumer before
+* re-packaging pauses.
+*/
+var SEGMENTS_AHEAD = 4;
+/**
+* The codec strings of the audio the cameras record, AAC (`mp4a.40.2` for AAC-LC), and mediabunny's
+* name for it. Other codecs are not re-packaged: the picture then plays on a silent clock.
+*/
+var AAC_CODEC_STRING_PREFIX = "mp4a.40.";
+var AAC = "aac";
+/**
+* AudioPackager over mediabunny: the samples re-packaged, unchanged, into fragmented MP4.
+* Segments are taken from the muxer's box callbacks rather than from its byte stream: that
+* yields whole `ftyp`/`moov`/`moof`/`mdat` boxes and leaves out the `mfra` index the muxer
+* appends at the end, which Media Source Extensions do not accept. Fragmented output keeps the
+* track's own timestamps, so segments started mid-track land at their true time.
+*/
+var MediabunnyAudioPackager = class {
+	segmentsOf(samples, configuration) {
+		const codec = muxedCodecOf(configuration);
+		return {
+			mimeType: `audio/mp4; codecs="${configuration.codec}"`,
+			duration: samples.duration,
+			segmentsFrom: (from) => ({ [Symbol.asyncIterator]: () => remux({
+				samples,
+				configuration,
+				codec
+			}, from) })
+		};
+	}
+};
+function muxedCodecOf(configuration) {
+	if (configuration.codec.startsWith(AAC_CODEC_STRING_PREFIX)) return AAC;
+	throw new GyroViewError("codec-unsupported", `audio in ${configuration.codec} cannot be re-packaged for playback`);
+}
+/**
+* Starts re-packaging from `from` into a channel and hands out its consumer's side. When the
+* consumer leaves, the samples are let go of at once, even while one is awaited, and the muxer
+* once the producer has noticed.
+*/
+function remux(parts, from) {
+	const channel = new SegmentChannel(SEGMENTS_AHEAD);
+	const output = new Output({
+		format: fragmentedMp4Into(channel),
+		target: new NullTarget()
+	});
+	const source = new EncodedAudioPacketSource(parts.codec);
+	output.addAudioTrack(source);
+	const samples = parts.samples.samplesFrom(from)[Symbol.asyncIterator]();
+	const production = produce({
+		samples,
+		configuration: parts.configuration,
+		output,
+		source,
+		channel
+	});
+	return channel.segments(() => {
+		samples.return?.();
+		releaseAfter(production, output);
+	});
+}
+/**
+* Frees the muxer once the producer has noticed the closed channel, without making a consumer
+* that left early (a seek) wait for a sample still in flight.
+*/
+async function releaseAfter(production, output) {
+	await production;
+	if (output.state === "finalized") return;
+	try {
+		await output.cancel();
+	} catch {}
+}
+/**
+* Feeds samples to the muxer at the consumer's pace; every failure ends up in the channel.
+*/
+async function produce(run) {
+	try {
+		await run.output.start();
+		let meta = { decoderConfig: decoderConfigOf(run.configuration) };
+		for (let next = await run.samples.next(); next.done !== true; next = await run.samples.next()) {
+			await run.channel.waitForRoom();
+			if (run.channel.isClosed) return;
+			await run.source.add(packetOf(next.value), meta);
+			meta = void 0;
+		}
+		if (run.channel.isClosed) return;
+		await run.output.finalize();
+		run.channel.close();
+	} catch (error) {
+		run.channel.fail(error);
+	}
+}
+function packetOf(sample) {
+	return new EncodedPacket(sample.data, "key", sample.timestamp, sample.duration);
+}
+function decoderConfigOf(configuration) {
+	return {
+		codec: configuration.codec,
+		sampleRate: configuration.sampleRate,
+		numberOfChannels: configuration.numberOfChannels,
+		...configuration.description && { description: configuration.description }
+	};
+}
+function fragmentedMp4Into(channel) {
+	const forward = (data) => {
+		channel.push(new Uint8Array(data));
+	};
+	return new Mp4OutputFormat({
+		fastStart: "fragmented",
+		minimumFragmentDuration: FRAGMENT_DURATION_SECONDS,
+		onFtyp: forward,
+		onMoov: forward,
+		onMoof: forward,
+		onMdat: forward
+	});
+}
+//#endregion
+export { MediabunnyAudioPackager };

package/dist/packages/adapters/mediabunny/src/MediabunnyCodecReader.js

@@ -0,0 +1,80 @@
+import { GyroViewError, isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
+import "../../../core/src/index.js";
+import { audioConfigurationOf, videoConfigurationOf } from "./decoderConfigurations.js";
+import { ALL_FORMATS, BufferSource, Input } from "mediabunny";
+//#region ../../packages/adapters/mediabunny/src/MediabunnyCodecReader.ts
+/**
+* CodecReader over mediabunny: opens the file type and movie boxes as a file of their own, in
+* memory, and tells each track's decoder configuration. mediabunny reads a sample only for a
+* video codec without its configuration box; the samples are not there, so that track is
+* refused.
+*/
+var MediabunnyCodecReader = class {
+	async read(movieBytes) {
+		const input = new Input({
+			formats: ALL_FORMATS,
+			source: new BufferSource(movieBytes)
+		});
+		try {
+			const [videoTracks, audioTracks] = await Promise.all([input.getVideoTracks(), input.getAudioTracks()]);
+			return {
+				video: await Promise.all(videoTracks.map((track, index) => videoCodecOf(track, index))),
+				audio: (await Promise.all(audioTracks.map((track) => audioCodecOf(track)))).flat()
+			};
+		} catch (error) {
+			throw failureOf(error);
+		} finally {
+			input.dispose();
+		}
+	}
+};
+async function videoCodecOf(track, trackIndex) {
+	const [config, codedWidth, codedHeight] = await Promise.all([
+		configurationOrNull(track),
+		track.getCodedWidth(),
+		track.getCodedHeight()
+	]);
+	if (config === null) throw new GyroViewError("codec-unsupported", `video track ${trackIndex} has no decoder configuration in its sample entry`);
+	const description = {
+		trackIndex,
+		codedWidth,
+		codedHeight,
+		codec: config.codec
+	};
+	return {
+		trackId: track.id,
+		description,
+		configuration: videoConfigurationOf(config, description)
+	};
+}
+/**
+* The configuration of a codec that carries it in the movie box; null for one that would need
+* a sample, which the movie bytes do not hold.
+*/
+async function configurationOrNull(track) {
+	try {
+		return await track.getDecoderConfig();
+	} catch {
+		return null;
+	}
+}
+/**
+* An audio track mediabunny cannot configure is left out: the picture then plays without sound
+* rather than not at all.
+*/
+async function audioCodecOf(track) {
+	const config = await track.getDecoderConfig();
+	return config === null ? [] : [{
+		trackId: track.id,
+		configuration: audioConfigurationOf(config)
+	}];
+}
+/**
+* A caller's abort and the core's own failures pass as they are; anything else mediabunny
+* throws means the bytes are no movie it can read.
+*/
+function failureOf(error) {
+	return isAbortError(error) || error instanceof GyroViewError ? error : new GyroViewError("unsupported-container", "the movie box is not a readable movie", { cause: error });
+}
+//#endregion
+export { MediabunnyCodecReader };

package/dist/packages/adapters/mediabunny/src/SegmentChannel.js

@@ -1,4 +1,5 @@
 import { GyroViewError, ensureInvariant } from "../../../core/src/shared/errors/GyroViewError.js";
+import { ITERATION_END } from "../../../core/src/shared/async/iteration.js";
 import "../../../core/src/index.js";
 //#region ../../packages/adapters/mediabunny/src/SegmentChannel.ts
 /**
@@ -43,12 +44,20 @@ var SegmentChannel = class {
 		this.failure ??= error instanceof Error ? error : new GyroViewError("decode", "audio re-packaging failed", { cause: error });
 		this.close();
 	}
-	async *segments() {
-		let next = await this.take();
-		while (next) {
-			yield next;
-			next = await this.take();
-		}
+	/**
+	* The consumer's side: the segments in order until the channel is closed and drained, then
+	* the producer's failure if it had one. Returning closes the channel at once, even while a
+	* segment is awaited, which then comes as the end. `onEnd` hears once of the end, however it
+	* came: the producer's resources may go.
+	*/
+	segments(onEnd = doNothing) {
+		return new SegmentReading({
+			take: () => this.take(),
+			close: () => {
+				this.close();
+			},
+			onEnd
+		});
 	}
 	/**
 	* The next segment; undefined once closed and drained; the producer's failure, if it had one.
@@ -80,5 +89,48 @@ var SegmentChannel = class {
 		for (const resolve of waiters) resolve();
 	}
 };
+/**
+* Iterates a channel's segments. A class, not a generator: a generator's return waits behind the
+* segment it awaits, and the producer would re-package another fragment for nobody.
+*/
+var SegmentReading = class {
+	parts;
+	hasEnded = false;
+	constructor(parts) {
+		this.parts = parts;
+	}
+	async next() {
+		if (this.hasEnded) return ITERATION_END;
+		try {
+			const segment = await this.parts.take();
+			return segment === void 0 || this.wasEnded() ? this.end() : {
+				done: false,
+				value: segment
+			};
+		} catch (error) {
+			this.end();
+			throw error;
+		}
+	}
+	return() {
+		this.parts.close();
+		return Promise.resolve(this.end());
+	}
+	[Symbol.asyncIterator]() {
+		return this;
+	}
+	/**
+	* Asked afresh after the wait: the consumer may have returned meanwhile.
+	*/
+	wasEnded() {
+		return this.hasEnded;
+	}
+	end() {
+		if (!this.hasEnded) this.parts.onEnd();
+		this.hasEnded = true;
+		return ITERATION_END;
+	}
+};
+function doNothing() {}
 //#endregion
 export { SegmentChannel };

package/dist/packages/adapters/mediabunny/src/decoderConfigurations.js

@@ -0,0 +1,28 @@
+import { copyOfBytes } from "./bufferSources.js";
+//#region ../../packages/adapters/mediabunny/src/decoderConfigurations.ts
+/**
+* A WebCodecs video decoder configuration in the core's terms; the coded size comes from the
+* track where the configuration leaves it out.
+*/
+function videoConfigurationOf(config, description) {
+	return {
+		codec: config.codec,
+		codedWidth: config.codedWidth ?? description.codedWidth,
+		codedHeight: config.codedHeight ?? description.codedHeight,
+		description: config.description === void 0 ? void 0 : copyOfBytes(config.description),
+		isFullRange: config.colorSpace?.fullRange ?? void 0
+	};
+}
+/**
+* A WebCodecs audio decoder configuration in the core's terms.
+*/
+function audioConfigurationOf(config) {
+	return {
+		codec: config.codec,
+		sampleRate: config.sampleRate,
+		numberOfChannels: config.numberOfChannels,
+		description: config.description === void 0 ? void 0 : copyOfBytes(config.description)
+	};
+}
+//#endregion
+export { audioConfigurationOf, videoConfigurationOf };

package/dist/packages/adapters/mediabunny/src/index.js

@@ -1,2 +1,3 @@
-import { MediabunnyDemuxer } from "./MediabunnyDemuxer.js";
-export { MediabunnyDemuxer };
+import { MediabunnyCodecReader } from "./MediabunnyCodecReader.js";
+import { MediabunnyAudioPackager } from "./MediabunnyAudioPackager.js";
+export { MediabunnyAudioPackager, MediabunnyCodecReader };

package/dist/packages/core/src/application/download/BlockStore.js

@@ -0,0 +1,97 @@
+import { ensureInvariant } from "../../shared/errors/GyroViewError.js";
+import { ByteRange } from "../../shared/binary/ByteRange.js";
+import { ByteRangeSet } from "../../shared/binary/ByteRangeSet.js";
+//#region ../../packages/core/src/application/download/BlockStore.ts
+var FillingBlock = class {
+	range;
+	bytes;
+	filled = 0;
+	/**
+	* No more of its bytes will come: all have, or its range was given up.
+	*/
+	isComplete = false;
+	constructor(range, bytes) {
+		this.range = range;
+		this.bytes = bytes;
+	}
+	get filledRange() {
+		return ByteRange.of(this.range.offset, this.filled);
+	}
+};
+/**
+* The bytes a download holds, a block for each range it asked for. A range within one block is
+* handed out as a view of it; one across blocks is copied out of them.
+*/
+var BlockStore = class {
+	blocks = [];
+	get held() {
+		return ByteRangeSet.of(this.blocks.map((block) => block.filledRange));
+	}
+	/**
+	* The memory the blocks take, whether their bytes have come or not.
+	*/
+	get allocatedBytes() {
+		return this.blocks.reduce((total, block) => total + block.bytes.byteLength, 0);
+	}
+	allocate(range) {
+		const block = new FillingBlock(range, new Uint8Array(range.length));
+		this.blocks.push(block);
+		return block;
+	}
+	write(block, chunk) {
+		const filling = this.fillingOf(block);
+		filling.bytes.set(chunk, filling.filled);
+		filling.filled += chunk.byteLength;
+	}
+	/**
+	* Every byte of the block has come.
+	*/
+	complete(block) {
+		this.fillingOf(block).isComplete = true;
+	}
+	/**
+	* Keeps of a block only what has come, as when its range is given up; a block that got
+	* nothing goes.
+	*/
+	trim(block) {
+		const filling = this.fillingOf(block);
+		filling.isComplete = true;
+		filling.bytes = filling.bytes.slice(0, filling.filled);
+		this.blocks = this.blocks.filter((held) => held.bytes.byteLength > 0);
+	}
+	/**
+	* The bytes of `range`, if every one of them has come.
+	*/
+	bytesOf(range) {
+		const within = this.blocks.find((block) => block.filledRange.contains(range));
+		if (within) return viewOf(within, range);
+		return this.held.covers(range) ? this.copyOf(range) : void 0;
+	}
+	/**
+	* Lets go of the complete blocks whose every byte `released` holds; a block still filling is
+	* its transfer's until it ends.
+	*/
+	release(released) {
+		this.blocks = this.blocks.filter((block) => !block.isComplete || !released.covers(block.filledRange));
+	}
+	fillingOf(block) {
+		const filling = this.blocks.find((held) => held === block);
+		ensureInvariant(filling !== void 0, "the block is not one this store holds");
+		return filling;
+	}
+	copyOf(range) {
+		const copy = new Uint8Array(range.length);
+		for (const block of this.blocks) {
+			const start = Math.max(block.range.offset, range.offset);
+			const end = Math.min(block.filledRange.end, range.end);
+			if (start < end) copy.set(block.bytes.subarray(start - block.range.offset, end - block.range.offset), start - range.offset);
+		}
+		return copy;
+	}
+};
+function viewOf(block, range) {
+	const start = range.offset - block.range.offset;
+	return block.bytes.subarray(start, start + range.length);
+}
+//#endregion
+export { BlockStore };

package/dist/packages/core/src/application/download/DownloadedAudioSamples.js

@@ -0,0 +1,50 @@
+import { Ending, ITERATION_END } from "../../shared/async/iteration.js";
+//#region ../../packages/core/src/application/download/DownloadedAudioSamples.ts
+/**
+* A sound track's samples read through the file's download, within the picture's reach.
+*/
+var DownloadedAudioSamples = class {
+	parts;
+	constructor(parts) {
+		this.parts = parts;
+	}
+	get duration() {
+		return this.parts.track.end;
+	}
+	samplesFrom(time) {
+		const { download, track } = this.parts;
+		return { [Symbol.asyncIterator]: () => new SampleReading(track, download.openCursor(track, track.sampleShownAt(time) ?? 0, time)) };
+	}
+};
+/**
+* One iteration over the samples; each is copied out of what was downloaded, so the samples a
+* media pipeline keeps do not keep the download's blocks alive.
+*/
+var SampleReading = class {
+	track;
+	cursor;
+	ending = new Ending();
+	constructor(track, cursor) {
+		this.track = track;
+		this.cursor = cursor;
+	}
+	async next() {
+		const read = await this.cursor.nextSample();
+		if (!read || this.ending.hasEnded()) return ITERATION_END;
+		return {
+			done: false,
+			value: {
+				timestamp: this.track.timestampOf(read.sample),
+				duration: this.track.durationOf(read.sample),
+				data: Uint8Array.from(read.bytes)
+			}
+		};
+	}
+	return() {
+		this.ending.end();
+		this.cursor.close();
+		return Promise.resolve(ITERATION_END);
+	}
+};
+//#endregion
+export { DownloadedAudioSamples };