@bubo-squared/gyroview 0.5.0 → 0.6.1

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

@@ -0,0 +1,150 @@
+//#region ../../packages/player/src/player/MotionLook.ts
+/**
+* The motion look setting, kept across loads like the others (ADR 0016), and what of the device
+* it hears: its availability while a recording is drawn, and its readings while motion look is
+* also on and the view mode follows the device. Each time the readings stop, the view is let go,
+* so it is level again everywhere else. Nothing of the page holds the player between recordings:
+* an element taken out of the page unloads, and can be collected.
+*/
+var MotionLook = class {
+	parts;
+	stateValue;
+	request;
+	/**
+	* Counts the requests `stop`, `dispose` and a change of availability overtook: an answer that
+	* comes after them changes nothing.
+	*/
+	generation = 0;
+	stopHearing;
+	stopFollowingAvailability;
+	/**
+	* The viewer refused access: the device's availability changes nothing after that.
+	*/
+	wasRefused = false;
+	constructor(parts) {
+		this.parts = parts;
+		this.stateValue = parts.sensor.availability === "available" ? "off" : "unavailable";
+	}
+	/**
+	* As last known: the device's availability is followed while a recording is drawn.
+	*/
+	get state() {
+		return this.stateValue;
+	}
+	/**
+	* Turns motion look on, asking for access first; resolves with the state it ends in and never
+	* rejects. A second call while the first asks waits for the same answer.
+	*/
+	start() {
+		this.followAvailability();
+		if (this.stateValue !== "off") return Promise.resolve(this.stateValue);
+		this.request ??= this.ask();
+		return this.request;
+	}
+	stop() {
+		this.overtakeRequest();
+		if (this.stateValue === "on") this.change("off");
+	}
+	/**
+	* The player calls it whenever a recording or the view mode may have changed.
+	*/
+	reconsider() {
+		this.reconsiderAvailability();
+		this.reconsiderHearing();
+	}
+	dispose() {
+		this.overtakeRequest();
+		this.stopFollowingAvailability?.();
+		this.stopFollowingAvailability = void 0;
+		this.stopHearing?.();
+		this.stopHearing = void 0;
+		this.parts.sensor.dispose();
+	}
+	reconsiderAvailability() {
+		const isDrawn = this.parts.hasRecording();
+		if (isDrawn && !this.stopFollowingAvailability) {
+			this.stopFollowingAvailability = this.parts.sensor.onAvailabilityChange(() => {
+				this.followAvailability();
+			});
+			this.followAvailability();
+		} else if (!isDrawn && this.stopFollowingAvailability) {
+			this.stopFollowingAvailability();
+			this.stopFollowingAvailability = void 0;
+		}
+	}
+	/**
+	* Hears the device exactly while motion look is on, a recording is drawn and the view mode
+	* follows the device; lets the view go whenever it stops.
+	*/
+	reconsiderHearing() {
+		const { sensor, view, hasRecording } = this.parts;
+		const shouldHear = this.stateValue === "on" && hasRecording() && view.followsDevice;
+		if (shouldHear && !this.stopHearing) this.stopHearing = sensor.listen((reading) => {
+			view.followDevice(reading);
+		});
+		else if (!shouldHear && this.stopHearing) {
+			this.stopHearing();
+			this.stopHearing = void 0;
+			view.letGo();
+		}
+	}
+	/**
+	* A device found to report its attitude after all may be turned on; one found not to, which
+	* may happen after it was turned on, can no longer be.
+	*/
+	followAvailability() {
+		const isAvailable = this.parts.sensor.availability === "available";
+		if (this.wasRefused || isAvailable === (this.stateValue !== "unavailable")) return;
+		this.overtakeRequest();
+		this.change(isAvailable ? "off" : "unavailable");
+	}
+	async ask() {
+		const generation = this.generation;
+		const access = await this.accessOrGesture();
+		if (generation !== this.generation) return this.stateValue;
+		this.request = void 0;
+		this.answer(access);
+		return this.stateValue;
+	}
+	/**
+	* A sensor's request never rejects; one that did is taken as wanting a gesture, so motion look
+	* may still be started from the next tap.
+	*/
+	async accessOrGesture() {
+		try {
+			return await this.parts.sensor.requestAccess();
+		} catch {
+			return "needs-gesture";
+		}
+	}
+	answer(access) {
+		if (access === "granted") this.change("on");
+		else if (access === "denied") {
+			this.wasRefused = true;
+			this.change("unavailable");
+			this.warn("motion-look-refused", REFUSED);
+		} else this.warn("motion-look-needs-gesture", NEEDS_GESTURE);
+	}
+	overtakeRequest() {
+		this.generation += 1;
+		this.request = void 0;
+	}
+	/**
+	* Announced once the change is whole (ADR 0021): the device heard, or let go, first.
+	*/
+	change(state) {
+		this.stateValue = state;
+		this.reconsiderHearing();
+		this.parts.events.emit("motionlookchange", state);
+	}
+	warn(code, message) {
+		this.parts.events.emit("warning", {
+			code,
+			message
+		});
+	}
+};
+var REFUSED = "motion look was refused: by the viewer, or by an iframe whose `allow` leaves out accelerometer, gyroscope and magnetometer";
+var NEEDS_GESTURE = "motion look asks for access, which this browser grants only from a user gesture such as a tap";
+//#endregion
+export { MotionLook };

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

@@ -1,25 +1,29 @@
 import { degrees } from "../../../core/src/shared/units/angle.js";
-import { asGyroViewError, hasErrorCode, messageOf } from "../../../core/src/shared/errors/GyroViewError.js";
+import { asGyroViewError } 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 { NO_ATTITUDE_SENSOR } from "../composition/attitudeSensor.js";
+import { AutomaticStarts } from "./AutomaticStarts.js";
 import { cssSizeOf } from "./DrawingBufferFit.js";
 import { FrameLoop } from "./FrameLoop.js";
 import { loadRecording } from "./loadRecording.js";
+import { MotionLook } from "./MotionLook.js";
 import { IDLE, loadingPhase, statusOf } from "./PlayerPhase.js";
 import { PictureSettings } from "./PictureSettings.js";
 import { PlayerSound } from "./PlayerSound.js";
+import { anglesOf } from "./viewAngles.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.
+* its settings (view, view mode, motion look, stabilization, gain matching, sound, loop) from
+* load to load. `<gyro-view>` is a facade over it.
 */
 var Player = class {
 	parts;
@@ -31,6 +35,7 @@ var Player = class {
 	loop;
 	phase = IDLE;
 	viewing;
+	motion;
 	picture = new PictureSettings(this.outbox);
 	/**
 	* A seek asked for before a recording was ready, where the next one starts.
@@ -43,10 +48,10 @@ var Player = class {
 			this.announceStatus();
 		},
 		onEnded: () => {
-			this.onEnded();
+			this.starts.ended();
 		}
 	});
-	isLoopingValue = false;
+	starts = new AutomaticStarts(this.outbox, () => this.play());
 	/**
 	* Past `dispose`: a listener of the idle it announces must not load again.
 	*/
@@ -65,6 +70,12 @@ var Player = class {
 		this.sound = new PlayerSound(parts.host.audio, this.outbox);
 		const { canvas } = parts.host;
 		this.viewing = new PlayerView(this.outbox, () => cssSizeOf(canvas));
+		this.motion = new MotionLook({
+			sensor: parts.attitude ?? NO_ATTITUDE_SENSOR,
+			view: this.viewing,
+			events: this.outbox,
+			hasRecording: () => this.loaded !== void 0
+		});
 	}
 	get status() {
 		return statusOf(this.phase);
@@ -85,7 +96,7 @@ var Player = class {
 		return !isFlowing(this.loaded?.pipeline.session.state);
 	}
 	get view() {
-		return this.viewing.current;
+		return anglesOf(this.viewing.current);
 	}
 	get viewMode() {
 		return this.viewing.viewMode;
@@ -96,6 +107,13 @@ var Player = class {
 	get canPan() {
 		return this.viewing.canPan;
 	}
+	/**
+	* Whether turning the device turns the normal view: `unavailable` where the device reports no
+	* attitude or access was refused.
+	*/
+	get motionLook() {
+		return this.motion.state;
+	}
 	get stabilization() {
 		return this.picture.stabilization;
 	}
@@ -103,7 +121,7 @@ var Player = class {
 		return this.picture.quality;
 	}
 	get isLooping() {
-		return this.isLoopingValue;
+		return this.starts.isLooping;
 	}
 	get volume() {
 		return this.sound.volume;
@@ -219,6 +237,22 @@ var Player = class {
 	}
 	setViewMode(mode) {
 		this.viewing.setMode(mode);
+		this.motion.reconsider();
+	}
+	/**
+	* Lets the device turn the normal view, as a window into the recording: its tilt and roll
+	* hold the pitch and keep the horizon level, drags turn the heading alone. Call it from a tap's
+	* handler: iOS asks the viewer for access there and refuses it anywhere else. Resolves with the
+	* state it ends in; a refusal is a warning, never a rejection.
+	*/
+	startMotionLook() {
+		return this.motion.start();
+	}
+	/**
+	* Gives the view back to the pointer, level, looking where it looked.
+	*/
+	stopMotionLook() {
+		this.motion.stop();
 	}
 	setStabilization(mode) {
 		this.picture.setStabilization(mode);
@@ -230,7 +264,7 @@ var Player = class {
 		this.picture.setQuality(quality);
 	}
 	setLooping(isLooping) {
-		this.isLoopingValue = isLooping;
+		this.starts.setLooping(isLooping);
 	}
 	/**
 	* Whether the lenses' exposure is matched along the seam; kept across loads.
@@ -248,6 +282,7 @@ var Player = class {
 	dispose() {
 		this.isDisposed = true;
 		this.unload();
+		this.motion.dispose();
 		this.parts.host.audio.removeEventListener("ended", this.tick);
 		this.sound.dispose();
 		this.events.removeAll();
@@ -280,7 +315,7 @@ var Player = class {
 			this.startAtPendingTime(loaded);
 			if (options.preload !== false) loaded.pipeline.session.preload();
 		});
-		if (options.autoplay && this.loaded === loaded) await this.autoplay();
+		if (options.autoplay && this.loaded === loaded) await this.starts.autoplay();
 	}
 	startAtPendingTime(loaded) {
 		const time = this.pendingStartTime;
@@ -294,6 +329,7 @@ var Player = class {
 			controller
 		};
 		this.viewing.attach(loaded.pipeline.renderer);
+		this.motion.reconsider();
 		const { session } = loaded.pipeline;
 		this.picture.attach(loaded.pipeline);
 		this.relay.attach(session);
@@ -303,36 +339,6 @@ var Player = class {
 		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() {
@@ -342,6 +348,7 @@ var Player = class {
 		this.loop.stop();
 		this.relay.detach();
 		this.viewing.attach(void 0);
+		this.motion.reconsider();
 		this.picture.attach(void 0);
 		if (previous.kind !== "loaded") return;
 		previous.loaded.dispose();

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

@@ -18,6 +18,7 @@ var PLAYER_EVENT_NAMES = keysOf({
 	frame: true,
 	viewchange: true,
 	viewmodechange: true,
+	motionlookchange: true,
 	stabilizationchange: true,
 	qualitychange: true,
 	volumechange: true,

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

@@ -1,10 +1,11 @@
-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 { followReading, withoutRoll } from "../../../core/src/domain/view/motionLookView.js";
+import { motionLookRulesFor, viewModeRulesFor } from "../../../core/src/domain/view/viewModes.js";
 import "../../../core/src/index.js";
+import { anglesOf, isSameAngles } from "./viewAngles.js";
 //#region ../../packages/player/src/player/PlayerView.ts
 /**
 * Every layout the player accepts has two lenses; a renderer attached says so itself.
@@ -12,9 +13,10 @@ import "../../../core/src/index.js";
 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.
+* renderer is attached, and the normal view's angles announced when they change. The viewer's
+* gestures and a host setting the view go through the mode's rules on the viewport as it is
+* now; while the device holds the view (motion look, ADR 0040), through the rules it follows
+* then.
 */
 var PlayerView = class {
 	events;
@@ -23,6 +25,10 @@ var PlayerView = class {
 	mode = DEFAULT_VIEW_MODE;
 	surface;
 	lensCount = LENS_COUNT_BEFORE_A_LOAD;
+	/**
+	* The device reading the held view follows from; none while the device does not hold it.
+	*/
+	previous;
 	constructor(events, measureViewport) {
 		this.events = events;
 		this.measureViewport = measureViewport;
@@ -40,6 +46,12 @@ var PlayerView = class {
 		return this.rules().canPan(this.framing);
 	}
 	/**
+	* Whether the device may turn the view in the current mode.
+	*/
+	get followsDevice() {
+		return motionLookRulesFor(this.mode) !== void 0;
+	}
+	/**
 	* 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.
@@ -51,10 +63,7 @@ var PlayerView = class {
 		surface?.setFraming(this.framing);
 	}
 	set(view) {
-		this.frame({
-			...this.framing,
-			view: clampView(view)
-		});
+		this.frame(this.rules().place(this.framing, view));
 	}
 	setMode(mode) {
 		if (mode === this.mode) return;
@@ -63,9 +72,28 @@ var PlayerView = class {
 		this.events.emit("viewmodechange", mode);
 	}
 	lookAt(yaw, pitch) {
+		this.frame(this.rules().place(this.framing, lookAt(this.framing.view, yaw, pitch)));
+	}
+	/**
+	* Turns the view as the device turned: from its first reading on, the device holds the view.
+	*/
+	followDevice(reading) {
+		const hold = followReading(this.framing.view, this.previous, reading);
+		this.previous = hold.reading;
 		this.frame({
 			...this.framing,
-			view: lookAt(this.framing.view, yaw, pitch)
+			view: hold.view
+		});
+	}
+	/**
+	* The device no longer holds the view: it stays where it looks, level again.
+	*/
+	letGo() {
+		if (!this.previous) return;
+		this.previous = void 0;
+		this.frame({
+			...this.framing,
+			view: withoutRoll(this.framing.view)
 		});
 	}
 	pan(delta) {
@@ -92,12 +120,15 @@ var PlayerView = class {
 	reset() {
 		this.frame(this.rules().reset(this.framing));
 	}
+	/**
+	* Draws any change; announces one of the angles a page sees, not a roll alone.
+	*/
 	frame(next) {
 		if (isSameFraming(next, this.framing)) return;
-		const hasViewChanged = !isSameView(next.view, this.framing.view);
+		const haveAnglesChanged = !isSameAngles(next.view, this.framing.view);
 		this.framing = next;
 		this.surface?.setFraming(next);
-		if (hasViewChanged) this.events.emit("viewchange", next.view);
+		if (haveAnglesChanged) this.events.emit("viewchange", anglesOf(next.view));
 	}
 	context() {
 		return {
@@ -106,7 +137,7 @@ var PlayerView = class {
 		};
 	}
 	rules() {
-		return viewModeRulesFor(this.mode);
+		return (this.previous === void 0 ? void 0 : motionLookRulesFor(this.mode)) ?? viewModeRulesFor(this.mode);
 	}
 };
 //#endregion

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

@@ -10,7 +10,7 @@ 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.
+* A view from the page, each angle checked and read as degrees, level.
 */
 function viewStateOf(view) {
 	ensureFinite(view.yaw, "yaw");
@@ -19,6 +19,7 @@ function viewStateOf(view) {
 	return {
 		yaw: degrees(view.yaw),
 		pitch: degrees(view.pitch),
+		roll: degrees(0),
 		fieldOfView: degrees(view.fieldOfView)
 	};
 }

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

@@ -0,0 +1,17 @@
+//#region ../../packages/player/src/player/viewAngles.ts
+/**
+* The view as a page sees it: a fresh object of the three angles, the roll the device gives the
+* held view kept inside the player (ADR 0040).
+*/
+function anglesOf(view) {
+	return {
+		yaw: view.yaw,
+		pitch: view.pitch,
+		fieldOfView: view.fieldOfView
+	};
+}
+function isSameAngles(a, b) {
+	return a.yaw === b.yaw && a.pitch === b.pitch && a.fieldOfView === b.fieldOfView;
+}
+//#endregion
+export { anglesOf, isSameAngles };