@bubo-squared/gyroview 0.1.0

package/dist/packages/player/src/player/Player.js

@@ -0,0 +1,377 @@
+import { degrees } from "../../../core/src/shared/units/angle.js";
+import { asGyroViewError, hasErrorCode, messageOf } from "../../../core/src/shared/errors/GyroViewError.js";
+import { seconds } from "../../../core/src/shared/units/time.js";
+import { Outbox } from "../../../core/src/shared/events/Outbox.js";
+import { isFlowing } from "../../../core/src/domain/playback/PlayerState.js";
+import { TypedEmitter } from "../../../core/src/shared/events/TypedEmitter.js";
+import "../../../core/src/index.js";
+import { ensureFinite, viewStateOf } from "./ensureFinite.js";
+import { cssSizeOf } from "./DrawingBufferFit.js";
+import { FrameLoop } from "./FrameLoop.js";
+import { loadRecording } from "./loadRecording.js";
+import { IDLE, loadingPhase, statusOf } from "./PlayerPhase.js";
+import { PictureSettings } from "./PictureSettings.js";
+import { PlayerSound } from "./PlayerSound.js";
+import { PlayerView } from "./PlayerView.js";
+import { SessionRelay } from "./SessionRelay.js";
+//#region ../../packages/player/src/player/Player.ts
+/**
+* The player without the element, which `createBrowserPlayer` gives: it plays one recording at a
+* time on the canvas and audio element it was handed, reports in media-element events, and keeps
+* its settings (view, view mode, stabilization, gain matching, sound, loop) from load to load.
+* `<gyro-view>` is a facade over it.
+*/
+var Player = class {
+	parts;
+	events = new TypedEmitter();
+	/**
+	* What the player and its parts announce, heard once each change is whole (ADR 0021).
+	*/
+	outbox = new Outbox(this.events);
+	loop;
+	phase = IDLE;
+	viewing;
+	picture = new PictureSettings(this.outbox);
+	/**
+	* A seek asked for before a recording was ready, where the next one starts.
+	*/
+	pendingStartTime;
+	sound;
+	relay = new SessionRelay({
+		events: this.outbox,
+		onState: () => {
+			this.announceStatus();
+		},
+		onEnded: () => {
+			this.onEnded();
+		}
+	});
+	isLoopingValue = false;
+	/**
+	* Past `dispose`: a listener of the idle it announces must not load again.
+	*/
+	isDisposed = false;
+	/**
+	* The status listeners heard last.
+	*/
+	lastStatus = "idle";
+	/**
+	* @internal A page gets its player from `createBrowserPlayer`, which composes the parts.
+	*/
+	constructor(parts) {
+		this.parts = parts;
+		this.loop = new FrameLoop(this.tick);
+		parts.host.audio.addEventListener("ended", this.tick);
+		this.sound = new PlayerSound(parts.host.audio, this.outbox);
+		const { canvas } = parts.host;
+		this.viewing = new PlayerView(this.outbox, () => cssSizeOf(canvas));
+	}
+	get status() {
+		return statusOf(this.phase);
+	}
+	get metadata() {
+		return this.loaded?.opened.metadata;
+	}
+	get currentTime() {
+		return this.loaded?.pipeline.session.currentTime ?? seconds(0);
+	}
+	get duration() {
+		return this.loaded?.opened.duration ?? seconds(0);
+	}
+	/**
+	* False while playing or holding for frames, as a media element's `paused`.
+	*/
+	get isPaused() {
+		return !isFlowing(this.loaded?.pipeline.session.state);
+	}
+	get view() {
+		return this.viewing.current;
+	}
+	get viewMode() {
+		return this.viewing.viewMode;
+	}
+	/**
+	* Whether a drag moves the picture as it is framed now; the view mode decides.
+	*/
+	get canPan() {
+		return this.viewing.canPan;
+	}
+	get stabilization() {
+		return this.picture.stabilization;
+	}
+	get quality() {
+		return this.picture.quality;
+	}
+	get isLooping() {
+		return this.isLoopingValue;
+	}
+	get volume() {
+		return this.sound.volume;
+	}
+	get isMuted() {
+		return this.sound.isMuted;
+	}
+	/**
+	* Whether `setVolume` changes anything on this platform; iOS leaves media at the device's volume.
+	*/
+	get canSetVolume() {
+		return this.sound.canSetVolume;
+	}
+	/**
+	* Replaces whatever was loaded. Resolves once the recording is ready (and started, with
+	* `autoplay`); rejects with the failure after reporting it as an `error` event. A load that a
+	* newer load or `unload` supersedes resolves quietly.
+	*/
+	async load(source, options = {}) {
+		if (this.isDisposed) return;
+		const loading = this.outbox.change(() => {
+			this.unload();
+			const next = loadingPhase();
+			this.phase = next;
+			this.announceStatus();
+			return next;
+		});
+		try {
+			await this.complete(loading, source, options);
+		} catch (error) {
+			if (loading.controller.signal.aborted) return;
+			throw this.failWith(error);
+		} finally {
+			loading.settled.resolve();
+		}
+	}
+	unload() {
+		this.outbox.change(() => {
+			this.release();
+			this.announceStatus();
+		});
+	}
+	/**
+	* Starts playback, after a load in progress is ready, as a media element's `play()` does.
+	* Rejects with the load's failure, or with `playback-blocked` when the browser wants a user
+	* gesture first; with nothing loaded there is nothing to start.
+	*/
+	async play() {
+		await this.loadInProgress();
+		if (this.phase.kind === "failed") throw this.phase.failure;
+		await this.loaded?.pipeline.session.play();
+	}
+	pause() {
+		this.loaded?.pipeline.session.pause();
+	}
+	stop() {
+		this.loaded?.pipeline.session.stop();
+	}
+	/**
+	* Seeks exactly to `time` seconds; while a recording is loading, before one is, or after its
+	* playback failed, the next one starts there, as a media element's default playback start
+	* position has it.
+	*/
+	seek(time) {
+		ensureFinite(time, "time");
+		const session = this.loaded?.pipeline.session;
+		if (session && session.state !== "error") session.seek(seconds(time));
+		else this.pendingStartTime = seconds(time);
+	}
+	/**
+	* Seeks to the key frame at or before `time` seconds: quick to show while a seek bar is dragged.
+	*/
+	async scrub(time) {
+		ensureFinite(time, "time");
+		await this.loaded?.pipeline.session.scrub(seconds(time));
+	}
+	setView(view) {
+		this.viewing.set(viewStateOf(view));
+	}
+	/**
+	* Points the normal view at `yaw` and `pitch`, in degrees: yaw positive to the right, pitch
+	* positive up.
+	*/
+	lookAt(yaw, pitch) {
+		ensureFinite(yaw, "yaw");
+		ensureFinite(pitch, "pitch");
+		this.viewing.lookAt(degrees(yaw), degrees(pitch));
+	}
+	/**
+	* The viewer dragged the picture by `delta` CSS pixels across the canvas.
+	*/
+	pan(delta) {
+		this.viewing.pan(delta);
+	}
+	/**
+	* The viewer turned by the given angles in degrees, as the arrow keys do.
+	*/
+	turn(yawDelta, pitchDelta) {
+		ensureFinite(yawDelta, "yaw turn");
+		ensureFinite(pitchDelta, "pitch turn");
+		this.viewing.turn(degrees(yawDelta), degrees(pitchDelta));
+	}
+	/**
+	* Zooms by `steps` (positive zooms in) toward `focus`, a point of the canvas as fractions of its
+	* size; about the centre when none is given.
+	*/
+	zoom(steps, focus) {
+		ensureFinite(steps, "zoom steps");
+		this.viewing.zoom(steps, focus);
+	}
+	resetView() {
+		this.viewing.reset();
+	}
+	setViewMode(mode) {
+		this.viewing.setMode(mode);
+	}
+	setStabilization(mode) {
+		this.picture.setStabilization(mode);
+	}
+	/**
+	* How finely the lens images are read and how many device pixels are drawn; kept across loads.
+	*/
+	setQuality(quality) {
+		this.picture.setQuality(quality);
+	}
+	setLooping(isLooping) {
+		this.isLoopingValue = isLooping;
+	}
+	/**
+	* Whether the lenses' exposure is matched along the seam; kept across loads.
+	*/
+	setGainMatching(isEnabled) {
+		this.picture.setGainMatching(isEnabled);
+	}
+	setVolume(volume) {
+		ensureFinite(volume, "volume");
+		this.sound.setVolume(volume);
+	}
+	setMuted(isMuted) {
+		this.sound.setMuted(isMuted);
+	}
+	dispose() {
+		this.isDisposed = true;
+		this.unload();
+		this.parts.host.audio.removeEventListener("ended", this.tick);
+		this.sound.dispose();
+		this.events.removeAll();
+	}
+	tick = () => {
+		this.loaded?.pipeline.session.tick();
+	};
+	/**
+	* Whatever it ends in: a failure is the load's to report, and `play` reads it from the phase.
+	*/
+	async loadInProgress() {
+		if (this.phase.kind === "loading") await this.phase.settled.promise;
+	}
+	get loaded() {
+		return this.phase.kind === "loaded" ? this.phase.loaded : void 0;
+	}
+	async complete(loading, source, options) {
+		const { signal } = loading.controller;
+		const loaded = await loadRecording({
+			source,
+			parts: this.parts,
+			signal
+		});
+		if (signal.aborted) {
+			loaded.dispose();
+			return;
+		}
+		this.outbox.change(() => {
+			this.attach(loaded, loading.controller);
+			this.startAtPendingTime(loaded);
+			if (options.preload !== false) loaded.pipeline.session.preload();
+		});
+		if (options.autoplay && this.loaded === loaded) await this.autoplay();
+	}
+	startAtPendingTime(loaded) {
+		const time = this.pendingStartTime;
+		this.pendingStartTime = void 0;
+		if (time !== void 0) loaded.pipeline.session.seek(time);
+	}
+	attach(loaded, controller) {
+		this.phase = {
+			kind: "loaded",
+			loaded,
+			controller
+		};
+		this.viewing.attach(loaded.pipeline.renderer);
+		const { session } = loaded.pipeline;
+		this.picture.attach(loaded.pipeline);
+		this.relay.attach(session);
+		this.loop.start();
+		this.announceStatus();
+		for (const warning of loaded.warnings) this.outbox.emit("warning", warning);
+		this.outbox.emit("ready", loaded.opened.metadata);
+	}
+	/**
+	* A refused start leaves the recording loaded and paused: a warning, never a failed load.
+	*/
+	async autoplay() {
+		try {
+			await this.play();
+		} catch (error) {
+			this.outbox.emit("warning", hasErrorCode(error, "playback-blocked") ? {
+				code: "autoplay-blocked",
+				message: "playback waits for a user gesture"
+			} : {
+				code: "playback-failed",
+				message: `autoplay failed: ${messageOf(error)}`
+			});
+		}
+	}
+	onEnded() {
+		this.outbox.emit("ended", void 0);
+		if (this.isLoopingValue) this.replay();
+	}
+	async replay() {
+		try {
+			await this.play();
+		} catch (error) {
+			this.outbox.emit("warning", {
+				code: "playback-failed",
+				message: `the loop could not restart playback: ${messageOf(error)}`
+			});
+		}
+	}
+	/**
+	* Lets go of whatever is loading or loaded, announcing nothing.
+	*/
+	release() {
+		const previous = this.phase;
+		this.phase = IDLE;
+		if (previous.kind === "loading") previous.controller.abort();
+		this.loop.stop();
+		this.relay.detach();
+		this.viewing.attach(void 0);
+		this.picture.attach(void 0);
+		if (previous.kind !== "loaded") return;
+		previous.loaded.dispose();
+		previous.controller.abort();
+	}
+	failWith(error) {
+		const failure = asGyroViewError(error, "invariant-violation", "the player failed unexpectedly");
+		this.outbox.change(() => {
+			this.release();
+			this.phase = {
+				kind: "failed",
+				failure
+			};
+			this.announceStatus();
+			this.outbox.emit("error", failure);
+		});
+		return failure;
+	}
+	/**
+	* Announces the status the phase gives now, heard once for each change: a status announced
+	* again before listeners heard the other one in between is heard once.
+	*/
+	announceStatus() {
+		const { status } = this;
+		this.outbox.post(() => {
+			if (status === this.lastStatus) return;
+			this.lastStatus = status;
+			this.events.emit("statuschange", status);
+		});
+	}
+};
+//#endregion
+export { Player };

package/dist/packages/player/src/player/PlayerEvents.js

@@ -0,0 +1,28 @@
+import { keysOf } from "../../../core/src/shared/keysOf.js";
+import "../../../core/src/index.js";
+//#region ../../packages/player/src/player/PlayerEvents.ts
+/**
+* Every event name once.
+*/
+var PLAYER_EVENT_NAMES = keysOf({
+	statuschange: true,
+	ready: true,
+	play: true,
+	playing: true,
+	waiting: true,
+	pause: true,
+	ended: true,
+	timeupdate: true,
+	seeking: true,
+	seeked: true,
+	frame: true,
+	viewchange: true,
+	viewmodechange: true,
+	stabilizationchange: true,
+	qualitychange: true,
+	volumechange: true,
+	warning: true,
+	error: true
+});
+//#endregion
+export { PLAYER_EVENT_NAMES };

package/dist/packages/player/src/player/PlayerPhase.js

@@ -0,0 +1,21 @@
+import { Deferred } from "../../../core/src/shared/async/Deferred.js";
+import "../../../core/src/index.js";
+//#region ../../packages/player/src/player/PlayerPhase.ts
+var IDLE = { kind: "idle" };
+function loadingPhase() {
+	return {
+		kind: "loading",
+		controller: new AbortController(),
+		settled: new Deferred()
+	};
+}
+function statusOf(phase) {
+	switch (phase.kind) {
+		case "idle": return "idle";
+		case "loading": return "loading";
+		case "loaded": return phase.loaded.pipeline.session.state;
+		case "failed": return "error";
+	}
+}
+//#endregion
+export { IDLE, loadingPhase, statusOf };

package/dist/packages/player/src/player/PlayerSound.js

@@ -0,0 +1,61 @@
+import { clamp } from "../../../core/src/shared/math/clamp.js";
+import "../../../core/src/index.js";
+//#region ../../packages/player/src/player/PlayerSound.ts
+/**
+* The sound, on the audio element the host lends: its volume and mute, kept across loads by the
+* element itself and announced whoever changes them (the controls, the keyboard, a script, the
+* browser's own media keys).
+*/
+var PlayerSound = class {
+	audio;
+	events;
+	/**
+	* Whether the platform lets a page set the volume: iOS keeps media at the device's volume and
+	* ignores the setting, where a volume slider would move and change nothing.
+	*/
+	canSetVolume;
+	constructor(audio, events) {
+		this.audio = audio;
+		this.events = events;
+		this.canSetVolume = isVolumeSettable(audio.ownerDocument);
+		audio.addEventListener("volumechange", this.onVolumeChange);
+	}
+	get volume() {
+		return this.audio.volume;
+	}
+	get isMuted() {
+		return this.audio.muted;
+	}
+	/**
+	* From 0 (silent) to 1 (as recorded); anything outside is clamped.
+	*/
+	setVolume(volume) {
+		this.audio.volume = clamp(volume, 0, 1);
+	}
+	setMuted(isMuted) {
+		this.audio.muted = isMuted;
+	}
+	dispose() {
+		this.audio.removeEventListener("volumechange", this.onVolumeChange);
+	}
+	onVolumeChange = () => {
+		this.events.emit("volumechange", {
+			volume: this.volume,
+			isMuted: this.isMuted
+		});
+	};
+};
+/**
+* A volume the probe sets, other than the default of 1.
+*/
+var PROBE_VOLUME = .5;
+/**
+* Tried on an element of its own, so the one playing hears no volume change.
+*/
+function isVolumeSettable(document) {
+	const probe = document.createElement("audio");
+	probe.volume = PROBE_VOLUME;
+	return probe.volume === PROBE_VOLUME;
+}
+//#endregion
+export { PlayerSound };

package/dist/packages/player/src/player/PlayerView.js

@@ -0,0 +1,113 @@
+import { clampView, isSameView } from "../../../core/src/domain/view/ViewState.js";
+import { DEFAULT_VIEW_MODE } from "../../../core/src/domain/view/ViewMode.js";
+import { SCREEN_CENTRE } from "../../../core/src/domain/view/screenLayout.js";
+import { lookAt } from "../../../core/src/domain/view/viewGestures.js";
+import { DEFAULT_FRAMING, isSameFraming } from "../../../core/src/domain/view/Framing.js";
+import { viewModeRulesFor } from "../../../core/src/domain/view/viewModes.js";
+import "../../../core/src/index.js";
+//#region ../../packages/player/src/player/PlayerView.ts
+/**
+* Every layout the player accepts has two lenses; a renderer attached says so itself.
+*/
+var LENS_COUNT_BEFORE_A_LOAD = 2;
+/**
+* How the picture is framed and which view mode shows it: kept across loads, drawn by whichever
+* renderer is attached, and the normal view announced when it changes. The viewer's gestures go
+* through the mode's rules on the viewport as it is now; a host setting the view directly is
+* obeyed as it is.
+*/
+var PlayerView = class {
+	events;
+	measureViewport;
+	framing = DEFAULT_FRAMING;
+	mode = DEFAULT_VIEW_MODE;
+	surface;
+	lensCount = LENS_COUNT_BEFORE_A_LOAD;
+	constructor(events, measureViewport) {
+		this.events = events;
+		this.measureViewport = measureViewport;
+	}
+	get current() {
+		return this.framing.view;
+	}
+	get viewMode() {
+		return this.mode;
+	}
+	/**
+	* Whether a drag moves the picture as it is framed now.
+	*/
+	get canPan() {
+		return this.rules().canPan(this.framing);
+	}
+	/**
+	* The renderer of the loaded recording, or nothing between loads. A new renderer draws the
+	* framing as it is now, however it changed while the recording was loading; the lens tiles are
+	* measured by the lenses it draws from then on.
+	*/
+	attach(surface) {
+		this.surface = surface;
+		if (surface) this.lensCount = surface.lensCount;
+		surface?.setViewMode(this.mode);
+		surface?.setFraming(this.framing);
+	}
+	set(view) {
+		this.frame({
+			...this.framing,
+			view: clampView(view)
+		});
+	}
+	setMode(mode) {
+		if (mode === this.mode) return;
+		this.mode = mode;
+		this.surface?.setViewMode(mode);
+		this.events.emit("viewmodechange", mode);
+	}
+	lookAt(yaw, pitch) {
+		this.frame({
+			...this.framing,
+			view: lookAt(this.framing.view, yaw, pitch)
+		});
+	}
+	pan(delta) {
+		this.frame(this.rules().pan(this.framing, delta, this.context()));
+	}
+	turn(yaw, pitch) {
+		this.frame(this.rules().turn(this.framing, {
+			yaw,
+			pitch
+		}, this.context()));
+	}
+	/**
+	* Zooms by `steps`, keeping the point of the viewport at `focus` on what it shows.
+	*/
+	zoom(steps, focus = SCREEN_CENTRE) {
+		this.frame(this.rules().zoom(this.framing, {
+			steps,
+			focus
+		}, this.context()));
+	}
+	/**
+	* Back to how the current mode starts; the other modes keep their framing.
+	*/
+	reset() {
+		this.frame(this.rules().reset(this.framing));
+	}
+	frame(next) {
+		if (isSameFraming(next, this.framing)) return;
+		const hasViewChanged = !isSameView(next.view, this.framing.view);
+		this.framing = next;
+		this.surface?.setFraming(next);
+		if (hasViewChanged) this.events.emit("viewchange", next.view);
+	}
+	context() {
+		return {
+			viewport: this.measureViewport(),
+			lensCount: this.lensCount
+		};
+	}
+	rules() {
+		return viewModeRulesFor(this.mode);
+	}
+};
+//#endregion
+export { PlayerView };

package/dist/packages/player/src/player/SessionRelay.js

@@ -0,0 +1,66 @@
+import { transportEventsFor } from "./transportEvents.js";
+//#region ../../packages/player/src/player/SessionRelay.ts
+/**
+* Relays the loaded session's events in media-element terms: transport events for its state
+* changes, time updates, drawn frames, errors and the end. Listens to one session at a time and
+* stops before that session is disposed, so its disposal is never announced. A change is relayed
+* whole, as a media element fires the events it queued before a listener's `pause()`; the
+* session announces a listener's newer change after it (ADR 0021).
+*/
+var SessionRelay = class {
+	targets;
+	stopListening = [];
+	lastState;
+	/**
+	* Counts detachments, so a change whose listener let the session go stops relaying.
+	*/
+	detachments = 0;
+	constructor(targets) {
+		this.targets = targets;
+	}
+	attach(session) {
+		this.detach();
+		this.lastState = session.state;
+		const { events } = this.targets;
+		this.stopListening = [
+			session.events.on("statechange", (state) => {
+				this.onStateChange(state, session);
+			}),
+			session.events.on("timeupdate", (time) => {
+				events.emit("timeupdate", time);
+			}),
+			session.events.on("present", (time) => {
+				events.emit("frame", time);
+			}),
+			session.events.on("ended", () => {
+				this.targets.onEnded();
+			}),
+			session.events.on("error", (error) => {
+				events.emit("error", error);
+			})
+		];
+	}
+	detach() {
+		for (const stop of this.stopListening) stop();
+		this.stopListening = [];
+		this.lastState = void 0;
+		this.detachments += 1;
+	}
+	onStateChange(state, session) {
+		const previous = this.lastState;
+		this.lastState = state;
+		const detachments = this.detachments;
+		for (const name of transportEventsFor(previous, state)) {
+			this.emitTransport(name, session);
+			if (this.detachments !== detachments) return;
+		}
+		this.targets.onState(state);
+	}
+	emitTransport(name, session) {
+		const { events } = this.targets;
+		if (name === "seeking" || name === "seeked") events.emit(name, session.currentTime);
+		else events.emit(name, void 0);
+	}
+};
+//#endregion
+export { SessionRelay };

package/dist/packages/player/src/player/ensureFinite.js

@@ -0,0 +1,26 @@
+import { degrees } from "../../../core/src/shared/units/angle.js";
+import { GyroViewError } from "../../../core/src/shared/errors/GyroViewError.js";
+import "../../../core/src/index.js";
+//#region ../../packages/player/src/player/ensureFinite.ts
+/**
+* A number from the page, or from another origin through the embed: NaN from an empty field, an
+* undefined value or text would reach the clock and the view, which cannot take it.
+*/
+function ensureFinite(value, name) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new GyroViewError("invalid-argument", `${name} must be a finite number`);
+}
+/**
+* A view from the page, each angle checked and read as degrees.
+*/
+function viewStateOf(view) {
+	ensureFinite(view.yaw, "yaw");
+	ensureFinite(view.pitch, "pitch");
+	ensureFinite(view.fieldOfView, "fieldOfView");
+	return {
+		yaw: degrees(view.yaw),
+		pitch: degrees(view.pitch),
+		fieldOfView: degrees(view.fieldOfView)
+	};
+}
+//#endregion
+export { ensureFinite, viewStateOf };