Skip to content

Audio

Classes

sound

Methods

close

Closes an opened sound, making the sound object available to be reloaded with a new one.

bool sound::close();

Returns:

bool: true if the sound could be closed, false otherwise for example if there is no sound opened.

Example:
void main() {
	sound s;
	s.load("C:/windows/media/ding.wav");
	alert("example", s.close()); // Will display true since a sound was previously opened.
	alert("example", s.close()); // Will now display false since the previous operation freed the sound object of any attached sound.
}
load

Loads a sound file with the specified settings.

  1. bool sound::load(string filename, pack@ soundpack = null, bool allow_preloads = true);
  2. bool sound::load(sound_close_callback@ close_cb, sound_length_callback@ length_cb, sound_read_callback@ read_cb, sound_seek_callback@ seek_cb, string data, string preload_filename = "");
Arguments (1):
Arguments (2):
Returns:

bool: true if the sound was successfully loaded, false otherwise.

Remarks:

The syntax for the sound_close_callback is:

void sound_close_callback(string user_data);

The syntax for the sound_length_callback is:

uint sound_length_callback(string user_data);

The syntax for the sound_read_callback is:

int sound_read_callback(string&out buffer, uint length, string user_data);

The syntax for the sound_seek_callback is:

bool sound_seek_callback(uint offset, string user_data);

pause

Pauses the sound.

bool sound::pause();

Returns:

bool: true if the sound was paused, false otherwise.

play

Starts playing the sound.

bool sound::play();

Returns:

bool: true if the sound was able to start playing, false otherwise.

play_looped

Starts playing the sound repeatedly.

bool sound::play_looped();

Returns:

bool: true if the sound was able to start playing, false otherwise.

play_wait

Starts playing the sound, blocking the calling thread until it's finished.

bool sound::play_wait();

Returns:

bool: true if the sound has successfully loaded and finished playing, false otherwise.

seek

Seeks to a particular point in the sound.

bool sound::seek(float ms);

Arguments:
Returns:

bool: true if the seeking was successful, false otherwise.

set_position

Sets the sound's position in 3d space.

bool sound::set_position(float listener_x, float listener_y, float listener_z, float sound_x, float sound_y, float sound_z, float rotation, float pan_step, float volume_step);

Arguments:
Returns:

bool: true if the position was successfully set, false otherwise.

stop

Stops the sound, if currently playing.

bool sound::stop();

Returns:

bool: true if the sound was successfully stopped, false otherwise.

stream_url

Load the specified URL.

bool sound::load_url(string url);

Arguments:
Returns:

Bool: True if the URL was successfully loaded; false otherwise.

Remarks:

This function should currently be considered beta.

Example:
void main() {
	sound s;
	bool success = s.stream_url("https://example.com/my_sound.mp3");
	alert("Result", "The sound is " + (success == false? "not " : "") + "ready to stream.");
}

Properties

active

Determine if the sound has successfully been loaded or not.

bool sound::active;

length

Get the length of a sound (in milliseconds).

float sound::length;

loaded_filename

Obtain the path of sound file that has been loaded.

string sound::loaded_filename;

paused

Determine if the sound is paused.

bool sound::paused;

playing

Determine if the sound is currently playing.

bool sound::playing;

Enums

audio_attenuator

This is a list of the built-in attenuators, which control how a positioned sound gets quieter with distance. These values are used with sound_default_3d_attenuator and set_sound_default_3d_attenuator().

audio_error_state

This is a list of the result codes that the sound system can report through SOUNDSYSTEM_LAST_ERROR.

The codes come from miniaudio, the library underneath NVGT's audio engine. AUDIO_ERROR_STATE_SUCCESS is 0 and every error is negative. Many of the general codes are shared with file and network operations, so not all of them can occur in practice. For a description of the current error, read SOUNDSYSTEM_LAST_ERROR_TEXT.

audio_panner

This is a list of the built-in panners, which control how a positioned sound is placed between the speakers. These values are used with sound_default_3d_panner and set_sound_default_3d_panner().

Global Properties

sound_default_3d_attenuator

The attenuator that newly positioned sounds use to make themselves quieter with distance.

const int sound_default_3d_attenuator;

void set_sound_default_3d_attenuator(int attenuator_id);

Arguments (set_sound_default_3d_attenuator):

Remarks:

This property is read only. To change it, call set_sound_default_3d_attenuator().

The default is audio_attenuator_basic. audio_attenuator_phonon uses Steam Audio's distance attenuation instead. Calling set_sound_global_hrtf(true) sets this property to audio_attenuator_phonon and also enables that attenuator.

The default only affects sounds that start being positioned after it changes. It is used when a sound hasn't been given an attenuator of its own.

Example:

void main() {
	alert("Default attenuator", sound_default_3d_attenuator == audio_attenuator_basic ? "basic" : "Steam Audio");
	if (set_sound_global_hrtf(true))
		alert("Default attenuator after enabling HRTF", sound_default_3d_attenuator == audio_attenuator_basic ? "basic" : "Steam Audio");
	set_sound_global_hrtf(false);
	set_sound_default_3d_attenuator(audio_attenuator_basic);
}

sound_default_3d_panner

The panner that newly positioned sounds use to place themselves between the speakers.

const int sound_default_3d_panner;

void set_sound_default_3d_panner(int panner_id);

Arguments (set_sound_default_3d_panner):

Remarks:

This property is read only. To change it, call set_sound_default_3d_panner().

The default is audio_panner_basic, which pans sounds with simple left and right volume changes. audio_panner_phonon_hrtf uses Steam Audio's HRTF processing to make sounds seem to come from a direction around the listener, and works best with headphones. Calling set_sound_global_hrtf(true) sets this property to audio_panner_phonon_hrtf and also enables that panner, which is easier than changing the panner yourself.

The default only affects sounds that start being positioned after it changes. It is used when a sound hasn't been given a panner of its own.

Example:

void main() {
	alert("Default panner", sound_default_3d_panner == audio_panner_basic ? "basic" : "HRTF");
	if (set_sound_global_hrtf(true))
		alert("Default panner after enabling HRTF", sound_default_3d_panner == audio_panner_basic ? "basic" : "HRTF");
	set_sound_global_hrtf(false);
	set_sound_default_3d_panner(audio_panner_basic);
}

sound_default_decryption_key

Sets the key used to decrypt sound files that were encrypted with the asset_encryptor datastream.

string sound_default_decryption_key;

Remarks:

This property can only be assigned, not read. Assign an empty string to stop decrypting sounds.

While a key is set, sounds loaded with sound::load() or sound::stream() are decrypted with it, whether they are loaded from disk or from a pack. Files that aren't encrypted still load normally while a key is set.

Set the key before you load an encrypted file for the first time. If sound::load() fails on an encrypted file because the right key wasn't set yet, later loads of the same filename keep failing even after the key is set. Streaming the file with sound::stream() is not affected.

When encrypting a file with asset_encryptor, close both the encryptor and the underlying file before loading the result, otherwise the end of the data may not have been written to disk yet.

Example:

void main() {
	// Create an encrypted sound to load. A real game would do this ahead of time.
	tone_synth synth;
	synth.freq_ms(440, 250);
	synth.write_wave_file("tone.wav");
	file input("tone.wav", "rb");
	string data = input.read();
	input.close();
	file output("tone.dat", "wb");
	asset_encryptor encryptor(output, "my secret key");
	encryptor.write(data);
	encryptor.close();
	output.close();
	// Now load it.
	sound_default_decryption_key = "my secret key";
	sound s;
	alert("Loading the encrypted sound", s.load("tone.dat") ? "succeeded" : "failed");
	s.close();
	file_delete("tone.wav");
	file_delete("tone.dat");
}

sound_default_engine

The audio engine used by sounds and audio nodes that aren't given one explicitly.

audio_engine@ sound_default_engine;

Remarks:

New sound objects, the sound_play() function and the constructors of most audio classes use this engine unless you pass a different one. Properties such as sound_output_device and sound_master_volume also act on this engine.

You can assign a different engine, for example one created with the AUDIO_ENGINE_NO_DEVICE flag so that audio is rendered into memory instead of being played. Only sounds created after the assignment use the new engine, while existing sounds keep the engine they were created with. Assigning null throws an exception, because a default engine must always exist.

Reading this property starts the sound system if it hasn't been started yet.

Example:

void main() {
	audio_engine@ engine = sound_default_engine;
	alert("Default engine", "The default engine has " + engine.get_output_channels(0) + " output channels.");
}

sound_default_mixer

The mixer that newly created sounds are attached to.

mixer@ sound_default_mixer;

Remarks:

This is null by default, which means new sounds play directly through the audio engine. If you assign a mixer, every sound created afterwards is attached to it, so you can control the volume or effects of all your sounds in one place. Sounds that already exist are not moved.

A sound can still be moved to a different mixer at any time with sound::set_mixer().

Example:

void main() {
	mixer game_sounds;
	@sound_default_mixer = game_sounds;
	sound s; // This sound is attached to game_sounds automatically.
	alert("Attached to the default mixer", s.get_mixer() is game_sounds ? "yes" : "no");
	@sound_default_mixer = null;
}

sound_default_pack

The pack that sounds are loaded from when no pack is passed to sound::load() or sound::stream().

pack_interface@ sound_default_pack;

Remarks:

This is null by default, which means sounds are loaded from files on disk. Assign an open pack_file to load sounds from that pack instead, and assign null to go back to loading from disk.

The pack must be open for reading when it is assigned, otherwise an exception is thrown. Always check the return value of pack_file::open() before assigning the pack. Reading the property returns the same pack object that was assigned, so you can get the pack_file back with cast<pack_file@>(sound_default_pack).

This value is also the default for the pack argument of sound_play() and other functions that load audio.

Example:

void main() {
	// Build a pack containing a short tone, then load the tone from it.
	tone_synth synth;
	synth.freq_ms(440, 250);
	synth.write_wave_file("tone.wav");
	pack_file p;
	p.create("sounds.dat");
	p.add_file("tone.wav", "tone.wav");
	p.close();
	file_delete("tone.wav");
	p.open("sounds.dat");
	@sound_default_pack = p;
	sound s;
	alert("Loading tone.wav from the pack", s.load("tone.wav") ? "succeeded" : "failed");
	s.close();
	@sound_default_pack = null;
	p.close();
	file_delete("sounds.dat");
}

sound_global_hrtf

Determine whether sounds are positioned using Steam Audio's HRTF processing.

const bool sound_global_hrtf;

bool set_sound_global_hrtf(bool enabled);

Arguments (set_sound_global_hrtf):

Returns (set_sound_global_hrtf):

bool: true if the setting was applied (or was already in effect), false if Steam Audio couldn't be initialized.

Remarks:

This property is read only. To change it, call set_sound_global_hrtf().

HRTF (head related transfer function) processing makes positioned sounds seem to come from a direction around the listener, including in front, behind, above and below, and works best with headphones. When it is disabled, sounds are positioned with simple left and right panning and distance attenuation.

Enabling HRTF sets sound_default_3d_panner to audio_panner_phonon_hrtf and sound_default_3d_attenuator to audio_attenuator_phonon.

Example:

void main() {
	if (!set_sound_global_hrtf(true)) {
		alert("Error", "HRTF could not be enabled.");
		return;
	}
	alert("HRTF", sound_global_hrtf ? "enabled" : "disabled");
	set_sound_global_hrtf(false);
	alert("HRTF", sound_global_hrtf ? "enabled" : "disabled");
}

sound_input_devices

A list of the names of all sound input devices, such as microphones, available on the system.

const string[]@ sound_input_devices;

Remarks:

The index of a device in this array is the device number accepted by the microphone constructor. Passing -1 instead of an index selects the system's default input device.

The array may be empty if the system has no input devices. It is the same array every time you access this property, so don't modify it. Make a copy first if you want to change it, for example to build a menu.

Reading this property starts the sound system if it hasn't been started yet.

Example:

void main() {
	const string[]@ devices = sound_input_devices;
	if (devices.length() == 0) {
		alert("Input devices", "No input devices were found.");
		return;
	}
	alert("Input devices", "The following input devices are available: " + join(devices, ", "));
}

sound_master_volume

The master volume of the default audio engine, in decibels.

float sound_master_volume;

Remarks:

This volume applies on top of the volume of every sound and mixer played through the default audio engine. 0 is full volume and -100 is silent. Values above 0 or below -100 are ignored and leave the volume unchanged.

Accessing this property starts the sound system if it isn't running yet, so it can be set at any time, including at the very start of your game.

Example:

void main() {
	sound_master_volume = -10;
	alert("Master volume", "The master volume is now " + sound_master_volume + " dB.");
	sound_master_volume = 0;
}

sound_output_device

The output device that the default audio engine plays sound through.

int sound_output_device;

Remarks:

The value is an index into the sound_output_devices array. Assign an index to switch devices, or assign -1 to use the system's default output device.

When read, this property returns the index of the device actually in use, so after assigning -1 it returns the index of the default device rather than -1. It returns -1 if the default audio engine has no device, for example if sound_default_engine was replaced with an engine created with AUDIO_ENGINE_NO_DEVICE.

Assigning an index that is out of range, or a device that can't be opened, has no effect and doesn't raise an error. Read the property again after assigning it if you need to know whether the switch succeeded.

Accessing this property starts the sound system if it hasn't been started yet.

Example:

void main() {
	int device = sound_output_device;
	if (device < 0) {
		alert("Output device", "No output device is in use.");
		return;
	}
	alert("Output device", "Sound is playing through " + sound_output_devices[device] + ".");
}

sound_output_devices

A list of the names of all sound output devices available on the system.

const string[]@ sound_output_devices;

Remarks:

The index of a device in this array is the value you assign to sound_output_device to switch to that device. Assigning -1 instead selects the system's default output device.

It is the same array every time you access this property, so don't modify it. Make a copy first if you want to change it, for example to build a menu.

Reading this property starts the sound system if it hasn't been started yet.

Example:

void main() {
	const string[]@ devices = sound_output_devices;
	if (devices.length() == 0) {
		alert("Output devices", "No output devices were found.");
		return;
	}
	alert("Output devices", "The following output devices are available: " + join(devices, ", "));
}

SOUNDSYSTEM_LAST_ERROR

The result code of the most recent sound system operation that reported one.

const audio_error_state SOUNDSYSTEM_LAST_ERROR;

Remarks:

This is one of the values in the audio_error_state enum. It is AUDIO_ERROR_STATE_SUCCESS (0) if the most recent operation succeeded, and a negative value if it failed.

Not every audio function updates this value, and some functions fail before reaching the point where it is set. It is most useful right after a call that returned false, such as sound::load(), to find out why. Use SOUNDSYSTEM_LAST_ERROR_TEXT to get a description of the error.

Example:

void main() {
	sound s;
	if (!s.load("this_file_does_not_exist.ogg"))
		alert("Unable to load the sound", "Error code " + SOUNDSYSTEM_LAST_ERROR + ": " + SOUNDSYSTEM_LAST_ERROR_TEXT);
}

SOUNDSYSTEM_LAST_ERROR_TEXT

A short English description of the error code in SOUNDSYSTEM_LAST_ERROR.

const string SOUNDSYSTEM_LAST_ERROR_TEXT;

Remarks:

If the most recent operation succeeded, this is "No error". The descriptions are general, for example a sound that failed to load may only report "Unknown error", so treat this as a hint for debugging rather than a message to show players.

Example:

void main() {
	sound s;
	if (!s.load("this_file_does_not_exist.ogg"))
		alert("Unable to load the sound", SOUNDSYSTEM_LAST_ERROR_TEXT);
}