@bubo-squared/gyroview 0.2.0 → 0.3.1

package/dist/packages/adapters/webcodecs/src/WebCodecsVideoDecoderPort.js

@@ -15,10 +15,11 @@ var HARDWARE_ACCELERATION = "no-preference";
 */
 var WebCodecsVideoDecoderPort = class {
 	/**
-	* A configuration WebCodecs finds malformed is one it does not support.
+	* A configuration WebCodecs finds malformed is one it does not support. A browser without
+	* WebCodecs refuses to answer, since no configuration would do.
 	*/
 	async isSupported(configuration) {
-		if (typeof VideoDecoder === "undefined") return false;
+		if (typeof VideoDecoder === "undefined") throw webCodecsUnavailable();
 		try {
 			return (await VideoDecoder.isConfigSupported(this.toWebCodecsConfig(configuration))).supported === true;
 		} catch {
@@ -33,7 +34,7 @@ var WebCodecsVideoDecoderPort = class {
 		}
 	}
 	configureDecoder(configuration, callbacks) {
-		if (typeof VideoDecoder === "undefined") throw new GyroViewError("codec-unsupported", "this browser has no WebCodecs VideoDecoder");
+		if (typeof VideoDecoder === "undefined") throw webCodecsUnavailable();
 		return new WebCodecsDecoderHandle(this.toWebCodecsConfig(configuration), callbacks);
 	}
 	toWebCodecsConfig(configuration) {
@@ -114,6 +115,14 @@ var WebCodecsDecoderHandle = class {
 		if (this.decoder.state !== "closed") this.decoder.close();
 	}
 };
+/**
+* Browsers expose WebCodecs only in secure contexts, so a page served over plain HTTP is the
+* likelier cause than an old browser, and the one its developer can fix.
+*/
+function webCodecsUnavailable() {
+	const reason = globalThis.isSecureContext ? "this browser has no WebCodecs VideoDecoder" : "WebCodecs exists only in secure contexts (HTTPS), and this page is not one";
+	return new GyroViewError("webcodecs-unavailable", reason);
+}
 function chunkOf(packet) {
 	return new EncodedVideoChunk({
 		type: packet.isKeyFrame ? "key" : "delta",

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 };

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

@@ -0,0 +1,122 @@
+import { GyroViewError } from "../../shared/errors/GyroViewError.js";
+import { Ending, ITERATION_END } from "../../shared/async/iteration.js";
+//#region ../../packages/core/src/application/download/DownloadedVideoTrack.ts
+/**
+* One lens's track, its packets read through the file's download. Where decoding may start comes
+* from the sample table; the first packet decoding starts from is checked against its own bytes,
+* and a sync sample found not to be a keyframe is passed over from then on, so the times it tells
+* agree with the packets it hands out.
+*/
+var DownloadedVideoTrack = class {
+	parts;
+	rejected = /* @__PURE__ */ new Set();
+	constructor(parts) {
+		this.parts = parts;
+	}
+	get description() {
+		return this.parts.codec.description;
+	}
+	decoderConfiguration() {
+		return Promise.resolve(this.parts.codec.configuration);
+	}
+	keyframeAt(time) {
+		return Promise.resolve(this.timeOf(this.keyframeSampleAt(time)));
+	}
+	firstKeyframe() {
+		return Promise.resolve(this.timeOf(this.firstKeyframeSample()));
+	}
+	packetsFrom(time) {
+		return { [Symbol.asyncIterator]: () => new PacketReading({
+			track: this.parts.track,
+			open: () => this.cursorFrom(time),
+			reject: (sample) => {
+				this.rejected.add(sample);
+			},
+			packetOf: (read) => this.packetOf(read)
+		}) };
+	}
+	sampleTimestamps() {
+		return Promise.resolve(this.parts.track.timestampsInPresentationOrder());
+	}
+	frameCount() {
+		return Promise.resolve(this.parts.track.sampleCount);
+	}
+	cursorFrom(time) {
+		const start = this.keyframeSampleAt(time) ?? this.firstKeyframeSample();
+		return start === void 0 ? void 0 : this.parts.download.openCursor(this.parts.track, start, time);
+	}
+	/**
+	* The sync sample decoding for `time` starts at, past those found not to be keyframes.
+	*/
+	keyframeSampleAt(time) {
+		const { track } = this.parts;
+		let sample = track.keyframeAt(time);
+		while (sample !== void 0 && this.rejected.has(sample)) sample = track.syncSampleAtOrBefore(sample - 1);
+		return sample;
+	}
+	firstKeyframeSample() {
+		const { track } = this.parts;
+		let sample = track.syncSampleAtOrAfter(0);
+		while (sample !== void 0 && this.rejected.has(sample)) sample = track.syncSampleAtOrAfter(sample + 1);
+		return sample;
+	}
+	timeOf(sample) {
+		const { track } = this.parts;
+		return sample === void 0 ? void 0 : {
+			timestamp: track.timestampOf(sample),
+			duration: track.durationOf(sample)
+		};
+	}
+	packetOf(read) {
+		const { track } = this.parts;
+		return {
+			timestamp: track.timestampOf(read.sample),
+			duration: track.durationOf(read.sample),
+			isKeyFrame: track.isSync(read.sample) && !this.rejected.has(read.sample),
+			data: read.bytes
+		};
+	}
+};
+/**
+* One iteration over a track's packets, its cursor opened at once so the download reads for it
+* straight away; returning it closes the cursor at once, even while a packet is awaited.
+*/
+var PacketReading = class {
+	parts;
+	cursor;
+	isVerified = false;
+	ending = new Ending();
+	constructor(parts) {
+		this.parts = parts;
+		this.cursor = parts.open();
+	}
+	async next() {
+		if (this.ending.hasEnded()) return ITERATION_END;
+		const { cursor } = this;
+		if (!cursor) throw new GyroViewError("no-key-frame", `track ${this.parts.track.trackId} has no key frame`);
+		const read = await cursor.nextSample();
+		if (!read || this.ending.hasEnded()) return ITERATION_END;
+		if (!this.isVerified && !this.parts.track.keyframeRule.isKeyframe(read.bytes)) return this.startEarlier(cursor, read);
+		this.isVerified = true;
+		return {
+			done: false,
+			value: this.parts.packetOf(read)
+		};
+	}
+	return() {
+		this.ending.end();
+		this.cursor?.close();
+		return Promise.resolve(ITERATION_END);
+	}
+	/**
+	* The sample decoding was to start at is no keyframe: starts again at the one before it.
+	*/
+	startEarlier(cursor, read) {
+		this.parts.reject(read.sample);
+		cursor.close();
+		this.cursor = this.parts.open();
+		return this.next();
+	}
+};
+//#endregion
+export { DownloadedVideoTrack };

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

@@ -0,0 +1,183 @@
+import { asGyroViewError, ensureInvariant } from "../../shared/errors/GyroViewError.js";
+import { ByteRange } from "../../shared/binary/ByteRange.js";
+import { ByteRangeSet } from "../../shared/binary/ByteRangeSet.js";
+import { BlockStore } from "./BlockStore.js";
+import { SampleCursor } from "./SampleCursor.js";
+import { Transfers } from "./Transfers.js";
+import { isReadyToResume } from "../../domain/download/isReadyToResume.js";
+import { planDownloads } from "../../domain/download/planDownloads.js";
+//#region ../../packages/core/src/application/download/FileDownload.ts
+var EVERY_BYTE = ByteRange.of(0, Number.MAX_SAFE_INTEGER);
+/**
+* One file of a recording downloaded while it plays (ADR 0029): the only reader of its bytes.
+* Its cursors say where the readers of its tracks stand; whenever that changes, or a range comes
+* whole, it plans anew, once per turn, what to ask for, give up and let go of, and hands each
+* waiting cursor its sample once the bytes have come. A range that failed is not asked for again
+* until a cursor opens, a seek or a replay, lest a failing server be asked without end.
+*/
+var FileDownload = class {
+	parts;
+	store = new BlockStore();
+	progressListeners = /* @__PURE__ */ new Set();
+	transfers;
+	cursors = /* @__PURE__ */ new Set();
+	host;
+	failures = [];
+	anchor;
+	isReadingAhead = false;
+	isPlanDue = false;
+	isDisposed = false;
+	constructor(parts) {
+		this.parts = parts;
+		this.transfers = new Transfers({
+			stream: parts.stream,
+			store: this.store,
+			listener: {
+				onChunk: () => {
+					this.serveCursors();
+					for (const listener of this.progressListeners) listener();
+				},
+				onEnd: () => {
+					this.schedulePlan();
+				},
+				onFailure: (range, error) => {
+					this.fail(range, error);
+				}
+			}
+		});
+		this.host = this.cursorHost();
+	}
+	/**
+	* A reader of `track` from `sample` on, reading toward `target` at once.
+	*/
+	openCursor(track, sample, target) {
+		ensureInvariant(this.parts.table.tracks.includes(track), "the track is not one of this file");
+		const cursor = new SampleCursor(track, {
+			sample,
+			target
+		}, this.host);
+		if (this.isDisposed) {
+			cursor.close();
+			return cursor;
+		}
+		this.failures = [];
+		this.cursors.add(cursor);
+		this.schedulePlan();
+		return cursor;
+	}
+	/**
+	* Playing has started: from now on the download reads ahead of the picture.
+	*/
+	startReadingAhead() {
+		this.isReadingAhead = true;
+		this.schedulePlan();
+	}
+	/**
+	* Enough is downloaded ahead of its pictures for playback that starved at `time` to play again.
+	*/
+	isReadyToResumeAt(time) {
+		return isReadyToResume({
+			cursors: this.positions(),
+			held: this.store.held,
+			time,
+			policy: this.parts.policy
+		});
+	}
+	onProgress(listener) {
+		const own = () => {
+			listener();
+		};
+		this.progressListeners.add(own);
+		return () => {
+			this.progressListeners.delete(own);
+		};
+	}
+	dispose() {
+		this.isDisposed = true;
+		this.transfers.cancelAll();
+		for (const cursor of this.cursors) cursor.close();
+	}
+	cursorHost() {
+		return {
+			bytesOf: (range) => this.store.bytesOf(range),
+			failureOf: (range) => this.failures.find((failed) => failed.range.overlaps(range))?.error,
+			changed: () => {
+				this.schedulePlan();
+			},
+			closed: (cursor) => {
+				this.cursors.delete(cursor);
+				this.schedulePlan();
+			}
+		};
+	}
+	schedulePlan() {
+		if (this.isPlanDue || this.isDisposed) return;
+		this.isPlanDue = true;
+		this.planAfterThisTurn();
+	}
+	/**
+	* Plans once every change made in this turn is in: a seek closes its old cursors and opens
+	* its new ones together, and the plan sees both.
+	*/
+	async planAfterThisTurn() {
+		await Promise.resolve();
+		this.isPlanDue = false;
+		if (this.isDisposed) return;
+		try {
+			this.plan();
+		} catch (error) {
+			this.failEveryRead(error);
+		}
+	}
+	/**
+	* A plan that could not be made fails every read, rather than leave them waiting for ever.
+	*/
+	failEveryRead(cause) {
+		const error = asGyroViewError(cause, "invariant-violation", "the download could not plan");
+		this.failures.push({
+			range: EVERY_BYTE,
+			error
+		});
+		for (const cursor of this.cursors) cursor.fail(EVERY_BYTE, error);
+	}
+	plan() {
+		const decisions = planDownloads({
+			cursors: this.positions(),
+			held: this.store.held,
+			transfers: this.transfers.states,
+			unreadable: ByteRangeSet.of(this.failures.map((failure) => failure.range)),
+			isReadingAhead: this.isReadingAhead,
+			anchor: this.anchor,
+			policy: this.parts.policy
+		});
+		this.anchor = decisions.anchor;
+		this.carryOut(decisions);
+	}
+	positions() {
+		return [...this.cursors].map((cursor) => ({
+			track: cursor.track,
+			sample: cursor.position,
+			isWaiting: cursor.isWaiting,
+			target: cursor.target
+		}));
+	}
+	carryOut(decisions) {
+		for (const id of decisions.cancel) this.transfers.cancel(id);
+		this.store.release(decisions.release);
+		for (const range of decisions.start) this.transfers.start(range);
+	}
+	serveCursors() {
+		for (const cursor of this.cursors) cursor.serve();
+	}
+	fail(range, cause) {
+		const error = asGyroViewError(cause, "source-unreadable", "a range of the recording could not be read");
+		this.failures.push({
+			range,
+			error
+		});
+		for (const cursor of this.cursors) cursor.fail(range, error);
+		this.schedulePlan();
+	}
+};
+//#endregion
+export { FileDownload };

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

@@ -0,0 +1,22 @@
+//#region ../../packages/core/src/application/download/RecordingBuffer.ts
+/**
+* A recording's buffer, over the downloads of its files (ADR 0011): ready to resume once every
+* file is, since the picture of a split pair needs both lenses.
+*/
+var RecordingBuffer = class {
+	files;
+	constructor(files) {
+		this.files = files;
+	}
+	isReadyToResumeAt(time) {
+		return this.files.every((file) => file.isReadyToResumeAt(time));
+	}
+	onProgress(listener) {
+		const stops = this.files.map((file) => file.onProgress(listener));
+		return () => {
+			for (const stop of stops) stop();
+		};
+	}
+};
+//#endregion
+export { RecordingBuffer };

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

@@ -0,0 +1,88 @@
+import { ensureInvariant } from "../../shared/errors/GyroViewError.js";
+//#region ../../packages/core/src/application/download/SampleCursor.ts
+/**
+* One reader of a track's samples, from a sample on, in decode order: the next sample is handed
+* out once its bytes have come, a read at a time. Closing it hands out no more, a read awaited
+* then coming as the end, so the download stops reading for it at once.
+*/
+var SampleCursor = class {
+	track;
+	host;
+	target;
+	next;
+	waiter;
+	isClosed = false;
+	constructor(track, start, host) {
+		this.track = track;
+		this.host = host;
+		this.next = start.sample;
+		this.target = start.target;
+	}
+	/**
+	* The next sample it hands out.
+	*/
+	get position() {
+		return this.next;
+	}
+	get isWaiting() {
+		return this.waiter !== void 0;
+	}
+	/**
+	* The next sample; undefined at the track's end or once closed. Rejects when its bytes failed.
+	*/
+	nextSample() {
+		if (this.isClosed || this.next >= this.track.sampleCount) return Promise.resolve(void 0);
+		ensureInvariant(this.waiter === void 0, "a cursor reads one sample at a time");
+		const range = this.track.rangeOf(this.next);
+		const bytes = this.host.bytesOf(range);
+		if (bytes) return Promise.resolve(this.take(bytes));
+		const failure = this.host.failureOf(range);
+		return failure === void 0 ? this.waitForBytes() : Promise.reject(failure);
+	}
+	/**
+	* Bytes came: hands the awaited sample on if they were its.
+	*/
+	serve() {
+		const { waiter } = this;
+		const bytes = waiter && this.host.bytesOf(this.track.rangeOf(this.next));
+		if (!waiter || !bytes) return;
+		this.waiter = void 0;
+		waiter.resolve(this.take(bytes));
+	}
+	/**
+	* A range failed: fails the awaited read if the sample lies there.
+	*/
+	fail(range, error) {
+		const { waiter } = this;
+		if (waiter === void 0 || !range.overlaps(this.track.rangeOf(this.next))) return;
+		this.waiter = void 0;
+		waiter.reject(error);
+	}
+	close() {
+		if (this.isClosed) return;
+		this.isClosed = true;
+		this.waiter?.resolve(void 0);
+		this.waiter = void 0;
+		this.host.closed(this);
+	}
+	waitForBytes() {
+		return new Promise((resolve, reject) => {
+			this.waiter = {
+				resolve,
+				reject
+			};
+			this.host.changed();
+		});
+	}
+	take(bytes) {
+		const sample = this.next;
+		this.next += 1;
+		this.host.changed();
+		return {
+			sample,
+			bytes
+		};
+	}
+};
+//#endregion
+export { SampleCursor };

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

@@ -0,0 +1,46 @@
+import { Ending, ITERATION_END } from "../../shared/async/iteration.js";
+//#region ../../packages/core/src/application/download/SourceByteStream.ts
+/**
+* A ByteStream over any random-access source, a range read whole and handed on as one chunk:
+* for sources whose reads are quick (a local file, bytes in memory), where streaming a range
+* piece by piece would gain nothing.
+*/
+var SourceByteStream = class {
+	source;
+	constructor(source) {
+		this.source = source;
+	}
+	stream(range) {
+		return { [Symbol.asyncIterator]: () => new WholeRangeReading(this.source, range) };
+	}
+};
+/**
+* One range, read on the first chunk asked for; given up, it reads nothing more and its read
+* under way comes as the end.
+*/
+var WholeRangeReading = class {
+	source;
+	range;
+	ending = new Ending();
+	constructor(source, range) {
+		this.source = source;
+		this.range = range;
+	}
+	async next() {
+		await Promise.resolve();
+		if (this.ending.hasEnded()) return ITERATION_END;
+		const bytes = await this.source.read(this.range);
+		if (this.ending.hasEnded()) return ITERATION_END;
+		this.ending.end();
+		return bytes.byteLength === 0 ? ITERATION_END : {
+			done: false,
+			value: bytes
+		};
+	}
+	return() {
+		this.ending.end();
+		return Promise.resolve(ITERATION_END);
+	}
+};
+//#endregion
+export { SourceByteStream };