@openbone/player 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -89,6 +89,7 @@ on the page, reloads the player with the new settings.
89
89
  | `setSkin(name)` | Switch skin (updates the `skin` attribute); `null` shows the default skin. |
90
90
  | `play()` / `pause()` | Start or stop playback and sound. |
91
91
  | `player` | The underlying `Player`, or `null` before the element is connected. |
92
+ | `audioContext` | An `AudioContext` to play through, set before `src`. Create and resume it in a click handler (a play button) and the player starts with sound even if it loads after that click. |
92
93
 
93
94
  | Event | `detail` |
94
95
  |---|---|
package/dist/audio.d.ts CHANGED
@@ -26,6 +26,9 @@ export declare class WebAudioBackend {
26
26
  private voices;
27
27
  private hostMuted;
28
28
  private unbind;
29
+ /** Looping sounds requested before audio was unlocked, by voice id; they start when the context runs. */
30
+ private pending;
31
+ private offline;
29
32
  constructor(doc: OpenBoneDocument, opts?: WebAudioOptions);
30
33
  /** True once the browser lets the context play. */
31
34
  get unlocked(): boolean;
@@ -37,6 +40,14 @@ export declare class WebAudioBackend {
37
40
  /** Create (if needed) and resume the context now. Call it from a user gesture (a click) so the browser allows sound. */
38
41
  activate(): AudioContext | null;
39
42
  private context;
43
+ /** Start the loops that were waiting for audio once the context runs (whoever resumed it). */
44
+ private watch;
45
+ private flushPending;
46
+ /**
47
+ * Where sounds are decoded: the live context once it exists, else an OfflineAudioContext, which the browser allows
48
+ * without a user gesture (decoded buffers play in any context).
49
+ */
50
+ private decoder;
40
51
  private masterNode;
41
52
  private busNode;
42
53
  /** Mutes set while playing by "mix" commands (mute buttons): bus id, "" = master. They win over the document. */
package/dist/audio.js CHANGED
@@ -16,10 +16,15 @@ export class WebAudioBackend {
16
16
  voices = new Map();
17
17
  hostMuted = false;
18
18
  unbind = null;
19
+ /** Looping sounds requested before audio was unlocked, by voice id; they start when the context runs. */
20
+ pending = new Map();
21
+ offline = null;
19
22
  constructor(doc, opts = {}) {
20
23
  this.doc = doc;
21
24
  this.opts = opts;
22
25
  this.ctx = opts.context ?? null;
26
+ if (this.ctx)
27
+ this.watch(this.ctx);
23
28
  }
24
29
  /** True once the browser lets the context play. */
25
30
  get unlocked() {
@@ -54,8 +59,36 @@ export class WebAudioBackend {
54
59
  if (!Ctor)
55
60
  return null;
56
61
  this.ctx = new Ctor();
62
+ this.watch(this.ctx);
57
63
  return this.ctx;
58
64
  }
65
+ /** Start the loops that were waiting for audio once the context runs (whoever resumed it). */
66
+ watch(ctx) {
67
+ ctx.addEventListener?.("statechange", () => this.flushPending());
68
+ }
69
+ flushPending() {
70
+ if (this.ctx?.state !== "running" || !this.pending.size)
71
+ return;
72
+ const cmds = [...this.pending.values()];
73
+ this.pending.clear();
74
+ for (const cmd of cmds)
75
+ this.play(cmd);
76
+ }
77
+ /**
78
+ * Where sounds are decoded: the live context once it exists, else an OfflineAudioContext, which the browser allows
79
+ * without a user gesture (decoded buffers play in any context).
80
+ */
81
+ decoder() {
82
+ if (this.ctx)
83
+ return this.ctx;
84
+ if (!this.offline) {
85
+ const Offline = globalThis.OfflineAudioContext ?? globalThis.webkitOfflineAudioContext;
86
+ if (!Offline)
87
+ return this.context();
88
+ this.offline = new Offline(2, 1, 48000);
89
+ }
90
+ return this.offline;
91
+ }
59
92
  masterNode(ctx) {
60
93
  if (!this.master) {
61
94
  this.master = ctx.createGain();
@@ -116,7 +149,7 @@ export class WebAudioBackend {
116
149
  const url = this.url(asset);
117
150
  let p = this.buffers.get(url);
118
151
  if (!p) {
119
- const ctx = this.context();
152
+ const ctx = this.decoder();
120
153
  if (!ctx)
121
154
  return Promise.resolve(null);
122
155
  p = fetch(url)
@@ -196,15 +229,24 @@ export class WebAudioBackend {
196
229
  };
197
230
  play(cmd) {
198
231
  const asset = this.doc.audio?.assets.find((a) => a.id === cmd.asset);
199
- const ctx = this.context();
232
+ // Never create the context here: before a user gesture the browser refuses it ("The AudioContext was not allowed
233
+ // to start"). It is created by unlock() / activate(), from a click or key press.
234
+ const ctx = this.ctx;
200
235
  const name = this.doc.audio?.sounds.find((s) => s.id === cmd.sound)?.name ?? asset?.name ?? cmd.sound;
201
- if (!asset || !ctx) {
202
- this.opts.onLog?.(`play ${name} skipped (${asset ? "no Web Audio" : "asset missing"})`, cmd);
236
+ if (!asset) {
237
+ this.opts.onLog?.(`play ${name} skipped (asset missing)`, cmd);
203
238
  return;
204
239
  }
205
- // One-shots before the first gesture would all burst out at unlock time: drop them. Loops start late.
206
- if (ctx.state !== "running" && !cmd.loop) {
207
- this.opts.onLog?.(`play ${name} skipped (audio locked until a click or key press)`, cmd);
240
+ if (!ctx || ctx.state !== "running") {
241
+ // One-shots before the first gesture would all burst out at unlock time: drop them. Loops (music, ambience)
242
+ // wait and start when audio unlocks.
243
+ if (!cmd.loop) {
244
+ this.opts.onLog?.(`play ${name} skipped (audio locked until a click or key press)`, cmd);
245
+ return;
246
+ }
247
+ this.pending.set(cmd.id, cmd);
248
+ this.opts.onLog?.(`play ${name} [${cmd.id}] loop waits for audio to unlock`, cmd);
249
+ void this.load(asset);
208
250
  return;
209
251
  }
210
252
  const gain = ctx.createGain();
@@ -348,6 +390,8 @@ export class WebAudioBackend {
348
390
  });
349
391
  }
350
392
  stop(id, fade, cmd) {
393
+ if (this.pending.delete(id))
394
+ this.opts.onLog?.(`stop [${id}] (had not started)`, cmd);
351
395
  const v = this.voices.get(id);
352
396
  if (!v)
353
397
  return;
@@ -373,6 +417,7 @@ export class WebAudioBackend {
373
417
  }
374
418
  /** Stop every voice (optionally fading). */
375
419
  stopAll(fade = 0) {
420
+ this.pending.clear();
376
421
  for (const id of [...this.voices.keys()])
377
422
  this.stop(id, fade);
378
423
  }
package/dist/bridge.d.ts CHANGED
@@ -30,6 +30,13 @@ export type BridgeCommand = {
30
30
  name?: string;
31
31
  } | {
32
32
  type: "getInputs";
33
+ } | {
34
+ type: "setMuted";
35
+ muted: boolean;
36
+ } | {
37
+ type: "setBusMuted";
38
+ bus: string | null;
39
+ muted: boolean | "toggle";
33
40
  };
34
41
  export interface BridgeInputInfo {
35
42
  name: string;
@@ -82,6 +89,8 @@ export interface BridgePlayer {
82
89
  playAnimation(name: string, loop?: boolean): void;
83
90
  setSkin(name: string | null): void;
84
91
  useStateMachine?(name?: string): void;
92
+ setMuted?(muted: boolean): void;
93
+ setBusMuted?(bus: string | null, muted: boolean | "toggle"): unknown;
85
94
  inputs(): BridgeInputInfo[];
86
95
  }
87
96
  /** Run a validated command against a player. Returns a reply message for queries. */
package/dist/bridge.js CHANGED
@@ -54,6 +54,18 @@ export function parseCommand(input) {
54
54
  return { type: "setSkin", name: typeof c.name === "string" && c.name ? c.name : null };
55
55
  case "useStateMachine":
56
56
  return { type: "useStateMachine", ...(typeof c.name === "string" ? { name: c.name } : {}) };
57
+ case "setMuted":
58
+ if (typeof c.muted !== "boolean")
59
+ throw new Error('OpenBone bridge: "setMuted" needs a boolean `muted`');
60
+ return { type: "setMuted", muted: c.muted };
61
+ case "setBusMuted": {
62
+ const m = c.muted ?? true;
63
+ if (typeof m !== "boolean" && m !== "toggle")
64
+ throw new Error('OpenBone bridge: "setBusMuted" needs `muted`: true, false or "toggle"');
65
+ if (c.bus !== null && c.bus !== undefined && typeof c.bus !== "string")
66
+ throw new Error('OpenBone bridge: "setBusMuted" needs a string `bus` (or null for the master)');
67
+ return { type: "setBusMuted", bus: c.bus ?? null, muted: m };
68
+ }
57
69
  default:
58
70
  throw new Error(`OpenBone bridge: unknown command "${String(c.type)}"`);
59
71
  }
@@ -83,6 +95,12 @@ export function applyCommand(p, c) {
83
95
  return null;
84
96
  case "getInputs":
85
97
  return { type: "inputs", inputs: p.inputs() };
98
+ case "setMuted":
99
+ p.setMuted?.(c.muted);
100
+ return null;
101
+ case "setBusMuted":
102
+ p.setBusMuted?.(c.bus, c.muted);
103
+ return null;
86
104
  }
87
105
  }
88
106
  /** Send a message to every host channel present on `w` (see the module comment). */
@@ -67,6 +67,8 @@ function start() {
67
67
  player.instance.useStateMachine(n);
68
68
  watchInputs();
69
69
  },
70
+ setMuted: (m) => player?.setMuted(m),
71
+ setBusMuted: (b, m) => player?.setBusMuted(b, m),
70
72
  inputs,
71
73
  };
72
74
  const watchInputs = () => player?.stateMachine?.on("inputChange", () => postToHost({ type: "inputs", inputs: inputs() }));
@@ -91,6 +93,8 @@ function start() {
91
93
  receive: run,
92
94
  setInput: (name, value) => run({ type: "setInput", name, value }),
93
95
  fire: (name) => run({ type: "fire", name }),
96
+ setMuted: (muted) => run({ type: "setMuted", muted }),
97
+ setBusMuted: (bus, muted = true) => run({ type: "setBusMuted", bus, muted }),
94
98
  play: (animation, loop) => run({ type: "play", animation, loop }),
95
99
  pause: () => run({ type: "pause" }),
96
100
  setSkin: (name) => run({ type: "setSkin", name }),
package/dist/element.d.ts CHANGED
@@ -2,7 +2,8 @@ import { Player } from "./player.js";
2
2
  /**
3
3
  * <openbone-player src="hero.obone" state-machine="ui" animation="idle" skin="red" fit="contain" renderer="webgl">
4
4
  * Events: "openbone-event" (detail = FiredEvent), "openbone-state" (detail = state change), "openbone-load".
5
- * Methods: setInput(name, value), fire(name), setText(slot, text), setSkin(name), play(), pause(), player (the underlying Player).
5
+ * Methods: setInput(name, value), fire(name), setText(slot, text), setSkin(name), play(), pause(),
6
+ * setMuted(muted), setBusMuted(bus, muted | "toggle"), toggleBus(bus), isBusMuted(bus), buses, player (the underlying Player).
6
7
  * Audio plays after the first click/key press; `muted` attribute starts muted, `audio="off"` disables it.
7
8
  * Changing the `skin` attribute switches the outfit without reloading.
8
9
  */
@@ -10,6 +11,11 @@ export declare class OpenBonePlayerElement extends HTMLElement {
10
11
  /** `skin` switches skins in place; any other of these reloads the player with the new settings. */
11
12
  static observedAttributes: string[];
12
13
  player: Player | null;
14
+ /**
15
+ * An AudioContext to play through instead of creating one, set before `src`. Create and resume it in a click
16
+ * handler (a play button) and the player starts with sound even when it loads after that click.
17
+ */
18
+ audioContext: AudioContext | null;
13
19
  private canvas;
14
20
  constructor();
15
21
  connectedCallback(): void;
@@ -26,6 +32,16 @@ export declare class OpenBonePlayerElement extends HTMLElement {
26
32
  fire(name: string): void;
27
33
  setSkin(name: string | null): void;
28
34
  play(): void;
35
+ /** Mute or unmute everything. */
36
+ setMuted(muted: boolean): void;
37
+ /** Mute, unmute or toggle a sound bus by name ("music", "sfx"…); null or "master" = the master. */
38
+ setBusMuted(bus: string | null, muted?: boolean | "toggle"): boolean | null;
39
+ toggleBus(bus: string | null): boolean | null;
40
+ isBusMuted(bus: string | null): boolean | null;
41
+ get buses(): {
42
+ name: string;
43
+ muted: boolean;
44
+ }[];
29
45
  pause(): void;
30
46
  }
31
47
  export declare function definePlayerElement(tag?: string): void;
package/dist/element.js CHANGED
@@ -2,7 +2,8 @@ import { Player } from "./player.js";
2
2
  /**
3
3
  * <openbone-player src="hero.obone" state-machine="ui" animation="idle" skin="red" fit="contain" renderer="webgl">
4
4
  * Events: "openbone-event" (detail = FiredEvent), "openbone-state" (detail = state change), "openbone-load".
5
- * Methods: setInput(name, value), fire(name), setText(slot, text), setSkin(name), play(), pause(), player (the underlying Player).
5
+ * Methods: setInput(name, value), fire(name), setText(slot, text), setSkin(name), play(), pause(),
6
+ * setMuted(muted), setBusMuted(bus, muted | "toggle"), toggleBus(bus), isBusMuted(bus), buses, player (the underlying Player).
6
7
  * Audio plays after the first click/key press; `muted` attribute starts muted, `audio="off"` disables it.
7
8
  * Changing the `skin` attribute switches the outfit without reloading.
8
9
  */
@@ -10,6 +11,11 @@ export class OpenBonePlayerElement extends HTMLElement {
10
11
  /** `skin` switches skins in place; any other of these reloads the player with the new settings. */
11
12
  static observedAttributes = ["src", "skin", "animation", "state-machine", "fit", "renderer", "autoplay", "background", "scripts", "audio", "muted"];
12
13
  player = null;
14
+ /**
15
+ * An AudioContext to play through instead of creating one, set before `src`. Create and resume it in a click
16
+ * handler (a play button) and the player starts with sound even when it loads after that click.
17
+ */
18
+ audioContext = null;
13
19
  canvas;
14
20
  constructor() {
15
21
  super();
@@ -61,6 +67,7 @@ export class OpenBonePlayerElement extends HTMLElement {
61
67
  background: this.background(),
62
68
  scripts: this.getAttribute("scripts") === "none" ? "none" : "quickjs",
63
69
  audio: this.getAttribute("audio") === "off" ? false : this.hasAttribute("muted") ? "muted" : true,
70
+ ...(this.audioContext ? { audioContext: this.audioContext } : {}),
64
71
  onEvent: (e) => this.dispatchEvent(new CustomEvent("openbone-event", { detail: e, bubbles: true, composed: true })),
65
72
  onStateChange: (e) => this.dispatchEvent(new CustomEvent("openbone-state", { detail: e, bubbles: true, composed: true })),
66
73
  onLoad: () => this.dispatchEvent(new CustomEvent("openbone-load", { bubbles: true, composed: true })),
@@ -92,6 +99,23 @@ export class OpenBonePlayerElement extends HTMLElement {
92
99
  play() {
93
100
  this.player?.play();
94
101
  }
102
+ /** Mute or unmute everything. */
103
+ setMuted(muted) {
104
+ this.player?.setMuted(muted);
105
+ }
106
+ /** Mute, unmute or toggle a sound bus by name ("music", "sfx"…); null or "master" = the master. */
107
+ setBusMuted(bus, muted = true) {
108
+ return this.player?.setBusMuted(bus, muted) ?? null;
109
+ }
110
+ toggleBus(bus) {
111
+ return this.player?.toggleBus(bus) ?? null;
112
+ }
113
+ isBusMuted(bus) {
114
+ return this.player?.isBusMuted(bus) ?? null;
115
+ }
116
+ get buses() {
117
+ return this.player?.buses ?? [];
118
+ }
95
119
  pause() {
96
120
  this.player?.pause();
97
121
  }
package/dist/player.d.ts CHANGED
@@ -82,6 +82,21 @@ export declare class Player {
82
82
  /** Mute or unmute this player's sounds. */
83
83
  setMuted(muted: boolean): void;
84
84
  get muted(): boolean;
85
+ /**
86
+ * Mute, unmute or toggle one sound bus by name or id ("music", "sfx"…), or the master with null / "master", e.g.
87
+ * from music and sound-effect buttons on your page. Same as a mute-button listener inside the artboard, so both
88
+ * stay in step. Returns the new state, or null when the file has no such bus (or hasn't loaded yet).
89
+ */
90
+ setBusMuted(bus: string | null, muted?: boolean | "toggle"): boolean | null;
91
+ /** Flip a bus's mute (see setBusMuted). Returns the new state. */
92
+ toggleBus(bus: string | null): boolean | null;
93
+ /** Whether a bus (name or id; null / "master" = master) is muted right now; null when there is no such bus. */
94
+ isBusMuted(bus: string | null): boolean | null;
95
+ /** The file's sound buses with their current mute state. */
96
+ get buses(): {
97
+ name: string;
98
+ muted: boolean;
99
+ }[];
85
100
  setInput(name: string, value: boolean | number | string): void;
86
101
  /**
87
102
  * Show fixed text (or a `{input}` template) in a slot's text attachment instead of its own; null restores it.
package/dist/player.js CHANGED
@@ -228,6 +228,26 @@ export class Player {
228
228
  get muted() {
229
229
  return this.audio?.muted ?? false;
230
230
  }
231
+ /**
232
+ * Mute, unmute or toggle one sound bus by name or id ("music", "sfx"…), or the master with null / "master", e.g.
233
+ * from music and sound-effect buttons on your page. Same as a mute-button listener inside the artboard, so both
234
+ * stay in step. Returns the new state, or null when the file has no such bus (or hasn't loaded yet).
235
+ */
236
+ setBusMuted(bus, muted = true) {
237
+ return this.instance?.setBusMuted(bus, muted) ?? null;
238
+ }
239
+ /** Flip a bus's mute (see setBusMuted). Returns the new state. */
240
+ toggleBus(bus) {
241
+ return this.setBusMuted(bus, "toggle");
242
+ }
243
+ /** Whether a bus (name or id; null / "master" = master) is muted right now; null when there is no such bus. */
244
+ isBusMuted(bus) {
245
+ return this.instance?.isBusMuted(bus) ?? null;
246
+ }
247
+ /** The file's sound buses with their current mute state. */
248
+ get buses() {
249
+ return (this.doc?.audio?.buses ?? []).map((b) => ({ name: b.name, muted: this.isBusMuted(b.id) ?? b.muted }));
250
+ }
231
251
  // ---- convenience API (Rive-like) ----
232
252
  setInput(name, value) {
233
253
  this.stateMachine?.setInput(name, value);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openbone/player",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Drop-in <openbone-player> web component and JS API for OpenBone animations",
5
5
  "keywords": [
6
6
  "openbone",
@@ -48,11 +48,11 @@
48
48
  },
49
49
  "dependencies": {
50
50
  "quickjs-emscripten": "^0.32.0",
51
- "@openbone/core": "0.3.0",
52
- "@openbone/render-canvas": "0.3.0",
53
- "@openbone/runtime": "0.3.0",
54
- "@openbone/render-webgl": "0.3.0",
55
- "@openbone/scripting": "0.3.0"
51
+ "@openbone/core": "0.4.0",
52
+ "@openbone/render-canvas": "0.4.0",
53
+ "@openbone/scripting": "0.4.0",
54
+ "@openbone/runtime": "0.4.0",
55
+ "@openbone/render-webgl": "0.4.0"
56
56
  },
57
57
  "peerDependencies": {
58
58
  "esbuild": ">=0.25.0"