krpano Soundinterface插件使用指南
个人主页：《爱蹦跶的大A阿》
当前正在更新专栏：《VUE》 、《JavaScript保姆级教程》、《krpano》、《Krpano中文文档》
✨ 正文
- Soundinterface Plugin扩展了krpano播放声音的功能。
- 它可以用于简单的事情，如背景音乐或声音效果，但也可以用于3D位置音频，例如环境效果或WebVR使用。
- 它支持声音精灵。
- 自动缓存和重用的声音文件。
- 有声音对象通过krpano操作或Javascript进行详细控制。
- 该插件自动处理浏览器/移动设备的自动播放限制，例如，当当前不允许播放时，它将自动等待下一个用户交互(触摸/点击)，并使用它开始播放声音。
- 在内部插件使用Howler.js库来处理浏览器的音频api。
Examples
|
背景声音 |
Depthmap Demotour |
Directional 3D Sound |
WebVR Drone Attack |
语法
注意-附加动作的声音接口插件是不可用的，直到插件被加载!
因此，要么使用preload="true"设置，要么使用onloaded事件来确保插件在使用任何Soundinterface plugin api之前已经加载并准备好了。
加载插件后，还可以作为全局soundinterface变量使用。
插件属性
| Variable name | Type | Default value | |
| soundinterface.rootpath | String | "" | |
|---|---|---|---|
|
|||
| Variable name | Type | Default value | |
| soundinterface.volume | Number | 1.0 | |
|
|||
| Variable name | Type | Default value | |
| soundinterface.mute | Boolean | false | |
|
|||
| Variable name | Type | Default value | |
| soundinterface.panningmodel | String | "simple" | |
|
|||
| Variable name | Type | Default value | |
| soundinterface.worldscale | Number | 1.0 | |
|
|||
| Variable name | Type | Default value | |
| soundinterface.autopause | Boolean | true | |
|
|||
| Variable name | Type | Default value | |
| soundinterface.autounlock | Boolean | true | |
|
|||
插件操作
Soundinterface插件将其动作直接添加到krpano。这意味着声音界面动作可以像任何其他krpano动作一样被调用。
动作/功能参考:
- preloadsound()
- playsound()
- streamsound()
- createsound()
- playsound_at_hv()
- playsound_at_xyz()
- playsound_at_hotspot()
- setup3dsound()
- pausesound()
- resumesound()
- togglesound()
- stopsound()
- destroysound()
- seeksound()
- mutesound()
- stopallsounds()
- pauseallsounds()
- resumeallsounds()
- sound[name].play()
- sound[name].pause()
- sound[name].toggle()
- sound[name].stop()
- sound[name].destroy()
- sound[name].sethv()
- sound[name].setxyz()
- sound[name].setup3d()
preloadsound(url)
- 预加载声音文件。
- 这可以用来减少稍后播放声音时的延迟。
参数:
- url
- 声音文件的路径和文件名。
- 有关的信息，请参阅此处 multiple Sound formats 和 Sound Sprites.
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)
- 播放一个声音。
- 注意-声音文件需要得到完全下载之前播放可以开始!这是 WebAudio API 的一个限制，它将用于播放声音。
当使用较大的声音文件并希望更快地开始声音时，请考虑使用 streamsound() 操作。 - 播放声音也会创建一个 Sound Object 以供进一步的动态使用。
- 当从Javascript调用这些动作时，这些动作将返回 Sound Object 作为返回值。
参数:
- name
- 声音的name / id。
- Will用来指代/称呼那个声音。
- 当已经存在具有该给定名称的声音并使用新url调用时，旧声音将被停止。
- 当使用'auto'作为名称时，将自动生成一个唯一的名称。
- url (可选)
- 声音文件的路径和文件名。
- 有关的信息，请参阅此处 multiple Sound formats 和 Sound Sprites.
- 当调用时没有url参数，并且有一个现有的声音与该名称，该声音将被恢复，如果它被暂停。
- loop (可选)
- 一个布尔值(true/false)来判断声音是否应该循环。
- 未设置时，默认为false(不循环)。
- volume (可选)
- 声音的音量。
- 取值范围:0.0 ~ 1.0，默认值=1.0。
- oncomplete (可选)
- 当声音完全播放时调用的代码。可以是krpano动作代码或Javascript函数。
- 当启用循环时，将不会调用此事件。
streamsound(name, url, loop*, volume*, oncomplete*)
- 流式传输声音-这意味着在加载时播放它。
- streamsound 动作在内部使用 HTML5 Audio API.。使用该API播放的声音不能使用以下功能:3D位置音频、立体声平移、声音精灵!在iOS上使用自定义卷级别是不可能的!在播放开始之前，可能需要触摸/点击屏幕!
- 为进一步的动态使用创建一个 Sound Object 。
- 当从Javascript调用这个动作时，将返回 Sound Object 作为返回值。
参数:
- name
- 声音的名称/ id。
- Will用来指代/称呼那个声音。
- 当已经存在具有该给定名称的声音并使用新url调用时，旧声音将被停止。
- 当使用'auto'作为名称时，将自动生成一个唯一的名称。
- url (可选)
- 声音文件的路径和文件名。
- 有关的信息，请参阅此处 multiple Sound formats.
- loop (可选)
- 一个布尔值(true/false)来判断声音是否应该循环。
- 未设置时，默认为false(不循环)。
- volume (可选)
- 那个声音的音量。
- 取值范围:0.0 ~ 1.0，默认值=1.0。
- oncomplete (可选)
- 当声音完全播放时调用的代码。可以是krpano动作代码或Javascript函数。
- 当启用循环时，将不会调用此事件。
createsound(name, url, streaming*)
- 创建并加载一个新的声音，但还没有开始播放。
- 为进一步的动态使用创建一个 Sound Object 。
- 声音的属性(例如音量，循环，3D位置，…)可以在创建 Sound Object 后改变。
- 当从Javascript调用这个动作时，将返回 Sound Object 作为返回值。
参数:
- name
- 声音的name / id。
- Will用来指代/称呼那个声音。
- 当已经存在具有该给定名称的声音并使用新url调用时，旧声音将被停止。
- 当使用'auto'作为名称时，将自动生成一个唯一的名称。
- url
- 声音文件的路径和文件名。
- 有关的信息，请参阅此处 multiple Sound formats 和 Sound Sprites.
- streaming (可选)
- 一个布尔值(true/false) -该声音是流式播放(true)还是预加载(false)。
- 当不设置时，默认为false，这意味着声音将被预加载。
- 要了解更多细节，请查看 playsound() 和streamsound() 操作。
playsound_at_hv(name, url, h, v, depth, loop, volume, oncomplete)
playsound_at_hv(name, url, h, v, depth, loop, volume, range, oncomplete)
- 在球形位置播放3D位置音频。
- 自定义3D音频空间化使用 setup3dsound() 或 sound[name].setup3d() 操作。
- 为进一步的动态使用创建一个 Sound Object。
- 当从Javascript调用这个动作时，将返回 Sound Object 作为返回值。
参数:
- name
- 声音的name / id。
- Will用来指代/称呼那个声音。
- 当已经存在具有该给定名称的声音并使用新url调用时，旧声音将被停止。
- 当使用'auto'作为名称时，将自动生成一个唯一的名称。
- url
- 声音文件的路径和文件名。
- 有关的信息，请参阅此处 multiple Sound formats 和 Sound Sprites.
- h and v
- 以度为单位的球面位置。
- 水平方向从-180到+180，垂直方向从-90到+90(超出此范围的值将自动换行)。
- 当不设置v时，将使用默认值0。
- depth (可选)
- 球面位置的深度/距离。
- 当不设置时，将使用默认值1000。
- loop (可选)
- 一个布尔值(true/false)来判断声音是否应该循环。
- 未设置时，默认为false(不循环)。
- volume (可选)
- 那个声音的音量。
- 取值范围:0.0 ~ 1.0，默认值=1.0。
- range (可选)
- 3D声音的“视距”。
- 范围值定义了在看向别处多少度之后，音量应该减少到沉默。
- 默认= 360.0。
- oncomplete (可选)
- 当声音完全播放时调用的代码。可以是krpano动作代码或Javascript函数。
- 当启用循环时，将不会调用此事件。
playsound_at_xyz(name, url, x,y,z, loop, volume, oncomplete)
playsound_at_xyz(name, url, x,y,z, loop, volume, range, oncomplete)
- 在3D XYZ位置播放3D位置音频。
- 自定义3D音频空间化使用 setup3dsound() 或 sound[name].setup3d() 操作。
- 为进一步的动态使用创建一个 Sound Object 。
- 当从Javascript调用这个动作时，将返回 Sound Object 作为返回值。
参数:
- name
- 声音的 name/ id。
- Will用来指代/称呼那个声音。
- 当已经存在具有该给定名称的声音并使用新url调用时，旧声音将被停止。
- 当使用'auto'作为名称时，将自动生成一个唯一的名称。
- url
- 声音文件的路径和文件名。
- 有关的信息，请参阅此处 multiple Sound formats 和 Sound Sprites.
- x, y, z
- 3D的XYZ位置。
- loop (optionally)
- 一个布尔值(true/false)来判断声音是否应该循环。
- 未设置时，默认为false(不循环)。
- volume (optionally)
- 声音的音量。
- 取值范围:0.0 ~ 1.0，默认值=1.0。
- range (optionally)
- 3D声音的“视距lookto-range'。
- 范围值定义了在看向别处多少度之后，音量应该减少到沉默。
- 默认= 360.0。
- oncomplete (optionally)
- 当声音完全播放时调用的代码。可以是krpano动作代码或Javascript函数。
- 当启用循环时，将不会调用此事件。
playsound_at_hotspot(name, url, hotspot, loop, volume, oncomplete)
playsound_at_hotspot(name, url, hotspot, loop, volume, range, oncomplete)
- 在 hotspot 位置播放3D位置音频。
- 自定义3D音频空间化使用 setup3dsound() 或 sound[name].setup3d() 操作。
- 为进一步的动态使用创建一个 Sound Object 。
- 当从Javascript调用这个动作时，将返回 Sound Object 作为返回值。
参数:
- name
- 声音的 name / id。
- Will用来指代/称呼那个声音。
- 当已经存在具有该给定名称的声音并使用新url调用时，旧声音将被停止。
- 当使用'auto'作为名称时，将自动生成一个唯一的名称。
- url
- 声音文件的路径和文件名。
- 有关的信息，请参阅此处 multiple Sound formats 和 Sound Sprites.
- hotspot
- 热点的名称或者直接是热点对象本身。
- loop (optionally)
- 一个布尔值(true/false)来判断声音是否应该循环。
- 未设置时，默认为false(不循环)。
- volume (optionally)
- 声音的音量。
- 取值范围:0.0 ~ 1.0，默认值=1.0。
- range (optionally)
- 3D声音的“视距lookto-range”。
- 范围值定义了在看向别处多少度之后，音量应该减少到沉默。
- 默认= 360.0。
- oncomplete (optionally)
- 当声音完全播放时调用的代码。可以是krpano动作代码或Javascript函数。
- 当启用循环时，将不会调用此事件。
setup3dsound(name, refDistance, rolloffFactor, distanceModel, panningModel)
- 自定义3D Positional Audio 声音。
Parameters:
- name
- 需要自定义的声音的 name / id 。
- 这个名字应该有个发音。
- refDistance
- 当声音较远时减小音量的参考距离。
- 默认值是1.0。
- rolloffFactor
- 定义当声音移开时音量减少的速度。
- 默认值是1.0。
- distanceModel (optionally)
- 定义使用哪种算法来减小声音的音量。
- 可用设置: linear, exponential 或 inverse (默认).
- panningModel (optionally)
- 空间化算法用于在三维空间中定位声音。
- 可用设置:: simple, equalpower 或 HRTF.
- 默认设置取决于 panningmodel 设置.
pausesound(name)
- 暂停一个声音。
参数:
- name
- 声音的 name / id 。
- 这个名字应该有个发音。
resumesound(name)
- 恢复一个暂停的声音。
- 当声音已经在播放时，什么也不会发生。
参数:
- name
- 声音的 name / id。
- 这个名字应该有个发音。
togglesound(name)
- 暂停或恢复一个声音。
参数:
- name
- 声音的 name / id。
- 这个名字应该有个发音
stopsound(name)
- 停止一个声音。
- 这意味着暂停声音，并寻求回到它的开始。
参数:
- name
- 声音的 name / id。
- 这个名字应该有个发音
destroysound(name)
- 停止声音并摧毁它。
- 之后，声音将被删除，恢复它将是不可能的。
参数:
- name
- 声音的 name / id。
- 这个名字应该有个发音
seeksound(name, position)
- 寻找一个声音到给定的播放位置。
- 当搜索完成后， 将调用 sound[name].onseeked 事件。
参数:
- name
- 声音的 name / id。
- 这个名字应该有个发音。
- position
- 以秒为单位的新播放位置。
mutesound(name, muted)
- 静音或取消静音的声音。
参数:
- name
- 声音的 name / id。
- 这个名字应该有个发音。
- muted
- 新的静音状态(true或false)。
stopallsounds()
- 停止并破坏所有电流声音。
pauseallsounds()
- 暂停所有当前播放的声音。
resumeallsounds()
- 恢复通过 pauseallsounds() 暂停的所有声音。
Sound Objects
- 每次当一个声音被创建或播放时，一个声音[name]对象将被创建。
- 当使用'auto'作为新声音的名称时，还会有一个名为autosound的全局变量引用最后创建的声音对象。
- 该声音对象的属性可以在运行时使用krpano操作或Javascript代码进行动态修改。
- 该对象还提供了一些函数和事件来进行更多的控制。
- 有些功能只能通过改变声音对象的设置来实现!
- 声音对象将在声音完全播放后自动移除(在oncomplete事件之后)。
例如:要改变声音的音量，只需 tween 它的音量:
tween(sound[sound1].volume, 0.5)所有可用的声音对象属性/事件/动作:
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 属性
| Variable name | Type | Default value | |
| sound[name].volume | Number | 1.0 | |
|---|---|---|---|
|
|||
| Variable name | Type | Default value | |
| sound[name].muted | Boolean | false | |
|
|||
| Variable name | Type | Default value | |
| sound[name].loop | Boolean | false | |
|
|||
| Variable name | Type | Default value | |
| sound[name].speed | Number | 1.0 | |
|
|||
| Variable name | Type | Default value | |
| sound[name].paused | Boolean | ||
|
|||
| Variable name | Type | Default value | |
| sound[name].duration | Number | ||
|
|||
| Variable name | Type | Default value | |
| sound[name].position | Number | ||
|
|||
| Variable name | Type | Default value | |
| sound[name].pan | Number | 0.0 | |
|
|||
| Variable name | Type | Default value | |
| sound[name].ath sound[name].atv sound[name].depth |
Number Number Number |
0.0 0.0 0.0 |
|
|
|||
| Variable name | Type | Default value | |
| sound[name].range | Number | 360.0 | |
|
|||
| Variable name | Type | Default value | |
| sound[name].tx sound[name].ty sound[name].tz |
Number Number Number |
0.0 0.0 0.0 |
|
|
|||
| Variable name | Type | Default value | |
| sound[name].onloaderror | Event | ||
|
|||
| Variable name | Type | Default value | |
| sound[name].onplay | Event | ||
|
|||
| Variable name | Type | Default value | |
| sound[name].onpause | Event | ||
|
|||
| Variable name | Type | Default value | |
| sound[name].onstop | Event | ||
|
|||
| Variable name | Type | Default value | |
| sound[name].onseeked | Event | ||
|
|||
| Variable name | Type | Default value | |
| sound[name].oncomplete | Event | ||
|
|||
Sound Object Actions
sound[name].play()
- 播放或恢复声音。
sound[name].pause()
- 暂停声音。
sound[name].toggle()
- 暂停或继续播放声音。
sound[name].stop()
- 停止声音。
- 这意味着暂停声音，并寻求回到它的开始。
sound[name].destroy()
- 停止声音并摧毁它。
- 之后，声音将被删除，恢复它将是不可能的。
sound[name].seek(position)
- 将声音搜索到给定的播放位置。
- 当搜索完成后，将调用 sound[name].onseeked 事件。
参数:
- position
- 以秒为单位的新播放位置。
sound[name].sethv(h, v*, depth*)
- 设置3D位置音频声音的球面位置。
- 另外，也可以单独更改ath, atv和depth属性。
参数:
- h and v
- 以度为单位的球面位置。
- 水平方向从-180到+180，垂直方向从-90到+90(超出此范围的值将自动换行)。
- 当不设置v时，将使用默认值0。
- depth (optionally)
- 球面位置的深度/距离。
- 当不设置时，将使用默认值1000。
sound[name].setxyz(x, y, z)
- 设置3D位置音频声音的3D XYZ位置。
- 另外，也可以单独更改tx、ty和tz属性。
参数:
- x, y, z
- 3D的XYZ位置。
sound[name].setup3d(refDistance, rolloffFactor, distanceModel, panningModel)
- 自定义3D位置音频声音设置。
参数:
- name
- 需要自定义的声音的 name/ id。
- 这个名字应该有个发音。
- refDistance
- 当声音较远时减小音量的参考距离。
- 默认值是1.0。
- rolloffFactor
- 定义当声音移开时音量减少的速度。
- 默认值是1.0。
- distanceModel (optionally)
- 定义使用哪种算法来减小声音的音量。
- 可用设置: linear, exponential or inverse (默认).
- panningModel (optionally)
- 空间化算法用于在三维空间中定位声音。
- 可用设置: simple, equalpower or HRTF.
- 默认设置取决于 panningmodel 设置。
声音格式
Soundinterface Plugin支持实际浏览器本身支持的所有声音格式/编解码器。由于浏览器可能不支持相同的格式，因此可以提供几种不同格式的声音文件。
不同的文件需要用字符分隔。插件将尝试从左到右加载文件-当一个文件无法加载或不支持，然后自动尝试下一个文件。
例子:
url="music.mp3|music.webm"Sound Sprites
Sound Sprites(或Audio Sprites)是一种将多个声音存储在一个文件中的方法(或者是一种裁剪声音/只使用其中一部分的方法)。
使用 Sound Sprites 的语法:
url="sounds.mp3[start,length]"- start - 以秒为单位的声音开始位置。
- length -声音的长度，以秒为单位。
当有几个声音使用相同的声音文件时，该声音文件将只加载一次。
播放的限制
在移动浏览器和许多更新的桌面浏览器中，视频或声音等媒体文件的自动播放受到限制或阻止。
它们只允许玩家在触碰或点击等用户互动后才能玩游戏。
因此，当尝试播放声音，而浏览器不允许播放时，soundinterface插件会自动等待第一次触摸或点击页面上的任何地方，并使用它来开始播放。
✨ 结语
