@bubo-squared/gyroview 0.2.0 → 0.3.0

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

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

@@ -0,0 +1,75 @@
+import { ByteRange } from "../../shared/binary/ByteRange.js";
+//#region ../../packages/core/src/application/download/Transfers.ts
+/**
+* The ranges a download has asked for and is receiving, each streamed into its block. A range
+* given up is returned to the stream at once, so nothing more of it comes.
+*/
+var Transfers = class {
+	parts;
+	nextId = 1;
+	running = /* @__PURE__ */ new Map();
+	constructor(parts) {
+		this.parts = parts;
+	}
+	get states() {
+		return [...this.running.values()].map((transfer) => ({
+			id: transfer.id,
+			remaining: remainingOf(transfer)
+		}));
+	}
+	start(range) {
+		const transfer = {
+			id: this.nextId,
+			block: this.parts.store.allocate(range),
+			chunks: this.parts.stream.stream(range)[Symbol.asyncIterator](),
+			delivered: 0
+		};
+		this.nextId += 1;
+		this.running.set(transfer.id, transfer);
+		this.pump(transfer);
+	}
+	cancel(id) {
+		const transfer = this.running.get(id);
+		if (!transfer) return;
+		this.running.delete(id);
+		transfer.chunks.return?.();
+		this.parts.store.trim(transfer.block);
+	}
+	cancelAll() {
+		for (const id of this.running.keys()) this.cancel(id);
+	}
+	async pump(transfer) {
+		try {
+			for (let next = await transfer.chunks.next(); next.done !== true; next = await transfer.chunks.next()) {
+				if (!this.isRunning(transfer)) return;
+				this.parts.store.write(transfer.block, next.value);
+				transfer.delivered += next.value.byteLength;
+				this.parts.listener.onChunk();
+			}
+			this.finish(transfer);
+		} catch (error) {
+			this.fail(transfer, error);
+		}
+	}
+	finish(transfer) {
+		if (!this.isRunning(transfer)) return;
+		this.running.delete(transfer.id);
+		this.parts.store.complete(transfer.block);
+		this.parts.listener.onEnd();
+	}
+	fail(transfer, error) {
+		if (!this.isRunning(transfer)) return;
+		this.running.delete(transfer.id);
+		this.parts.store.trim(transfer.block);
+		this.parts.listener.onFailure(remainingOf(transfer), error);
+	}
+	isRunning(transfer) {
+		return this.running.get(transfer.id) === transfer;
+	}
+};
+function remainingOf(transfer) {
+	const { range } = transfer.block;
+	return ByteRange.of(range.offset + transfer.delivered, range.length - transfer.delivered);
+}
+//#endregion
+export { Transfers };

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

@@ -0,0 +1,37 @@
+import { GyroViewError } from "../../shared/errors/GyroViewError.js";
+import { DownloadedAudioSamples } from "./DownloadedAudioSamples.js";
+import { DownloadedVideoTrack } from "./DownloadedVideoTrack.js";
+import { FileDownload } from "./FileDownload.js";
+//#region ../../packages/core/src/application/download/startFileDownload.ts
+/**
+* Use case: download a file while it plays, its tracks joined to their codecs by track id.
+*/
+function startFileDownload(start) {
+	const download = new FileDownload(start);
+	return {
+		download,
+		videoTracks: start.codecs.video.map((codec) => new DownloadedVideoTrack({
+			download,
+			track: trackOf(start.table, codec.trackId, "video"),
+			codec
+		})),
+		audioTracks: start.codecs.audio.map((codec) => ({
+			samples: new DownloadedAudioSamples({
+				download,
+				track: trackOf(start.table, codec.trackId, "audio")
+			}),
+			configuration: codec.configuration
+		})),
+		duration: start.table.duration,
+		dispose: () => {
+			download.dispose();
+		}
+	};
+}
+function trackOf(table, trackId, kind) {
+	const track = table.trackWithId(trackId);
+	if (track?.kind !== kind) throw new GyroViewError("unsupported-container", `the movie box has no ${kind} track ${trackId} to read`);
+	return track;
+}
+//#endregion
+export { startFileDownload };

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

@@ -0,0 +1,53 @@
+import { Deferred } from "../../shared/async/Deferred.js";
+//#region ../../packages/core/src/application/playback/Buffering.ts
+/**
+* A session's `buffering`: entering it and why, the `play` waiting for the clock to start
+* meanwhile, and what ends it, told in one place.
+*/
+var Buffering = class {
+	lifecycle;
+	cause = "priming";
+	startAttempt;
+	constructor(lifecycle) {
+		this.lifecycle = lifecycle;
+	}
+	/**
+	* The `play` waiting for buffering to end, if one is.
+	*/
+	get waitingStart() {
+		return this.startAttempt?.promise;
+	}
+	enter(cause) {
+		this.cause = cause;
+		this.lifecycle.moveTo("buffering");
+	}
+	/**
+	* Buffers for the first frames of a start, which the promise waits for.
+	*/
+	enterForStart() {
+		const attempt = new Deferred();
+		this.startAttempt = attempt;
+		this.enter("priming");
+		return attempt.promise;
+	}
+	/**
+	* Buffering is over at `now`: what its cause waits for is there.
+	*/
+	isOverAt(run, now) {
+		if (!run || !this.lifecycle.is("buffering")) return false;
+		return this.cause === "priming" ? run.isPrimedAt(now) : run.isReadyToResumeAt(now);
+	}
+	/**
+	* The waiting `play`, taken out to be settled by whoever ends the wait.
+	*/
+	takeStart() {
+		const attempt = this.startAttempt;
+		this.startAttempt = void 0;
+		return attempt;
+	}
+	settleStart() {
+		this.takeStart()?.resolve();
+	}
+};
+//#endregion
+export { Buffering };

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

@@ -16,6 +16,11 @@ var DecodePipeline = class {
 	options;
 	stop = new RunStop();
 	hasRun = false;
+	/**
+	* The run's packet reads, which an abort returns at once: a read left to the run's unwinding
+	* would go on reading until its awaits settle.
+	*/
+	iterators = [];
 	constructor(frameSources, decoderPort, options) {
 		this.frameSources = frameSources;
 		this.decoderPort = decoderPort;
@@ -40,10 +45,12 @@ var DecodePipeline = class {
 		}
 	}
 	/**
-	* Ends the run early; pending decodes are discarded. Safe before, during and after the run.
+	* Ends the run early: its packet reads are let go of at once, pending decodes discarded. Safe
+	* before, during and after the run.
 	*/
 	abort() {
 		this.stop.stop();
+		closeIterators(this.iterators);
 	}
 	async openRun(from, output) {
 		const { stop } = this;
@@ -59,7 +66,8 @@ var DecodePipeline = class {
 		const pairer = new FramePairer(this.frameSources.length, this.options.pairTolerance, (pair) => {
 			gate.push(pair);
 		});
-		const iterators = stop.wasStopped ? [] : await this.packetIteratorsFrom(from);
+		const iterators = stop.wasStopped ? [] : this.packetIteratorsFrom(from);
+		this.iterators = iterators;
 		const onError = (error) => {
 			failure.resolve(error);
 			stop.stop();
@@ -123,11 +131,7 @@ var DecodePipeline = class {
 		}
 	}
 	packetIteratorsFrom(from) {
-		return Promise.all(this.frameSources.map(async (track) => {
-			const start = await track.keyPacketAt(from) ?? await track.firstKeyPacket();
-			if (!start) throw new GyroViewError("no-key-frame", `track ${track.description.trackIndex} has no key frame`);
-			return track.packetsFrom(start)[Symbol.asyncIterator]();
-		}));
+		return this.frameSources.map((track) => track.packetsFrom(from)[Symbol.asyncIterator]());
 	}
 };
 function shouldStop(run) {