@bvdmitri/gyroview 0.0.0-stage → 0.9.0-cutaway.2

package/dist/index.d.ts

@@ -0,0 +1,1204 @@
+/**
+ * A page's own way of sending the player's requests for a recording, in place of the platform's
+ * `fetch`: to add a header the server asks for, such as `Authorization` with a token read afresh
+ * for each request, or to sign each request. `window.fetch` itself fits.
+ *
+ * It is called on its own (without `this`), for HEAD and for byte-range GET requests, with the
+ * URL as a string and `init` holding `method`, `headers` (a plain object with `Range`), `cache`,
+ * the `signal` that ends the request when there is one, and `credentials` when `crossorigin`
+ * sets them. It must pass `init` on as given, adding only its own headers: without
+ * `cache: 'no-store'` browsers may answer a range from a cache entry they hold half of (ADR
+ * 0013), and without the signal a recording given up goes on downloading. It must resolve to the
+ * server's `Response` itself, whose status, type and headers the player reads. After a request
+ * fails, it may be called once more with `mode: 'no-cors'`, only to learn whether the server is
+ * reachable; browsers send no `Authorization` header with such a request.
+ */
+export type RecordingFetch = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * A recording reachable over HTTP with Range support (see README, "Serving recordings").
+ */
+export interface UrlInput {
+	readonly url: string;
+	/**
+	 * Whether every request for the recording carries the visitor's cookies, in fetch's terms:
+	 * `include` sends them to any origin, which must then allow the page's origin by name and
+	 * with `Access-Control-Allow-Credentials: true`. Unset, the player's shared request settings
+	 * decide, and fetch's `same-origin` when they do not. The element's
+	 * `crossorigin="use-credentials"` sets `include`.
+	 */
+	readonly credentials?: RequestCredentials | undefined;
+	/**
+	 * Sends every request for the recording, its other lens's file included, in place of the
+	 * platform's `fetch` and of a `fetch` the player's shared request settings name. The element's
+	 * `fetch` property sets it.
+	 */
+	readonly fetch?: RecordingFetch | undefined;
+}
+/**
+ * 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;
+	readonly ExtendedMei: 6;
+};
+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;
+	readonly offsetV6: 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;
+	/**
+	 * Slots the camera left all zero, as it leaves the first ones it never wrote; no damage.
+	 */
+	readonly unwrittenSamples: 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;
+}
+declare const COLOUR_PRIMARIES: readonly [
+	"bt709",
+	"bt470bg",
+	"smpte170m",
+	"bt2020",
+	"smpte432"
+];
+declare const TRANSFER_CHARACTERISTICS: readonly [
+	"bt709",
+	"smpte170m",
+	"iec61966-2-1",
+	"linear",
+	"pq",
+	"hlg"
+];
+declare const MATRIX_COEFFICIENTS: readonly [
+	"rgb",
+	"bt709",
+	"bt470bg",
+	"smpte170m",
+	"bt2020-ncl"
+];
+type Unspecified = "unspecified";
+export type ColourPrimaries = (typeof COLOUR_PRIMARIES)[number] | Unspecified;
+export type TransferCharacteristics = (typeof TRANSFER_CHARACTERISTICS)[number] | Unspecified;
+export type MatrixCoefficients = (typeof MATRIX_COEFFICIENTS)[number] | Unspecified;
+export type ColourRange = "full" | "limited" | Unspecified;
+export interface TrackColour {
+	readonly primaries: ColourPrimaries;
+	readonly transfer: TransferCharacteristics;
+	readonly matrix: MatrixCoefficients;
+	readonly range: ColourRange;
+}
+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;
+	readonly colour: TrackColour;
+}
+export declare const STABILIZATION_MODES: readonly [
+	"off",
+	"lock",
+	"horizon",
+	"follow"
+];
+export type StabilizationMode = (typeof STABILIZATION_MODES)[number];
+/**
+ * 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 codes. 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",
+	"embed-unreachable",
+	"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",
+	"no-source",
+	"play-interrupted",
+	"playback-blocked",
+	"range-unsupported",
+	"render-unavailable",
+	"source-changed",
+	"source-truncated",
+	"source-unreadable",
+	"unsupported-calibration",
+	"unsupported-container",
+	"unsupported-gyro-record",
+	"unsupported-info-format",
+	"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;
+type Listener<Payload> = (payload: Payload) => void;
+interface Listenable<Events extends object> {
+	on<Name extends keyof Events>(name: Name, listener: Listener<Events[Name]>): () => 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.
+ */
+/**
+ * Where the player draws and sounds. The canvas is read at each load and each measure, so a host
+ * may hand a fresh one between loads, as the element does for one whose WebGL context is gone.
+ */
+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, motion look, 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. A
+ * recording is `seeking` from a seek until the picture there is drawn.
+ */
+export type PlayerStatus = "idle" | "loading" | PlayerState;
+/**
+ * Motion look as it stands: `unavailable` where the device reports no attitude or access was
+ * refused, `off`, or `on`, the device turning the normal view (ADR 0040).
+ */
+export type MotionLookState = "unavailable" | "off" | "on";
+/**
+ * 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) 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.
+ * - `motion-look-refused`: the viewer, or an iframe's `allow`, refused access to the device's
+ *   attitude; motion look is unavailable.
+ * - `motion-look-needs-gesture`: motion look was started outside a user gesture, where iOS does
+ *   not ask; it stays off.
+ */
+export type WarningCode = "recording-degraded" | "no-sound" | "autoplay-blocked" | "playback-failed" | "ignored-attribute" | "refused-property" | "motion-look-refused" | "motion-look-needs-gesture";
+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 motionlookchange: MotionLookState;
+	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, motion look, stabilization, gain matching, sound, loop) from
+ * load to load. `<gyro-view>` is a facade over it.
+ */
+export declare class Player {
+	private readonly parts;
+	/**
+	 * What the player announces, to listen to: only the player and its parts emit.
+	 */
+	readonly events: Listenable<PlayerEvents>;
+	private readonly emitter;
+	/**
+	 * What the player and its parts announce, heard once each change is whole (ADR 0021).
+	 */
+	private readonly outbox;
+	private readonly statuses;
+	private readonly loop;
+	private phase;
+	private readonly viewing;
+	private readonly motion;
+	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 readonly starts;
+	/**
+	 * Whether the recording plays again from the start at its end; kept across loads.
+	 */
+	private shouldLoop;
+	/**
+	 * Past `dispose`: a listener of the idle it announces must not load again.
+	 */
+	private isDisposed;
+	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;
+	/**
+	 * Whether turning the device turns the normal view: `unavailable` where the device reports no
+	 * attitude or access was refused.
+	 */
+	get motionLook(): MotionLookState;
+	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, `autoplay` starting it
+	 * then, a refusal a warning; 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, and resolves once it runs, as a media
+	 * element's `play()` does. Rejects with the load's failure, with `playback-blocked` when the
+	 * browser wants a user gesture first, with `no-source` when nothing is loaded or loading, and
+	 * with `play-interrupted` when a newer load or `unload` replaced the load it waited for.
+	 */
+	play(): Promise<void>;
+	pause(): void;
+	/**
+	 * Pauses, or starts playing and reports a refused start as a `warning`: what a tap on the
+	 * picture or a play button does.
+	 */
+	togglePlayback(): 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;
+	/**
+	 * 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(): Promise<MotionLookState>;
+	/**
+	 * Gives the view back to the pointer, level, looking where it looked.
+	 */
+	stopMotionLook(): 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;
+	private get loaded();
+	private complete;
+	private startAtPendingTime;
+	private attach;
+	/**
+	 * Lets go of whatever is loading or loaded, announcing nothing.
+	 */
+	private release;
+	private failWith;
+}
+/**
+ * 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 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;
+	/**
+	 * The toggle that lets the device's own turns turn the normal view.
+	 */
+	readonly motionLook: string;
+	readonly stabilization: string;
+	readonly viewMode: string;
+	readonly fullscreen: string;
+	/**
+	 * The button that closes a menu shown over the whole player, as it is on a narrow one.
+	 */
+	readonly close: 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>>;
+	/**
+	 * One line under each choice of the Stabilization menu, where there is room for it.
+	 */
+	readonly stabilizationModeDescriptions: Readonly<Record<StabilizationMode, string>>;
+	readonly viewModes: Readonly<Record<ViewMode, string>>;
+	/**
+	 * One line under each choice of the View menu, where there is room for it.
+	 */
+	readonly viewModeDescriptions: 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 writeChoiceText;
+	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;
+	/**
+	 * Whether the element fills the screen, through the Fullscreen API or pinned over the page.
+	 */
+	isFullscreen(): boolean;
+	warn(warning: PlayerWarning): void;
+}
+interface KeyboardHost extends Pick<ControlsHost, "togglePlay" | "toggleFullscreen" | "isFullscreen"> {
+	readonly player: Pick<Player, "currentTime" | "seek" | "stop" | "turn" | "zoom" | "resetView" | "isMuted" | "setMuted">;
+	exitFullscreen(): void;
+}
+type PlaybackToggle = Pick<Player, "togglePlayback">;
+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;
+type HttpFetch = (url: string, init: RequestInit) => Promise<Response>;
+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?: HttpFetch;
+}
+export interface BrowserPortsOptions {
+	/**
+	 * Shared by every request the player makes for the recording and its other lens file. A
+	 * recording's own `credentials` and `fetch` (`UrlInput`) take the place of theirs.
+	 */
+	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, the GPU pipeline and the
+ * device's attitude, 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>;
+export interface RenditionOptions extends Pick<BrowserPortsOptions, "http"> {
+	/**
+	 * How many pixels across the equirectangular picture is; half as many down. A multiple of
+	 * four, so that both sides are even as encoders take them.
+	 */
+	readonly width: number;
+	/**
+	 * Where the rendition starts, in the recording's seconds; its start by default.
+	 */
+	readonly from?: number;
+	/**
+	 * Where it ends, not included; the recording's end by default, and at most.
+	 */
+	readonly to?: number;
+	/**
+	 * The player's own settings by default: its default stabilization, exposure matched along
+	 * the seam, its default quality.
+	 */
+	readonly stabilization?: StabilizationMode;
+	readonly gainMatching?: boolean;
+	readonly quality?: PictureQuality;
+	/**
+	 * Where the picture is drawn; an `OffscreenCanvas` of the rendition's own if none.
+	 */
+	readonly canvas?: HTMLCanvasElement | OffscreenCanvas;
+	/**
+	 * Stops the opening, or the rendering, as `dispose` does.
+	 */
+	readonly signal?: AbortSignal;
+}
+/**
+ * A recording rendered frame by frame into stitched, stabilized equirectangular pictures, for an
+ * encoder to take (ADR 0045). Unlike the player, it follows no clock: it draws every frame of the
+ * span exactly once, in order, when the consumer asks for the next, so a slow encoder loses
+ * nothing and a fast one waits only for the decoder. Works in a dedicated worker.
+ *
+ * @example
+ * ```ts
+ * const rendition = await openRendition({ main: { blob: file, name: file.name } }, { width: 3840 });
+ * for await (const frame of rendition.frames()) {
+ *   await videoSource.add(new VideoSample(frame)); // a Mediabunny VideoSampleSource
+ *   frame.close();
+ * }
+ * ```
+ */
+export interface Rendition {
+	readonly metadata: PlayerMetadata;
+	readonly width: number;
+	readonly height: number;
+	/**
+	 * Of the span rendered, in seconds.
+	 */
+	readonly duration: number;
+	/**
+	 * One `VideoFrame` per frame of the span, its timestamp in microseconds from the span's start,
+	 * which the consumer closes. Iterated once; leaving the loop early stops the rendering.
+	 */
+	frames(): AsyncGenerator<VideoFrame, void, undefined>;
+	/**
+	 * Stops the rendering and lets go of the recording.
+	 */
+	dispose(): void;
+}
+/**
+ * Opens a recording, as the player would, to render it frame by frame (see {@link Rendition}).
+ * Rejects with the `GyroViewError` a load would meet, and with `invalid-argument` for a width or
+ * span that holds no picture.
+ */
+export declare function openRendition(source: PlayerSource, options: RenditionOptions): Promise<Rendition>;
+/**
+ * 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;
+	crossOrigin: "anonymous" | "use-credentials" | 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;
+	/**
+	 * How the recording's requests are sent: `null`, the default, for the platform's `fetch`, or a
+	 * page's function in its place (`RecordingFetch`), to add a header such as `Authorization` or
+	 * to sign each request. Set from script only; there is no attribute. Like `crossorigin`, a
+	 * change loads a recording named by URL again, and local files play on; the same function set
+	 * again changes nothing, so a framework may set it on every render. A function that reads its
+	 * token afresh for each request goes on playing when the token is renewed.
+	 */
+	fetch: RecordingFetch | null;
+	/**
+	 * 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 controlsBar;
+	private readonly fullscreen;
+	private readonly idle;
+	private readonly posterImage;
+	private readonly canvas;
+	private gestures;
+	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;
+	/**
+	 * Whether turning the device turns the normal view: `on`, `off`, or `unavailable` where the
+	 * device reports no attitude or access was refused.
+	 */
+	get motionLook(): MotionLookState;
+	/**
+	 * 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, one the attributes set just now asked for,
+	 * or, out of the document, the connection; resolves once playback runs. Rejects when the
+	 * browser refuses to start, with `no-source` without a recording, and with `play-interrupted`
+	 * when the element left the document or its recording was replaced first.
+	 */
+	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;
+	/**
+	 * Lets the device turn the normal view, as a window into the recording. 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 (`motionLook`); a refusal is a `warning`, never a rejection.
+	 */
+	startMotionLook(): Promise<MotionLookState>;
+	/**
+	 * Gives the view back to the pointer, level, looking where it looked.
+	 */
+	stopMotionLook(): 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;
+	/**
+	 * A move within the document disconnects and connects again at once: only an element still out
+	 * of it a microtask later was removed. It lets its recording go, and leaves the pinned fill as
+	 * the browser's fullscreen element leaves fullscreen.
+	 */
+	private leaveIfRemoved;
+	/**
+	 * The canvas is read at each load, since a fresh one replaces one whose context is gone.
+	 */
+	private pipelineHost;
+	private readonly onCanvasReplaced;
+	/**
+	 * 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;
+	private readonly togglePlayback;
+	/**
+	 * Queued, as a media element queues its events: an attribute in the markup is read as the
+	 * element is defined, and a property before it, both before a page's script after the
+	 * definition adds its listener.
+	 */
+	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 crossorigin?: "anonymous" | "use-credentials" | "" | 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 {};