Sound Functions

Please note that, while playing sounds, that the sound resource must stay loaded. If the sound resource is unloaded at any time, the sound will be forcefully stopped. This means that if your script finishes execution, all sounds are unloaded and stopped.

soundLoad

sound soundLoad(filename)

Loads a sound file (must be compatible with OpenAL). Nothing else. Returns the sound resource on success or nil on failure.

Example

local sound = soundLoad(getExecutionPath() .. "/sound.wav");

soundPlay

soundPlay(sound)

Plays a sound that has already been loaded.

Example

local sound = soundLoad(getExecutionPath() .. "/sound.wav");
if( sound ) then -- make sure it was loaded
  soundPlay(sound);
end

soundStop

soundStop(sound)

Stops a sound if it is playing.

Example

local sound = soundLoad(getExecutionPath() .. "/sound.wav");
soundPlay(sound);
yrest(500); -- Let it play for 500ms, otherwise we won't hear anything
soundStop(sound);
soundPlay(sound); -- Starts playing the sound from the beginning

soundPause

soundPause(sound)

Pauses a playing sound so that it can be continued later.

Example

local sound = soundLoad(getExecutionPath() .. "/sound.wav");
soundPlay(sound);
yrest(500); -- Play the first 500ms of it
soundPause(sound);
yrest(1000); -- Wait one second, then resume playing
soundPlay(sound);

soundGetState

string soundGetState(sound)

Returns the current state of a sound as a string. Possible returned values include: playing, paused, stopped, initial. "playing", "paused", and "stopped" are self explanatory, but "initial" refers to a sound resource that has been loaded and not messed with at all yet.

Example

local sound = soundLoad(getExecutionPath() .. "/sound.wav");
print("State:", soundGetState(sound));
-- This will print: State:  initial

soundSetVolume

soundSetVolume(sound, volume)

Allows you to change the volume of a loaded sound resource. 'volume' should be between 0.0 (no sound) to 1.0 (max volume), normally. The volume can exceed 1.0 if your sound card supports it (this would effectively make the sound louder, obviously).

Example

local sound = soundLoad(getExecutionPath() .. "/sound.wav");
soundSetVolume(sound, 0.5);
soundPlay(sound); -- Will now not be as loud.

soundSetLooping

soundSetLooping(sound, loop)

Sets whether a sound should loop or stop after it has finished playing. 'loop' should be either true (loop) or false (stop, the default). You should change this before playing the sound.

Example

local sound = soundLoad(getExecutionPath() .. "/sound.wav");
soundSetLooping(sound, true);
soundPlay(sound); -- Will now loop continually until told to stop.