Sound Functions

From SolarStrike wiki
Jump to: navigation, search

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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.