@ericchen1990/pano-view 2.2.2 → 2.3.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
@@ -500,6 +502,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 +1063,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 +1074,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 +1349,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

package/README.zh-CN.md

@@ -64,6 +64,7 @@ import "@ericchen1990/pano-view/styles.css";
 - [`PanoVideo`](#panovideo) — 全景球面上的 2:1 等距圆柱视频
 - [`Tile`](#tile) — krpano 风格多分辨率立方体 tile
 - [`Scenes`](#scenes) — 受控多场景过渡
+- [`BackgroundAudio`](#backgroundaudio) — 全部场景共用、或按场景切换的背景声
 - [`PanoFilter`](#panofilter) — 对全景源应用色彩与艺术滤镜
 
 ### 控件
@@ -87,6 +88,7 @@ import "@ericchen1990/pano-view/styles.css";
 - [`GraphicHotspot`](#graphichotspot) — 内置形状或 SVG
 - [`SequenceHotspot`](#sequencehotspot) — 精灵图动画
 - [`VideoHotspot`](#videohotspot) — HTML 视频纹理
+- [`AudioHotspot`](#audiohotspot) — 球面位置上的定向声源
 - [`TextHotspot`](#texthotspot) — 球面位置上的栅格化纯文本
 - [`IframeHotspot`](#iframehotspot) — 球面位置上的嵌入文档叠加层
 - [`PolygonHotspot`](#polygonhotspot) — 闭合球面区域
@@ -418,6 +420,56 @@ const scenes: Scene[] = [
 </PanoViewer>
 ```
 
+## BackgroundAudio
+
+`BackgroundAudio` 在查看器里播放背景音乐或环境声。它不是热点：没有球面位置、没有标记、音量也不随视角变化。必须作为 `PanoViewer` 的子组件，与 `Scenes`、`Sphere` 或 `Tile` **并列**。不要写进 `Scenes` 的 `renderHotspots`：场景过渡时热点会卸载，背景声也会被停掉。
+
+`playing` 由宿主控制，组件不会自行改这个值。`loop` 默认 `true`。浏览器可能拦住自动播放；此时 `onPlaybackStateChange` 收到 `"blocked"`，在 `playing` 仍为 true 时会于下一次点击或按键后重试。
+
+有两种用法，选一种即可。
+
+**全部场景共用一条音轨** — 只传 `src`，不要传 `sources`。切换场景时音频继续播放，不会重头开始。
+
+```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>;
+```
+
+**每个场景一条音轨** — 传 `sources`（键为 `Scene.id`）和当前的 `sceneId`。省略 `sceneId` 会抛错。切换场景时，若文件变了会按 `fadeMs` 交叉淡化（默认 400 毫秒；`0` 为硬切）；若两个场景指向同一文件则继续播，不会重启。
+
+```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>;
+```
+
+可选：同时传 `src` 作为未列出场景的默认音轨。某个场景要静音时，把该 id 写成 `""`（会覆盖 `src`，而不是回退到默认轨）。
+
+```tsx
+<BackgroundAudio
+  src="/bgm/default.mp3"
+  sources={{ lobby: "/bgm/courtyard.mp3", terrace: "" }}
+  sceneId={activeSceneId}
+  playing={isBgmPlaying}
+/>;
+```
+
+上例中：`lobby` 播院子声，`terrace` 静音，其它场景播 `default.mp3`。
+
+需要绑在全景某一点、随视角左右移动的声音，请用 `AudioHotspot`，不要用 `BackgroundAudio`。
+
 ## Gyro
 
 `Gyro` 为可选的设备方向控制，默认关闭。在 `PanoViewer` 内渲染并通过 `enabled` 控制。相对模式（默认）将启用时的视图作为起始方向。设 `absolute` 可跟随罗盘朝向，用 `north` 指定指向北方的全景 yaw。
@@ -818,7 +870,7 @@ import {
 />
 ```
 
-持久化或宿主编辑器可使用导出的判别联合类型 `HotspotDefinition`。新增变体会破坏 exhaustive switch 的类型兼容；除现有点与路径类别外，还需处理 `text` 与 `iframe`：
+持久化或宿主编辑器可使用导出的判别联合类型 `HotspotDefinition`。新增变体会破坏 exhaustive switch 的类型兼容；除现有点与路径类别外，还需处理 `audio`：
 
 ```ts
 import type { HotspotDefinition } from "@ericchen1990/pano-view";
@@ -828,6 +880,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 }] },
@@ -1047,6 +1100,37 @@ import { VideoHotspot } from "@ericchen1990/pano-view";
 
 视频通过 `onError` 报告媒体与 poster 失败。与 `SequenceHotspot` 相同，不会自行改变 `playing`，以保证源变更、卸载与 React StrictMode 生命周期可预测。
 
+## AudioHotspot
+
+`AudioHotspot` 在球面位置播放定向声音。立体声像跟随相机朝向；`range` 为看离声源多少度后音量降到静音。默认 `360` 表示不因视角衰减（仅左右声像）。定点声源可使用较小值，例如 `90`。
+
+播放走 Howler.js 的 Web Audio（已打进本包，宿主不必安装 `howler`）。文件需先解码再起播，推荐 MP3。`src` 可以是字符串或回退 URL 数组。不要用 HTML5 流式播放，否则会失去立体声像。
+
+`playing` 与 `VideoHotspot` 一样受控。`loop` 默认 `false`，`muted` 默认 `false`，`volume` 默认 `1`，`pauseWhenHidden` 默认 `true`（标签页隐藏时暂停，仍为 `playing` 则回来后恢复）。首次用户手势会解锁音频；若自动播放被拦，会报告 `"blocked"`，并在 `playing` 仍为 true 时于下一次指针或按键后重试 `play()`。
+
+默认标记在 **停止**（扬声器）与 **播放**（扬声器 + 声波）之间切换。可用 `icon` 自定义停止图标、`playingIcon` 自定义播放图标。只设 `icon` 时两种状态共用该图。`marker={false}` 则无视觉，仍作为定点声源。非空间的全 tour 或按场景背景声请使用 [`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)}
+/>;
+```
+
+与其他媒体热点相同，`AudioHotspot` 不会自行改变 `playing`。
+
 ## TextHotspot
 
 `TextHotspot` 将纯文本栅格化到 canvas 纹理。不接受 HTML 或 Markdown。`\n` 为硬换行；`whiteSpace="normal"`（默认）在热点角向宽度内自动换行。尺寸与其他点热点一样为度。排版使用与 CSS 相同的名称（`fontFamily`、`fontSize`、`fontWeight`、`fontStyle`），但绘制在 canvas 上，非 DOM 样式。`fontSize` 为 canvas 像素（默认 96），不随面板高度缩放。`fontWeight` 默认 `600`，`fontStyle` 默认 `"normal"`。`padding` 与 `borderRadius` 仍为纹理较短边的比例，故仍随 `width` / `height` 变化。