Scripting/SAudioSource

From sine.space Wiki
Jump to: navigation, search

The SAudioSource class deals with the Audio Source component, which allows the object to play sounds in the scene.

Members

Play

void Play ()

Starts playing the audio clip.

-- For example, we have a short chime that we want to play every time a new avatar joins the scene.

hostObject = Space.Host.ExecutingObject;

function welcomeSound ()

hostObject.Audio.Play();

end

Space.Scene.OnPlayerJoin(welcomeSound);

Stop

void Stop ()

Stops playing the audio clip.

hostObject = Space.Host.ExecutingObject;

function audioOnOff ()

if hostObject.Audio.IsPlaying then
hostObject.Audio.Stop();
else
hostObject.Audio.Play();
end
Space.Log(hostObject.Audio.IsPlaying);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(audioOnOff);

-- Now, we can make the sound play or stop playing just by clicking the object.

Pause

void Pause ()

Pauses the audio clip.

hostObject = Space.Host.ExecutingObject;

function pauseOnOff ()

if hostObject.Audio.IsPlaying then
hostObject.Audio.Pause();
else
hostObject.Audio.UnPause();
end
Space.Log(hostObject.Audio.IsPlaying);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(pauseOnOff);

-- Now, every time an object is clicked, the sound clip is paused/unpaused

UnPause

void UnPause ()

Unpauses the audio clip.

See the code example for Pause ().

PlayOneShot

void PlayOneShot (SResource clip, float volume)

Plays the audio clip just ones at a desired volume.

hostObject = Space.Host.ExecutingObject;

function playOnce ()

hostObject.Audio.PlayOneShot(Space.Resources[0],0.5);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(playOnce);
-- Now, every time the object is clicked, a sound clip we have in Scripting Runtime Resources is played at half the volume.

-- This happens regardless if the audio clip in the AudioClip property is playing or not.

Properties

Enabled

bool Enabled {get;set;}

Is the Audio Source component enabled?

hostObject = Space.Host.ExecutingObject;

function audioOnOff ()

hostObject.Audio.Enabled = not hostObject.Audio.Enabled;
Space.Log(hostObject.Audio.Enabled);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(audioOnOff);
-- When the host object is clicked, the Audio Source component gets enabled, if it was disabled,

-- or disabled, if it was enabled, and its new state is printed to the console.

Loop

bool Loop {get;set;}

Is looping of the sound clip enabled?

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.Loop);
-- False by default.

if not hostObject.Audio.Loop then

hostObject.Audio.Loop = true;

end

-- Now it is looping.

DopplerLevel

float DopplerLevel {get;set;}

The Doppler level of the Audio Source. (See: Doppler Effect)

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.DopplerLevel);
-- 1 by default
hostObject.Audio.DopplerLevel = 5;

-- The highest possible value

Volume

float Volume {get;set;}

The Volume level of the Audio Source.

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.Volume);
-- 1 by default

function audioVolumeDecr ()

if hostObject.Audio.Volume > 0 then
hostObject.Audio.Volume = hostObject.Audio.Volume - 0.2;
end
Space.Log(hostObject.Audio.Volume);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(audioVolumeDecr);

-- Now, every time we click this object, the Volume level is decreased by 0.2, until it reaches 0.

Pitch

float Pitch {get;set;}

The Pitch level for the Audio Source.

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.Pitch);
-- 1 by default

function audioPitchChange ()

if hostObject.Audio.Pitch < 3 then
hostObject.Audio.Pitch = hostObject.Audio.Pitch + 0.5;
end
Space.Log(hostObject.Audio.Pitch);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(audioPitchChange);

-- Now, every time we click this object, the Pitch level is increased by 0.5, until it reaches 3.

Time

float Time {get;set;}

Playback position in seconds.

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.Time);
-- 0 by default (the beginning of the sound clip)
hostObject.Audio.Time = 15;
-- jumps to the 0:15 position of the sound clip
hostObject.Audio.Time = 75;

-- jumps to the 1:15 position of the sound clip

IsPlaying

bool IsPlaying {get;}

Is the sound clip playing right now?

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.IsPlaying);

-- prints True (by default), if the sound clip is playing, or False, if it doesn't, to the console

PanStereo

float PanStereo {get;set;}

Pans the sound to the left or right. Values range from -1 to 1: 0 is the middle, -1 is full left, 1 is full right.

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.PanStereo);
-- Prints the current Pan Stereo level (0 by default)
hostObject.Audio.PanStereo = 0.5;

-- Pans the sound halfway from the middle to the right

SpatialBlend

float SpatialBlend {get;set;}

The level of impact 3D effects make on the AudioSource. 0 - no impact (full 2D sound), 1 - maximum impact (full 3D sound).

hostObject = Space.Host.ExecutingObject;

function spBlendChange ()

if hostObject.Audio.SpatialBlend < 1 then
hostObject.Audio.SpatialBlend = hostObject.Audio.SpatialBlend + 0.2;
else
hostObject.Audio.SpatialBlend = 0;
end
Space.Log(hostObject.Audio.SpatialBlend);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(spBlendChange);
-- Spatial Blend is increased by 0.2 every time the object is clicked, until it reaches 1.

-- Then with the next click, it resets back to 0.

Spatialize

bool Spatialize {get;set;}

Is spatialization enabled?

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.Spatialize);
-- Prints the current state of spatialization (False by default) to the console
hostObject.Audio.Spatialize = true;

-- Now spatialization is enabled

SpatializePostEffects

bool SpatializePostEffects {get;set;}

Is spatialization enabled before or after other filters are in action?

hostObject = Space.Host.ExecutingObject;

-- Because enabling this property makes sense only if spatialization itself is enabled, let's enable it first.
hostObject.Audio.Spatialize = true;

if hostObject.Audio.Spatialize then

hostObject.Audio.SpatializePostEffects = true;

end

Space.Log(hostObject.Audio.SpatializePostEffects);

-- prints "True" to the console

ReverbZoneMix

float ReverbZoneMix {get;set;}

The level at which the audio coming from this Audio Source will be mixed into the global reverb of the scene (accomplished with Reverb Zones).

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.ReverbZoneMix);
-- prints "1" to the console (by default) - normal level of mixing in
hostObject.Audio.ReverbZoneMix = 0.5;

-- Now this audio will be fainter by half in the global reverb.

BypassEffects

bool BypassEffects {get;set;}

When true, none of global sound effects (reverbs, filters, etc.) are applied to the audio from this Audio Source.

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.BypassEffects);
-- prints "False" to the console (by default);
hostObject.Audio.BypassEffects = true;

-- Now the sound is not affected by any global effects.

BypassListenerEffects

bool BypassListenerEffects {get;set;}

When true, whichever global effects are set on the Audio Listener will not be applied to the audio from this Audio Source.

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.BypassListenerEffects);
-- prints "False" to the console (by default);
hostObject.Audio.BypassListenerEffects = true;

-- Now the sound is not affected by any global effects on Audio Listeners.

BypassReverbZones

bool BypassReverbZones {get;set;}

When true, the audio from this Audio Source is not mixed into the global reverb generated through Reverb Zones.

hostObject = Space.Host.ExecutingObject;

Space.Log(hostObject.Audio.BypassReverbZones);
-- prints "False" to the console (by default);
hostObject.Audio.BypassReverbZones = true;

-- Now the sound is not mixed into the global reverb.

Spread

float Spread {get;set;}

The angle of spread of the audio channels in the 3D space (only works for stereo and multichannel audio). 0 by default - all channels are concentrated at the same speaker location, making it "mono".

hostObject = Space.Host.ExecutingObject;

function increaseSpread ()

if hostObject.Audio.Spread < 360 then
hostObject.Audio.Spread = hostObject.Audio.Spread + 90;
end
Space.Log(hostObject.Audio.Spread);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(increaseSpread);

-- Every time an object is clicked, the spread increases by 90 degrees - compare the sound at different angles of spread!


Priority

int Priority {get;set;}

The priority of this Audio Source: when there are more Audio Sources playing than channels available, Priority defines which channels will be discarded in favour of those with a higher priority. 0 is the highest priority, 255 - the lowest.

hostObject = Space.Host.ExecutingObject;

function changePriority ()

if hostObject.Audio.Priority == 0 then
hostObject.Audio.Priority = 255;
else
hostObject.Audio.Priority = 0;
end
Space.Log(hostObject.Audio.Priority);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(changePriority);
-- Now the Audio Source alternates between the highest and the lowest priorities.
-- This can be useful, for example, in a scene with an ambient sound set at Priority 128, where we have a speaker, which plays a certain looped audio nonstop.
-- When we want to hear the audio, we change it to the highest priority, so it blocks the ambient sound.

-- When we don't, we change it to the lowest, and the ambient sound dominates the scene again.

Mute

bool Mute {get;set;}

Is the audio muted? If True, the Volume is set to 0. If False, the Volume is restored to the original level.

hostObject = Space.Host.ExecutingObject;

function muteOnOff ()

hostObject.Audio.Mute = not hostObject.Audio.Mute;
Space.Log(hostObject.Audio.Mute);

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(muteOnOff);

-- Now clicking the object works like the Mute button.

MinDistance

float MinDistance {get;set;}

At which distance from the Audio Source the sound will begin ceasing? The sound will be heard at its maximum volume within this distance. (Spatial Blend should not be equal to 0 for this property to take effect.)

hostObject = Space.Host.ExecutingObject;

hostObject.Audio.MinDistance = 10;
-- Now the sound will be heard at its maximum volume within 10 metres from the Audio Source.

-- If the listener moves further than 10 metres away, it will begin ceasing.

MaxDistance

float MaxDistance {get;set;}

At which distance from the Audio Source the sound will no longer be heard? (Spatial Blend should not be equal to 0 for this property to take effect.)

hostObject = Space.Host.ExecutingObject;

hostObject.Audio.MaxDistance = 100;

-- Now the sound will be heard within 100 metres from the Audio Source.

AudioClip

SResource AudioClip {get;set;}

The audio clip that is or will be played by this Audio Source.

-- In this example, there are 3 audio clips in Scripting Runtime Resources

hostObject = Space.Host.ExecutingObject;
local nextTrack = 0;

function changeTrack ()

hostObject.Audio.AudioClip = Space.Resources[nextTrack];
hostObject.Audio.Play();
Space.Log(Space.Resources[nextTrack].Name);
if nextTrack == 2 then -- replace 2 with n-1, where n is the amount of audio clips you have added to Resources
nextTrack = 0;
else
nextTrack = nextTrack + 1;
end

end

hostObject.SubscribeToEvents();
hostObject.OnMouseDown(changeTrack);
-- Now, every time the object is clicked, the next audio clip is played.

-- What's more, the list is looped (the index resets back to 0 when it gets to the end of the list)!