CreateJS-SoundJS翻译

时间:2019-12-18 发布者: 访问量:3381

SoundJS库管理网络上的音频播放。它通过 '抽象出实际音频实现' 的插件来工作,所以可能在任何平台上播放的,而不必了解声音播放的机制。
 
使用SoundJS,可以使用 'Sound' 类的公共API。该API是:
安装音频播放插件
注册(和预加载)声音
创建和播放声音
主音量、静音以及一次性停止对所有声音的控制
 
控制声音
播放声音,会创建 'AbstractSoundInstance' 实例,该实例可以单独进行控制。
暂停、恢复、搜索、停止声音
控制声音的音量、静音、声像
监听声音实例的事件,播放完成、循环、失败时触发通知
 
示例:
createjs.Sound.alternateExtensions = ['mp3'];
createjs.Sound.on('fileload', this.loadHandler, this);
createjs.Sound.resisterSound('path/sound/声音.ogg', 'sound1');
function loadHandler(event){
// 每个注册的声音都会触发
var instance = createjs.Sound.play('sound1'); // 播放指定id的声音(这里是上面注册的 'sound1'),也可以使用 '声音的全路径' 或 'event.src'
instance.on('complete', this.handleComplete, this);
instance.volume = 0.5;
}
 
浏览器支持:
音频可以在支持 'Web Audio'(http://caniuse.com/audio-api) 或 'HTMLAudioElement'(http://caniuse.com/audio) 的浏览器上使用。Flash fallback可用于任何支持Flash播放器的浏览器,Cordova插件可用于任何支持 Cordova.Media 的web视图。不支持IE8和更早版本,及时是 Flash fallback 也不支持。要支持以前的浏览器,可使用旧版本的SoundJS(0.5.2之前)
 
大致看了下提供的类文件,有分类特性:
 
// Sound库其他
SoundJS
Sound
AudioSprite
PlayPropsConfig
 
// 2个基类
AbstractPlugin
AbstractSoundInstance
 
// 上面提到的4个不同的插件
WebAudioLoader
WebAudioPlugin
WebAudioSoundInstance
 
HTMLAudioPlugin
HTMLAudioSoundInstance
HTMLAudioTagPool
 
FlashAudioLoader
FlashAudioPlugin
FlashAudioSoundInstance
 
CordovaAudioLoader
CordovaAudioPlugin
CordovaAudioSoundInstance
 
// 额外的事件对象
ErrorEvent
 
// CreateJS 套件里公共部分
Event
EventDispatcher
Utility Methods
 
1.SoundJS
SoundJS 是一个静态类,可获取类库的具体信息,例如:库的版本、构建日期等。SoundJS类已经被重命名为 Sound。查看 'Sound' 获取更多信息
 
2.Sound
Sound类是公共API,用于创建声音,控制整体声音级别,以及管理插件。该类上所有的声音API都是静态的。
 
注册和预加载
播放声音前,必须先进行注册。可以使用 'registerSound' 方法,注册多个声音使用 'registerSounds' 方法。如果在 使用 'play' 方法来尝试播放它,或使用 'createInstance' 来创建它 之前,没有注册声音,将会自动注册声音源,但是播放将会失败,因为声音源还未准备好。如果使用 'PreloadJS',则会在预加载声音时,自动处理声音注册。建议预先加载声音,不管是通过内部的注册函数还是外部的 'PreloadJS',以便在使用声音时准备就绪。
 
播放
在声音注册和预加载后,立即播放声音,使用 'play' 方法。该方法返回一个 'AbstractSoundInstance' 实例,可以用来暂停、恢复、静音等操作。可以查看 'AbstractSoundInstance' 获取更多信息。
 
插件
默认情况下,使用 'WebAudioPlugin' 或 'HTMLAudioPlugin' 插件(当可用时),但开发人员可以更改插件优先级,或添加新的插件(例如:提供的 'FlashAudioPlugin' 插件)。安装插件,或指定不同的插件顺序,查看 'Sound/intallPlugins'。
 
示例:
createjs.FlashAudioPlugin.swfPath = '../src/flashaudio';
createjs.Sound.registerPlugins([createjs.WebAudioPlugin, createjs.FlashAudioPlugin]);
createjs.Sound.alternateExtensions(['mp3']);
createjs.Sound.on('fileload', this.loadHandler, this);
createjs.Sound.registerSound('path/sound/声音.ogg', 'sound1');
function loadHandler(event){
// 每个注册的声音都会触发
var instance = createjs.Sound.play('sound1'); // 播放指定id的声音(这里是上面注册的 'sound1'),也可以使用 '声音的全路径' 或 'event.src'
instance.on('complete', this.handleComplete, this);
instance.volume = 0.5;
}
 
可以在 'registerSound' 的 'data' 参数中,指定 '同一声音同时播放的最大实例数'。注意:如果未置顶,则会使用默认的最大限制数。目前 'HTMLAudioPlugin' 默认限制为2,而 'WebAudioPlugin' 和 'FlashAudioPlugin' 默认限制为100。
 
createjs.Sound.registerSound('声音.mp3', 'sound1', 4);
 
'Sound' 可以作为 'PreloadJS' 插件使用,以帮助正确预加载音频。通过 'PreloadJS' 预加载的音频,会自动注册到 'Sound' 类。当音频未预加载时,'Sound' 将自动执行内部加载。因此,如果音频未完成加载,可能会在第一次播放时,播放失败。使用 'fileload' 事件可以确定,声音什么时候完成的预加载。建议在播放所有声音前,预先加载。
 
var queue = new createjs.LoadQueue();
queue.installPlugin(createjs.Sound);
 
音频精灵(audio sprites - 音频雪碧图)
从0.6.0版本后,'SoundJS' 增加了对 'AudioSprite' 的支持。对不熟悉 '音频精灵' 的人来说,'音频精灵' 类似 'CSS精灵' 或 '精灵表单':多个音频资源分组合并到单个文件中。
 
示例:
var assetsPath = './assets/';
    var sounds = [{
        src: 'MyAudioSprite.ogg', data: {
        audioSprite: [
                {id: 'sound1', startTime: 0, duration: 500},
                {id: 'sound2', startTime: 1000, duration: 400},
                {id: 'sound3', startTime: 1700, duration: 1000}
                ]
            }
        }];
    createjs.Sound.alternateExtensions = ['mp3'];
    createjs.Sound.on('fileload', loadSound);
    createjs.Sound.registerSounds(sounds, assetsPath);
    // 加载完成后播放
    createjs.Sound.play('sound2');
 
手机播放
运行iOS的设备需要通过在用户发起的事件(例如触摸/点击)中播放至少一个声音来“解锁”WebAudio上下文。 早期版本的SoundJS包含了一个“MobileSafe”示例,但SoundJS 0.6.2不再需要这个示例。
1.在SoundJS 0.4.1及以上版本中,您可以初始化插件,也可以在用户输入事件的调用堆栈中使用playEmptySound方法手动解锁音频上下文
2.在SoundJS 0.6.2及以上版本中,SoundJS将自动侦听第一个文档级别的“mousedown”和“touchend”事件,并解锁WebAudio。这将继续检查这些事件,直到WebAudio上下文变为“解锁”(从“暂停”变为“正在运行”)
3.“mousedown”和“touchend”事件都可以用来在iOS9 +中解锁音频,“touchstart”事件可以在iOS8及更低版本中使用。当手势被解释为“点击”时,“touchend”事件将仅在iOS9中起作用,所以如果用户长按按钮,它将不再起作用。
4.当使用EaselJS Touch类时,由于MouseEvents被阻止,单击画布时,“mousedown”事件不会触发,以确保只有触摸事件触发。为了解决这个问题,你可以依靠“touchend”,或者:
1.将Touch类构造函数的allowDefault属性设置为true(默认为false)。
2.将EaselJS Stage上的preventSelection属性设置为false。
这些设置可能会改变您的应用程序的行为,不建议。
 
加载备用路径和无扩展文件
'SoundJS' 支持加载备用路径和无扩展文件,通过给 'src' 属性,传递一个对象来代替字符串,该属性是使用hash格式:{extension: 'path', extension2: 'path2'}。'SoundJS' 通过extension名,来判断是否支持该格式的文件。
 
可以将不同格式的文件,存放到不同的目录下,或CDN上。
 
按顺序依次尝试是否支持该格式,一旦支持则停止检测。对于 'SoundJS' 内部加载或通过 'PreloadJS' 加载,都有效。
 
注意:播放需要一个 'id'
 
示例:
var sounds = {
path: './audioPath/',
manifest: [
{id: 'cool', src: {mp3: 'mp3/声音.mp3', ogg: 'ogg/声音.ogg'}}
]
};
 
已知的浏览器和操作系统问题
不翻译了,看文档
 
3.AudioSprite
注意:AudioSprite不是一个类,但是它的用法很容易在文档中被忽略,所以单独提出来,可称为快速参考。
 
'音频精灵' 很像 'CSS精灵' 或 图像 '精灵表单':将多个音频资源分组合并为一个文件。'音频精灵' 可以解决某些浏览器的一次只能加载和播放一个声音的限制。建议在音频剪辑之间至少保持300ms的静音,来处理HTML音频标签不准确的情况,以防止意外播放相邻剪辑的音频。
 
音频精灵的优点
1.对于仅允许单个音频实例的旧版浏览器和设备提供更强大的支持(如:iOS 5)。
2.为IE9 audio标签限制提供了解决方法,IE9 audio 标签严格限制了一次可以加载多种不同的声音。
3.加载更快,将多次请求合并为一次。特别是在移动设备上,每个文件的网络往返行程会有明显延迟。
 
音频精灵的缺点
1.使用HTML或Flash音频时不能保证平滑的循环。如果需要平滑的循环,并且要支持非网络音频的浏览器,尽量避免使用 '音频精灵'
2.不能保证HTML音频会立即播放,特别是第一次播放。在某些浏览器(chrome!),HTML音频只能以当前下载速度加载,所以我们依靠 'canplaythrough' 事件,来确定音频是否已加载。因为 '音频精灵' 必须跳到前方,来播放特定的声音,音频可能还没有完全下载下来。
3.'音频精灵' 共享同样的核心资源,因此,如果有一个包含5个声音的 '音频精灵',并且被限制只能同时播放2个实例,就只能同时播放2个声音。
 
示例:
createjs.Sound.initializeDefaultPlugins();
    var assetsPath = './assets/';
    var sounds = [{
        src: 'MyAudioSprite.ogg', data: {
        audioSprite: [
                {id: 'sound1', startTime: 0, duration: 500},
                {id: 'sound2', startTime: 1000, duration: 400},
                {id: 'sound3', startTime: 1700, duration: 1000}
                ]
            }
        }];
    createjs.Sound.alternateExtensions = ['mp3'];
    createjs.Sound.on('fileload', loadSound);
    createjs.Sound.registerSounds(sounds, assetsPath);
    // 加载完成后播放
    createjs.Sound.play('sound2');
 
当创建新的 'AbstractSoundInstance' 时,也可以通过设置 'startTime' 和 'duration' 来在线创建 '音频精灵'
 
createjs.Sound.play('MyAudioSprite', {startTime: 1000, duration: 400});
 
优秀的 CreateJS社区 已经创建了一个工具来创建 '音频精灵',在https://github.com/tonistiigi/audiosprite 查看源码,以及 'jsfiddle'(http://jsfiddle.net/bharat_battu/g8fFP/12/) 将输出转换为 SoundJS 格式。
 
4.PlayPropsConfig
PlayPropsConfig 类,是一个存储可选的播放属性的类,以传递给 'Sound:play' 和 'AbstractSoundInstance:play' 调用。
 
可选的播放属性包括:
interrupt - 如果已经播放了最大个数的声音实例,如何中断正在播放的具有相同资源的任意的音频实例。可选值定义在 'Sound' 类的 'INTERRUPT_TYPE' 常量,默认由 'defaultInterruptBehavior' 定义。
delay - 音频开始播放的延迟时间,单位 'ms'
offset - 音频开始播放的偏移时间量,单位 'ms'
loop - 音频循环播放次数。默认是 '0-不循环', -1 - 无限循环
volume - 声音的音量,0-1之间。注意:主音量应用于单个音量
pan - 声音的左-右声部(如果支持),在-1(左)和1(右)之间。
startTime - 创建 '音频精灵'(和 duration 一起使用) 开始播放和循环时的初始偏移量,单位 'ms' 
duration - 创建 '音频精灵'(和 startTime 一起使用) 播放剪辑的时间量,单位 'ms' 
 
示例:
var props = new createjs.PlayPropsConfig().set({interrupt: createjs.Sound.INTERRUPT_ANY, loop: -1, volume: 0.5});
createjs.Sound.play('声音.mp3', props); // Sound:play
mySoundInstance.play(props); // AbstractSoundInstance:play
 
5.AbstractPlugin
所有其他插件类的基类
 
6.AbstractSoundInstance
当调用 'Sound API' 的 'play' 或 'createInstance' 方法时,都会创建 'AbstractSoundInstance' 实例。根据当前活动插件(4种不同插件类型),返回 'AbstractSoundInstance' 实例,以供用户后续控制
 
示例:
var myInstance = createjs.Sound.play('声音.mp3');
 
额外的附加参数,提供了一个快速方法,来决定如何播放声音。请参阅 'Sound API' 的 'play' 方法,查看播放参数列表
 
一旦创建了 'AbstractSoundInstance',就可以存储一个直接通过 'AbstractSoundInstance' 控制音频的引用。如果未存储引用,'AbstractSoundInstance' 将播放它的音频(和任何循环),然后从 'Sound' 类取消引用,标记为可清除,之后被垃圾回收清除。如果音频播放已完成,简单的调用 'play' 方法,将重建引用,来控制声音。
 
var myInstance = createjs.Sound.play('声音.mp3', {loop: 2});
myInstance.on('loop', handleLoop);
function handleLoop(event){
myInstance.volume = myInstance.volume * 0.5;
}
 
当声音播放完成、循环播放或播放失败,事件分发会通知事件监听器
var myInstance = createjs.Sound.play('声音.mp3', {loop: 2});
myInstance.on('complete', handleComplete);
myInstance.on('loop', handleLoop);
myInstance.on('failed', handleFailed);
 
7.WebAudioLoader
 
8.WebAudioPlugin
 
9.WebAudioSoundInstance
 
10.HTMLAudioPlugin
 
11.HTMLAudioSoundInstance
 
12.HTMLAudioTagPool
 
13.FlashAudioLoader
 
14.FlashAudioPlugin
 
15.FlashAudioSoundInstance
 
16.CordovaAudioLoader
 
17.CordovaAudioPlugin
 
18.CordovaAudioSoundInstance
 
19.ErrorEvent
通用错误事件,描述发生的错误,以及任何细节
 
// 下面几个,在 CreateJS 套件里是公共的
20.Event
 
21.EventDispatcher
 
22.Utility Methods
发布于
  用户评论
    生活编程