@bubo-squared/gyroview 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 What changed for a page using the package, newest first. Until 1.0, a minor version may change
 the API.
 
+## 0.3.1 (2026-09-30)
+
+New:
+
+- Every error has a `category`, derived from its code, that says whose side the failure is on:
+  `browser`, `recording`, `source`, `usage` or `internal`; `GYRO_VIEW_ERROR_CATEGORIES` and the
+  type `GyroViewErrorCategory` list them. The README's "When a recording cannot play" gives the
+  codes of each, and what a `<video>` fallback can and cannot do (ADR 0030).
+- The `webcodecs-unavailable` error: the browser has no WebCodecs, on a page not served over
+  HTTPS or in an old browser.
+
+What a page may notice:
+
+- A page on plain HTTP, or a browser without WebCodecs, hears `webcodecs-unavailable` where it
+  heard `codec-unsupported`, whose message blamed the codec.
+
 ## 0.3.0 (2026-09-30)
 
 What a page may notice:

package/README.md

@@ -5,6 +5,9 @@ camera's dual-fisheye file directly, over HTTP byte ranges or from a local file,
 lenses in hardware with WebCodecs, and stitches and gyro-stabilizes them on the GPU. No Insta360
 Studio export step.
 
+**Try it first:** [insv-player.com](https://insv-player.com/) plays `.insv` files with this
+package. Drop your own recording to check that your camera and browser work before you install.
+
 ## Install
 
 ```sh
@@ -188,7 +191,8 @@ loads a recording only for the player in view, removing `src` from the others.
 
 ## Requirements
 
-- **A secure page.** WebCodecs exists only on `https://` pages, or `http://localhost`.
+- **A secure page.** WebCodecs exists only on `https://` pages, or `http://localhost`; elsewhere
+  the player fails with `webcodecs-unavailable`.
 - **Recordings served in byte ranges.** The server answers `Range` requests with `206`, and
   sends CORS headers when the recordings live on another origin than the page:
 
@@ -205,17 +209,20 @@ loads a recording only for the player in view, removing `src` from the others.
   `Access-Control-Allow-Credentials: true`.
 
 - **A hardware HEVC decoder.** 5.7K plays on recent laptops and phones; 8K needs a Level 6
-  decoder (Apple Silicon, recent NVIDIA and Intel). A recording the browser cannot decode fails
-  with the `codec-unsupported` error.
+  decoder (Apple Silicon, recent NVIDIA and Intel). On Linux, Chrome reaches the decoder only
+  through VA-API: an Intel or AMD GPU whose driver offers HEVC, not NVIDIA's own driver or a
+  virtual machine (`chrome://gpu` lists `Decode hevc main` under Video Acceleration
+  Information when it can). H.264 recordings do not need it. A recording the browser cannot
+  decode fails with the `codec-unsupported` error.
 
 The supported browsers, with the oldest versions that have what the player uses (WebCodecs,
 WebGL 2, container queries, and on iPhone `ManagedMediaSource` for the sound):
 
-| Browser               | From | Notes                                                    |
-| --------------------- | ---- | -------------------------------------------------------- |
-| Chrome, Edge desktop  | 107  | HEVC is decoded in hardware from this version on.        |
-| Safari on macOS       | 16.4 |                                                          |
-| Safari on iPhone/iPad | 17.1 | 16.4 to 17.0 play without sound, with a `warning` event. |
+| Browser               | From | Notes                                                             |
+| --------------------- | ---- | ----------------------------------------------------------------- |
+| Chrome, Edge desktop  | 107  | HEVC is decoded in hardware from this version on (Linux: VA-API). |
+| Safari on macOS       | 16.4 |                                                                   |
+| Safari on iPhone/iPad | 17.1 | 16.4 to 17.0 play without sound, with a `warning` event.          |
 
 Firefox and Chrome on Android are untested: they play what their decoders accept.
 
@@ -224,8 +231,10 @@ Until 1.0, a minor version may change the API; [CHANGELOG.md](./CHANGELOG.md) sa
 ## Reference
 
 Every attribute, method, event and keyboard shortcut is in the
-[project README](https://github.com/bubo-squared/GyroView#using-the-player); hosting and the
-error codes are in [docs/DEPLOYMENT.md](https://github.com/bubo-squared/GyroView/blob/main/docs/DEPLOYMENT.md).
+[project README](https://github.com/bubo-squared/GyroView#using-the-player), and what a failure
+tells a page, with what a `<video>` fallback can do, under
+[When a recording cannot play](https://github.com/bubo-squared/GyroView#when-a-recording-cannot-play);
+hosting and the error codes are in [docs/DEPLOYMENT.md](https://github.com/bubo-squared/GyroView/blob/main/docs/DEPLOYMENT.md).
 
 ## License
 

package/dist/index.d.ts

@@ -261,7 +261,7 @@ interface DragDelta {
 export type ViewMode = "raw-lenses" | "equirectangular" | "normal";
 export declare const VIEW_MODES: readonly ViewMode[];
 /**
- * Stable machine-readable failure categories. Embedders switch on these; messages are for humans.
+ * Stable machine-readable failure codes. Embedders switch on these; messages are for humans.
  */
 export declare const GYRO_VIEW_ERROR_CODES: readonly [
 	"binary-out-of-bounds",
@@ -291,12 +291,30 @@ export declare const GYRO_VIEW_ERROR_CODES: readonly [
 	"unsupported-container",
 	"unsupported-gyro-record",
 	"unsupported-info-format",
-	"unsupported-layout"
+	"unsupported-layout",
+	"webcodecs-unavailable"
 ];
 export type GyroViewErrorCode = (typeof GYRO_VIEW_ERROR_CODES)[number];
+/**
+ * Whose side a failure is on, for embedders that handle failures by kind: the browser cannot
+ * decode or draw the recording, the file is not one the player can play, its bytes could not be
+ * read, the page misused the API, or the player failed in a way it did not expect.
+ */
+export declare const GYRO_VIEW_ERROR_CATEGORIES: readonly [
+	"browser",
+	"recording",
+	"source",
+	"usage",
+	"internal"
+];
+export type GyroViewErrorCategory = (typeof GYRO_VIEW_ERROR_CATEGORIES)[number];
 export declare function isGyroViewErrorCode(value: unknown): value is GyroViewErrorCode;
 export declare class GyroViewError extends Error {
 	readonly code: GyroViewErrorCode;
+	/**
+	 * Its own property rather than a getter, so a serialized or logged copy of the error keeps it.
+	 */
+	readonly category: GyroViewErrorCategory;
 	constructor(code: GyroViewErrorCode, message: string, options?: ErrorOptions);
 }
 export declare function hasErrorCode(error: unknown, code: GyroViewErrorCode): boolean;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { GYRO_VIEW_ERROR_CODES, GyroViewError, hasErrorCode, isGyroViewErrorCode } from "./packages/core/src/shared/errors/GyroViewError.js";
+import { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GyroViewError, hasErrorCode, isGyroViewErrorCode } from "./packages/core/src/shared/errors/GyroViewError.js";
 import { STABILIZATION_MODES } from "./packages/core/src/domain/motion/stabilization/Stabilizer.js";
 import { PICTURE_QUALITIES } from "./packages/core/src/domain/view/PictureQuality.js";
 import { VIEW_MODES } from "./packages/core/src/domain/view/ViewMode.js";
@@ -10,4 +10,4 @@ import { inspectRecording } from "./packages/player/src/inspectRecording.js";
 import { GyroViewElement } from "./packages/player/src/element/GyroViewElement.js";
 import { GYRO_VIEW_TAG, defineGyroView } from "./packages/player/src/element/defineGyroView.js";
 import "./packages/player/src/index.js";
-export { GYRO_VIEW_ERROR_CODES, GYRO_VIEW_TAG, GyroViewElement, GyroViewError, PICTURE_QUALITIES, Player, STABILIZATION_MODES, VIEW_MODES, attachKeyboard, attachViewGestures, createBrowserPlayer, defineGyroView, hasErrorCode, inspectRecording, isGyroViewErrorCode };
+export { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GYRO_VIEW_TAG, GyroViewElement, GyroViewError, PICTURE_QUALITIES, Player, STABILIZATION_MODES, VIEW_MODES, attachKeyboard, attachViewGestures, createBrowserPlayer, defineGyroView, hasErrorCode, inspectRecording, isGyroViewErrorCode };

package/dist/packages/adapters/webcodecs/src/WebCodecsVideoDecoderPort.js

@@ -15,10 +15,11 @@ var HARDWARE_ACCELERATION = "no-preference";
 */
 var WebCodecsVideoDecoderPort = class {
 	/**
-	* A configuration WebCodecs finds malformed is one it does not support.
+	* A configuration WebCodecs finds malformed is one it does not support. A browser without
+	* WebCodecs refuses to answer, since no configuration would do.
 	*/
 	async isSupported(configuration) {
-		if (typeof VideoDecoder === "undefined") return false;
+		if (typeof VideoDecoder === "undefined") throw webCodecsUnavailable();
 		try {
 			return (await VideoDecoder.isConfigSupported(this.toWebCodecsConfig(configuration))).supported === true;
 		} catch {
@@ -33,7 +34,7 @@ var WebCodecsVideoDecoderPort = class {
 		}
 	}
 	configureDecoder(configuration, callbacks) {
-		if (typeof VideoDecoder === "undefined") throw new GyroViewError("codec-unsupported", "this browser has no WebCodecs VideoDecoder");
+		if (typeof VideoDecoder === "undefined") throw webCodecsUnavailable();
 		return new WebCodecsDecoderHandle(this.toWebCodecsConfig(configuration), callbacks);
 	}
 	toWebCodecsConfig(configuration) {
@@ -114,6 +115,14 @@ var WebCodecsDecoderHandle = class {
 		if (this.decoder.state !== "closed") this.decoder.close();
 	}
 };
+/**
+* Browsers expose WebCodecs only in secure contexts, so a page served over plain HTTP is the
+* likelier cause than an old browser, and the one its developer can fix.
+*/
+function webCodecsUnavailable() {
+	const reason = globalThis.isSecureContext ? "this browser has no WebCodecs VideoDecoder" : "WebCodecs exists only in secure contexts (HTTPS), and this page is not one";
+	return new GyroViewError("webcodecs-unavailable", reason);
+}
 function chunkOf(packet) {
 	return new EncodedVideoChunk({
 		type: packet.isKeyFrame ? "key" : "delta",

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

@@ -28,8 +28,8 @@ var KEY_FRAME_LATE = {
 * a deadline. The host resolves `deadline` once the probe has taken too long (the core has no
 * timers); sources still undecided then report `timed-out`, or `key-frame-late` while their key
 * frame was still being read, and their decoders are closed. A track that cannot be read rejects
-* the probe with its own failure, and the other sources' decoders are closed then, not at the
-* deadline.
+* the probe with its own failure, as a platform without decoders does, and the other sources'
+* decoders are closed then, not at the deadline.
 */
 async function probeDecoding(frameSources, decoderPort, deadline) {
 	const probes = frameSources.map((track) => new SourceProbe(track, decoderPort));

package/dist/packages/core/src/index.js

@@ -1,7 +1,7 @@
 import { degrees } from "./shared/units/angle.js";
 import "./domain/optics/EquidistantModel.js";
 import "./domain/format/calibration/CalibrationVersion.js";
-import { GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf } from "./shared/errors/GyroViewError.js";
+import { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf } from "./shared/errors/GyroViewError.js";
 import { lazy } from "./shared/lazy.js";
 import { microseconds, microsecondsToSeconds, milliseconds, seconds, secondsToMicroseconds } from "./shared/units/time.js";
 import "./domain/motion/exposure/ExposureRecord.js";
@@ -64,4 +64,4 @@ import { WallClock } from "./application/playback/WallClock.js";
 import { isFlowing } from "./domain/playback/PlayerState.js";
 import { TypedEmitter } from "./shared/events/TypedEmitter.js";
 import { PlaybackSession } from "./application/playback/PlaybackSession.js";
-export { ByteRange, DEFAULT_FRAMING, DEFAULT_PICTURE_QUALITY, DEFAULT_STABILIZATION_MODE, DEFAULT_VIEW_MODE, Deferred, Ending, GYRO_VIEW_ERROR_CODES, GainMatchingFrameSink, GyroViewError, IDENTITY_MATRIX3, ITERATION_END, Outbox, PICTURE_QUALITIES, PlaybackSession, RecordingBuffer, RunStop, SCREEN_CENTRE, STABILIZATION_MODES, STOPPED, SourceByteStream, StabilizingFrameSink, TypedEmitter, VIEW_MODES, WallClock, asGyroViewError, aspectOf, aspectOfArea, buildStitchingSetup, clamp, clampView, degrees, detectLensLayout, downloadPolicyFor, ensureIndexInRange, ensureInvariant, fileNameOfUrl, hasErrorCode, inspectRecording, isAbortError, isFlowing, isGyroViewErrorCode, isSameFraming, isSameView, keysOf, lazy, lensFrameOrder, locateOtherLensFile, lookAt, messageOf, microseconds, microsecondsToSeconds, milliseconds, pixelRatioCapOf, planeHalfExtentOf, probeDecoding, readRecording, readSampleTable, seconds, secondsToMicroseconds, stabilizerFor, startFileDownload, timeRecording, viewModeRulesFor, zoomStepsForPinch };
+export { ByteRange, DEFAULT_FRAMING, DEFAULT_PICTURE_QUALITY, DEFAULT_STABILIZATION_MODE, DEFAULT_VIEW_MODE, Deferred, Ending, GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GainMatchingFrameSink, GyroViewError, IDENTITY_MATRIX3, ITERATION_END, Outbox, PICTURE_QUALITIES, PlaybackSession, RecordingBuffer, RunStop, SCREEN_CENTRE, STABILIZATION_MODES, STOPPED, SourceByteStream, StabilizingFrameSink, TypedEmitter, VIEW_MODES, WallClock, asGyroViewError, aspectOf, aspectOfArea, buildStitchingSetup, clamp, clampView, degrees, detectLensLayout, downloadPolicyFor, ensureIndexInRange, ensureInvariant, fileNameOfUrl, hasErrorCode, inspectRecording, isAbortError, isFlowing, isGyroViewErrorCode, isSameFraming, isSameView, keysOf, lazy, lensFrameOrder, locateOtherLensFile, lookAt, messageOf, microseconds, microsecondsToSeconds, milliseconds, pixelRatioCapOf, planeHalfExtentOf, probeDecoding, readRecording, readSampleTable, seconds, secondsToMicroseconds, stabilizerFor, startFileDownload, timeRecording, viewModeRulesFor, zoomStepsForPinch };

package/dist/packages/core/src/shared/errors/GyroViewError.js

@@ -1,6 +1,6 @@
 //#region ../../packages/core/src/shared/errors/GyroViewError.ts
 /**
-* Stable machine-readable failure categories. Embedders switch on these; messages are for humans.
+* Stable machine-readable failure codes. Embedders switch on these; messages are for humans.
 */
 var GYRO_VIEW_ERROR_CODES = [
 	"binary-out-of-bounds",
@@ -30,17 +30,69 @@ var GYRO_VIEW_ERROR_CODES = [
 	"unsupported-container",
 	"unsupported-gyro-record",
 	"unsupported-info-format",
-	"unsupported-layout"
+	"unsupported-layout",
+	"webcodecs-unavailable"
 ];
+/**
+* Whose side a failure is on, for embedders that handle failures by kind: the browser cannot
+* decode or draw the recording, the file is not one the player can play, its bytes could not be
+* read, the page misused the API, or the player failed in a way it did not expect.
+*/
+var GYRO_VIEW_ERROR_CATEGORIES = [
+	"browser",
+	"recording",
+	"source",
+	"usage",
+	"internal"
+];
+/**
+* A record, so a new code cannot be added without its category.
+*/
+var CATEGORY_OF_CODE = {
+	"binary-out-of-bounds": "recording",
+	"binary-unsafe-integer": "recording",
+	"codec-unsupported": "browser",
+	cors: "source",
+	decode: "browser",
+	"embed-destroyed": "usage",
+	"index-out-of-range": "internal",
+	"invalid-argument": "usage",
+	"invalid-byte-range": "recording",
+	"invalid-calibration": "recording",
+	"invalid-protobuf": "recording",
+	"invalid-trailer": "recording",
+	"invariant-violation": "internal",
+	"missing-second-file": "recording",
+	"no-calibration": "recording",
+	"no-info-record": "recording",
+	"no-key-frame": "recording",
+	"playback-blocked": "browser",
+	"range-unsupported": "source",
+	"render-unavailable": "browser",
+	"source-changed": "source",
+	"source-truncated": "source",
+	"source-unreadable": "source",
+	"unsupported-calibration": "recording",
+	"unsupported-container": "recording",
+	"unsupported-gyro-record": "recording",
+	"unsupported-info-format": "recording",
+	"unsupported-layout": "recording",
+	"webcodecs-unavailable": "browser"
+};
 function isGyroViewErrorCode(value) {
 	return typeof value === "string" && GYRO_VIEW_ERROR_CODES.includes(value);
 }
 var GyroViewError = class extends Error {
 	code;
+	/**
+	* Its own property rather than a getter, so a serialized or logged copy of the error keeps it.
+	*/
+	category;
 	constructor(code, message, options) {
 		super(message, options);
 		this.code = code;
 		this.name = "GyroViewError";
+		this.category = CATEGORY_OF_CODE[code];
 	}
 };
 /**
@@ -79,4 +131,4 @@ function ensureIndexInRange(index, length, subject) {
 	if (!Number.isSafeInteger(index) || index < 0 || index >= length) throw new GyroViewError("index-out-of-range", `${subject} index ${index} is outside 0..${length - 1}`);
 }
 //#endregion
-export { GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf };
+export { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf };

package/dist/packages/player/src/controls/messages.js

@@ -78,7 +78,8 @@ var DEFAULT_MESSAGES = {
 		"unsupported-container": UNREADABLE,
 		"unsupported-gyro-record": UNREADABLE,
 		"unsupported-info-format": UNREADABLE,
-		"unsupported-layout": UNREADABLE
+		"unsupported-layout": UNREADABLE,
+		"webcodecs-unavailable": UNSUPPORTED_BROWSER
 	}
 };
 /**