|
|
| (8 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | The SAudioSource class deals with the Audio Source component, which allows the object to play sounds in the scene.
| + | This page has moved to: https://docs.sine.space/v/scripting/client-scripting/components/saudiosource |
| − | | + | |
| − | ==Members==
| + | |
| − | | + | |
| − | {{ScriptFunction|void|Play|()|Starts playing the audio clip.|5=
| + | |
| − | ''-- For example, we have a short chime that we want to play every time a new avatar joins the scene.''
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function welcomeSound ()<br>
| + | |
| − | :hostObject.Audio.Play();<br> | + | |
| − | end<br><br>
| + | |
| − | Space.Scene.OnPlayerJoin(welcomeSound);}}
| + | |
| − | | + | |
| − | {{ScriptFunction|void|Stop|()|Stops playing the audio clip.|5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function audioOnOff ()<br>
| + | |
| − | :if hostObject.Audio.IsPlaying then<br> | + | |
| − | ::hostObject.Audio.Stop();<br>
| + | |
| − | :else<br>
| + | |
| − | ::hostObject.Audio.Play();<br>
| + | |
| − | :end<br>
| + | |
| − | :Space.Log(hostObject.Audio.IsPlaying);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(audioOnOff);<br>
| + | |
| − | ''-- Now, we can make the sound play or stop playing just by clicking the object.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|void|Pause|()|Pauses the audio clip.|5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function pauseOnOff ()<br>
| + | |
| − | :if hostObject.Audio.IsPlaying then<br>
| + | |
| − | ::hostObject.Audio.Pause();<br>
| + | |
| − | :else<br>
| + | |
| − | ::hostObject.Audio.UnPause();<br>
| + | |
| − | :end<br>
| + | |
| − | :Space.Log(hostObject.Audio.IsPlaying);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(pauseOnOff);<br>
| + | |
| − | ''-- Now, every time an object is clicked, the sound clip is paused/unpaused''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|void|UnPause|()|Unpauses the audio clip.|See the code example for Pause ().}}
| + | |
| − | | + | |
| − | {{ScriptFunction|void|PlayOneShot|(SResource clip, float volume)|Plays the audio clip just ones at a desired volume.|5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function playOnce ()<br>
| + | |
| − | :hostObject.Audio.PlayOneShot(Space.Resources[0],0.5);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(playOnce);<br>
| + | |
| − | ''-- 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==
| + | |
| − | | + | |
| − | {{ScriptFunction|bool|Enabled|{get;set;}|Is the Audio Source component enabled?|5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function audioOnOff ()<br>
| + | |
| − | :hostObject.Audio.Enabled = not hostObject.Audio.Enabled;<br>
| + | |
| − | :Space.Log(hostObject.Audio.Enabled);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(audioOnOff);<br>
| + | |
| − | ''-- When the host object is clicked, the Audio Source component gets enabled, if it was disabled,'' <br>
| + | |
| − | ''-- or disabled, if it was enabled, and its new state is printed to the console.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|bool|Loop|{get;set;}|Is looping of the sound clip enabled?|5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.Loop);<br>
| + | |
| − | ''-- False by default.''<br><br>
| + | |
| − | if not hostObject.Audio.Loop then<br>
| + | |
| − | :hostObject.Audio.Loop = true;<br>
| + | |
| − | end<br>
| + | |
| − | ''-- Now it is looping.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|float|DopplerLevel|{get;set;}|The Doppler level of the Audio Source. (See: Doppler Effect)|5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.DopplerLevel);<br>
| + | |
| − | ''-- 1 by default''<br>
| + | |
| − | hostObject.Audio.DopplerLevel = 5;<br>
| + | |
| − | ''-- The highest possible value''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|float|Volume|{get;set;}|The Volume level of the Audio Source. |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br>
| + | |
| − | Space.Log(hostObject.Audio.Volume);<br>
| + | |
| − | ''-- 1 by default''<br><br>
| + | |
| − | function audioVolumeDecr ()<br>
| + | |
| − | :if hostObject.Audio.Volume > 0 then<br>
| + | |
| − | ::hostObject.Audio.Volume = hostObject.Audio.Volume - 0.2;<br>
| + | |
| − | :end<br>
| + | |
| − | :Space.Log(hostObject.Audio.Volume);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(audioVolumeDecr);<br>
| + | |
| − | ''-- Now, every time we click this object, the Volume level is decreased by 0.2, until it reaches 0.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|float|Pitch|{get;set;}|The Pitch level for the Audio Source. |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br>
| + | |
| − | Space.Log(hostObject.Audio.Pitch);<br>
| + | |
| − | ''-- 1 by default''<br><br>
| + | |
| − | function audioPitchChange ()<br>
| + | |
| − | :if hostObject.Audio.Pitch < 3 then<br>
| + | |
| − | ::hostObject.Audio.Pitch = hostObject.Audio.Pitch + 0.5;<br>
| + | |
| − | :end<br>
| + | |
| − | :Space.Log(hostObject.Audio.Pitch);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(audioPitchChange);<br>
| + | |
| − | ''-- Now, every time we click this object, the Pitch level is increased by 0.5, until it reaches 3.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|float|Time|{get;set;}|Playback position in seconds. |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.Time);<br>
| + | |
| − | ''-- 0 by default (the beginning of the sound clip)''<br>
| + | |
| − | hostObject.Audio.Time = 15;<br>
| + | |
| − | ''-- jumps to the 0:15 position of the sound clip''<br>
| + | |
| − | hostObject.Audio.Time = 75;<br>
| + | |
| − | ''-- jumps to the 1:15 position of the sound clip''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|bool|IsPlaying|{get;}|Is the sound clip playing right now? |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.IsPlaying);<br>
| + | |
| − | ''-- prints True (by default), if the sound clip is playing, or False, if it doesn't, to the console''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|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. |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.PanStereo);<br>
| + | |
| − | ''-- Prints the current Pan Stereo level (0 by default)''<br>
| + | |
| − | hostObject.Audio.PanStereo = 0.5;<br>
| + | |
| − | ''-- Pans the sound halfway from the middle to the right''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|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).|5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function spBlendChange ()<br>
| + | |
| − | :if hostObject.Audio.SpatialBlend < 1 then<br>
| + | |
| − | ::hostObject.Audio.SpatialBlend = hostObject.Audio.SpatialBlend + 0.2;<br>
| + | |
| − | :else<br>
| + | |
| − | ::hostObject.Audio.SpatialBlend = 0;<br>
| + | |
| − | :end<br>
| + | |
| − | :Space.Log(hostObject.Audio.SpatialBlend);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(spBlendChange);<br>
| + | |
| − | ''-- 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.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|bool|Spatialize|{get;set;}|Is spatialization enabled? |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br>
| + | |
| − | Space.Log(hostObject.Audio.Spatialize);<br>
| + | |
| − | ''-- Prints the current state of spatialization (False by default) to the console''<br>
| + | |
| − | hostObject.Audio.Spatialize = true;<br>
| + | |
| − | ''-- Now spatialization is enabled''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|bool|SpatializePostEffects|{get;set;}|Is spatialization enabled before or after other filters are in action? |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br>
| + | |
| − | ''-- Because enabling this property makes sense only if spatialization itself is enabled, let's enable it first.''<br>
| + | |
| − | hostObject.Audio.Spatialize = true;<br><br>
| + | |
| − | if hostObject.Audio.Spatialize then<br>
| + | |
| − | :hostObject.Audio.SpatializePostEffects = true;<br>
| + | |
| − | end<br><br>
| + | |
| − | Space.Log(hostObject.Audio.SpatializePostEffects);<br>
| + | |
| − | ''-- prints "True" to the console''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|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). |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.ReverbZoneMix);<br>
| + | |
| − | ''-- prints "1" to the console (by default) - normal level of mixing in''<br>
| + | |
| − | hostObject.Audio.ReverbZoneMix = 0.5;<br>
| + | |
| − | ''-- Now this audio will be fainter by half in the global reverb.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|bool|BypassEffects|{get;set;}|When true, none of global sound effects (reverbs, filters, etc.) are applied to the audio from this Audio Source. |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.BypassEffects);<br>
| + | |
| − | ''-- prints "False" to the console (by default);''<br>
| + | |
| − | hostObject.Audio.BypassEffects = true;<br>
| + | |
| − | ''-- Now the sound is not affected by any global effects.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|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. |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.BypassListenerEffects);<br>
| + | |
| − | ''-- prints "False" to the console (by default);''<br>
| + | |
| − | hostObject.Audio.BypassListenerEffects = true;<br>
| + | |
| − | ''-- Now the sound is not affected by any global effects on Audio Listeners.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|bool|BypassReverbZones|{get;set;}|When true, the audio from this Audio Source is not mixed into the global reverb generated through Reverb Zones.|5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | Space.Log(hostObject.Audio.BypassReverbZones);<br>
| + | |
| − | ''-- prints "False" to the console (by default);''<br>
| + | |
| − | hostObject.Audio.BypassReverbZones = true;<br>
| + | |
| − | ''-- Now the sound is not mixed into the global reverb.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|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". |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function increaseSpread ()<br>
| + | |
| − | :if hostObject.Audio.Spread < 360 then<br>
| + | |
| − | ::hostObject.Audio.Spread = hostObject.Audio.Spread + 90;<br>
| + | |
| − | :end<br>
| + | |
| − | :Space.Log(hostObject.Audio.Spread);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(increaseSpread);<br>
| + | |
| − | ''-- Every time an object is clicked, the spread increases by 90 degrees - compare the sound at different angles of spread!''}}
| + | |
| − | | + | |
| − | | + | |
| − | {{ScriptFunction|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. |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function changePriority ()<br>
| + | |
| − | :if hostObject.Audio.Priority == 0 then<br>
| + | |
| − | ::hostObject.Audio.Priority = 255;<br>
| + | |
| − | :else <br>
| + | |
| − | ::hostObject.Audio.Priority = 0;<br>
| + | |
| − | :end<br>
| + | |
| − | :Space.Log(hostObject.Audio.Priority);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(changePriority);<br>
| + | |
| − | ''-- Now the Audio Source alternates between the highest and the lowest priorities.''<br>
| + | |
| − | ''-- 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.''<br>
| + | |
| − | ''-- When we want to hear the audio, we change it to the highest priority, so it blocks the ambient sound.'' <br>
| + | |
| − | ''-- When we don't, we change it to the lowest, and the ambient sound dominates the scene again.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|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. |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | function muteOnOff ()<br>
| + | |
| − | :hostObject.Audio.Mute = not hostObject.Audio.Mute;<br>
| + | |
| − | :Space.Log(hostObject.Audio.Mute);<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(muteOnOff);<br>
| + | |
| − | ''-- Now clicking the object works like the Mute button.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|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.) |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | hostObject.Audio.MinDistance = 10;<br>
| + | |
| − | ''-- Now the sound will be heard at its maximum volume within 10 metres from the Audio Source.''<br>
| + | |
| − | ''-- If the listener moves further than 10 metres away, it will begin ceasing.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|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.) |5=
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br><br>
| + | |
| − | hostObject.Audio.MaxDistance = 100;<br>
| + | |
| − | ''-- Now the sound will be heard within 100 metres from the Audio Source.''}}
| + | |
| − | | + | |
| − | {{ScriptFunction|SResource|AudioClip|{get;set;}|The audio clip that is or will be played by this Audio Source. |5=
| + | |
| − | ''-- In this example, there are 3 audio clips in Scripting Runtime Resources''
| + | |
| − | hostObject = Space.Host.ExecutingObject;<br>
| + | |
| − | local nextTrack = 0;<br><br>
| + | |
| − | function changeTrack ()<br>
| + | |
| − | :hostObject.Audio.AudioClip = Space.Resources[nextTrack];<br>
| + | |
| − | :hostObject.Audio.Play();<br>
| + | |
| − | :Space.Log(Space.Resources[nextTrack].Name);<br>
| + | |
| − | :if nextTrack == 2 then ''-- replace 2 with n-1, where n is the amount of audio clips you have added to Resources''<br>
| + | |
| − | ::nextTrack = 0;<br>
| + | |
| − | :else<br>
| + | |
| − | ::nextTrack = nextTrack + 1; <br>
| + | |
| − | :end<br>
| + | |
| − | end<br><br>
| + | |
| − | hostObject.SubscribeToEvents();<br>
| + | |
| − | hostObject.OnMouseDown(changeTrack);<br>
| + | |
| − | ''-- Now, every time the object is clicked, the next audio clip is played.'' <br>
| + | |
| − | ''-- What's more, the list is looped (the index resets back to 0 when it gets to the end of the list)!''}}
| + | |
| − | | + | |
| − | {{Scripting Navbox}}
| + | |
