News Examples Documentation Download Buy Forum Contact

Documentation

Plugins

XML Extensions

Tools


Third Party Software
for krpano

Soundinterface Plugin soundinterface.js Version 1.21

  • 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.

Examples

Background Sound
Depthmap Demotour
Directional 3D Sound
WebVR Drone Attack

Syntax

<plugin name="soundinterface"
        url="soundinterface.js"
        preload="true"
        rootpath=""
        volume="1.0"
        mute="false"
        panningmodel="simple"
        worldscale="1.0"
        autopause="true"
        autounlock="true"
        />
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.

Plugin Attributes

Variable name Type Default value
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.
Variable nameTypeDefault value
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.
Variable nameTypeDefault value
soundinterface.mute Boolean false
  • A global muting for all sounds.
Variable nameTypeDefault value
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.
Variable nameTypeDefault value
soundinterface.worldscale Number 1.0
  • A global scale for all sound 3D positions.
Variable nameTypeDefault value
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.
Variable nameTypeDefault value
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.

Plugin Actions

The Soundinterface plugin add its actions directly to krpano. That means the soundinterface actions can be called like any other krpano actions.

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 (optionally)
    • 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 (optionally)
    • A boolean (true/false) if that sound should be looped or not.
    • When not set, the default is false (no looping).
  • volume (optionally)
    • The volume for that sound.
    • Value range: 0.0 - 1.0, default=1.0.
  • oncomplete (optionally)
    • 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 (optionally)
  • loop (optionally)
    • A boolean (true/false) if that sound should be looped or not.
    • When not set, the default is false (no looping).
  • volume (optionally)
    • The volume for that sound.
    • Value range: 0.0 - 1.0, default=1.0.
  • oncomplete (optionally)
    • 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 (optionally)
    • 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 (optionally)
    • The depth / distance of the spherical position.
    • When not set, the default value 1000 will be used.
  • loop (optionally)
    • A boolean (true/false) if that sound should be looped or not.
    • When not set, the default is false (no looping).
  • volume (optionally)
    • The volume for that sound.
    • Value range: 0.0 - 1.0, default=1.0.
  • range (optionally)
    • 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 (optionally)
    • 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
    • The 3D XYZ position.
  • loop (optionally)
    • A boolean (true/false) if that sound should be looped or not.
    • When not set, the default is false (no looping).
  • volume (optionally)
    • The volume for that sound.
    • Value range: 0.0 - 1.0, default=1.0.
  • range (optionally)
    • 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 (optionally)
    • 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 (optionally)
    • A boolean (true/false) if that sound should be looped or not.
    • When not set, the default is false (no looping).
  • volume (optionally)
    • The volume for that sound.
    • Value range: 0.0 - 1.0, default=1.0.
  • range (optionally)
    • 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 (optionally)
    • 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 (optionally)
    • 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 (optionally)
    • 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)
  • Pauses a sound.

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)
  • Mute or unmute a sound.

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).
stopallsounds()
  • Stop and destroy all current sounds.
pauseallsounds()
  • Pause all current playing sounds.
resumeallsounds()

Sound Objects

  • 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()

Sound Object Attributes

Variable name Type Default value
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.
Variable nameTypeDefault value
sound[name].muted Boolean false
  • Mute or unmute the sound.
Variable nameTypeDefault value
sound[name].loop Boolean false
  • Should the sound be looped or not.
Variable nameTypeDefault value
sound[name].speed Number 1.0
  • The playback speed: 0.5 - 4.0.
Variable nameTypeDefault value
sound[name].paused Boolean
  • Is the sound currently paused?
Variable nameTypeDefault value
sound[name].duration Number
  • The duration / playback-length of the sound.
Variable nameTypeDefault value
sound[name].position Number
  • The current playback position.
  • Can be also set for seeking (same as a seek() call).
Variable nameTypeDefault value
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!
Variable nameTypeDefault value
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.
Variable nameTypeDefault value
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.
Variable nameTypeDefault value
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.
Variable nameTypeDefault value
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.
Variable nameTypeDefault value
sound[name].onplay Event
  • This event will be called when the sounds starts to play.
Variable nameTypeDefault value
sound[name].onpause Event
  • This event will be called when the sounds gets paused.
Variable nameTypeDefault value
sound[name].onstop Event
  • This event will be called when the sounds gets stopped.
Variable nameTypeDefault value
sound[name].onseeked Event
  • This event will be called after finished seeking the sound.
Variable nameTypeDefault value
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 Object Actions

sound[name].play()
  • Play or resumes the sound.
sound[name].pause()
  • Pauses 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 (optionally)
    • 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:
  • x, y, z
    • The 3D XYZ position.
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 (optionally)
    • 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 (optionally)
    • 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.

Sound Formats

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

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.

Autoplay Restrictions

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.