NssAudio

A simple audio player for sound effects with built-in SFX commands. NUI

Getting Started

NssAudio plays audio files from a base path. It also provides static SFX methods for common UI sounds that require no setup.

import {NssAudio} from "nui://nss_libs/ui/NssAudio/NssAudio.js";

const audio = new NssAudio('nui://my_resource/html/sounds/');
audio.setVolume(0.5);
audio.playAudio('click.mp3');

Constructor

new NssAudio(audio_path?, volume?)

Creates a new audio player instance.

Param	Type	Default	Description
audio_path	string	''	Base path for audio files (e.g. 'nui://my_resource/sounds/')
volume	number	0.5	Initial volume between 0 and 1

const audio = new NssAudio('nui://my_resource/html/sounds/', 0.25);

Methods

.playAudio(filename, prevent_reset?, loop?)

Plays an audio file. Returns a Promise that resolves when playback ends.

Param	Type	Default	Description
filename	string	—	The audio filename (appended to the base path)
prevent_reset	boolean	false	If true, does not reset the audio element before playing
loop	boolean	false	If true, loops the audio indefinitely

Returns Promise<string> — resolves with the filename when playback ends.

audio.playAudio('notification.mp3').then((filename) => {
    console.log(filename + ' finished playing');
});

---

.loopAudio(filename)

Plays an audio file in a loop until stop() is called.

Param	Type	Default	Description
filename	string	—	The audio filename

Returns Promise<string> — resolves with the filename when stopped.

audio.loopAudio('ambient.mp3');
// Later:
audio.stop();

---

.stop(force_ended_event?)

Stops the current audio playback.

Param	Type	Default	Description
force_ended_event	boolean	false	If true, fires the ended event callback even though the audio was stopped manually

Returns undefined

audio.stop(true); // Stop and resolve the playAudio promise

---

.setVolume(volume)

Sets the playback volume.

Param	Type	Default	Description
volume	number	—	Volume between 0 (mute) and 1 (full)

Returns undefined

audio.setVolume(0.3);

---

.setAudioPath(path)

Changes the base audio path.

Param	Type	Default	Description
path	string	—	The new base path

Returns undefined

audio.setAudioPath('nui://my_resource/html/other_sounds/');

---

.setRandomPlaybackRate(min, max)

Enables random pitch variation for each playback. Useful for natural-sounding repeated effects.

Param	Type	Default	Description
min	number	—	Minimum playback rate (e.g. 0.7)
max	number	—	Maximum playback rate (e.g. 1.5)

Returns undefined

audio.setRandomPlaybackRate(0.8, 1.2);
audio.playAudio('footstep.mp3'); // Slightly different pitch each time

---

.setPlaybackRate(rate)

Sets a fixed playback rate.

Param	Type	Default	Description
rate	number	—	The playback rate (1.0 = normal speed)

Returns undefined

audio.setPlaybackRate(1.5); // 1.5x speed

---

.isPlaying()

Checks if audio is currently playing.

Returns boolean — true if playing.

if (audio.isPlaying()) {
    audio.stop();
}

---

.getDuration()

Returns the total duration of the current audio file.

Returns number|false — duration in seconds, or false if not available.

const duration = audio.getDuration();

---

.getCurrentTime()

Returns the current playback position.

Returns number — current time in seconds.

const time = audio.getCurrentTime();

---

.getDurationInPercent()

Returns the playback progress as a percentage.

Returns number|false — progress between 0 and 1, or false if duration is not available.

const progress = audio.getDurationInPercent(); // e.g. 0.42

---

.resetAudio()

Pauses playback and removes the audio element from the DOM.

Returns undefined

audio.resetAudio();

Static SFX Methods

Built-in UI sound effects. No instance needed — call directly on the class. Each accepts an optional volume parameter.

Method	Default Volume	Description
NssAudio.playSfxBack(volume)	—	Back/cancel sound
NssAudio.playSfxNext(volume)	0.5	Next/confirm sound
NssAudio.playSfxUpDown(volume)	0.25	Navigation sound (hover)
NssAudio.playSfxShowMenu(volume)	—	Menu open sound
NssAudio.playSfxIndexOpen(volume)	—	Index open sound
NssAudio.playSfxIndexClose(volume)	—	Index close sound
NssAudio.playSfxHideMenu1(volume)	—	Menu close variant 1
NssAudio.playSfxHideMenu2(volume)	—	Menu close variant 2
NssAudio.playSfxHideMenu3(volume)	—	Menu close variant 3

NssAudio.playSfxBack(0.25);
NssAudio.playSfxShowMenu(0.5);

---

Master Volume

Control the global SFX volume with:

Method	Description
NssAudio.setMasterVolumeInPercent(percent)	Set master volume (0–100)
NssAudio.resetMasterVolumeInPercent()	Reset to default

NssAudio.setMasterVolumeInPercent(50); // 50% of all SFX volume

Events / Callbacks

None. Use the Promise returned by playAudio() to react to playback completion.

CSS

None. NssAudio has no visual representation.

Dependencies

• NssUiComponentInterface — base class (no NssResponsive dependency).

Things to Know

TIP

AbortError on play() is silently ignored (common when rapidly switching sounds). All other DOMException errors are logged to console.

INFO

Static SFX methods use an internal singleton player pointing to nui://nss_libs/ui/NssAudio/sfx/.

• NssButtons, NssModal, and NssPadLock use NssAudio internally for their UI sounds.