@bubo-squared/gyroview 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,959 @@
+/**
+ * A recording reachable over HTTP with Range support (see README, "Serving recordings").
+ */
+export interface UrlInput {
+	readonly url: string;
+}
+/**
+ * A recording already in the browser: a `File` from a picker or a drop.
+ */
+export interface BlobInput {
+	readonly blob: Blob;
+	readonly name: string;
+}
+export type MediaInput = UrlInput | BlobInput;
+/**
+ * Everything that names what to play. The second input is the other lens's file of a
+ * split-file recording, found beside the main one by itself when left out.
+ */
+export interface PlayerSource {
+	readonly main: MediaInput;
+	readonly second?: MediaInput | undefined;
+}
+declare const brand: unique symbol;
+type Brand<Base, Name extends string> = Base & {
+	readonly [brand]: Name;
+};
+declare const space: unique symbol;
+interface Size<Space extends string> {
+	readonly width: number;
+	readonly height: number;
+	readonly [space]?: Space;
+}
+declare const CalibrationVersion: {
+	readonly Legacy: 1;
+	readonly Polynomial: 2;
+	readonly Mei: 3;
+};
+type CalibrationVersion = (typeof CalibrationVersion)[keyof typeof CalibrationVersion];
+type Milliseconds = Brand<number, "Milliseconds">;
+type Seconds = Brand<number, "Seconds">;
+type FrameTimeSourceName = "exposure-record" | "track-timestamps" | "nominal";
+type LensLayoutKind = "multi-track" | "split-files" | "packed";
+type FileLayoutHint = Exclude<LensLayoutKind, "packed">;
+type TrackOrderHint = "stream-10-first" | "stream-00-first";
+type LensDimension = Size<"video pixels">;
+interface SensorRanges {
+	readonly accelerometerG: number | undefined;
+	readonly gyroscopeDps: number | undefined;
+}
+interface WindowCrop {
+	readonly sensorWidth: number | undefined;
+	readonly sensorHeight: number | undefined;
+	readonly cropWidth: number | undefined;
+	readonly cropHeight: number | undefined;
+	readonly cropOffsetX: number | undefined;
+	readonly cropOffsetY: number | undefined;
+}
+interface CalibrationStrings {
+	readonly offset: string | undefined;
+	readonly offsetV2: string | undefined;
+	readonly offsetV3: string | undefined;
+}
+/**
+ * Everything the player learns from the info record. Absent fields are `undefined`; nothing here
+ * is assumed present except on cameras where a field has been observed.
+ */
+export interface RecordingInfo {
+	readonly serialNumber: string | undefined;
+	readonly model: string | undefined;
+	readonly firmware: string | undefined;
+	readonly calibration: CalibrationStrings;
+	readonly dimension: LensDimension | undefined;
+	readonly frameRate: number | undefined;
+	readonly captureMode: string | undefined;
+	/**
+	 * Capture-clock time of the first encoded frame, in the unit the gyro record uses
+	 * (microseconds for the raw layout, milliseconds for the float layout). Resolve it through
+	 * `firstFrameCaptureTime`, never by hand.
+	 */
+	readonly firstFrameTimestamp: number | undefined;
+	/**
+	 * Rolling-shutter readout duration of one frame.
+	 */
+	readonly readoutTime: Seconds | undefined;
+	readonly windowCrop: WindowCrop | undefined;
+	/**
+	 * How much later than the frames the gyro samples are stamped.
+	 */
+	readonly gyroOffset: Milliseconds | undefined;
+	readonly gyroType: number | undefined;
+	readonly isRawGyro: boolean | undefined;
+	/**
+	 * The frame time source the camera says to trust first (`pts_type`).
+	 */
+	readonly preferredFrameTimeSource: FrameTimeSourceName | undefined;
+	readonly sensorRanges: SensorRanges | undefined;
+	readonly fileLayout: FileLayoutHint | undefined;
+	readonly trackOrder: TrackOrderHint | undefined;
+}
+type TrailerWrapper = "inst-box" | "bare";
+/**
+ * One top-level box of the file: its four-character type, where it starts and how long it is.
+ */
+export interface BoxSummary {
+	readonly type: string;
+	readonly offset: number;
+	readonly size: number;
+}
+export interface RecordSummary {
+	readonly id: number;
+	readonly format: number;
+	readonly offset: number;
+	readonly size: number;
+}
+export interface LensSummary {
+	readonly lensIndex: number;
+	readonly model: string;
+	readonly principalPoint: readonly [
+		x: number,
+		y: number
+	];
+	readonly orientationDegrees: readonly [
+		yaw: number,
+		pitch: number,
+		roll: number
+	];
+	readonly translationMetres: readonly [
+		x: number,
+		y: number,
+		z: number
+	];
+}
+export interface CalibrationSummary {
+	readonly version: CalibrationVersion;
+	readonly canvas: readonly [
+		width: number,
+		height: number
+	];
+	readonly lenses: readonly LensSummary[];
+}
+export interface GyroSummary {
+	readonly layout: string;
+	readonly samples: number;
+	readonly strayBytes: number;
+	/**
+	 * Samples left out because their bytes cannot be a reading; a wrong layout guess shows here.
+	 */
+	readonly damagedSamples: number;
+	/**
+	 * Stamps put back where their neighbours say they belong: glitched stamps. A wrong stamp unit
+	 * scales them all alike and shows in the mean interval and the span instead.
+	 */
+	readonly mendedStamps: number;
+	readonly spanSeconds: number;
+	readonly meanIntervalUs: number | undefined;
+	/**
+	 * Mean |acceleration| over the leading samples; about 1 g proves the range scaling. Undefined
+	 * for a record without samples.
+	 */
+	readonly meanAccelerationMagnitudeG: number | undefined;
+}
+/**
+ * A gyro record whose sample layout could not be told, and why.
+ */
+export interface UnreadableGyro {
+	readonly unreadable: string;
+}
+/**
+ * An exposure record the trailer lists that did not parse: an entry no clock could have stamped
+ * or no shutter could take.
+ */
+export interface DamagedExposure {
+	readonly damaged: true;
+}
+/**
+ * An exposure record the trailer lists that was not read, and why.
+ */
+export interface UnreadExposure {
+	readonly unread: string;
+}
+/**
+ * The record's entries; the times and the mean are undefined for a record without any, so the
+ * summary stays plain data that serializes as it reads.
+ */
+export interface ExposureSummary {
+	readonly entries: number;
+	readonly firstCaptureTimeUs: number | undefined;
+	readonly lastCaptureTimeUs: number | undefined;
+	readonly meanShutterTimeSeconds: number | undefined;
+	/**
+	 * Index of the entry that belongs to the first encoded frame, when the info record says.
+	 */
+	readonly firstEncodedFrameEntry: number | undefined;
+}
+export type ExposureReport = ExposureSummary | DamagedExposure | UnreadExposure;
+/**
+ * What a recording's file holds, as plain data: its boxes, the trailer and its records, the info
+ * record, the calibration and summaries of the gyro and exposure records. Serializable, so a
+ * report, a page or a test can take it without the domain objects.
+ */
+export interface RecordingInspection {
+	readonly fileSize: number;
+	readonly boxes: readonly BoxSummary[];
+	readonly trailerWrapper: TrailerWrapper;
+	readonly trailerVersion: number;
+	readonly payloadStart: number;
+	readonly records: readonly RecordSummary[];
+	readonly info: RecordingInfo;
+	/**
+	 * Undefined when the recording carries no usable calibration string.
+	 */
+	readonly calibration: CalibrationSummary | undefined;
+	/**
+	 * Why calibration strings were skipped, whether or not one was usable.
+	 */
+	readonly calibrationWarnings: readonly string[];
+	readonly gyro: GyroSummary | UnreadableGyro | undefined;
+	readonly exposure: ExposureReport | undefined;
+}
+interface VideoTrackDescription {
+	readonly trackIndex: number;
+	readonly codedWidth: number;
+	readonly codedHeight: number;
+	/**
+	 * WebCodecs codec string, for example `hvc1.1.6.L153.B0` or `avc1.640033`.
+	 */
+	readonly codec: string;
+}
+export type StabilizationMode = "off" | "lock" | "horizon" | "follow";
+export declare const STABILIZATION_MODES: readonly StabilizationMode[];
+/**
+ * How finely the renderer reads the lens images for each screen pixel, and how many device pixels
+ * per CSS pixel the drawing buffer may hold ({@link pixelRatioCapOf}): `fast` reads one bilinear
+ * tap of the frame as decoded; `balanced` reads through a mip chain over the pixel's footprint,
+ * which stops the shimmer where the frame is minified; `high` adds extra taps (ADR 0024).
+ */
+export type PictureQuality = "fast" | "balanced" | "high";
+export declare const PICTURE_QUALITIES: readonly PictureQuality[];
+interface ScreenPoint {
+	readonly x: number;
+	readonly y: number;
+}
+interface DragDelta {
+	readonly x: number;
+	readonly y: number;
+}
+/**
+ * What the player shows: `raw-lenses` is each lens's decoded image on its own, unstitched, and
+ * what the player opens on; `equirectangular` is the whole stitched sphere as a 2:1 panorama;
+ * `normal` is a rectilinear window into the stitched sphere that the viewer turns and zooms.
+ * The order is the view menu's, first to last (ADR 0022).
+ */
+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.
+ */
+export declare const GYRO_VIEW_ERROR_CODES: readonly [
+	"binary-out-of-bounds",
+	"binary-unsafe-integer",
+	"codec-unsupported",
+	"cors",
+	"decode",
+	"embed-destroyed",
+	"index-out-of-range",
+	"invalid-argument",
+	"invalid-byte-range",
+	"invalid-calibration",
+	"invalid-protobuf",
+	"invalid-trailer",
+	"invariant-violation",
+	"missing-second-file",
+	"no-calibration",
+	"no-info-record",
+	"no-key-frame",
+	"playback-blocked",
+	"range-unsupported",
+	"render-unavailable",
+	"source-truncated",
+	"source-unreadable",
+	"unsupported-calibration",
+	"unsupported-container",
+	"unsupported-gyro-record",
+	"unsupported-info-format",
+	"unsupported-layout"
+];
+export type GyroViewErrorCode = (typeof GYRO_VIEW_ERROR_CODES)[number];
+export declare function isGyroViewErrorCode(value: unknown): value is GyroViewErrorCode;
+export declare class GyroViewError extends Error {
+	readonly code: GyroViewErrorCode;
+	constructor(code: GyroViewErrorCode, message: string, options?: ErrorOptions);
+}
+export declare function hasErrorCode(error: unknown, code: GyroViewErrorCode): boolean;
+type Listener<Payload> = (payload: Payload) => void;
+declare class TypedEmitter<Events extends object> {
+	private readonly reportListenerError;
+	private readonly listeners;
+	constructor(reportListenerError?: (error: unknown) => void);
+	on<Name extends keyof Events>(name: Name, listener: Listener<Events[Name]>): () => void;
+	/**
+	 * The listeners there when the emit began hear it, as `dispatchEvent` delivers: one added
+	 * meanwhile waits for the next emit, so a listener that subscribes itself again runs once, and
+	 * one removed meanwhile hears no more.
+	 */
+	emit<Name extends keyof Events>(name: Name, payload: Events[Name]): void;
+	/**
+	 * The listeners of an event under way are dropped too, as an unsubscribe drops one: whoever
+	 * removed them is past hearing from them.
+	 */
+	removeAll(): void;
+}
+type PlayerState = "ready" | "playing" | "buffering" | "paused" | "seeking" | "ended" | "error" | "disposed";
+export interface ImuFrameSummary {
+	readonly name: string;
+	readonly isVerified: boolean;
+}
+/**
+ * What the player learned about a recording while opening it, for the `ready` event: enough for
+ * an embedder to know which camera, layout and degraded features it got.
+ */
+export interface PlayerMetadata {
+	readonly model: string | undefined;
+	readonly firmware: string | undefined;
+	readonly captureMode: string | undefined;
+	readonly layout: LensLayoutKind;
+	readonly layoutEvidence: readonly string[];
+	/**
+	 * The lens tracks in lens order.
+	 */
+	readonly tracks: readonly VideoTrackDescription[];
+	readonly calibrationVersion: CalibrationVersion;
+	readonly frameTimeSource: FrameTimeSourceName | undefined;
+	readonly hasGyro: boolean;
+	readonly imuFrame: ImuFrameSummary | undefined;
+	readonly hasAudio: boolean;
+	/**
+	 * In seconds.
+	 */
+	readonly duration: number;
+}
+/**
+ * The DOM the pipeline draws on and plays sound through; both borrowed from the element.
+ */
+export interface PipelineHost {
+	readonly canvas: HTMLCanvasElement;
+	readonly audio: HTMLMediaElement;
+}
+/**
+ * A view as a page gives it and gets it back: yaw positive to the right, pitch positive up, and
+ * the horizontal field of view, all in degrees.
+ */
+export interface ViewAngles {
+	readonly yaw: number;
+	readonly pitch: number;
+	readonly fieldOfView: number;
+}
+/**
+ * What concerns one load only. The settings (view, view mode, stabilization, gain matching,
+ * sound, loop) belong to the player and carry over from load to load; set them on the player.
+ */
+export interface LoadOptions {
+	/**
+	 * Start as soon as the recording is ready; a refusal by the autoplay policy is a warning.
+	 */
+	readonly autoplay?: boolean;
+	/**
+	 * Decode the first frame as soon as the recording is ready, so it shows instead of a black
+	 * canvas. Default true; off keeps the decoders idle until play.
+	 */
+	readonly preload?: boolean;
+}
+/**
+ * The session's states plus the two only the player knows: nothing loaded, and loading.
+ */
+export type PlayerStatus = "idle" | "loading" | PlayerState;
+/**
+ * The sound as it is now: volume from 0 to 1, and whether it is muted.
+ */
+export interface SoundLevel {
+	readonly volume: number;
+	readonly isMuted: boolean;
+}
+/**
+ * What a `warning` is about, for a page that acts on some and not others:
+ * - `recording-degraded`: the recording lacks, or has damaged, data the player works around (no
+ *   gyro, an unverified IMU frame, fallback frame times or calibration); `ready`'s metadata says
+ *   what it got.
+ * - `no-sound`: the recording has no sound, or none this browser plays; a silent clock runs.
+ * - `autoplay-blocked`: the browser waits for a user gesture before it starts playback.
+ * - `playback-failed`: a start (a press, autoplay, the loop) or the seek bar's preview failed.
+ * - `ignored-attribute`: an attribute's value names nothing the element knows; the setting stays.
+ * - `refused-property`: a property set before the element was defined was refused.
+ */
+export type WarningCode = "recording-degraded" | "no-sound" | "autoplay-blocked" | "playback-failed" | "ignored-attribute" | "refused-property";
+export interface PlayerWarning {
+	readonly code: WarningCode;
+	/**
+	 * What happened exactly, for a developer.
+	 */
+	readonly message: string;
+}
+export interface PlayerEvents {
+	readonly statuschange: PlayerStatus;
+	readonly ready: PlayerMetadata;
+	readonly play: undefined;
+	/**
+	 * Frames are ready and the clock runs: after `play` or after `waiting`.
+	 */
+	readonly playing: undefined;
+	/**
+	 * Playback holds for frames: on starting, after a seek, or when decoding falls behind.
+	 */
+	readonly waiting: undefined;
+	readonly pause: undefined;
+	readonly ended: undefined;
+	/**
+	 * The media time, every quarter second of playback and on a pause, a seek or the end.
+	 */
+	readonly timeupdate: number;
+	readonly seeking: number;
+	readonly seeked: number;
+	/**
+	 * A picture was drawn; the media time it shows.
+	 */
+	readonly frame: number;
+	readonly viewchange: ViewAngles;
+	readonly viewmodechange: ViewMode;
+	readonly stabilizationchange: StabilizationMode;
+	/**
+	 * The picture quality changed, to the one named.
+	 */
+	readonly qualitychange: PictureQuality;
+	/**
+	 * The volume or the mute changed, from whatever changed it.
+	 */
+	readonly volumechange: SoundLevel;
+	/**
+	 * Something the player worked around; the code says what, the message says it exactly.
+	 */
+	readonly warning: PlayerWarning;
+	readonly error: GyroViewError;
+}
+/**
+ * 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.
+ */
+export declare class Player {
+	private readonly parts;
+	readonly events: TypedEmitter<PlayerEvents>;
+	/**
+	 * What the player and its parts announce, heard once each change is whole (ADR 0021).
+	 */
+	private readonly outbox;
+	private readonly loop;
+	private phase;
+	private readonly viewing;
+	private readonly picture;
+	/**
+	 * A seek asked for before a recording was ready, where the next one starts.
+	 */
+	private pendingStartTime;
+	private readonly sound;
+	private readonly relay;
+	private isLoopingValue;
+	/**
+	 * Past `dispose`: a listener of the idle it announces must not load again.
+	 */
+	private isDisposed;
+	/**
+	 * The status listeners heard last.
+	 */
+	private lastStatus;
+	get status(): PlayerStatus;
+	get metadata(): PlayerMetadata | undefined;
+	get currentTime(): number;
+	get duration(): number;
+	/**
+	 * False while playing or holding for frames, as a media element's `paused`.
+	 */
+	get isPaused(): boolean;
+	get view(): ViewAngles;
+	get viewMode(): ViewMode;
+	/**
+	 * Whether a drag moves the picture as it is framed now; the view mode decides.
+	 */
+	get canPan(): boolean;
+	get stabilization(): StabilizationMode;
+	get quality(): PictureQuality;
+	get isLooping(): boolean;
+	get volume(): number;
+	get isMuted(): boolean;
+	/**
+	 * Whether `setVolume` changes anything on this platform; iOS leaves media at the device's volume.
+	 */
+	get canSetVolume(): boolean;
+	/**
+	 * 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.
+	 */
+	load(source: PlayerSource, options?: LoadOptions): Promise<void>;
+	unload(): void;
+	/**
+	 * 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.
+	 */
+	play(): Promise<void>;
+	pause(): void;
+	stop(): void;
+	/**
+	 * 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: number): void;
+	/**
+	 * Seeks to the key frame at or before `time` seconds: quick to show while a seek bar is dragged.
+	 */
+	scrub(time: number): Promise<void>;
+	setView(view: ViewAngles): void;
+	/**
+	 * Points the normal view at `yaw` and `pitch`, in degrees: yaw positive to the right, pitch
+	 * positive up.
+	 */
+	lookAt(yaw: number, pitch: number): void;
+	/**
+	 * The viewer dragged the picture by `delta` CSS pixels across the canvas.
+	 */
+	pan(delta: DragDelta): void;
+	/**
+	 * The viewer turned by the given angles in degrees, as the arrow keys do.
+	 */
+	turn(yawDelta: number, pitchDelta: number): void;
+	/**
+	 * 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: number, focus?: ScreenPoint): void;
+	resetView(): void;
+	setViewMode(mode: ViewMode): void;
+	setStabilization(mode: StabilizationMode): void;
+	/**
+	 * How finely the lens images are read and how many device pixels are drawn; kept across loads.
+	 */
+	setQuality(quality: PictureQuality): void;
+	setLooping(isLooping: boolean): void;
+	/**
+	 * Whether the lenses' exposure is matched along the seam; kept across loads.
+	 */
+	setGainMatching(isEnabled: boolean): void;
+	setVolume(volume: number): void;
+	setMuted(isMuted: boolean): void;
+	dispose(): void;
+	private readonly tick;
+	/**
+	 * Whatever it ends in: a failure is the load's to report, and `play` reads it from the phase.
+	 */
+	private loadInProgress;
+	private get loaded();
+	private complete;
+	private startAtPendingTime;
+	private attach;
+	/**
+	 * A refused start leaves the recording loaded and paused: a warning, never a failed load.
+	 */
+	private autoplay;
+	private onEnded;
+	private replay;
+	/**
+	 * Lets go of whatever is loading or loaded, announcing nothing.
+	 */
+	private release;
+	private failWith;
+	/**
+	 * 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.
+	 */
+	private announceStatus;
+}
+/**
+ * The element's labels: what its buttons, sliders, menus and overlays are called, and its own
+ * name for assistive technology.
+ */
+export interface GyroViewLabels {
+	/**
+	 * The element's name, unless the page names it.
+	 */
+	readonly player: string;
+	readonly loading: string;
+	readonly play: string;
+	readonly pause: string;
+	readonly stop: string;
+	readonly seek: string;
+	/**
+	 * How the seek bar tells assistive technology where it is: `{time}` and `{duration}` are
+	 * replaced.
+	 */
+	readonly position: string;
+	readonly mute: string;
+	readonly volume: string;
+	readonly resetView: string;
+	readonly stabilization: string;
+	readonly viewMode: string;
+	readonly fullscreen: string;
+}
+type LabelName = keyof GyroViewLabels;
+/**
+ * Every word `<gyro-view>` shows, or says to assistive technology: English by default, each
+ * replaceable through the element's `messages` property.
+ */
+export interface GyroViewMessages {
+	readonly labels: GyroViewLabels;
+	readonly stabilizationModes: Readonly<Record<StabilizationMode, string>>;
+	readonly viewModes: Readonly<Record<ViewMode, string>>;
+	/**
+	 * What a visitor reads when a recording cannot play, by the failure's code. The `error`
+	 * event carries the developer's account of it.
+	 */
+	readonly errors: Readonly<Record<GyroViewErrorCode, string>>;
+}
+/**
+ * The words a page gives: any of them, table by table.
+ */
+export type GyroViewMessageOverrides = {
+	readonly [Table in keyof GyroViewMessages]?: Partial<GyroViewMessages[Table]>;
+};
+declare class Wording {
+	private words;
+	get current(): GyroViewMessages;
+	/**
+	 * The defaults with the page's own words in their place; `write` shows them.
+	 */
+	replace(overrides: unknown): void;
+	/**
+	 * Calls `element` by the label `name` names, now and after every change of words.
+	 */
+	label(element: Element, name: LabelName): void;
+	/**
+	 * Tells the visitor in `element` that the recording failed with `code`.
+	 */
+	showError(element: Element, code: GyroViewErrorCode): void;
+	/**
+	 * Fills in every word below `root` that its markup names.
+	 */
+	write(root: ParentNode): void;
+	private writeLabel;
+	private writeText;
+	private writeChoices;
+	private writeError;
+}
+interface ControlsHost {
+	readonly player: Player;
+	/**
+	 * The words the controls say, the page's where it gave its own.
+	 */
+	readonly wording: Wording;
+	/**
+	 * Plays or pauses; the element reports a refused start.
+	 */
+	togglePlay(): void;
+	toggleFullscreen(): void;
+	warn(warning: PlayerWarning): void;
+}
+interface KeyboardHost extends Pick<ControlsHost, "togglePlay" | "toggleFullscreen"> {
+	readonly player: Pick<Player, "currentTime" | "seek" | "stop" | "turn" | "zoom" | "resetView" | "isMuted" | "setMuted">;
+	readonly isFullscreen: () => boolean;
+	exitFullscreen(): void;
+}
+type PlaybackToggle = Pick<Player, "isPaused" | "pause" | "play" | "events">;
+export interface ViewGestureOptions {
+	/**
+	 * Hears a tap on the surface, a press without a drag, with the kind of pointer that made it
+	 * (`mouse`, `touch`, `pen`). By default a tap plays or pauses, as on `<gyro-view>`.
+	 */
+	readonly onTap?: (pointerType: string) => void;
+}
+export interface KeyboardOptions {
+	/**
+	 * What F does; by default the target fills the screen through the Fullscreen API, which
+	 * iPhone Safari offers to video elements only.
+	 */
+	readonly toggleFullscreen?: () => void;
+}
+/**
+ * The gestures `<gyro-view>` answers, for an interface of a page's own around the headless
+ * player: a drag looks around (or moves a zoomed picture), a pinch or a wheel turn zooms toward
+ * the fingers or the pointer, a tap plays or pauses. `surface` is the canvas or an element over
+ * it. Returns what removes them.
+ */
+export declare function attachViewGestures(surface: HTMLElement, player: Pick<Player, "pan" | "zoom" | "canPan"> & PlaybackToggle, options?: ViewGestureOptions): () => void;
+/**
+ * The keyboard shortcuts `<gyro-view>` answers, on `target`, which a page makes focusable: space
+ * or K play and pause, J and L seek, S stops, the arrows look around (with Shift they seek), plus
+ * and minus zoom, 0 resets the view, M mutes, F fills the screen and Escape leaves it. Returns
+ * what removes them.
+ */
+export declare function attachKeyboard(target: HTMLElement, player: KeyboardHost["player"] & PlaybackToggle, options?: KeyboardOptions): () => void;
+interface HttpRequestOptions {
+	/**
+	 * Extra request settings, for example credentials or headers. `Range` is set by the caller.
+	 * Requests bypass the browser's HTTP cache unless these settings choose another `cache` mode.
+	 */
+	readonly requestInit?: RequestInit;
+	readonly fetch?: typeof fetch;
+}
+export interface BrowserPortsOptions {
+	/**
+	 * Shared by every request the player makes for the recording and its other lens file.
+	 */
+	readonly http?: HttpRequestOptions;
+	/**
+	 * How long the decode probe may take before a lens is reported as timed out. Default 15 s,
+	 * generous because hardware decoders wake slowly.
+	 */
+	readonly probeTimeoutMs?: number;
+}
+/**
+ * A player composed for a browser: HTTP, blob and WebCodecs ports and the GPU pipeline, drawing
+ * on the host's canvas and sounding through its audio element. What `<gyro-view>` plays with,
+ * and where a page that wants the player without the element starts.
+ */
+export declare function createBrowserPlayer(host: PipelineHost, options?: BrowserPortsOptions): Player;
+export interface InspectOptions extends Pick<BrowserPortsOptions, "http"> {
+	/**
+	 * Abandons the requests for a URL; the inspection then rejects.
+	 */
+	readonly signal?: AbortSignal;
+}
+/**
+ * Reads what a recording's file holds without playing it (see `RecordingInspection`): from a URL,
+ * in byte ranges as playback reads it, or from a `Blob`, such as a `File` from a picker. Rejects
+ * with the `GyroViewError` a load would meet, for example `cors` or `invalid-trailer`.
+ */
+export declare function inspectRecording(recording: Blob | string, options?: InspectOptions): Promise<RecordingInspection>;
+/**
+ * Local files to play, from a picker or a drop.
+ */
+export interface FileSource {
+	readonly main: File;
+	readonly second?: File;
+}
+interface LiveSettings {
+	stabilization: StabilizationMode;
+	viewMode: ViewMode;
+	quality: PictureQuality;
+	fov: number;
+	yaw: number;
+	pitch: number;
+	muted: boolean;
+	loop: boolean;
+	volume: number;
+}
+/**
+ * The events `<gyro-view>` dispatches: each player event as a `CustomEvent` of the same name,
+ * its payload in `detail`. They take the place of the element events some share a name with
+ * (`play`, `pause`, `error`...), which a custom element never fires itself.
+ */
+export type GyroViewElementEventMap = Omit<HTMLElementEventMap, keyof PlayerEvents> & {
+	readonly [Name in keyof PlayerEvents]: CustomEvent<PlayerEvents[Name]>;
+};
+declare const ElementBase: typeof HTMLElement;
+declare class TypedEventElement extends ElementBase {
+	addEventListener<Name extends keyof GyroViewElementEventMap>(type: Name, listener: (this: this, event: GyroViewElementEventMap[Name]) => unknown, options?: boolean | AddEventListenerOptions): void;
+	addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+	removeEventListener<Name extends keyof GyroViewElementEventMap>(type: Name, listener: (this: this, event: GyroViewElementEventMap[Name]) => unknown, options?: boolean | EventListenerOptions): void;
+	removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+/**
+ * `<gyro-view>`: the player as an element. Attributes name what to play and configure the
+ * settings; the settings' properties report what is in effect now, as a media element's `muted`
+ * does; the player's events are dispatched as `CustomEvent`s of the same name with the payload
+ * in `detail`. Facade over {@link Player}, the controls and the gestures (ADR 0016).
+ */
+export declare class GyroViewElement extends TypedEventElement implements LiveSettings {
+	static readonly observedAttributes: readonly string[];
+	src: string | null;
+	src2: string | null;
+	poster: string | null;
+	preload: "none" | "auto";
+	gainMatch: "on" | "off";
+	autoplay: boolean;
+	controls: boolean;
+	stabilization: StabilizationMode;
+	viewMode: ViewMode;
+	quality: PictureQuality;
+	fov: number;
+	yaw: number;
+	pitch: number;
+	muted: boolean;
+	loop: boolean;
+	volume: number;
+	/**
+	 * Properties the page set before the element was defined, kept until it is connected.
+	 */
+	private readonly earlyProperties;
+	private readonly player;
+	private readonly loads;
+	private readonly wording;
+	private readonly fullscreen;
+	private readonly idle;
+	private readonly posterImage;
+	constructor();
+	/**
+	 * Where the player is: `idle` or `loading`, then the loaded recording's playback state.
+	 */
+	get status(): PlayerStatus;
+	/**
+	 * What the player learned about the loaded recording; undefined until it is ready.
+	 */
+	get metadata(): PlayerMetadata | undefined;
+	/**
+	 * The media time shown, in seconds; setting it seeks there exactly.
+	 */
+	get currentTime(): number;
+	set currentTime(time: number);
+	/**
+	 * The loaded recording's length in seconds; 0 without one.
+	 */
+	get duration(): number;
+	/**
+	 * True unless playback is under way or waiting for data to go on, as a media element's.
+	 */
+	get paused(): boolean;
+	/**
+	 * Where the normal view looks: yaw and pitch in degrees, and the horizontal field of view.
+	 */
+	get view(): ViewAngles;
+	/**
+	 * Every word the element shows or says to assistive technology. Setting it replaces any of
+	 * them, table by table (`labels`, `stabilizationModes`, `viewModes`, `errors`); the others keep
+	 * their English defaults, and `null` brings them all back.
+	 */
+	get messages(): GyroViewMessages;
+	set messages(overrides: GyroViewMessageOverrides | null | undefined);
+	connectedCallback(): void;
+	disconnectedCallback(): void;
+	attributeChangedCallback(name: string, _previous: string | null, value: string | null): void;
+	/**
+	 * Starts playing, waiting for a load in progress, or one the attributes set just now asked
+	 * for; rejects when the browser refuses to start.
+	 */
+	play(): Promise<void>;
+	/**
+	 * Pauses, keeping the frame on screen.
+	 */
+	pause(): void;
+	/**
+	 * Pauses and goes back to the start.
+	 */
+	stop(): void;
+	/**
+	 * Seeks exactly to `time` seconds; right after a new `src`, the new recording starts there.
+	 */
+	seek(time: number): void;
+	/**
+	 * Seeks to the key frame at or before `time`: quick to show while a seek bar is dragged.
+	 */
+	scrub(time: number): Promise<void>;
+	/**
+	 * Points the normal view at `yaw` and `pitch`, in degrees: yaw positive to the right, pitch
+	 * positive up.
+	 */
+	lookAt(yaw: number, pitch: number): void;
+	/**
+	 * Brings the current view mode back to how it starts, the others keeping their framing.
+	 */
+	resetView(): void;
+	/**
+	 * Zooms by `steps` (positive zooms in, each step by a factor of 1.1, within each view mode's
+	 * limits) toward `focus`, a point of the picture as fractions of its size; about the centre
+	 * when none is given.
+	 */
+	zoom(steps: number, focus?: ScreenPoint): void;
+	/**
+	 * Stabilizes the picture in `mode` (`off`, `lock`, `horizon`, `follow`); any other value,
+	 * an unset one included, is refused.
+	 */
+	setStabilization(mode: StabilizationMode): void;
+	/**
+	 * Shows the picture in `mode` (`raw-lenses`, `equirectangular`, `normal`); any other value,
+	 * an unset one included, is refused.
+	 */
+	setViewMode(mode: ViewMode): void;
+	/**
+	 * Reads the lens images as `quality` says (`fast`, `balanced`, `high`); any other value, an
+	 * unset one included, is refused.
+	 */
+	setQuality(quality: PictureQuality): void;
+	/**
+	 * Fills the screen with the player, through the Fullscreen API or pinned over the page, or
+	 * leaves it.
+	 */
+	toggleFullscreen(): Promise<void>;
+	/**
+	 * Loads what the attributes (or the files handed in) name: the change already waiting to be
+	 * read, or else now; out of the document, once connected. Resolves once the recording is
+	 * ready; rejects with the failure, which is dispatched as an `error` event too.
+	 */
+	load(): Promise<void>;
+	/**
+	 * Plays local files instead of the `src` attributes, until `src` or `src2` change.
+	 */
+	loadFiles(files: FileSource): void;
+	/**
+	 * What the controls and the keyboard ask of the element. They live as long as the element:
+	 * their listeners sit on its own shadow tree and host, and on its player.
+	 */
+	private controlsHost;
+	/**
+	 * A tap on the picture toggles playback, except a touch that brought hidden controls back:
+	 * touch has no hover to reveal them, so that tap is the viewer asking to see them. Without
+	 * controls there is nothing to reveal, and every tap toggles.
+	 */
+	private readonly onPictureTap;
+	/**
+	 * Pauses, or starts playing and reports a refused start as a warning.
+	 */
+	private readonly togglePlayback;
+	private readonly warn;
+}
+/**
+ * The attributes `<gyro-view>` takes, for a framework's JSX declaration of the element (React,
+ * Preact, Solid): each is optional, a number may be given as text, and a boolean attribute is
+ * set by `true`.
+ */
+export interface GyroViewAttributes {
+	readonly src?: string | undefined;
+	readonly src2?: string | undefined;
+	readonly poster?: string | undefined;
+	readonly preload?: "none" | "auto" | undefined;
+	readonly "gain-match"?: "on" | "off" | undefined;
+	readonly autoplay?: boolean | undefined;
+	readonly muted?: boolean | undefined;
+	readonly loop?: boolean | undefined;
+	readonly controls?: boolean | undefined;
+	readonly stabilization?: StabilizationMode | undefined;
+	readonly "view-mode"?: ViewMode | undefined;
+	readonly quality?: PictureQuality | undefined;
+	readonly fov?: number | string | undefined;
+	readonly yaw?: number | string | undefined;
+	readonly pitch?: number | string | undefined;
+}
+export declare const GYRO_VIEW_TAG = "gyro-view";
+declare global {
+	interface HTMLElementTagNameMap {
+		[GYRO_VIEW_TAG]: GyroViewElement;
+	}
+}
+/**
+ * Registers `<gyro-view>` once. A page that loads the package twice keeps the first definition,
+ * and hears once that another copy was there first, which may be another version. Without a
+ * custom element registry (a server rendering the page) there is nothing to register.
+ */
+export declare function defineGyroView(): void;
+
+export {};