@bubo-squared/gyroview 0.1.0

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

@@ -0,0 +1,188 @@
+import { GyroViewError, ensureInvariant } from "../../shared/errors/GyroViewError.js";
+import { FramePairer } from "./FramePairer.js";
+import { StartGate } from "./StartGate.js";
+import { Deferred } from "../../shared/async/Deferred.js";
+import { RunStop, STOPPED } from "../../shared/async/RunStop.js";
+//#region ../../packages/core/src/application/playback/DecodePipeline.ts
+/**
+* Decodes the frame sources of a recording in lockstep from a chosen time: starts every decoder at
+* the key packet at or before that time (the first one, for a time before it), feeds packets
+* round-robin with bounded decoder queues, pairs the resulting frames and hands pairs to the output
+* queue through a {@link StartGate}. One instance runs once; each `DecodeRun` creates its own.
+*/
+var DecodePipeline = class {
+	frameSources;
+	decoderPort;
+	options;
+	stop = new RunStop();
+	hasRun = false;
+	constructor(frameSources, decoderPort, options) {
+		this.frameSources = frameSources;
+		this.decoderPort = decoderPort;
+		this.options = options;
+		if (frameSources.length === 0) throw new GyroViewError("invariant-violation", "a decode pipeline needs at least one frame source");
+	}
+	/**
+	* Runs until the tracks end, the output queue is closed or {@link abort} is called. Resolves
+	* with a report; rejects when a decoder fails or a track cannot be read.
+	*/
+	async run(from, output) {
+		ensureInvariant(!this.hasRun, "a decode pipeline runs once; create a new one for each run");
+		this.hasRun = true;
+		const run = await this.openRun(from, output);
+		try {
+			const hasReachedEnd = await this.feed(run);
+			await settle(run, hasReachedEnd);
+			if (run.failure.isSettled) throw await run.failure.promise;
+			return reportOf(run, hasReachedEnd);
+		} finally {
+			closeRun(run);
+		}
+	}
+	/**
+	* Ends the run early; pending decodes are discarded. Safe before, during and after the run.
+	*/
+	abort() {
+		this.stop.stop();
+	}
+	async openRun(from, output) {
+		const { stop } = this;
+		const failure = new Deferred();
+		const tally = {
+			packets: 0,
+			pairs: 0
+		};
+		const gate = new StartGate(from, (pair) => {
+			tally.pairs += 1;
+			output.push(pair);
+		});
+		const pairer = new FramePairer(this.frameSources.length, this.options.pairTolerance, (pair) => {
+			gate.push(pair);
+		});
+		const iterators = stop.wasStopped ? [] : await this.packetIteratorsFrom(from);
+		const onError = (error) => {
+			failure.resolve(error);
+			stop.stop();
+		};
+		try {
+			return {
+				output,
+				stop,
+				failure,
+				tally,
+				gate,
+				pairer,
+				iterators,
+				decoders: stop.wasStopped ? [] : await this.createDecoders(pairer, onError)
+			};
+		} catch (error) {
+			closeIterators(iterators);
+			throw error;
+		}
+	}
+	/**
+	* Opens one decoder per frame source; if any refuses, the ones already open are closed again.
+	*/
+	async createDecoders(pairer, onError) {
+		const results = await Promise.allSettled(this.frameSources.map(async (track, sourceIndex) => this.decoderPort.create(await track.decoderConfiguration(), {
+			onFrame: (frame) => {
+				pairer.push(sourceIndex, frame);
+			},
+			onError
+		})));
+		const opened = results.flatMap((result) => result.status === "fulfilled" ? [result.value] : []);
+		const refusal = results.find((result) => result.status === "rejected");
+		if (refusal) {
+			for (const decoder of opened) decoder.close();
+			throw toError(refusal.reason);
+		}
+		return opened;
+	}
+	/**
+	* Resolves to true when every track ran out of packets, false when aborted or the queue closed.
+	*/
+	async feed(run) {
+		while (!shouldStop(run)) {
+			await run.stop.race(() => run.output.waitForRoom());
+			if (shouldStop(run)) return false;
+			const round = await run.stop.race(() => nextRound(run.iterators));
+			if (round === STOPPED) return false;
+			if (!round) return true;
+			await this.decodeRound(run, round);
+		}
+		return false;
+	}
+	async decodeRound(run, packets) {
+		for (const [sourceIndex, decoder] of run.decoders.entries()) {
+			const packet = packets[sourceIndex];
+			if (!packet) continue;
+			await run.stop.race(() => decoder.waitForPendingBelow(this.options.maxPendingPackets));
+			if (shouldStop(run)) return;
+			decoder.decode(packet);
+			run.tally.packets += 1;
+		}
+	}
+	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]();
+		}));
+	}
+};
+function shouldStop(run) {
+	return run.stop.wasStopped || run.output.isClosedForGood;
+}
+/**
+* After the feed: a finished run drains the decoders and, having reached the end, releases the
+* pair the gate held back. An abort, before or while draining, leaves what is pending to the
+* decoders' closing.
+*/
+async function settle(run, hasReachedEnd) {
+	if (await run.stop.race(() => drain(run.decoders, run.failure)) !== STOPPED && hasReachedEnd) run.gate.release();
+}
+/**
+* A decoder that fails while draining has already aborted the run and settled its failure.
+*/
+async function drain(decoders, failure) {
+	try {
+		await Promise.all(decoders.map((decoder) => decoder.flush()));
+	} catch (error) {
+		if (!failure.isSettled) throw error;
+	}
+}
+function closeRun(run) {
+	for (const decoder of run.decoders) decoder.close();
+	run.pairer.discardAll();
+	run.gate.discard();
+	closeIterators(run.iterators);
+}
+function closeIterators(iterators) {
+	for (const iterator of iterators) iterator.return?.();
+}
+function reportOf(run, hasReachedEnd) {
+	return {
+		packetsDecoded: run.tally.packets,
+		pairsDelivered: run.tally.pairs,
+		unpairedFrames: run.pairer.unpaired,
+		pairsDroppedBeforeStart: run.gate.dropped,
+		hasReachedEnd
+	};
+}
+function toError(reason) {
+	return reason instanceof Error ? reason : new GyroViewError("decode", "a decoder could not be created", { cause: reason });
+}
+/**
+* One packet per frame source, or undefined as soon as any of them is exhausted.
+*/
+async function nextRound(iterators) {
+	const results = await Promise.all(iterators.map((iterator) => iterator.next()));
+	const packets = [];
+	for (const result of results) {
+		if (result.done === true) return void 0;
+		packets.push(result.value);
+	}
+	return packets;
+}
+//#endregion
+export { DecodePipeline };

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

@@ -0,0 +1,93 @@
+import { seconds } from "../../shared/units/time.js";
+import { FramePairQueue } from "./FramePairQueue.js";
+import { DecodePipeline } from "./DecodePipeline.js";
+//#region ../../packages/core/src/application/playback/DecodeRun.ts
+/**
+* Pairs queued before the clock (re)starts, so playback does not stall on its first frames.
+*/
+var PRIMING_PAIRS = 2;
+/**
+* A shown frame this far behind the clock, with nothing decoded to follow it, means the decoders
+* have fallen behind: several frames at any frame rate, well beyond jitter.
+*/
+var STARVATION_LAG_SECONDS = .25;
+/**
+* One decode of every frame source from a time into a queue of its own: the pipeline, the pairs
+* it delivered and whether it reached the end, which live and go together. Once aborted it drops
+* what arrives late and reports nothing, so a run a seek replaced never speaks for its successor.
+*/
+var DecodeRun = class DecodeRun {
+	listener;
+	queue;
+	pipeline;
+	primingPairs;
+	isAborted = false;
+	hasReachedEnd = false;
+	hasHandedOutPair = false;
+	constructor(parts, listener) {
+		this.listener = listener;
+		this.primingPairs = Math.min(PRIMING_PAIRS, parts.queueCapacity);
+		this.queue = new FramePairQueue(parts.queueCapacity, () => {
+			if (!this.isAborted) listener.onProgress();
+		});
+		this.pipeline = new DecodePipeline(parts.frameSources, parts.decoderPort, parts.pipeline);
+	}
+	static start(parts, from, listener) {
+		const run = new DecodeRun(parts, listener);
+		run.follow(run.pipeline.run(from, run.queue));
+		return run;
+	}
+	/**
+	* Everything has been decoded and every pair handed out.
+	*/
+	get isDrained() {
+		return this.hasReachedEnd && this.queue.length === 0;
+	}
+	/**
+	* Enough frames are decoded to start moving at `now`: a couple queued, reaching the clock's time
+	* (pairs it has already passed would leave it starved at once), or the run is over and what is
+	* left is already there.
+	*/
+	isPrimedAt(now) {
+		const hasCaughtUp = (this.queue.newestTimestamp() ?? -Infinity) >= now;
+		return this.hasReachedEnd || hasCaughtUp && this.queue.length >= this.primingPairs;
+	}
+	/**
+	* Nothing is queued, the run is not over, and the frame on screen (shown for `shownAt`, if any)
+	* is well behind the clock: the decoders cannot keep up, even when each tick still finds a
+	* pair to show.
+	*/
+	isStarvedAt(now, shownAt) {
+		const isWaitingOnDecoders = this.queue.length === 0 && !this.hasReachedEnd;
+		const lag = now - (shownAt ?? -Infinity);
+		return isWaitingOnDecoders && lag > STARVATION_LAG_SECONDS;
+	}
+	/**
+	* The latest pair due at `time`. Until the run has handed one out, its first pair is due at
+	* once: on tracks whose first frame comes after `time`, that frame is the picture there.
+	*/
+	takePairAt(time) {
+		const head = this.queue.peekTimestamp();
+		const isFirst = !this.hasHandedOutPair && head !== void 0;
+		const pair = this.queue.takePairAt(isFirst ? seconds(Math.max(time, head)) : time);
+		if (pair) this.hasHandedOutPair = true;
+		return pair;
+	}
+	abort() {
+		this.isAborted = true;
+		this.pipeline.abort();
+		this.queue.close();
+	}
+	async follow(report) {
+		try {
+			const { hasReachedEnd } = await report;
+			if (this.isAborted) return;
+			this.hasReachedEnd = hasReachedEnd;
+			this.listener.onProgress();
+		} catch (error) {
+			if (!this.isAborted) this.listener.onFailure(error);
+		}
+	}
+};
+//#endregion
+export { DecodeRun };

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

@@ -0,0 +1,93 @@
+import { ensureInvariant } from "../../shared/errors/GyroViewError.js";
+import { closeFramePair } from "../../ports/FramePair.js";
+//#region ../../packages/core/src/application/playback/FramePairQueue.ts
+/**
+* Buffer of decoded pairs between the decode pipeline (producer) and the renderer (consumer).
+* `capacity` is a soft limit: the producer waits for room before feeding more packets, but frames
+* already in flight always land, so the queue may briefly hold `capacity` plus the decoders'
+* pending limit. Pairs leave the queue when the consumer takes them; the consumer then owns them
+* and closes them when they are superseded.
+*/
+var FramePairQueue = class {
+	capacity;
+	onPush;
+	pairs = [];
+	roomWaiters = [];
+	isClosed = false;
+	/**
+	* `onPush` hears about every pair kept, so a consumer waiting for frames need not poll.
+	*/
+	constructor(capacity, onPush = doNothing) {
+		this.capacity = capacity;
+		this.onPush = onPush;
+		ensureInvariant(Number.isSafeInteger(capacity) && capacity > 0, "queue capacity must be positive");
+	}
+	get length() {
+		return this.pairs.length;
+	}
+	get isFull() {
+		return this.pairs.length >= this.capacity;
+	}
+	get isClosedForGood() {
+		return this.isClosed;
+	}
+	/**
+	* Resolves once the queue is below capacity, or immediately once it was closed.
+	*/
+	waitForRoom() {
+		return !this.isFull || this.isClosed ? Promise.resolve() : new Promise((resolve) => {
+			this.roomWaiters.push(resolve);
+		});
+	}
+	/**
+	* Adds a pair; a closed queue closes the pair instead of keeping it.
+	*/
+	push(pair) {
+		if (this.isClosed) {
+			closeFramePair(pair);
+			return;
+		}
+		this.pairs.push(pair);
+		this.onPush();
+	}
+	/**
+	* Removes and returns the latest pair at or before `time`, closing older pairs it skips over.
+	* Undefined when no queued pair is due yet; newer pairs stay queued.
+	*/
+	takePairAt(time) {
+		let taken;
+		while (this.pairs.length > 0 && (this.pairs[0]?.timestamp ?? Infinity) <= time) {
+			if (taken) closeFramePair(taken);
+			taken = this.pairs.shift();
+		}
+		if (taken) this.wakeWaiters();
+		return taken;
+	}
+	peekTimestamp() {
+		return this.pairs[0]?.timestamp;
+	}
+	/**
+	* The time of the pair queued last, the furthest decoding has come.
+	*/
+	newestTimestamp() {
+		return this.pairs.at(-1)?.timestamp;
+	}
+	/**
+	* Drops and closes everything held, and every pair pushed from now on.
+	*/
+	close() {
+		this.isClosed = true;
+		for (const pair of this.pairs) closeFramePair(pair);
+		this.pairs.length = 0;
+		this.wakeWaiters();
+	}
+	wakeWaiters() {
+		if (this.isFull && !this.isClosed) return;
+		const waiters = this.roomWaiters;
+		this.roomWaiters = [];
+		for (const resolve of waiters) resolve();
+	}
+};
+function doNothing() {}
+//#endregion
+export { FramePairQueue };

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

@@ -0,0 +1,60 @@
+import { ensureIndexInRange } from "../../shared/errors/GyroViewError.js";
+import { seconds } from "../../shared/units/time.js";
+//#region ../../packages/core/src/application/playback/FramePairer.ts
+/**
+* Buffers decoded frames per frame source and emits a {@link FramePair} as soon as every source has
+* a frame for the same instant. The tracks of one recording share the camera clock, so their
+* timestamps agree exactly; the tolerance only absorbs floating-point conversion noise.
+*/
+var FramePairer = class {
+	tolerance;
+	onPair;
+	queues;
+	unpairedCount = 0;
+	constructor(sourceCount, tolerance, onPair) {
+		this.tolerance = tolerance;
+		this.onPair = onPair;
+		this.queues = Array.from({ length: sourceCount }, () => []);
+	}
+	/**
+	* Frames dropped because no other source ever produced a matching instant.
+	*/
+	get unpaired() {
+		return this.unpairedCount;
+	}
+	push(sourceIndex, frame) {
+		ensureIndexInRange(sourceIndex, this.queues.length, "frame source");
+		this.queues[sourceIndex]?.push(frame);
+		this.drain();
+	}
+	/**
+	* Closes everything still buffered, for example when stopping mid-stream.
+	*/
+	discardAll() {
+		for (const queue of this.queues) {
+			for (const frame of queue) frame.close();
+			queue.length = 0;
+		}
+	}
+	drain() {
+		while (this.queues.every((queue) => queue.length > 0)) {
+			const heads = this.queues.map((queue) => queue[0]).filter((frame) => frame !== void 0);
+			const earliest = Math.min(...heads.map((frame) => frame.timestamp));
+			if (heads.every((frame) => Math.abs(frame.timestamp - earliest) <= this.tolerance)) this.emit(heads, seconds(earliest));
+			else this.dropHeadAt(earliest);
+		}
+	}
+	emit(frames, timestamp) {
+		for (const queue of this.queues) queue.shift();
+		this.onPair({
+			timestamp,
+			frames
+		});
+	}
+	dropHeadAt(timestamp) {
+		this.queues.find((candidate) => candidate[0]?.timestamp === timestamp)?.shift()?.close();
+		this.unpairedCount += 1;
+	}
+};
+//#endregion
+export { FramePairer };