Javascript must be activated for this page!
NOTE: This page is from an older version, see the latest version
here .
The Soundinterface Plugin extends krpano with functionality for playing sounds.
It can be used for simple things like Background Music or Sound Effects ,
but also for 3D Positional Audio , e.g. for environmental effects or WebVR usage.
It supports Sound Sprites .
Automatic caching and reusing of sound files.
There are Sound Objects for detailed control via krpano actions or Javascript.
The plugin handles the browser/mobile autoplay restrictions automatically, e.g. when playback is currently
not allowed it will automatically wait for the next user-interaction (touch/click) and use that to start playing the sound.
Internally the plugin uses the Howler.js library
for dealing with the browsers Audio APIs.
Background Sound
Depthmap Demotour
Directional 3D Sound
WebVR Drone Attack
Note - the additional actions of the Soundinterface Plugin are not available until the plugin is loaded!
Therefore either use the
preload="true" setting
or alternatively the
onloaded event
to make sure that the plugin is loaded and ready before using any of the Soundinterface Plugin APIs.
After loading the plugin will be additionally also available as global soundinterface variable.
Attribute name
Full variable name
Type
Default value
rootpath
soundinterface.rootpath
String
""
Root path for the sound files.
By default the sound file urls are relative to html file.
It also possible to use url-placeholders e.g. like %VIEWER% here.
Attribute nameFull variable name Type Default value
volume
soundinterface.volume
Number
1.0
The global volume for all sounds.
Value range: 0.0 - 1.0, default=1.0.
Can be dynamically changed anytime.
Attribute nameFull variable name Type Default value
mute
soundinterface.mute
Boolean
false
A global muting for all sounds.
Attribute nameFull variable name Type Default value
panningmodel
soundinterface.panningmodel
String
"simple"
The default spatialisation algorithm to use to locate the sound in 3D space.
Available settings:
simple (the default) - uses a more simple model for calculating the stereo-panning and volume of a 3D sound.
The calculation will be done by the plugin itself and therefore produces the same results in all browsers.
The default and recommended to use.
equalpower - also a simple model but calculated by the Browser itself.
HRTF - a more complex model for calculating the 3D sound results.
It involves different frequency responses for each ear depending on the sound location
and even calculates Doppler Effects for moving sound sources.
Browser Support Notes:
iOS and Safari don't support stereo-panning, there always the HRTF mode is used.
Firefox and Edge works fine with all modes.
IE11 doesn't have WebAudio support, there only 2D sounds will be played.
Attribute nameFull variable name Type Default value
worldscale
soundinterface.worldscale
Number
1.0
A global scale for all sound 3D positions.
Attribute nameFull variable name Type Default value
autopause
soundinterface.autopause
Boolean
true
When enabled automatically pause all sounds when hiding (minimizing) the browser or changing the browser-tab.
And automatically resume all paused sounds when showing the browser or the browser-tab again.
Attribute nameFull variable name Type Default value
autounlock
soundinterface.autounlock
Boolean
true
Should the plugin try to automatically unlock the browsers sound playback on start using the first touch or click events.
The plugin might play a silent audio stream until the actual sound files begin to play.
See also here for more: Autoplay Restrictions .
The Soundinterface plugin add its actions directly to krpano.
That means the soundinterface actions can be called like any other krpano actions.
Actions / Functions Reference:
preloadsound(url)
Preload a sound file.
This can be used to reduce the latency when playing a sound later.
Parameters:
playsound(name)
playsound(name, url)
playsound(name, url, loop)
playsound(name, url, loop, oncomplete)
playsound(name, url, loop, volume)
playsound(name, url, loop, volume, oncomplete)
Play a sound.
Note - the sound file need to get fully downloaded before the playing can start!
That's a limitation of the WebAudio API that
will be used for playing the sounds.
When using larger sound files and wanting quicker starts of the sound,
consider using the streamsound() action instead.
Playing a sound also creates a Sound Object for further dynamic usage.
When called from Javascript these actions will return the Sound Object as return value.
Parameters:
name
The name / id of the sound.
Will be used to refer / address that sound.
When there exists already a sound with that given name and calling with a new url,
the old sound will be stopped.
When using 'auto' as name, an automatic unique name will be generated.
url
The path and filename of a sound file.
See also here for information about multiple Sound formats and Sound Sprites .
When calling without url parameter and there is an existing sound with that name, that sound will be resumed if it is paused.
loop
A boolean (true/false) if that sound should be looped or not.
When not set, the default is false (no looping).
volume
The volume for that sound.
Value range: 0.0 - 1.0, default=1.0.
oncomplete
The code to call when the sound has fully played. Can be krpano actions code or Javascript functions.
When looping is enabled, this event will not be called.
streamsound(name, url, loop*, volume*, oncomplete*)
Stream a sound - that means play it while loading.
The streamsound action uses internally the HTML5 Audio API .
Sounds played using that API can't use these features: 3D Positional Audio, Stereo Panning, Sound Sprites!
On iOS using a custom volume-level will be not possible! And it might be necessary to touch/click the screen
before the playback can be started!
Creates a Sound Object for further dynamic usage.
When called from Javascript this action will return the Sound Object as return value.
Parameters:
name
The name / id of the sound.
Will be used to refer / address that sound.
When there exists already a sound with that given name and calling with a new url,
the old sound will be stopped.
When using 'auto' as name, an automatic unique name will be generated.
url
loop
A boolean (true/false) if that sound should be looped or not.
When not set, the default is false (no looping).
volume
The volume for that sound.
Value range: 0.0 - 1.0, default=1.0.
oncomplete
The code to call when the sound has fully played. Can be krpano actions code or Javascript functions.
When looping is enabled, this event will not be called.
createsound(name, url, streaming*)
Creates and loads a new sound, but doesn't starts playing it yet.
Creates a Sound Object for further dynamic usage.
The properties of the sound (e.g. volume, looping, 3D position, ...) can be changed after creation with that Sound Object .
When called from Javascript this action will return the Sound Object as return value.
Parameters:
name
The name / id of the sound.
Will be used to refer / address that sound.
When there exists already a sound with that given name and calling with a new url,
the old sound will be stopped.
When using 'auto' as name, an automatic unique name will be generated.
url
streaming
A boolean (true/false) - should that sound be streamed (true) or preloaded (false).
When not set, the default is false, that means the sound will be preloaded.
For more details please have also a look at the playsound() and streamsound() actions.
playsound_at_hv(name, url, h, v, depth, loop, volume, oncomplete )
playsound_at_hv(name, url, h, v, depth, loop, volume, range, oncomplete )
Plays a 3D Positional Audio sound at spherical position.
For customizing the 3D audio spatialisation use the setup3dsound() or sound[name].setup3d() actions.
Creates a Sound Object for further dynamic usage.
When called from Javascript this action will return the Sound Object as return value.
Parameters:
name
The name / id of the sound.
Will be used to refer / address that sound.
When there exists already a sound with that given name and calling with a new url,
the old sound will be stopped.
When using 'auto' as name, an automatic unique name will be generated.
url
h and v
The spherical position in degrees.
From -180 to +180 horizontally and -90 to +90 vertically (values out of this range will automatically wrap around).
When v will be not set, the default value 0 will be used.
depth
The depth / distance of the spherical position.
When not set, the default value 1000 will be used.
loop
A boolean (true/false) if that sound should be looped or not.
When not set, the default is false (no looping).
volume
The volume for that sound.
Value range: 0.0 - 1.0, default=1.0.
range
The 'lookto-range' for 3D sounds.
The range value defines after how many degrees of looking away the volume should be reduced to silence.
Default=360.0.
oncomplete
The code to call when the sound has fully played. Can be krpano actions code or Javascript functions.
When looping is enabled, this event will not be called.
playsound_at_xyz(name, url, x,y,z, loop, volume, oncomplete )
playsound_at_xyz(name, url, x,y,z, loop, volume, range, oncomplete )
Plays a 3D Positional Audio sound at 3D XYZ position.
For customizing the 3D audio spatialisation use the setup3dsound() or sound[name].setup3d() actions.
Creates a Sound Object for further dynamic usage.
When called from Javascript this action will return the Sound Object as return value.
Parameters:
name
The name / id of the sound.
Will be used to refer / address that sound.
When there exists already a sound with that given name and calling with a new url,
the old sound will be stopped.
When using 'auto' as name, an automatic unique name will be generated.
url
x , y , z
loop
A boolean (true/false) if that sound should be looped or not.
When not set, the default is false (no looping).
volume
The volume for that sound.
Value range: 0.0 - 1.0, default=1.0.
range
The 'lookto-range' for 3D sounds.
The range value defines after how many degrees of looking away the volume should be reduced to silence.
Default=360.0.
oncomplete
The code to call when the sound has fully played. Can be krpano actions code or Javascript functions.
When looping is enabled, this event will not be called.
playsound_at_hotspot(name, url, hotspot, loop, volume, oncomplete )
playsound_at_hotspot(name, url, hotspot, loop, volume, range, oncomplete )
Plays a 3D Positional Audio sound at hotspot position.
For customizing the 3D audio spatialisation use the setup3dsound() or sound[name].setup3d() actions.
Creates a Sound Object for further dynamic usage.
When called from Javascript this action will return the Sound Object as return value.
Parameters:
name
The name / id of the sound.
Will be used to refer / address that sound.
When there exists already a sound with that given name and calling with a new url,
the old sound will be stopped.
When using 'auto' as name, an automatic unique name will be generated.
url
hotspot
Either the name of a hotspot or directly a hotspot object itself.
loop
A boolean (true/false) if that sound should be looped or not.
When not set, the default is false (no looping).
volume
The volume for that sound.
Value range: 0.0 - 1.0, default=1.0.
range
The 'lookto-range' for 3D sounds.
The range value defines after how many degrees of looking away the volume should be reduced to silence.
Default=360.0.
oncomplete
The code to call when the sound has fully played. Can be krpano actions code or Javascript functions.
When looping is enabled, this event will not be called.
setup3dsound(name, refDistance, rolloffFactor, distanceModel, panningModel )
Customize a 3D Positional Audio sound.
Parameters:
name
The name / id of the sound to customize.
There need to be a sound with that name.
refDistance
The reference distance for reducing the volume when the sound is farther away.
The default is 1.0.
rolloffFactor
Defines how quick the volume is reduced when the sound moves away.
The default is 1.0.
distanceModel
Define which algorithm to use to reduce the volume of the sound as it moves away.
Available settings: linear , exponential or inverse (the default).
panningModel
The spatialisation algorithm to use to locate the sound in 3D space.
Available settings: simple , equalpower or HRTF .
The default setting depends on the panningmodel setting.
pausesound(name)
Parameters:
name
The name / id of a sound.
There need to be a sound with that name.
resumesound(name)
Resumes a paused a sound.
When the sound is already playing, nothing will happen.
Parameters:
name
The name / id of a sound.
There need to be a sound with that name.
togglesound(name)
Either pause or resume a sound.
Parameters:
name
The name / id of a sound.
There need to be a sound with that name.
stopsound(name)
Stop a sound.
That means pausing the sound and seeking it back to its beginning.
Parameters:
name
The name / id of a sound.
There need to be a sound with that name.
destroysound(name)
Stops a sound and destroys it.
After that the sound will be removed, resuming it will be not possible.
Parameters:
name
The name / id of a sound.
There need to be a sound with that name.
seeksound(name, position)
Seeks a sound to the given playback position.
When the seeking is done, the sound[name].onseeked event will be called.
Parameters:
name
The name / id of a sound.
There need to be a sound with that name.
position
The new playback position in seconds.
mutesound(name, muted)
Parameters:
name
The name / id of a sound.
There need to be a sound with that name.
muted
The new muted state (true or false).
Everytime when a sound will be created or played a sound[name] object will be created.
When having used 'auto' as name for a new sound, then there will be also a global variable named autosound that refers to that last created sound object.
The attributes of that sound object can be dynamically modified at runtime using krpano actions or Javascript code.
The object offers also several functions and events for more control.
Some functionality is only available by changing settings of the sound object!
The sound object will get automatically removed when that sound has fully played (after the oncomplete event).
Example: for changing the volume of a sound, just
tween its volume:
tween(sound[sound1].volume, 0.5)
All available Sound Object Attributes / Events / Actions:
Attributes:
sound[name].volume
sound[name].muted
sound[name].loop
sound[name].speed
sound[name].paused
sound[name].duration
sound[name].position
sound[name].pan
sound[name].ath
sound[name].atv
sound[name].depth
sound[name].range
sound[name].tx
sound[name].ty
sound[name].tz
Events:
sound[name].onloaderror
sound[name].onplay
sound[name].onpause
sound[name].onstop
sound[name].onseeked
sound[name].oncomplete
Actions:
sound[name].play()
sound[name].pause()
sound[name].toggle()
sound[name].stop()
sound[name].destroy()
sound[name].seek()
sound[name].sethv()
sound[name].setxyz()
sound[name].setup3d()
Attribute name
Full variable name
Type
Default value
volume
sound[name].volume
Number
1.0
The volume of the sounds.
Value range: 0.0 - 1.0, default=1.0.
Can be dynamically changed anytime.
Attribute nameFull variable name Type Default value
muted
sound[name].muted
Boolean
false
Mute or unmute the sound.
Attribute nameFull variable name Type Default value
loop
sound[name].loop
Boolean
false
Should the sound be looped or not.
Attribute nameFull variable name Type Default value
speed
sound[name].speed
Number
1.0
The playback speed: 0.5 - 4.0.
Attribute nameFull variable name Type Default value
paused
sound[name].paused
Boolean
Is the sound currently paused?
Attribute nameFull variable name Type Default value
duration
sound[name].duration
Number
The duration / playback-length of the sound.
Attribute nameFull variable name Type Default value
position
sound[name].position
Number
The current playback position.
Can be also set for seeking (same as a seek() call).
Attribute nameFull variable name Type Default value
pan
sound[name].pan
Number
0.0
Set the stereo panning: from -1.0 (left) +1.0 (right).
Can not be used together with 3D sounds!
Attribute nameFull variable name Type Default value
ath
atv
depth
sound[name].ath
sound[name].atv
sound[name].depth
Number Number Number
0.0 0.0 0.0
Set the spherical position for a 3D Positional Audio sound.
Attribute nameFull variable name Type Default value
range
sound[name].range
Number
360.0
The 'lookto-range' for 3D sounds.
The range value defines after how many degrees of looking away from the sound source the volume should be reduced to silence.
Attribute nameFull variable name Type Default value
tx
ty
tz
sound[name].tx
sound[name].ty
sound[name].tz
Number Number Number
0.0 0.0 0.0
Set the 3D XYZ position for a 3D Positional Audio sound.
Attribute nameFull variable name Type Default value
onloaderror
sound[name].onloaderror
Event
This event will be called when there is a loading error.
The lasterror variable will contain the error message.
When this event is not set, the error will be processed by the krpano onloaderror event.
Attribute nameFull variable name Type Default value
onplay
sound[name].onplay
Event
This event will be called when the sounds starts to play.
Attribute nameFull variable name Type Default value
onpause
sound[name].onpause
Event
This event will be called when the sounds gets paused.
Attribute nameFull variable name Type Default value
onstop
sound[name].onstop
Event
This event will be called when the sounds gets stopped.
Attribute nameFull variable name Type Default value
onseeked
sound[name].onseeked
Event
This event will be called after finished seeking the sound.
Attribute nameFull variable name Type Default value
oncomplete
sound[name].oncomplete
Event
This event will be called when the sound was completely played.
When the sound is looping, this event will be not called.
sound[name].play()
Play or resumes the sound.
sound[name].toggle()
Either pause or resume the sound.
sound[name].stop()
Stop the sound.
That means pausing the sound and seeking it back to its beginning.
sound[name].destroy()
Stops a sound and destroys it.
After that the sound will be removed, resuming it will be not possible.
sound[name].seek(position)
Seeks the sound to the given playback position.
When the seeking is done, the sound[name].onseeked event will be called.
Parameters:
position
The new playback position in seconds.
sound[name].sethv(h, v*, depth*)
Set the spherical position for a 3D Positional Audio sound.
Alternatively it would be also possible to change the ath , atv and depth attributes individually.
Parameters:
h and v
The spherical position in degrees.
From -180 to +180 horizontally and -90 to +90 vertically (values out of this range will automatically wrap around).
When v will be not set, the default value 0 will be used.
depth
The depth / distance of the spherical position.
When not set, the default value 1000 will be used.
sound[name].setxyz(x, y, z)
Set the 3D XYZ position for a 3D Positional Audio sound.
Alternatively it would be also possible to change the tx , ty and tz attributes individually.
Parameters:
sound[name].setup3d(refDistance, rolloffFactor, distanceModel, panningModel)
Customize the 3D Positional Audio sound settings.
Parameters:
name
The name / id of the sound to customize.
There need to be a sound with that name.
refDistance
The reference distance for reducing the volume when the sound is farther away.
The default is 1.0.
rolloffFactor
Defines how quick the volume is reduced when the sound moves away.
The default is 1.0.
distanceModel
Define which algorithm to use to reduce the volume of the sound as it moves away.
Available settings: linear , exponential or inverse (the default).
panningModel
The spatialisation algorithm to use to locate the sound in 3D space.
Available settings: simple , equalpower or HRTF .
The default setting depends on the panningmodel setting.
The Soundinterface Plugin supports all sound formats / codecs that the actual browser itself is supporting.
And because browsers might not have support for the same formats, it is possible to provide several sound files with different formats.
The different files would need be separated them by
| characters. The plugin will try to load the
files from left to right - when one file can't be loaded or isn't supported, then automatically the next one will be tried.
Example:
url="music.mp3|music.webm"
Sound Sprites (or Audio Sprites) are a way to store several sounds in one file (or alternatively
a way to crop a sound / to use only a part of it).
The syntax to use Sound Sprites:
url="sounds.mp3[start,length]"
start - The start-position of the sound in seconds.
length -The length of the sound in seconds.
When there are several sounds using the same sound file, that sound file will be loaded only once.
In mobile browsers and also new in many newer desktop browsers the automatic playback
for media files like video or sound is restricted or blocked.
They allow playing only after an user-interaction like a touch or a click.
So when trying to play a sound and the playback is not allowed by the browser, the soundinterface plugin automatically
waits for the first the touch or click anywhere on the page and uses that to starts the playback.