@bubo-squared/gyroview 0.1.0

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

@@ -0,0 +1,417 @@
+import { asGyroViewError } from "../../shared/errors/GyroViewError.js";
+import { seconds } from "../../shared/units/time.js";
+import { clamp } from "../../shared/math/clamp.js";
+import { closeFramePair } from "../../ports/FramePair.js";
+import { Deferred } from "../../shared/async/Deferred.js";
+import { TypedEmitter } from "../../shared/events/TypedEmitter.js";
+import { ClockWatch, isAtEndOfMedia, isStoppedFromOutside } from "./ClockWatch.js";
+import { SeekOrder } from "./SeekOrder.js";
+import { TimeUpdates } from "./TimeUpdates.js";
+import { SessionLifecycle } from "./SessionLifecycle.js";
+import { DecodeRun } from "./DecodeRun.js";
+import { keyframeTimeAt } from "./keyframeTimeAt.js";
+//#region ../../packages/core/src/application/playback/PlaybackSession.ts
+/**
+* Use case: drives one recording through the decode pipeline in step with the clock and hands
+* frame pairs to the sink. The host calls {@link tick} once per animation frame; everything
+* else is event-driven. Sound follows the picture: the clock waits in `buffering` until frames
+* are ready, on starting, after a seek and whenever decoding falls behind.
+*
+* Every change is made whole before its listeners hear of it (ADR 0021): what a method does
+* after announcing never depends on what a listener did meanwhile. The one exception is the
+* clock's start, which waits for `playing` to be heard, so that a listener pausing on it keeps
+* the sound from ever starting.
+*/
+var PlaybackSession = class {
+	parts;
+	events = new TypedEmitter();
+	lifecycle = new SessionLifecycle(this.events);
+	/**
+	* The decode under way, if any: one per start or seek, replaced whole.
+	*/
+	run;
+	/**
+	* The pair on screen, kept open until the next one replaces it.
+	*/
+	presented;
+	timeUpdates = new TimeUpdates(this.lifecycle);
+	/**
+	* The `play` call waiting for the clock to start once frames are ready.
+	*/
+	startAttempt;
+	clockWatch = new ClockWatch();
+	seeks = new SeekOrder();
+	constructor(parts) {
+		this.parts = parts;
+	}
+	get state() {
+		return this.lifecycle.current;
+	}
+	get currentTime() {
+		return this.parts.clock.currentTime;
+	}
+	/**
+	* Starts or resumes, resolving once the clock runs. A paused session keeps its pipeline and
+	* the pairs it prefetched; a fresh one starts decoding anew, and an ended one or one paused at
+	* the end starts over from the beginning, and waits in `buffering` for the first pairs.
+	* Rejects, back in `paused`, when the clock refuses to start (autoplay policy); the host then
+	* waits for a user gesture. Pausing meanwhile, a listener's pause included, resolves quietly.
+	*/
+	async play() {
+		if (this.lifecycle.current === "playing") return;
+		if (this.lifecycle.current === "buffering") {
+			await this.startAttempt?.promise;
+			return;
+		}
+		await this.lifecycle.change(() => this.beginStart());
+	}
+	/**
+	* Stops the clock, whatever the state says: a clock start still under way may have been asked
+	* for before a pause. A running clock stops where it ran to, which no tick takes for a move
+	* from outside.
+	*/
+	pause() {
+		this.lifecycle.change(() => {
+			const wasRunning = this.parts.clock.isRunning;
+			this.parts.clock.pause();
+			if (wasRunning) this.clockWatch.stoppedAt(this.parts.clock.currentTime);
+			if (!this.lifecycle.canMoveTo("paused")) return;
+			this.lifecycle.moveTo("paused");
+			this.settleStartAttempt();
+			this.timeUpdates.announce(this.parts.clock.currentTime);
+		});
+	}
+	/**
+	* Pause and return to the beginning, showing the first frame again on the next tick.
+	*/
+	stop() {
+		this.lifecycle.change(() => {
+			this.pause();
+			this.seek(seconds(0));
+		});
+	}
+	/**
+	* Jumps to a time. A playing session resumes through `buffering` once the frames there have
+	* been decoded; a paused one shows the target frame and stays paused.
+	*/
+	seek(time) {
+		if (this.lifecycle.isOneOf("disposed", "error")) return;
+		this.lifecycle.change(() => {
+			const target = seconds(clamp(time, 0, this.parts.duration));
+			this.seeks.begin(this.lifecycle.current);
+			this.moveClockTo(target);
+			this.startRun(target);
+			this.lifecycle.moveTo("seeking");
+			this.lifecycle.moveTo(this.seeks.resumesPlaying ? "buffering" : "paused");
+			this.timeUpdates.announce(target);
+		});
+	}
+	/**
+	* Seeks to the key frame at or before `time`: what a dragged seek bar can show at once,
+	* without decoding a whole group of pictures first.
+	*/
+	async scrub(time) {
+		const [track] = this.parts.frameSources;
+		if (!track || this.lifecycle.isOneOf("disposed", "error")) return;
+		const target = seconds(clamp(time, 0, this.parts.duration));
+		const ticket = this.seeks.claimScrub();
+		const keyframeTime = await keyframeTimeAt(track, target);
+		if (!this.seeks.isScrubCurrent(ticket) || this.lifecycle.isOneOf("disposed", "error")) return;
+		this.seek(keyframeTime);
+	}
+	/**
+	* Starts decoding at the current time without playing, so the frame there shows while the
+	* session is still `ready`.
+	*/
+	preload() {
+		if (this.run || this.lifecycle.current !== "ready") return;
+		this.lifecycle.change(() => {
+			this.startRun(this.parts.clock.currentTime);
+		});
+	}
+	/**
+	* Presents the frame pair due at the clock's time, if a newer one has arrived, and follows
+	* the clock: to the end, into `buffering`, into failure, and into a start or a stop the
+	* platform made by itself (media keys, an audio interruption).
+	*/
+	tick() {
+		if (this.lifecycle.isOneOf("disposed", "error")) return;
+		this.lifecycle.change(() => {
+			const { failure } = this.parts.clock;
+			if (failure) {
+				this.fail(failure);
+				return;
+			}
+			const now = this.parts.clock.currentTime;
+			if (this.clockWatch.wasMovedFromOutside({
+				now,
+				state: this.lifecycle.current
+			})) {
+				this.followMoveFromOutside(now);
+				return;
+			}
+			if (this.haveTicksStopped(now)) {
+				this.restartAt(now);
+				return;
+			}
+			this.presentDue(now);
+			if (this.lifecycle.is("playing")) this.followClock(now);
+			else if (this.isStartedFromOutside()) this.followStartFromOutside();
+		});
+	}
+	/**
+	* Hands the pair on screen to the sink again, so a change in how it is drawn shows while the
+	* picture stands still; while playing, the next pair shows it soon enough.
+	*/
+	redraw() {
+		if (!this.presented || this.lifecycle.isOneOf("playing", "error")) return;
+		const { presented } = this;
+		this.lifecycle.change(() => this.draw(presented));
+	}
+	dispose() {
+		if (this.lifecycle.current === "disposed") return;
+		this.lifecycle.change(() => {
+			this.abortRun();
+			if (this.presented) closeFramePair(this.presented.pair);
+			this.presented = void 0;
+			this.parts.clock.pause();
+			this.lifecycle.moveTo("disposed");
+			this.settleStartAttempt();
+		});
+		this.events.removeAll();
+	}
+	/**
+	* A start from where the session stands, from the beginning when it stands at the end: what
+	* to await once it has been announced, or nothing when there is nothing to start.
+	*/
+	beginStart() {
+		if (this.isAtTheEnd()) this.seek(seconds(0));
+		if (!this.lifecycle.canMoveTo("buffering")) return void 0;
+		if (!this.run) this.startRun(this.parts.clock.currentTime);
+		if (!this.isPrimed()) return this.startOncePrimed();
+		this.enterPlaying();
+		return this.startClockOnceHeard();
+	}
+	/**
+	* `buffering` until the frames are ready, the clock held meanwhile, even one the platform
+	* started (a media key's play). A pause settles the wait.
+	*/
+	startOncePrimed() {
+		const attempt = new Deferred();
+		this.startAttempt = attempt;
+		this.parts.clock.pause();
+		this.lifecycle.moveTo("buffering");
+		return attempt.promise;
+	}
+	/**
+	* Starts the clock once `playing` has been heard, unless a listener paused on it: an audio
+	* element told to pause while it starts refuses the start.
+	*/
+	async startClockOnceHeard() {
+		await Promise.resolve();
+		if (this.lifecycle.is("playing")) await this.startClock();
+	}
+	/**
+	* Playing from the clock's time now: ticks that never come from here on are missed ticks
+	* too, as when playback starts in a hidden tab or an offscreen frame.
+	*/
+	enterPlaying() {
+		this.clockWatch.playingFrom(this.parts.clock.currentTime);
+		this.lifecycle.moveTo("playing");
+	}
+	presentDue(now) {
+		const pair = this.run?.takePairAt(now);
+		if (pair) this.present(pair, now);
+	}
+	/**
+	* The end first, then a stop from outside, then starvation: a clock that ran out while the
+	* ticks were away leaves stale pairs behind, which must not hold it in `buffering`.
+	*/
+	followClock(now) {
+		if (this.isPlayedOut(now)) {
+			this.end();
+			return;
+		}
+		if (isStoppedFromOutside(this.parts.clock)) {
+			this.lifecycle.moveTo("paused");
+			this.timeUpdates.announce(now);
+			return;
+		}
+		if (this.run?.isStarvedAt(now, this.presented?.pair.timestamp) === true) {
+			this.parts.clock.pause();
+			this.lifecycle.moveTo("buffering");
+			return;
+		}
+		this.timeUpdates.followPlayback(now);
+	}
+	/**
+	* The platform started the clock by itself (a media key's play) while the session stood
+	* still: the session follows, as it follows a stop.
+	*/
+	isStartedFromOutside() {
+		return this.parts.clock.isRunning && this.lifecycle.isOneOf("ready", "paused", "ended");
+	}
+	async followStartFromOutside() {
+		try {
+			await this.play();
+		} catch {}
+	}
+	/**
+	* Stops the clock and puts it at `time`, remembering where it landed (a clock clamps to the
+	* end of its own media).
+	*/
+	moveClockTo(time) {
+		this.parts.clock.pause();
+		this.parts.clock.seek(time);
+		this.clockWatch.placedAt(this.parts.clock.currentTime);
+	}
+	/**
+	* Follows the clock where the platform moved it, as a seek there: a stop that came with the
+	* move is followed first and a start after it, as each would be followed alone.
+	*/
+	followMoveFromOutside(now) {
+		const wasRunning = this.parts.clock.isRunning;
+		if (!wasRunning && this.lifecycle.is("playing")) this.pause();
+		this.seek(now);
+		if (wasRunning && this.lifecycle.is("paused")) this.followStartFromOutside();
+	}
+	/**
+	* Ticks were missed while the clock ran on; an ended clock is left to end the session.
+	*/
+	haveTicksStopped(now) {
+		return this.clockWatch.wereTicksMissed({
+			now,
+			state: this.lifecycle.current
+		}) && !this.parts.clock.hasEnded;
+	}
+	/**
+	* Decodes anew from the clock's time, holding the clock until the frames there are ready:
+	* the seek a page would take for the viewer's is not needed, the clock is where it must be.
+	* A clock past the end ends there; one the platform stopped meanwhile lands `paused`.
+	*/
+	restartAt(now) {
+		const { clock, duration } = this.parts;
+		if (now >= duration) {
+			this.moveClockTo(duration);
+			this.end();
+			return;
+		}
+		const wasRunning = clock.isRunning;
+		clock.pause();
+		this.startRun(now);
+		this.lifecycle.moveTo(wasRunning ? "buffering" : "paused");
+		if (!wasRunning) this.timeUpdates.announce(now);
+	}
+	/**
+	* Ended, or paused at the end: a play from there starts over, as a media element does.
+	*/
+	isAtTheEnd() {
+		return this.lifecycle.current === "ended" || isAtEndOfMedia(this.parts.clock, this.parts.duration);
+	}
+	isPrimed() {
+		return this.run?.isPrimedAt(this.parts.clock.currentTime) === true;
+	}
+	/**
+	* Called as pairs arrive and when a run ends: the moment `buffering` has what it waits for.
+	*/
+	resumeIfPrimed() {
+		if (this.lifecycle.current === "buffering" && this.isPrimed()) this.resume();
+	}
+	/**
+	* Leaves `buffering` for `playing` and starts the clock; a refusal (only possible before the
+	* first start) lands `paused` and is reported to the waiting `play`.
+	*/
+	async resume() {
+		const attempt = this.takeStartAttempt();
+		this.enterPlaying();
+		try {
+			await this.startClockOnceHeard();
+			attempt?.resolve();
+		} catch (error) {
+			attempt?.reject(error);
+		}
+	}
+	async startClock() {
+		try {
+			await this.parts.clock.start();
+		} catch (error) {
+			if (this.lifecycle.is("playing")) this.lifecycle.moveTo("paused");
+			throw error;
+		}
+	}
+	settleStartAttempt() {
+		this.takeStartAttempt()?.resolve();
+	}
+	takeStartAttempt() {
+		const attempt = this.startAttempt;
+		this.startAttempt = void 0;
+		return attempt;
+	}
+	/**
+	* The clock's own media ran out (an audio track shorter than the video: the pairs after it are
+	* unreachable, and the decoders may wait for room to decode them forever), or everything
+	* decoded to the end has been shown and the clock passed the duration.
+	*/
+	isPlayedOut(now) {
+		const hasShownAll = this.run?.isDrained === true && now >= this.parts.duration;
+		return this.parts.clock.hasEnded || hasShownAll;
+	}
+	present(pair, mediaTime) {
+		if (this.presented) closeFramePair(this.presented.pair);
+		this.presented = {
+			pair,
+			mediaTime
+		};
+		if (this.draw(this.presented)) this.lifecycle.announce("present", mediaTime);
+	}
+	/**
+	* A sink that cannot draw (a renderer the GPU refused) fails the session, never unheard.
+	*/
+	draw(presentation) {
+		try {
+			this.parts.sink.present(presentation);
+			return true;
+		} catch (error) {
+			this.fail(asGyroViewError(error, "render-unavailable", "the picture could not be drawn"));
+			return false;
+		}
+	}
+	/**
+	* Replaces the run under way; the one replaced reports to nobody, so only the current run may
+	* wake a waiting start, end or fail the session.
+	*/
+	startRun(from) {
+		this.abortRun();
+		this.run = DecodeRun.start(this.parts, from, {
+			onProgress: () => {
+				this.resumeIfPrimed();
+			},
+			onFailure: (error) => {
+				this.fail(error);
+			}
+		});
+	}
+	abortRun() {
+		this.run?.abort();
+		this.run = void 0;
+	}
+	end() {
+		if (!this.lifecycle.canMoveTo("ended")) return;
+		this.parts.clock.pause();
+		this.lifecycle.moveTo("ended");
+		this.timeUpdates.announce(this.parts.clock.currentTime);
+		this.lifecycle.announce("ended", void 0);
+	}
+	fail(error) {
+		if (!this.lifecycle.canMoveTo("error")) return;
+		this.lifecycle.change(() => {
+			this.parts.clock.pause();
+			this.abortRun();
+			this.lifecycle.moveTo("error");
+			this.settleStartAttempt();
+			this.lifecycle.announce("error", asGyroViewError(error, "decode", "playback failed"));
+		});
+	}
+};
+//#endregion
+export { PlaybackSession };

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

@@ -0,0 +1,36 @@
+import { isFlowing } from "../../domain/playback/PlayerState.js";
+//#region ../../packages/core/src/application/playback/SeekOrder.ts
+/**
+* The seeks of a session in order, and whether the latest resumes playing. A scrub lands only if
+* no seek or scrub came after it while it looked up its key frame.
+*/
+var SeekOrder = class {
+	generation = 0;
+	scrubs = 0;
+	isFromFlowing = false;
+	/**
+	* Whether the seek under way resumes playing once its frames are ready.
+	*/
+	get resumesPlaying() {
+		return this.isFromFlowing;
+	}
+	/**
+	* A new seek, begun from `state`.
+	*/
+	begin(state) {
+		this.isFromFlowing = isFlowing(state);
+		this.generation += 1;
+	}
+	claimScrub() {
+		this.scrubs += 1;
+		return {
+			seek: this.generation,
+			scrub: this.scrubs
+		};
+	}
+	isScrubCurrent(ticket) {
+		return ticket.seek === this.generation && ticket.scrub === this.scrubs;
+	}
+};
+//#endregion
+export { SeekOrder };

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

@@ -0,0 +1,42 @@
+import { Outbox } from "../../shared/events/Outbox.js";
+import { PlayerStateMachine } from "../../domain/playback/PlayerState.js";
+//#region ../../packages/core/src/application/playback/SessionLifecycle.ts
+/**
+* A session's state and what it announces. Each change the session makes through
+* {@link change} is heard once it is whole (ADR 0021): no listener runs in the middle of one,
+* and a listener's own change supersedes what the older one had still to announce.
+*/
+var SessionLifecycle = class {
+	machine = new PlayerStateMachine();
+	outbox;
+	constructor(events) {
+		this.outbox = new Outbox(events);
+	}
+	get current() {
+		return this.machine.state;
+	}
+	is(state) {
+		return this.machine.state === state;
+	}
+	isOneOf(...states) {
+		return this.machine.isOneOf(...states);
+	}
+	canMoveTo(next) {
+		return this.machine.canTransitionTo(next);
+	}
+	moveTo(next) {
+		this.machine.transitionTo(next);
+		this.announce("statechange", next);
+	}
+	announce(name, payload) {
+		this.outbox.emit(name, payload);
+	}
+	/**
+	* Runs `make` as one change, announcing what it announced once the outermost change is whole.
+	*/
+	change(make) {
+		return this.outbox.change(make);
+	}
+};
+//#endregion
+export { SessionLifecycle };

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

@@ -0,0 +1,55 @@
+import { closeFramePair } from "../../ports/FramePair.js";
+//#region ../../packages/core/src/application/playback/StartGate.ts
+/**
+* Sits between the pairer and the output of one decode run. Pairs at or after the start pass
+* straight through. Pairs before the start exist only because decoding had to begin at a key
+* frame; of those the gate keeps the newest and releases it ahead of the first pair after the
+* start, because that is the frame on screen at the start. Older ones are closed.
+*/
+var StartGate = class {
+	from;
+	deliver;
+	held;
+	droppedCount = 0;
+	constructor(from, deliver) {
+		this.from = from;
+		this.deliver = deliver;
+	}
+	/**
+	* How many pairs before the start were superseded by a newer one and closed.
+	*/
+	get dropped() {
+		return this.droppedCount;
+	}
+	push(pair) {
+		if (pair.timestamp >= this.from) {
+			this.release();
+			this.deliver(pair);
+			return;
+		}
+		this.hold(pair);
+	}
+	/**
+	* Delivers the held pair, if any. A run that ends before reaching the start (a start at or
+	* past the last frame) calls this so that last frame is still shown.
+	*/
+	release() {
+		if (!this.held) return;
+		const pair = this.held;
+		this.held = void 0;
+		this.deliver(pair);
+	}
+	discard() {
+		if (this.held) closeFramePair(this.held);
+		this.held = void 0;
+	}
+	hold(pair) {
+		if (this.held) {
+			closeFramePair(this.held);
+			this.droppedCount += 1;
+		}
+		this.held = pair;
+	}
+};
+//#endregion
+export { StartGate };

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

@@ -0,0 +1,31 @@
+//#region ../../packages/core/src/application/playback/TimeUpdates.ts
+/**
+* How much media time passes between two announcements while playing: the slowest cadence of a
+* media element's `timeupdate`, often enough for a seek bar and cheap to relay across
+* `postMessage`.
+*/
+var INTERVAL_SECONDS = .25;
+/**
+* The cadence of a session's `timeupdate`: every quarter second of playback, and at once when
+* the session says so (a pause, a seek, the end).
+*/
+var TimeUpdates = class {
+	lifecycle;
+	announced;
+	constructor(lifecycle) {
+		this.lifecycle = lifecycle;
+	}
+	announce(time) {
+		this.announced = time;
+		this.lifecycle.announce("timeupdate", time);
+	}
+	/**
+	* Announces the time if a quarter second of playback passed since the last announcement.
+	*/
+	followPlayback(now) {
+		const { announced } = this;
+		if (announced === void 0 || Math.abs(now - announced) >= INTERVAL_SECONDS) this.announce(now);
+	}
+};
+//#endregion
+export { TimeUpdates };

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

@@ -0,0 +1,46 @@
+import { milliseconds, millisecondsToSeconds, seconds } from "../../shared/units/time.js";
+//#region ../../packages/core/src/application/playback/WallClock.ts
+/**
+* PlaybackClock that advances with `now` (milliseconds of real time, from a monotonic source)
+* and never ends or fails by itself: for recordings without a playable audio track, and tests.
+*/
+var WallClock = class {
+	now;
+	hasEnded = false;
+	failure = void 0;
+	isRunningNow = false;
+	positionAtAnchor = seconds(0);
+	anchorMs = 0;
+	constructor(now) {
+		this.now = now;
+	}
+	get isRunning() {
+		return this.isRunningNow;
+	}
+	get currentTime() {
+		if (!this.isRunningNow) return this.positionAtAnchor;
+		const elapsed = millisecondsToSeconds(milliseconds(this.now() - this.anchorMs));
+		return seconds(this.positionAtAnchor + elapsed);
+	}
+	start() {
+		if (!this.isRunningNow) {
+			this.anchorMs = this.now();
+			this.isRunningNow = true;
+		}
+		return Promise.resolve();
+	}
+	pause() {
+		if (!this.isRunningNow) return;
+		this.positionAtAnchor = this.currentTime;
+		this.isRunningNow = false;
+	}
+	seek(time) {
+		this.positionAtAnchor = time;
+		this.anchorMs = this.now();
+	}
+	dispose() {
+		this.pause();
+	}
+};
+//#endregion
+export { WallClock };

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

@@ -0,0 +1,15 @@
+//#region ../../packages/core/src/application/playback/keyframeTimeAt.ts
+/**
+* The time of the key frame at or before `time`, where a dragged seek bar can show a picture at
+* once; `time` itself when the track has none there or cannot say (a recording let go meanwhile).
+* A read that is truly broken then fails the decode, where the session reports it.
+*/
+async function keyframeTimeAt(track, time) {
+	try {
+		return (await track.keyPacketAt(time))?.timestamp ?? time;
+	} catch {
+		return time;
+	}
+}
+//#endregion
+export { keyframeTimeAt };