{"id":21311536,"url":"https://github.com/wonderlandengine/wonderland-spatial-audio","last_synced_at":"2025-07-11T23:32:41.904Z","repository":{"id":199191082,"uuid":"641044555","full_name":"WonderlandEngine/wonderland-spatial-audio","owner":"WonderlandEngine","description":"Spatial audio components for Wonderland Engine.","archived":false,"fork":false,"pushed_at":"2024-11-17T18:05:37.000Z","size":15317,"stargazers_count":6,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-17T19:18:28.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WonderlandEngine.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-15T16:56:59.000Z","updated_at":"2024-11-17T18:05:40.000Z","dependencies_parsed_at":"2023-12-24T12:31:58.815Z","dependency_job_id":"ea50605c-ef17-4e94-846f-cf4e64e40f8a","html_url":"https://github.com/WonderlandEngine/wonderland-spatial-audio","commit_stats":null,"previous_names":["wonderlandengine/wonderland-spatial-audio"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WonderlandEngine%2Fwonderland-spatial-audio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WonderlandEngine%2Fwonderland-spatial-audio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WonderlandEngine%2Fwonderland-spatial-audio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WonderlandEngine%2Fwonderland-spatial-audio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WonderlandEngine","download_url":"https://codeload.github.com/WonderlandEngine/wonderland-spatial-audio/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225769410,"owners_count":17521276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-21T17:18:46.181Z","updated_at":"2024-11-21T17:18:47.151Z","avatar_url":"https://github.com/WonderlandEngine.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![build](https://github.com/WonderlandEngine/wonderland-spatial-audio/actions/workflows/github-pages.yml/badge.svg)\n\n# Wonderland Spatial Audio\n\n[NPM Package](https://www.npmjs.com/package/@wonderlandengine/spatial-audio)\n\nThe Wonderland Audio System simplifies audio management with\n[Wonderland Engine](https://wonderlandengine.com). These components offer efficient control\nover audio sources and listeners and enable seamless updates of their positions and\norientations in the [WebAudio](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) context.\n\n[View Live Example](https://wonderlandengine.github.io/wonderland-spatial-audio/)\n\n[View Documentation](https://wonderlandengine.github.io/wonderland-spatial-audio/docs/)\n\n\n## Usage Guide\n\nInstructions on how to set up and use Wonderland Spatial Audio:\n\n### Installation\n\nInstall the components in your project:\n\n```sh\nnpm install --save @wonderlandengine/spatial-audio\n```\n\nWonderland Editor will automatically detect the components from this package and they will\nbe available to attach to objects.\n\n### Audio Listener\n\n1. For VR audio: attach an `audio-listener` component to the `Player \u003e Head` object.\n   This controls position and orientation of the receiver. Updates occur each frame.\n\n2. For PC/mobile audio: attach the `audio-listener` component to the `NonVrCamera`.\n   Only one listener component should be active at any given time. To achieve this, use\n   the `vr-mode-active-switch` component.\n\n ⚠️  The listener is necessary for spatial panning to work correctly in the `AudioManager` and `AudioSource`!\n\n### Audio Sources\n\nAdd an `audio-source` component to objects that should play sound. Set the `src`\nproperty to a URL in the `static` folder of your project.\n(E.g., for `static/sfx/sound.mp3` enter `sfx/sound.mp3`).\nIf `spatial` is set to `None`, all settings below are ignored.\n\n- Changing the `volume` parameter will only take effect when calling the `play()` function. If the audio is already \n  playing, use `setVolumeDuringPlayback()` instead.\n\n### AudioManager\n\nThe `AudioManager` can be used to play audio from anywhere in your project! It is a way to conveniently \nmanage audio files. This package provides a global instance of the manager called `globalAudioManager`. \nTo make use of it, create your own identifiers and then load up the manager with your audio files:\n\n```js\nenum MySounds {\n    Gunshot,\n    Zombie,\n}\n\nglobalAudioManager.load('sfx/gunshot.mp3', MySounds.Gunshot);\n// You can even load multiple files for one ID. On play, a random file of the provided ones will be selected. \nglobalAudioManager.load(['sfx/zombie_01.mp3', 'sfx/zombie_02.mp3'], MySounds.Zombie);\n```\n⚠️ Only load() and loadBatch() can be used in top-level code!\n\nThere are two ways of playing an audio file that has loaded:\n\n```js\nglobalAudioManager.play(MySounds.Gunshot);          // Standard way, returns an ID with which audio can be stopped or paused.\nglobalAudioManager.autoplay(MySounds.Gunshot);      // Plays the audio as soon as the user has interacted with the site.\n```\n\nCheckout the `PlayConfig` type, for all the configuration settings! It can be added to change the playback behaviour.\n\n```js\nonPress() {\n    this.object.getPositionWorld(posVec);\n    globalAudioManager.play(MySounds.Gunshot, {\n        volume: 0.8,\n        loop: true,\n        position: posVec,\n        channel: AudioChannel.Sfx,\n        priority: false\n    });\n}\n```\n\nThe `AudioManager` has three main channels: Sfx, Music and Master. Use these to group your audio and \ncontrol the volume globally. On using `play()`, the respective channels can be selected via the `PlayConfig`. \n\n## Considerations\n\n### Best Practices\n\n- **HRTF Performance:** The `HRTF` setting demands substantial performance resources.\n  For less critical audio effects, consider deactivating it and rely on regular\n  (equal-power) 3D panning.\n\n- **Stationary Audio Sources:** If an `audio-source` in a scene will remain at the same\n  position, activate the `isStationary` flag to disable position updates each frame for\n  better performance.\n\n### Meta Quest 2 Performance\n\nOn Meta Quest 2, the maximum number of simultaneously playing audio sources is\napproximately 30.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwonderlandengine%2Fwonderland-spatial-audio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwonderlandengine%2Fwonderland-spatial-audio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwonderlandengine%2Fwonderland-spatial-audio/lists"}