close panorama

Sound Interface Plugin soundinterface.swf / soundinterface.js Version 1.16
for Flash and HTML5
Select Version:

  • The Sound Interface plugin extends krpano with actions for playing and controlling sounds directly from xml.
  • The plugin must be loaded only once for all sounds. The sounds itself will be started / stopped / controlled by calling the Sound Interface actions.
  • See also the HTML5 / iOS (iPhone/iPad) notes.
Note - the Sound Interface actions are not available until the plugin was loaded. Either use the plugin onloaded event or use the preload="true" setting to make sure that the plugin was loaded and is ready for usage. The plugin will automatically set keep="true" for itself, so it is not necessary to set that!

Syntax

Simple include syntax: (Flash only)
<plugin name="soundinterface" url="soundinterface.swf" preload="true" />

Full include syntax with all available settings: (for Flash and HTML5)
<plugin name="soundinterface"
        url="soundinterface.swf"
        alturl="soundinterface.js"
        preload="true"
        rootpath=""
        volume="1.0"
        mute="false"
        />

Plugin Attributes

  • rootpath  (optionally)
    • root path for the the sound files
    • relative from the xml file, default=""
    • it's possible to use placeholders like %SWFPATH% here
  • volume  (optionally)
    • the global volume for all sounds
    • 0.0 - 1.0, default=1.0
    • can be dynamically changed by actions (set(), tween(), ...)
  • mute  (optionally)
    • set the global mute for all sounds
    • true or false, default=false
    • can be dynamically changed by actions (set(), ...)

Plugin Actions

The Sound Interface plugin add its actions directly to the krpano root. That means the actions can be called like normal krpano actions.
  • preloadsound(audiofile)
    • preloads a sound file
    • this can be used to reduce the latency when starting to play
    • audiofilefile = the path and filename of a sound file
  • playsound(name, audiofile, loops*, oncomplete*)
    • plays a sound file
    • name = unique identification name for the sound (use "auto" for an automatic id)
    • audiofile = the path and filename of a sound file
    • loops = number of loops, 0=endless, default=1 (*optional)
    • oncomplete = actions that will be called on complete (*optional)
  • playsound2D(name, audiofile, volume*, pan*, loops*, oncomplete*)  (Flash only)
    • plays a sound file with adjustable volume and panning
    • name = unique identification name for the sound (use "auto" for an automatic id)
    • audiofile = the path and filename of a sound file
    • volume = sound volume (0.0 - 1.0, default=1.0) (*optional)
    • pan = left/right panning (-1.0(=left) - +1.0(=right), default=0.0) (*optional)
    • loops = number of loops, 0=endless, default=1 (*optional)
    • oncomplete = actions that will be called on complete (*optional)
  • playsound3D(name, audiofile, ath, atv, range*, volume*, loops*, oncomplete*)  (Flash only)
    • plays a directional 3D sound at a given spherical position
    • name = unique identification name for the sound (use "auto" for an automatic id)
    • audiofile = the path and filename of a sound file
    • ath = horizontal sound source position (-180 .. 180)
    • atv = vertical sound source position (-90 .. +90)
    • range = range of the sound (in degrees, default=90) (*optional)
    • volume = sound volume (0.0 - 1.0, default=1.0) (*optional)
    • loops = number of loops, 0=endless, default=1 (*optional)
    • oncomplete = actions that will be called on complete (*optional)
  • playsound3Dh(name, audiofile, ath, range*, volume*, loops*, oncomplete*)  (Flash only)
    • plays a directional 3D sound at a given horizontal position
    • independent of the vertical looking direction
    • name = unique identification name for the sound (use "auto" for an automatic id)
    • audiofile = the path and filename of a sound file
    • ath = horizontal sound source position (-180 .. 180)
    • atv = vertical sound source position (-90 .. +90)
    • range = range of the sound (in degrees, default=90) (*optional)
    • volume = sound volume (0.0 - 1.0, default=1.0) (*optional)
    • loops = number of loops, 0=endless, default=1 (*optional)
    • oncomplete = actions that will be called on complete (*optional)
  • playsound3DHS(name, audiofile, hotspotname, range*, volume*, loops*, oncomplete*)  (Flash only)
    • plays a directional 3D sound at a hotspot position
    • when the hotspot moves the sound will follow it
    • name = unique identification name for the sound (use "auto" for an automatic id)
    • audiofile = the path and filename of a sound file
    • hotspotname = name of the hotspot
    • range = range of the sound (in degrees, default=90) (*optional)
    • volume = sound volume (0.0 - 1.0, default=1.0) (*optional)
    • loops = number of loops, 0=endless, default=1 (*optional)
    • oncomplete = actions that will be called on complete (*optional)
  • pausesound(name)
    • pauses a sound
    • name = identification name of the sound
  • resumesound(name)
    • resumes a paused sound
    • name = identification name of the sound
  • pausesoundtoggle(name)
    • pauses OR resumes a sound
    • name = identification name of the sound
  • stopsound(name)
    • stops playing a sound
    • name = identification name of the sound
  • stopallsounds(globalstop*)
    • stop all playing sounds
    • globalstop = true or false, default=false (*optional)
      By default only the sounds started by the soundinterface will be stopped, but with true as parameter also all other flash sounds, e.g. from the videoplayer plugin or any other source, will be stopped.

Sound Object  (Flash only)

When a sound will be played a sound[name] object will be created in krpano. This object can be dynamically modifed with other krpano actions. The sound object will remove itself automatically when that sound has played or when stopsound will be called.

For example to tween/change the volume of a sound:
tween(sound[sound1].volume, 0.5)

Sound Object Attributes

sound[name].volume
sound[name].pan
sound[name].loops
sound[name].paused
sound[name].is3d
sound[name].hotspot
sound[name].ath
sound[name].atv
sound[name].range
sound[name].oncomplete

  • volume
    • sound volume (0.0 - 1.0, default=1.0)
  • pan
    • left/right panning (-1.0(=left) - +1.0(=right, default=0.0)
  • loops
    • number of loops, 0=endless, default=1
  • paused
    • is the sound paused or not, true or false
  • is3d
    • is the sound a 3D sound (play at ath/atv or at a hotspot position), true or false
  • hotspot
    • name of the hotspot where the 3D sound should play
  • ath
    • horizontal sound source position (-180 .. 180)
  • atv
    • vertical sound source position (-90 .. +90)
  • range
    • range of the sound (in degrees, default=90)
  • oncomplete
    • actions that will be called on complete, default=null

HTML5 and iOS (iPhone / iPad) Notes

Some HTML5 browsers doesn't support MP3 or MP4 audio files like the Flashplayer. There different audio formats like OGG or WAV need to be used. To provide several audio formats and let the plugin automatically choose the appropriate one, set the paths to all audio files at once and separate them by a pipe | character.
Example:
playsound(bg, 'sound.mp3|sound.ogg');
The technically possibilities with HTML5 are not same as with the Flashplayer. So when using the krpano HTML5 viewer not all features of the soundinterface plugin are supported.

Especially the 3D Sound features are not available here, as long as there is no volume panning available in HTML5 '3D Sound' will be not possible.

The Sound Object is also not supported here at the moment.

iOS (iPhone / iPad) Notes

There are additional system limitations on iOS devices (iPhone and iPad):
  • No Autoplay / Autostart!
    A sound can't start to play automatically! An user interaction is needed to start playing the sound, e.g. a touch on the screen by the user. The krpano soundinterface plugin automatically detects that situations and when the playing is not possible it automatically queues the playsound() command and waits for the next user interaction to start the sound automatically (e.g. when the user touches the screen to pan the pano or to click a button).
  • Only one sound at one time!
    Only one sound file can be played at one time! When there is the new playsound() call the last sound will be automatically stopped.
  • No volume change!
    Changing the volume of a sound is not allowed on iOS devices.

Examples

Background Sound with Pause/Mute Button
CLICK TO VIEW THE EXAMPLE