krpano 1.19-pr16 (build 2018-04-04)

Sound Interface Plugin soundinterface.swf / soundinterface.js

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

Syntax

<plugin name="soundinterface"
        url.flash="soundinterface.swf"
        url.html5="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.

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.

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.