@ericchen1990/pano-view 2.2.2 → 2.4.0

package/README.md

@@ -81,6 +81,7 @@ the stylesheet, the overlays still mount, but they render unstyled.
 - [`PanoVideo`](#panovideo) — 2:1 equirectangular video on the panorama sphere
 - [`Tile`](#tile) — krpano-style multires cube tiles
 - [`Scenes`](#scenes) — controlled multi-scene transitions
+- [`BackgroundAudio`](#backgroundaudio) — one shared track, or a different track per scene
 - [`PanoFilter`](#panofilter) — color and artistic filters on the panorama source
 
 ### Controls
@@ -104,6 +105,7 @@ the stylesheet, the overlays still mount, but they render unstyled.
 - [`GraphicHotspot`](#graphichotspot) — built-in shapes or SVG at a position
 - [`SequenceHotspot`](#sequencehotspot) — sprite-sheet animation
 - [`VideoHotspot`](#videohotspot) — HTML video texture
+- [`AudioHotspot`](#audiohotspot) — directional sound at a spherical position
 - [`TextHotspot`](#texthotspot) — rasterized plain text at a position
 - [`IframeHotspot`](#iframehotspot) — embedded document overlay at a position
 - [`PolygonHotspot`](#polygonhotspot) — closed spherical area
@@ -162,7 +164,242 @@ export function ControlledExample() {
 }
 ```
 
-The handle exposes `getView`, `setView`, `reset`, `startAutoRotate`, `stopAutoRotate`, and `toggleFullscreen`. Mouse, touch, and keyboard input are enabled by default — you do not need to render control components for ordinary viewing. Render `MouseControls`, `TouchControls`, or `KeyboardControls` only to override properties (the child replaces that channel's default instance). Tune shared behaviour through `controls` (`inertia`, `invert`, `bouncingLimits`, `fovSpeed`, `frictionStop`, `rotateDamping`, `zoomDamping`, and top-level `rotateSpeed` / `zoomSpeed`). Disable a channel with `controls.mouse` / `touch` / `keyboard` set to `false`, or pass an options object (including `enabled`) to override defaults without mounting a child. Auto-rotation is off until you render `AutoRotate`. The two auto-rotation handle methods remain supported for compatibility. A default context menu (Reset view / Enter fullscreen) is also mounted — see [`PanoContextMenu`](#panocontextmenu).
+The handle exposes view, fullscreen, scene, VR, video, and background-audio controls so custom UIs can drive the viewer from a single ref:
+
+**View** — `getView`, `setView`, `reset`.
+
+**Fullscreen** — `enterFullscreen`, `exitFullscreen`, `toggleFullscreen`, `isFullscreen`.
+
+**Scenes** (requires `<Scenes />`) — `setScene(id)`, `nextScene`, `previousScene`, `getActiveSceneId`, `getSceneIds`, `isSceneTransitioning`. `Scenes` now accepts an optional `defaultActiveSceneId` (uncontrolled) or keeps the existing `activeSceneId` (controlled). In controlled mode imperative calls invoke `onActiveSceneIdChange`.
+
+**WebVR** (requires `<WebVR />`) — `enterVR`, `exitVR`, `toggleVR`, `isVRAvailable`, `isVREnabled`, `getVRMode`, `requestVRPermission`.
+
+**Video** (requires `<PanoVideo />`) — `getVideo` returns the `PanoVideoController`, `subscribeVideo` subscribes to host changes, plus convenience aliases `playVideo`, `pauseVideo`, `toggleVideo`, `seekVideo`, `setVideoVolume`, `setVideoMuted`, `toggleVideoMuted`.
+
+**Background Audio** (requires `<BackgroundAudio />`) — `getBackgroundAudio` returns the `BackgroundAudioController`, `subscribeBackgroundAudio` subscribes to host changes, plus convenience aliases `playBackgroundAudio`, `pauseBackgroundAudio`, `toggleBackgroundAudio`, `setBackgroundAudioVolume`, `setBackgroundAudioMuted`, `toggleBackgroundAudioMuted`. `BackgroundAudio` now accepts an optional `playing` prop (controlled) or uses `defaultPlaying` (uncontrolled).
+
+Methods that depend on an unmounted child component (e.g. `enterVR` without `<WebVR />`) are safe no-ops — they return `false`, `void`, or `null`.
+
+### Fullscreen
+
+```tsx
+import { useRef } from "react";
+import { PanoViewer, Sphere, type PanoViewerHandle } from "@ericchen1990/pano-view";
+
+function FullscreenExample() {
+  const ref = useRef<PanoViewerHandle>(null);
+
+  return (
+    <>
+      <button onClick={() => void ref.current?.enterFullscreen()}>Enter fullscreen</button>
+      <button onClick={() => void ref.current?.exitFullscreen()}>Exit fullscreen</button>
+      <button onClick={() => console.log(ref.current?.isFullscreen())}>Is fullscreen?</button>
+      <PanoViewer ref={ref} style={{ height: 560 }}>
+        <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
+      </PanoViewer>
+    </>
+  );
+}
+```
+
+### Imperative scene switching
+
+Use `defaultActiveSceneId` for uncontrolled mode — imperative calls update the internal state directly. For controlled mode keep passing `activeSceneId`; imperative calls invoke `onActiveSceneIdChange` so the parent can update its state.
+
+```tsx
+import { useRef } from "react";
+import {
+  PanoViewer,
+  Scenes,
+  type PanoViewerHandle,
+  type Scene,
+} from "@ericchen1990/pano-view";
+
+const scenes: Scene[] = [
+  { id: "lobby", type: "sphere", src: "/lobby.webp", previewUrl: "/lobby-preview.webp" },
+  { id: "roof",  type: "sphere", src: "/roof.webp",  previewUrl: "/roof-preview.webp" },
+];
+
+function SceneExample() {
+  const ref = useRef<PanoViewerHandle>(null);
+
+  return (
+    <>
+      <button onClick={() => ref.current?.setScene("roof")}>Go to roof</button>
+      <button onClick={() => ref.current?.nextScene()}>Next</button>
+      <button onClick={() => ref.current?.previousScene()}>Previous</button>
+      <p>Current: {ref.current?.getActiveSceneId()}</p>
+      <PanoViewer ref={ref} style={{ height: 560 }}>
+        <Scenes defaultActiveSceneId="lobby" scenes={scenes} transition="dissolve" />
+      </PanoViewer>
+    </>
+  );
+}
+```
+
+### WebVR
+
+`enterVR` and `requestVRPermission` must be called from a user gesture.
+
+```tsx
+import { useRef } from "react";
+import { PanoViewer, Sphere, WebVR, type PanoViewerHandle } from "@ericchen1990/pano-view";
+
+function VRExample() {
+  const ref = useRef<PanoViewerHandle>(null);
+
+  return (
+    <>
+      <button
+        onClick={async () => {
+          await ref.current?.requestVRPermission();
+          await ref.current?.enterVR();
+        }}
+      >
+        Enter VR
+      </button>
+      <button onClick={() => void ref.current?.exitVR()}>Exit VR</button>
+      <button onClick={() => console.log(ref.current?.getVRMode())}>Mode?</button>
+      <PanoViewer ref={ref} style={{ height: 560 }}>
+        <WebVR />
+        <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
+      </PanoViewer>
+    </>
+  );
+}
+```
+
+### Custom video controls
+
+Set `controls={false}` on `PanoVideo` and drive playback from the viewer ref. Use `subscribeVideo` with `useSyncExternalStore` for reactive snapshots.
+
+```tsx
+import { useRef, useSyncExternalStore } from "react";
+import {
+  PanoViewer,
+  PanoVideo,
+  type PanoViewerHandle,
+} from "@ericchen1990/pano-view";
+
+function VideoExample() {
+  const ref = useRef<PanoViewerHandle>(null);
+
+  const snapshot = useSyncExternalStore(
+    (cb) => ref.current?.subscribeVideo(cb) ?? (() => {}),
+    () => ref.current?.getVideo()?.getSnapshot() ?? null,
+    () => null,
+  );
+
+  return (
+    <>
+      <button onClick={() => void ref.current?.toggleVideo()}>
+        {snapshot?.playing ? "Pause" : "Play"}
+      </button>
+      <button onClick={() => ref.current?.toggleVideoMuted()}>
+        {snapshot?.muted ? "Unmute" : "Mute"}
+      </button>
+      {snapshot && (
+        <input
+          type="range"
+          min={0}
+          max={snapshot.duration}
+          value={snapshot.currentTime}
+          onChange={(e) => ref.current?.seekVideo(Number(e.target.value))}
+        />
+      )}
+      <PanoViewer ref={ref} style={{ height: 560 }}>
+        <PanoVideo controls={false} src="/tour.mp4" />
+      </PanoViewer>
+    </>
+  );
+}
+```
+
+### Custom background audio controls
+
+`BackgroundAudio` supports uncontrolled mode — omit `playing` and use `defaultPlaying` instead. Drive it from the viewer ref.
+
+```tsx
+import { useRef, useSyncExternalStore } from "react";
+import {
+  PanoViewer,
+  Sphere,
+  BackgroundAudio,
+  type PanoViewerHandle,
+} from "@ericchen1990/pano-view";
+
+function BGMExample() {
+  const ref = useRef<PanoViewerHandle>(null);
+
+  const snapshot = useSyncExternalStore(
+    (cb) => ref.current?.subscribeBackgroundAudio(cb) ?? (() => {}),
+    () => ref.current?.getBackgroundAudio()?.getSnapshot() ?? null,
+    () => null,
+  );
+
+  return (
+    <>
+      <button onClick={() => ref.current?.toggleBackgroundAudio()}>
+        {snapshot?.playing ? "Pause BGM" : "Play BGM"}
+      </button>
+      <button onClick={() => ref.current?.toggleBackgroundAudioMuted()}>
+        {snapshot?.muted ? "Unmute" : "Mute"}
+      </button>
+      <input
+        type="range"
+        min={0}
+        max={1}
+        step={0.01}
+        value={snapshot?.volume ?? 1}
+        onChange={(e) =>
+          ref.current?.setBackgroundAudioVolume(Number(e.target.value))
+        }
+      />
+      <PanoViewer ref={ref} style={{ height: 560 }}>
+        <BackgroundAudio defaultPlaying src="/bgm.mp3" />
+        <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
+      </PanoViewer>
+    </>
+  );
+}
+```
+
+### All-in-one example
+
+```tsx
+import { useRef } from "react";
+import {
+  PanoViewer,
+  Scenes,
+  WebVR,
+  PanoVideo,
+  BackgroundAudio,
+  type PanoViewerHandle,
+} from "@ericchen1990/pano-view";
+
+function TourPlayer() {
+  const ref = useRef<PanoViewerHandle>(null);
+
+  return (
+    <>
+      <nav>
+        <button onClick={() => ref.current?.previousScene()}>← Prev</button>
+        <button onClick={() => ref.current?.nextScene()}>Next →</button>
+        <button onClick={() => void ref.current?.toggleFullscreen()}>Fullscreen</button>
+        <button onClick={() => void ref.current?.enterVR()}>Enter VR</button>
+        <button onClick={() => ref.current?.toggleBackgroundAudio()}>BGM</button>
+      </nav>
+      <PanoViewer ref={ref} style={{ height: "100vh" }}>
+        <WebVR />
+        <BackgroundAudio defaultPlaying src="/bgm.mp3" />
+        <Scenes defaultActiveSceneId="lobby" scenes={scenes} transition="dissolve" />
+      </PanoViewer>
+    </>
+  );
+}
+```
+
+The two deprecated auto-rotation handle methods (`startAutoRotate`, `stopAutoRotate`) remain for compatibility. Mouse, touch, and keyboard input are enabled by default — you do not need to render control components for ordinary viewing. Render `MouseControls`, `TouchControls`, or `KeyboardControls` only to override properties (the child replaces that channel's default instance). Tune shared behaviour through `controls` (`inertia`, `invert`, `bouncingLimits`, `fovSpeed`, `frictionStop`, `rotateDamping`, `zoomDamping`, and top-level `rotateSpeed` / `zoomSpeed`). Disable a channel with `controls.mouse` / `touch` / `keyboard` set to `false`, or pass an options object (including `enabled`) to override defaults without mounting a child. Auto-rotation is off until you render `AutoRotate`. A default context menu (Reset view / Enter fullscreen) is also mounted — see [`PanoContextMenu`](#panocontextmenu).
 
 Drag and zoom update a target view that the camera follows smoothly. `rotateDamping` and `zoomDamping` control that following speed in seconds^-1 (defaults: `14` and `16` respectively); lower values feel softer, while `0` disables smoothing for that axis. Both values must be non-negative finite numbers. Imperative `setView()` and `reset()` remain immediate.
 
@@ -500,6 +737,71 @@ Auto-rotation is off by default. Render `AutoRotate` inside `PanoViewer` to enab
 </PanoViewer>
 ```
 
+## BackgroundAudio
+
+`BackgroundAudio` plays background music or ambience for the viewer. It is not
+a hotspot: there is no spherical position, no marker, and volume does not
+follow the camera. Render it as a child of `PanoViewer`, **alongside** `Scenes`,
+`Sphere`, or `Tile`. Do not put it in `Scenes`' `renderHotspots` — hotspots
+unmount during scene transitions and would stop the audio.
+
+`playing` is controlled by the host; the component does not change it. `loop`
+defaults to `true`. Browsers may block autoplay; `onPlaybackStateChange` then
+receives `"blocked"`, and the component retries `play()` after the next click
+or keypress while `playing` remains true.
+
+Pick one of the two patterns.
+
+**One track for every scene** — pass `src` only; omit `sources`. Scene changes
+do not restart the audio.
+
+```tsx
+import { BackgroundAudio, PanoViewer, Scenes } from "@ericchen1990/pano-view";
+
+<PanoViewer style={{ height: 560 }}>
+  <BackgroundAudio src="/bgm/tour.mp3" playing={isBgmPlaying} />
+  <Scenes scenes={scenes} activeSceneId={activeSceneId} />
+</PanoViewer>;
+```
+
+**A different track per scene** — pass `sources` (keys are `Scene.id`) and the
+current `sceneId`. Omitting `sceneId` throws. When the file changes, playback
+crossfades over `fadeMs` (default 400 ms; `0` is a hard cut). When two scenes
+point at the same file, playback continues without restarting.
+
+```tsx
+<PanoViewer style={{ height: 560 }}>
+  <BackgroundAudio
+    sources={{
+      lobby: "/bgm/lobby.mp3",
+      terrace: "/bgm/terrace.mp3",
+    }}
+    sceneId={activeSceneId}
+    playing={isBgmPlaying}
+  />
+  <Scenes scenes={scenes} activeSceneId={activeSceneId} />
+</PanoViewer>;
+```
+
+Optional: also pass `src` as the default for scenes missing from `sources`. To
+silence a scene, set that id to `""` (this overrides `src`; it does not fall
+back to the default track).
+
+```tsx
+<BackgroundAudio
+  src="/bgm/default.mp3"
+  sources={{ lobby: "/bgm/courtyard.mp3", terrace: "" }}
+  sceneId={activeSceneId}
+  playing={isBgmPlaying}
+/>;
+```
+
+In that example, `lobby` plays the courtyard clip, `terrace` is silent, and
+every other scene plays `default.mp3`.
+
+For a sound attached to a point in the panorama that pans with the view, use
+`AudioHotspot`, not `BackgroundAudio`.
+
 ## Gyro
 
 `Gyro` is an opt-in device-orientation control and is disabled by default.
@@ -996,8 +1298,8 @@ color, border, corner radius, shadow, padding, and font size.
 
 For persistence or a host-owned editor, use the exported discriminated
 `HotspotDefinition` union. Adding a variant is a TypeScript breaking change for
-exhaustive switches; handle `text` and `iframe` alongside the existing point
-and path categories:
+exhaustive switches; handle `audio` alongside the existing point and path
+categories:
 
 ```ts
 import type { HotspotDefinition } from "@ericchen1990/pano-view";
@@ -1007,6 +1309,7 @@ const hotspots: HotspotDefinition[] = [
   { type: "graphic", id: "marker", position: { yaw: -18, pitch: 9 }, graphic: { kind: "ring" } },
   { type: "sequence", id: "pulse", position: { yaw: -42, pitch: -7 }, src: "/hotspots/pulse.png", frameCount: 20 },
   { type: "video", id: "clip", position: { yaw: 48, pitch: 6 }, src: "/hotspots/clip.webm" },
+  { type: "audio", id: "fountain", position: { yaw: -30, pitch: -8 }, src: "/hotspots/fountain.mp3", range: 90 },
   { type: "text", id: "caption", position: { yaw: 0, pitch: -16 }, text: "Courtyard overlook" },
   { type: "iframe", id: "guide", position: { yaw: -62, pitch: 4 }, src: "/hotspots/embed.html" },
   { type: "polygon", id: "zone", vertices: [{ yaw: 12, pitch: 4 }, { yaw: 22, pitch: 4 }, { yaw: 18, pitch: 14 }] },
@@ -1281,6 +1584,55 @@ Video reports media and poster failures through `onError`. Like
 `SequenceHotspot`, it does not change `playing` by itself. This keeps source
 changes, unmounts, and React StrictMode lifecycles deterministic.
 
+## AudioHotspot
+
+`AudioHotspot` plays a directional sound at a spherical position. Stereo
+panning follows the camera look direction; `range` is the look-away angle in
+degrees at which volume reaches silence. The default `360` disables look
+attenuation (stereo pan only). Use a smaller `range` such as `90` for a
+spot source.
+
+Playback uses Web Audio via Howler.js (bundled; hosts do not install
+`howler`). The file must decode before play starts — MP3 is the recommended
+format. `src` may be a string or an array of fallback URLs. Do not use HTML5
+streaming (`html5`); it drops stereo panning.
+
+`playing` is controlled like `VideoHotspot`. `loop` defaults to `false`,
+`muted` to `false`, `volume` to `1`, and `pauseWhenHidden` to `true` (pause
+when the tab is hidden, resume if `playing` is still true). A first user
+gesture unlocks audio; if autoplay is blocked, the hotspot reports
+`"blocked"` and retries `play()` after the next pointer or key event while
+`playing` remains true.
+
+The default marker switches between a built-in **stopped** icon (speaker)
+and a **playing** icon (speaker plus sound waves). Pass `icon`
+for a custom stopped image and `playingIcon` for a custom playing image.
+If only `icon` is set, it is used for both states. `marker={false}` hides
+the visual for an invisible positional source. For a
+non-spatial tour or per-scene soundtrack, use [`BackgroundAudio`](#backgroundaudio).
+
+```tsx
+import { AudioHotspot } from "@ericchen1990/pano-view";
+
+<AudioHotspot
+  id="fountain"
+  ariaLabel="Fountain"
+  position={{ yaw: -30, pitch: -8 }}
+  src="/hotspots/fountain.mp3"
+  playing={isFountainPlaying}
+  loop
+  volume={0.8}
+  range={90}
+  onClick={() => setFountainPlaying((playing) => !playing)}
+  onEnded={() => setFountainPlaying(false)}
+  onPlaybackStateChange={(state) => console.log(state)}
+  onPlaybackError={(error) => console.error(error)}
+/>;
+```
+
+Like the other media hotspots, `AudioHotspot` does not change `playing` by
+itself.
+
 ## TextHotspot
 
 `TextHotspot` rasterizes plain text onto a canvas texture. It does not accept