@primitiv/audio 0.19.0

package/LICENSE.txt

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Thomas Piquet (THP Software)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,9 @@
+# @primitiv/audio
+
+> **Internal package** - This is an internal module of the [Primitiv Engine](https://primitivengine.com/).
+
+For documentation, examples, and guides, visit **[primitivengine.com](https://primitivengine.com/)**.
+
+## 📄 License
+
+Apache-2.0 - See [LICENSE.txt](./LICENSE.txt).

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var g=Object.defineProperty;var N=Object.getOwnPropertyDescriptor;var T=Object.getOwnPropertyNames;var S=Object.prototype.hasOwnProperty;var w=(l,e)=>{for(var t in e)g(l,t,{get:e[t],enumerable:!0})},I=(l,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of T(e))!S.call(l,n)&&n!==t&&g(l,n,{get:()=>e[n],enumerable:!(i=N(e,n))||i.enumerable});return l};var C=l=>I(g({},"__esModule",{value:!0}),l);var V={};w(V,{AudioEngine:()=>v,ManagedSource:()=>p,RetroTones:()=>f,SoundBank:()=>h,SpatialProcessor:()=>m});module.exports=C(V);var x=require("@primitiv/logger");var A=require("@primitiv/logger"),y=A.Logger.create("audio:soundbank"),h=class{sounds=new Map;nameToId=new Map;audioContext;constructor(e){this.audioContext=e}async loadFromData(e,t,i){try{let n=await this.audioContext.decodeAudioData(i.buffer);this.store(e,t,n)}catch(n){throw y.error(`Failed to decode sound "${t}" (${e})`,n),n}}async loadFromUrl(e,t,i){try{let a=await(await fetch(i)).arrayBuffer(),s=await this.audioContext.decodeAudioData(a);this.store(e,t,s)}catch(n){throw y.error(`Failed to load sound "${t}" from URL ${i}`,n),n}}store(e,t,i){this.sounds.set(e,i),this.nameToId.set(t,e)}get(e){if(typeof e=="number")return this.sounds.get(e);let t=this.nameToId.get(e);return t!==void 0?this.sounds.get(t):void 0}has(e){return this.get(e)!==void 0}clear(){this.sounds.clear(),this.nameToId.clear()}getAll(){let e=[],t=new Map;for(let[i,n]of this.nameToId)t.set(n,i);for(let[i,n]of this.sounds)e.push({soundId:i,name:t.get(i)??`Sound ${i}`,duration:n.duration});return e}};var p=class{instanceId;soundId;name;source;gainNode;pannerNode;lowpassNode;highpassNode;reverbSend;audioContext;destination;t=!1;n=!1;e=1;s=1;i=null;position;onEnded;constructor(e,t,i,n,a,s={}){this.audioContext=e,this.instanceId=t,this.soundId=i,this.name=s.name??"",this.destination=a,this.e=s.volume??1,this.position=s.position,this.source=e.createBufferSource(),this.source.buffer=n,this.source.loop=s.loop??!1,this.source.playbackRate.value=s.pitch??1,this.gainNode=e.createGain();let c=s.fadeIn??0;c>0?(this.gainNode.gain.setValueAtTime(0,e.currentTime),this.gainNode.gain.linearRampToValueAtTime(this.e,e.currentTime+c)):this.gainNode.gain.value=this.e,s.position&&(this.pannerNode=e.createStereoPanner()),this.source.connect(this.gainNode),this.pannerNode?(this.gainNode.connect(this.pannerNode),this.pannerNode.connect(this.destination)):this.gainNode.connect(this.destination),s.reverbNode&&(this.reverbSend=e.createGain(),this.reverbSend.gain.value=s.reverb??0,this.gainNode.connect(this.reverbSend),this.reverbSend.connect(s.reverbNode)),s.lowpass&&this.setLowpass(s.lowpass),s.highpass&&this.setHighpass(s.highpass),this.source.onended=()=>{this.n||(this.t=!0,this.onEnded?.())}}start(e=0){this.source.start(0,e)}stop(e=0){this.t||(e>0?(this.gainNode.gain.linearRampToValueAtTime(0,this.audioContext.currentTime+e),this.i=setTimeout(()=>this.internalStop(),e*1e3)):this.internalStop())}internalStop(){this.i!==null&&(clearTimeout(this.i),this.i=null);try{this.source.stop()}catch{}this.t=!0,this.onEnded?.()}setVolume(e,t=0){this.e=e,this.updateTotalVolume(t)}setSpatialVolume(e){this.s=e,this.updateTotalVolume()}updateTotalVolume(e=0){let t=this.e*this.s;e>0?this.gainNode.gain.linearRampToValueAtTime(t,this.audioContext.currentTime+e):this.gainNode.gain.setValueAtTime(t,this.audioContext.currentTime)}setPan(e){this.pannerNode&&this.pannerNode.pan.setValueAtTime(e,this.audioContext.currentTime)}setPitch(e){this.source.playbackRate.setValueAtTime(e,this.audioContext.currentTime)}setLowpass(e){e<=0?this.lowpassNode=void 0:(this.lowpassNode||(this.lowpassNode=this.audioContext.createBiquadFilter(),this.lowpassNode.type="lowpass"),this.lowpassNode.frequency.setValueAtTime(e,this.audioContext.currentTime)),this.updateChain()}setHighpass(e){e<=0?this.highpassNode=void 0:(this.highpassNode||(this.highpassNode=this.audioContext.createBiquadFilter(),this.highpassNode.type="highpass"),this.highpassNode.frequency.setValueAtTime(e,this.audioContext.currentTime)),this.updateChain()}updateChain(){this.source.disconnect(),this.lowpassNode&&this.lowpassNode.disconnect(),this.highpassNode&&this.highpassNode.disconnect();let e=this.source;this.lowpassNode&&(e.connect(this.lowpassNode),e=this.lowpassNode),this.highpassNode&&(e.connect(this.highpassNode),e=this.highpassNode),e.connect(this.gainNode),this.reverbSend&&this.gainNode.connect(this.reverbSend)}setReverb(e){this.reverbSend&&this.reverbSend.gain.setTargetAtTime(e,this.audioContext.currentTime,.1)}isPlaying(){return!this.t&&!this.n}};var m=class{config={listenerX:0,listenerY:0,maxDistance:200,referenceDistance:20,rolloffFactor:1,panSpread:1};configure(e){e.maxDistance!==void 0&&(this.config.maxDistance=e.maxDistance),e.referenceDistance!==void 0&&(this.config.referenceDistance=e.referenceDistance),e.rolloffFactor!==void 0&&(this.config.rolloffFactor=e.rolloffFactor),e.panSpread!==void 0&&(this.config.panSpread=e.panSpread)}setListenerPosition(e,t){this.config.listenerX=e,this.config.listenerY=t}getConfig(){return this.config}calculate2D(e,t){let{listenerX:i,listenerY:n,maxDistance:a,referenceDistance:s,panSpread:c}=this.config,r=e-i,o=t-n,u=Math.sqrt(r*r+o*o),d;u<=s?d=1:u>=a?d=0:d=1-(u-s)/(a-s);let b=0;return a>0&&c>0&&(b=r/a*c,b=Math.max(-1,Math.min(1,b))),{pan:b,distanceVolume:d}}};var f=class{static playStartSound(e,t){let i=e.currentTime,n=[261.63,329.63,392,523.25],a=.06,s=.07;n.forEach((c,r)=>{let o=i+r*s,u=e.createOscillator(),d=e.createGain();u.type="square",u.frequency.setValueAtTime(c,o),d.gain.setValueAtTime(0,o),d.gain.linearRampToValueAtTime(.2,o+.005),d.gain.setValueAtTime(.2,o+a-.01),d.gain.linearRampToValueAtTime(0,o+a),u.connect(d),d.connect(t),u.start(o),u.stop(o+a)})}static noteToFrequency(e){let t=/^([A-G])([#b]?)(\d)$/i,i=e.match(t);if(!i)return null;let[,n,a,s]=i,c=parseInt(s,10),o={C:0,D:2,E:4,F:5,G:7,A:9,B:11}[n.toUpperCase()];a==="#"?o+=1:a==="b"&&(o-=1);let u=o+(c+1)*12;return 440*Math.pow(2,(u-49)/12)}};var B=x.Logger.create("audio:engine"),v=class{ctx=null;masterGain=null;reverbBus=null;soundBank=null;spatial=new m;instances=new Map;nextInstanceId=1;onAudioEvent=null;initialize(){if(this.ctx)return!0;try{return this.ctx=new(window.AudioContext||window.webkitAudioContext),this.masterGain=this.ctx.createGain(),this.masterGain.connect(this.ctx.destination),this.ctx.state==="suspended"&&this.ctx.resume(),this.reverbBus=this.ctx.createConvolver(),this.reverbBus.buffer=this.createImpulseResponse(2,2),this.reverbBus.connect(this.masterGain),this.soundBank=new h(this.ctx),!0}catch(e){return B.error("Failed to initialize",e),!1}}createImpulseResponse(e,t){if(!this.ctx)throw new Error("Context not initialized");let i=this.ctx.sampleRate,n=i*e,a=this.ctx.createBuffer(2,n,i);for(let s=0;s<2;s++){let c=a.getChannelData(s);for(let r=0;r<n;r++){let o=Math.pow(1-r/n,t);c[r]=(Math.random()*2-1)*o}}return a}getLoader(){return this.soundBank}setMasterVolume(e){this.masterGain&&(this.masterGain.gain.value=Math.max(0,Math.min(1,e)))}getMasterVolume(){return this.masterGain?.gain.value??1}play(e,t={}){if(!this.ctx||!this.masterGain||!this.soundBank)return null;let i=this.soundBank.get(e);if(!i)return null;let n=t.instanceId??this.nextInstanceId++,a=typeof e=="number"?e:-1,s=new p(this.ctx,n,a,i,this.masterGain,{...t,name:t.name??(typeof e=="string"?e:""),reverbNode:this.reverbBus||void 0});if(t.position){let{pan:c,distanceVolume:r}=this.spatial.calculate2D(t.position.x,t.position.y);s.setSpatialVolume(r),s.setPan(c)}return s.onEnded=()=>{this.onAudioEvent?.({type:"playback-ended",instanceId:n,soundId:a}),this.instances.delete(n)},this.instances.set(n,s),s.start(),this.onAudioEvent?.({type:"playback-started",instanceId:n,soundId:a}),{instanceId:n}}stop(e){if(typeof e=="number"){let t=this.instances.get(e);if(t)return t.stop(),1}else{let t=0;for(let i of this.instances.values())(e==="all"||i.name===e)&&(i.stop(),t++);return t}return 0}stopAll(){let e=this.instances.size;return this.instances.forEach(t=>t.stop()),this.instances.clear(),e}fadeOut(e,t){if(e==="all"){let i=this.instances.size;return this.instances.forEach(n=>n.stop(t)),i}if(typeof e=="number"){let i=this.instances.get(e);if(i)return i.stop(t),1}return 0}pause(e){return 0}resume(e){return 0}setListenerPosition(e,t){this.spatial.setListenerPosition(e,t);for(let i of this.instances.values())if(i.position){let{pan:n,distanceVolume:a}=this.spatial.calculate2D(i.position.x,i.position.y);i.setPan(n),i.setSpatialVolume(a)}}configureSpatial(e){this.spatial.configure(e)}setEffects(e,t){let i=this.instances.get(e);i&&(t.lowpass!==void 0&&i.setLowpass(t.lowpass),t.highpass!==void 0&&i.setHighpass(t.highpass),t.reverb!==void 0&&i.setReverb(t.reverb),t.pitch!==void 0&&i.setPitch(t.pitch),t.volume!==void 0&&i.setVolume(t.volume))}stopBySoundId(e){let t=0;for(let i of this.instances.values())i.soundId===e&&(i.stop(),t++);return t}fadeOutBySoundId(e,t){let i=0;for(let n of this.instances.values())n.soundId===e&&(n.stop(t),i++);return i}pauseBySoundId(e){return 0}resumeBySoundId(e){return 0}playTone(e,t,i={}){if(!this.ctx||!this.masterGain)return;let{type:n="sine",volume:a=.3,attack:s=.01,release:c=.1}=i,r=this.ctx.currentTime,o=this.ctx.createOscillator();o.type=n,o.frequency.setValueAtTime(e,r);let u=this.ctx.createGain();u.gain.setValueAtTime(0,r),u.gain.linearRampToValueAtTime(a,r+s),u.gain.setValueAtTime(a,r+t-c),u.gain.linearRampToValueAtTime(0,r+t),o.connect(u),u.connect(this.masterGain),o.start(r),o.stop(r+t)}playStartSound(){this.ctx&&this.masterGain&&f.playStartSound(this.ctx,this.masterGain)}destroy(){this.stopAll(),this.ctx&&(this.ctx.close().catch(()=>{}),this.ctx=null),this.masterGain=null,this.reverbBus=null,this.soundBank=null,this.onAudioEvent=null}};

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+import { ISoundLoader, IAudioProcessor, AudioAck, AudioPlayOptions, AudioPlayResult, AudioSpatialOptions, SoundInstanceId, SpatialAudioConfig } from '@primitiv/types';
+
+/**
+ * Low-level cache for decoded AudioBuffers.
+ * Implements ISoundLoader for platform-agnostic sound loading.
+ */
+declare class SoundBank implements ISoundLoader {
+    private sounds;
+    private nameToId;
+    private audioContext;
+    constructor(audioContext: AudioContext);
+    /**
+     * Load a sound from binary data (MP3, WAV, etc.)
+     */
+    loadFromData(soundId: number, name: string, data: Uint8Array): Promise<void>;
+    /**
+     * Load a sound from an external URL
+     */
+    loadFromUrl(soundId: number, name: string, url: string): Promise<void>;
+    /**
+     * Store a decoded buffer directly
+     */
+    store(soundId: number, name: string, buffer: AudioBuffer): void;
+    /**
+     * Get a decoded buffer by ID or name
+     */
+    get(idOrName: number | string): AudioBuffer | undefined;
+    /**
+     * Check if a sound is loaded
+     */
+    has(idOrName: number | string): boolean;
+    /**
+     * Clear all cached sounds
+     */
+    clear(): void;
+    /**
+     * Get all loaded sounds as an array of descriptors.
+     * Used by the visual-debugger assets panel.
+     */
+    getAll(): Array<{
+        soundId: number;
+        name: string;
+        duration: number;
+    }>;
+}
+
+declare class AudioEngine implements IAudioProcessor {
+    private ctx;
+    private masterGain;
+    private reverbBus;
+    private soundBank;
+    private spatial;
+    private instances;
+    private nextInstanceId;
+    /**
+     * Optional callback invoked on audio lifecycle events
+     * (playback-started, playback-ended).
+     *
+     * Set by ClientRuntime to queue acks for the server.
+     */
+    onAudioEvent: ((ack: AudioAck) => void) | null;
+    initialize(): boolean;
+    private createImpulseResponse;
+    getLoader(): SoundBank | null;
+    /**
+     * Set the master volume (0.0 = muted, 1.0 = full).
+     */
+    setMasterVolume(volume: number): void;
+    /**
+     * Get the current master volume.
+     */
+    getMasterVolume(): number;
+    play(sound: string | number, options?: AudioPlayOptions): AudioPlayResult | null;
+    stop(target: number | string): number;
+    stopAll(): number;
+    fadeOut(target: number | string | 'all', duration: number): number;
+    pause(_target: number | string | 'all'): number;
+    resume(_target: number | string | 'all'): number;
+    setListenerPosition(x: number, y: number): void;
+    configureSpatial(config: AudioSpatialOptions): void;
+    setEffects(instanceId: number, options: {
+        lowpass?: number;
+        highpass?: number;
+        reverb?: number;
+        pitch?: number;
+        volume?: number;
+    }): void;
+    stopBySoundId(soundId: number): number;
+    fadeOutBySoundId(soundId: number, duration: number): number;
+    pauseBySoundId(_soundId: number): number;
+    resumeBySoundId(_soundId: number): number;
+    /**
+     * Play a pure oscillator tone.
+     *
+     * @param frequency - Tone frequency in Hz (e.g. 440 for A4)
+     * @param duration  - Duration in seconds
+     * @param options   - Oscillator type, volume, attack & release envelope
+     */
+    playTone(frequency: number, duration: number, options?: {
+        type?: OscillatorType;
+        volume?: number;
+        attack?: number;
+        release?: number;
+    }): void;
+    playStartSound(): void;
+    /**
+     * Destroy the audio engine and release all resources.
+     * Closes the underlying AudioContext to free the browser audio thread.
+     * After calling destroy(), this instance must not be reused.
+     */
+    destroy(): void;
+}
+
+/**
+ * Managed wrapper for a playing sound instance.
+ * Handles volume, pitch, filters and lifecycle events.
+ */
+declare class ManagedSource {
+    readonly instanceId: SoundInstanceId;
+    readonly soundId: number;
+    readonly name: string;
+    private source;
+    private gainNode;
+    private pannerNode?;
+    private lowpassNode?;
+    private highpassNode?;
+    private reverbSend?;
+    private audioContext;
+    private destination;
+    private _stopped;
+    private _paused;
+    private _baseVolume;
+    private _spatialVolume;
+    private _fadeOutTimer;
+    position?: {
+        x: number;
+        y: number;
+    };
+    onEnded?: () => void;
+    constructor(ctx: AudioContext, instanceId: SoundInstanceId, soundId: number, buffer: AudioBuffer, dest: AudioNode, options?: AudioPlayOptions);
+    start(offset?: number): void;
+    stop(duration?: number): void;
+    private internalStop;
+    setVolume(volume: number, duration?: number): void;
+    setSpatialVolume(volume: number): void;
+    private updateTotalVolume;
+    setPan(pan: number): void;
+    setPitch(pitch: number): void;
+    setLowpass(freq: number): void;
+    setHighpass(freq: number): void;
+    private updateChain;
+    setReverb(amount: number): void;
+    isPlaying(): boolean;
+}
+
+/**
+ * Handles spatial audio configuration and updates.
+ * Supports legacy 2D math and modern 3D panner nodes.
+ */
+declare class SpatialProcessor {
+    private config;
+    configure(options: AudioSpatialOptions): void;
+    setListenerPosition(x: number, y: number): void;
+    getConfig(): Readonly<SpatialAudioConfig>;
+    /**
+     * Legacy 2D calculation (ported from UTSP)
+     */
+    calculate2D(soundX: number, soundY: number): {
+        pan: number;
+        distanceVolume: number;
+    };
+}
+
+/**
+ * Utility for generating retro arcade-style sounds and tones.
+ */
+declare class RetroTones {
+    /**
+     * Play a retro arcade arpeggio
+     */
+    static playStartSound(ctx: AudioContext, dest: AudioNode): void;
+    /**
+     * Convert note name (e.g. 'A4', 'C#5') to frequency
+     */
+    static noteToFrequency(note: string): number | null;
+}
+
+export { AudioEngine, ManagedSource, RetroTones, SoundBank, SpatialProcessor };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{Logger as A}from"@primitiv/logger";import{Logger as y}from"@primitiv/logger";var g=y.create("audio:soundbank"),p=class{sounds=new Map;nameToId=new Map;audioContext;constructor(e){this.audioContext=e}async loadFromData(e,t,i){try{let n=await this.audioContext.decodeAudioData(i.buffer);this.store(e,t,n)}catch(n){throw g.error(`Failed to decode sound "${t}" (${e})`,n),n}}async loadFromUrl(e,t,i){try{let a=await(await fetch(i)).arrayBuffer(),s=await this.audioContext.decodeAudioData(a);this.store(e,t,s)}catch(n){throw g.error(`Failed to load sound "${t}" from URL ${i}`,n),n}}store(e,t,i){this.sounds.set(e,i),this.nameToId.set(t,e)}get(e){if(typeof e=="number")return this.sounds.get(e);let t=this.nameToId.get(e);return t!==void 0?this.sounds.get(t):void 0}has(e){return this.get(e)!==void 0}clear(){this.sounds.clear(),this.nameToId.clear()}getAll(){let e=[],t=new Map;for(let[i,n]of this.nameToId)t.set(n,i);for(let[i,n]of this.sounds)e.push({soundId:i,name:t.get(i)??`Sound ${i}`,duration:n.duration});return e}};var m=class{instanceId;soundId;name;source;gainNode;pannerNode;lowpassNode;highpassNode;reverbSend;audioContext;destination;t=!1;n=!1;e=1;s=1;i=null;position;onEnded;constructor(e,t,i,n,a,s={}){this.audioContext=e,this.instanceId=t,this.soundId=i,this.name=s.name??"",this.destination=a,this.e=s.volume??1,this.position=s.position,this.source=e.createBufferSource(),this.source.buffer=n,this.source.loop=s.loop??!1,this.source.playbackRate.value=s.pitch??1,this.gainNode=e.createGain();let c=s.fadeIn??0;c>0?(this.gainNode.gain.setValueAtTime(0,e.currentTime),this.gainNode.gain.linearRampToValueAtTime(this.e,e.currentTime+c)):this.gainNode.gain.value=this.e,s.position&&(this.pannerNode=e.createStereoPanner()),this.source.connect(this.gainNode),this.pannerNode?(this.gainNode.connect(this.pannerNode),this.pannerNode.connect(this.destination)):this.gainNode.connect(this.destination),s.reverbNode&&(this.reverbSend=e.createGain(),this.reverbSend.gain.value=s.reverb??0,this.gainNode.connect(this.reverbSend),this.reverbSend.connect(s.reverbNode)),s.lowpass&&this.setLowpass(s.lowpass),s.highpass&&this.setHighpass(s.highpass),this.source.onended=()=>{this.n||(this.t=!0,this.onEnded?.())}}start(e=0){this.source.start(0,e)}stop(e=0){this.t||(e>0?(this.gainNode.gain.linearRampToValueAtTime(0,this.audioContext.currentTime+e),this.i=setTimeout(()=>this.internalStop(),e*1e3)):this.internalStop())}internalStop(){this.i!==null&&(clearTimeout(this.i),this.i=null);try{this.source.stop()}catch{}this.t=!0,this.onEnded?.()}setVolume(e,t=0){this.e=e,this.updateTotalVolume(t)}setSpatialVolume(e){this.s=e,this.updateTotalVolume()}updateTotalVolume(e=0){let t=this.e*this.s;e>0?this.gainNode.gain.linearRampToValueAtTime(t,this.audioContext.currentTime+e):this.gainNode.gain.setValueAtTime(t,this.audioContext.currentTime)}setPan(e){this.pannerNode&&this.pannerNode.pan.setValueAtTime(e,this.audioContext.currentTime)}setPitch(e){this.source.playbackRate.setValueAtTime(e,this.audioContext.currentTime)}setLowpass(e){e<=0?this.lowpassNode=void 0:(this.lowpassNode||(this.lowpassNode=this.audioContext.createBiquadFilter(),this.lowpassNode.type="lowpass"),this.lowpassNode.frequency.setValueAtTime(e,this.audioContext.currentTime)),this.updateChain()}setHighpass(e){e<=0?this.highpassNode=void 0:(this.highpassNode||(this.highpassNode=this.audioContext.createBiquadFilter(),this.highpassNode.type="highpass"),this.highpassNode.frequency.setValueAtTime(e,this.audioContext.currentTime)),this.updateChain()}updateChain(){this.source.disconnect(),this.lowpassNode&&this.lowpassNode.disconnect(),this.highpassNode&&this.highpassNode.disconnect();let e=this.source;this.lowpassNode&&(e.connect(this.lowpassNode),e=this.lowpassNode),this.highpassNode&&(e.connect(this.highpassNode),e=this.highpassNode),e.connect(this.gainNode),this.reverbSend&&this.gainNode.connect(this.reverbSend)}setReverb(e){this.reverbSend&&this.reverbSend.gain.setTargetAtTime(e,this.audioContext.currentTime,.1)}isPlaying(){return!this.t&&!this.n}};var f=class{config={listenerX:0,listenerY:0,maxDistance:200,referenceDistance:20,rolloffFactor:1,panSpread:1};configure(e){e.maxDistance!==void 0&&(this.config.maxDistance=e.maxDistance),e.referenceDistance!==void 0&&(this.config.referenceDistance=e.referenceDistance),e.rolloffFactor!==void 0&&(this.config.rolloffFactor=e.rolloffFactor),e.panSpread!==void 0&&(this.config.panSpread=e.panSpread)}setListenerPosition(e,t){this.config.listenerX=e,this.config.listenerY=t}getConfig(){return this.config}calculate2D(e,t){let{listenerX:i,listenerY:n,maxDistance:a,referenceDistance:s,panSpread:c}=this.config,r=e-i,o=t-n,u=Math.sqrt(r*r+o*o),l;u<=s?l=1:u>=a?l=0:l=1-(u-s)/(a-s);let h=0;return a>0&&c>0&&(h=r/a*c,h=Math.max(-1,Math.min(1,h))),{pan:h,distanceVolume:l}}};var b=class{static playStartSound(e,t){let i=e.currentTime,n=[261.63,329.63,392,523.25],a=.06,s=.07;n.forEach((c,r)=>{let o=i+r*s,u=e.createOscillator(),l=e.createGain();u.type="square",u.frequency.setValueAtTime(c,o),l.gain.setValueAtTime(0,o),l.gain.linearRampToValueAtTime(.2,o+.005),l.gain.setValueAtTime(.2,o+a-.01),l.gain.linearRampToValueAtTime(0,o+a),u.connect(l),l.connect(t),u.start(o),u.stop(o+a)})}static noteToFrequency(e){let t=/^([A-G])([#b]?)(\d)$/i,i=e.match(t);if(!i)return null;let[,n,a,s]=i,c=parseInt(s,10),o={C:0,D:2,E:4,F:5,G:7,A:9,B:11}[n.toUpperCase()];a==="#"?o+=1:a==="b"&&(o-=1);let u=o+(c+1)*12;return 440*Math.pow(2,(u-49)/12)}};var x=A.create("audio:engine"),v=class{ctx=null;masterGain=null;reverbBus=null;soundBank=null;spatial=new f;instances=new Map;nextInstanceId=1;onAudioEvent=null;initialize(){if(this.ctx)return!0;try{return this.ctx=new(window.AudioContext||window.webkitAudioContext),this.masterGain=this.ctx.createGain(),this.masterGain.connect(this.ctx.destination),this.ctx.state==="suspended"&&this.ctx.resume(),this.reverbBus=this.ctx.createConvolver(),this.reverbBus.buffer=this.createImpulseResponse(2,2),this.reverbBus.connect(this.masterGain),this.soundBank=new p(this.ctx),!0}catch(e){return x.error("Failed to initialize",e),!1}}createImpulseResponse(e,t){if(!this.ctx)throw new Error("Context not initialized");let i=this.ctx.sampleRate,n=i*e,a=this.ctx.createBuffer(2,n,i);for(let s=0;s<2;s++){let c=a.getChannelData(s);for(let r=0;r<n;r++){let o=Math.pow(1-r/n,t);c[r]=(Math.random()*2-1)*o}}return a}getLoader(){return this.soundBank}setMasterVolume(e){this.masterGain&&(this.masterGain.gain.value=Math.max(0,Math.min(1,e)))}getMasterVolume(){return this.masterGain?.gain.value??1}play(e,t={}){if(!this.ctx||!this.masterGain||!this.soundBank)return null;let i=this.soundBank.get(e);if(!i)return null;let n=t.instanceId??this.nextInstanceId++,a=typeof e=="number"?e:-1,s=new m(this.ctx,n,a,i,this.masterGain,{...t,name:t.name??(typeof e=="string"?e:""),reverbNode:this.reverbBus||void 0});if(t.position){let{pan:c,distanceVolume:r}=this.spatial.calculate2D(t.position.x,t.position.y);s.setSpatialVolume(r),s.setPan(c)}return s.onEnded=()=>{this.onAudioEvent?.({type:"playback-ended",instanceId:n,soundId:a}),this.instances.delete(n)},this.instances.set(n,s),s.start(),this.onAudioEvent?.({type:"playback-started",instanceId:n,soundId:a}),{instanceId:n}}stop(e){if(typeof e=="number"){let t=this.instances.get(e);if(t)return t.stop(),1}else{let t=0;for(let i of this.instances.values())(e==="all"||i.name===e)&&(i.stop(),t++);return t}return 0}stopAll(){let e=this.instances.size;return this.instances.forEach(t=>t.stop()),this.instances.clear(),e}fadeOut(e,t){if(e==="all"){let i=this.instances.size;return this.instances.forEach(n=>n.stop(t)),i}if(typeof e=="number"){let i=this.instances.get(e);if(i)return i.stop(t),1}return 0}pause(e){return 0}resume(e){return 0}setListenerPosition(e,t){this.spatial.setListenerPosition(e,t);for(let i of this.instances.values())if(i.position){let{pan:n,distanceVolume:a}=this.spatial.calculate2D(i.position.x,i.position.y);i.setPan(n),i.setSpatialVolume(a)}}configureSpatial(e){this.spatial.configure(e)}setEffects(e,t){let i=this.instances.get(e);i&&(t.lowpass!==void 0&&i.setLowpass(t.lowpass),t.highpass!==void 0&&i.setHighpass(t.highpass),t.reverb!==void 0&&i.setReverb(t.reverb),t.pitch!==void 0&&i.setPitch(t.pitch),t.volume!==void 0&&i.setVolume(t.volume))}stopBySoundId(e){let t=0;for(let i of this.instances.values())i.soundId===e&&(i.stop(),t++);return t}fadeOutBySoundId(e,t){let i=0;for(let n of this.instances.values())n.soundId===e&&(n.stop(t),i++);return i}pauseBySoundId(e){return 0}resumeBySoundId(e){return 0}playTone(e,t,i={}){if(!this.ctx||!this.masterGain)return;let{type:n="sine",volume:a=.3,attack:s=.01,release:c=.1}=i,r=this.ctx.currentTime,o=this.ctx.createOscillator();o.type=n,o.frequency.setValueAtTime(e,r);let u=this.ctx.createGain();u.gain.setValueAtTime(0,r),u.gain.linearRampToValueAtTime(a,r+s),u.gain.setValueAtTime(a,r+t-c),u.gain.linearRampToValueAtTime(0,r+t),o.connect(u),u.connect(this.masterGain),o.start(r),o.stop(r+t)}playStartSound(){this.ctx&&this.masterGain&&b.playStartSound(this.ctx,this.masterGain)}destroy(){this.stopAll(),this.ctx&&(this.ctx.close().catch(()=>{}),this.ctx=null),this.masterGain=null,this.reverbBus=null,this.soundBank=null,this.onAudioEvent=null}};export{v as AudioEngine,m as ManagedSource,b as RetroTones,p as SoundBank,f as SpatialProcessor};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@primitiv/audio",
+  "version": "0.19.0",
+  "description": "Primitiv audio module",
+  "author": "THP Software",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thp-software/primitiv",
+    "directory": "packages/audio"
+  },
+  "homepage": "https://primitivengine.com",
+  "bugs": {
+    "url": "https://github.com/thp-software/primitiv/issues"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@primitiv/logger": "0.19.0",
+    "@primitiv/types": "0.19.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "rimraf dist && node ../../scripts/build-package.mjs packages/audio",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx src/**/*.test.ts"
+  }
+}