Difference between revisions of "Scripting/SAudioSource"

Revision as of 09:29, 5 January 2021

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

TimeSamples

int TimeSamples {get; set;}

Playback position in PCM samples.

local Object = Space.Scene.Find("Audio Source")

Space.Log(Object.Audio.TimeSamples)

Length

float Length {get; set;}

Return Audio Length.

local Object = Space.Scene.Find("Audio Source")

Space.Log(Object.Audio.Length)

Samples

bool Samples {get; set;}

Return Audio Samples.

local Object = Space.Scene.Find("Audio Source")

Space.Log(Object.Audio.Samples)

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 ResourceshostObject = 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)!

@@ Line 116: / Line 116: @@
 hostObject.Audio.Time = 75;<br>
 ''-- jumps to the 1:15 position of the sound clip''}}
+{{ScriptFunction|int|TimeSamples|{get; set;}|Playback position in PCM samples. |5=
+local Object = Space.Scene.Find("Audio Source")<br>
+Space.Log(Object.Audio.TimeSamples)}}
+{{ScriptFunction|float|Length|{get; set;}|Return Audio Length.|5=
+local Object = Space.Scene.Find("Audio Source")<br>
+Space.Log(Object.Audio.Length)}}
+{{ScriptFunction|bool|Samples|{get; set;}|Return Audio Samples.|5=
+local Object = Space.Scene.Find("Audio Source")<br>
+Space.Log(Object.Audio.Samples)}}
 {{ScriptFunction|bool|IsPlaying|{get;}|Is the sound clip playing right now? |5=

Navigation

User Portal

Creation Portal

Tools