isis/boombox.js

Browser sound library which blended HTMLVideo and HTMLAudio and WebAudio

boombox

HTMLVideo, HTMLAudio, WebAudioを包括したブラウザ向け音声ライブラリです。

Audio系APIを統一したインターフェースで提供し、ラジカセ(boombox)のようなシンプルな操作で利用する事が可能です。

Why you should use boombox?

ブラウザでサウンドを鳴らすには、HTMLAudio/WebAudio/HTMLVideo が一般的に使われますが、APIの呼び出し方法やブラウザサポートなどがまちまちです。

boomboxは上記のような環境差異を吸収し一貫したAPIを提供しています。 また、ブラウザが非アクティブ時には音を停止したり、複数のサウンドを同時に利用するといった、スマートフォン特有の要件も想定して作成されています。

WebAudio では、ミキシングといった高度な利用も想定したAPIになっていますが、boombox はこれらの機能は拡張していません。あくまで基本的なブラウザでの利用シーンを想定しています。

しかし、これらの高度な機能へのアクセスは阻害しませんので、boomboxを拡張することは可能です。

Demo

Single Sound

Mix Sound

Features

• Play(再生)
• Pause(中断)
• Stop(停止)
• Replay(頭から再生)
• Resume(途中から再生)
• PowerON/PowerOFF(電源をON/OFF)
• Volume (音量の変更)
• LoopReproducing(ループ再生)
• Multi Sound Playing(複数サウンド再生)
  • ブラウザの対応状況に依存しますが、可能な限りサポート
• CORS Settings
  • crossOrigin、サウンドファイル配信サーバー・ロードオプションを適切に設定すればCORSを回避可能です。
• Filterings
  • 環境ごとに音の出し分けを行うフィルタリングをサポート

Reference information

OS/Browser	audio load event
IOS 5: Safari	suspend
IOS 6, 7: Safari	suspend
Android 2.3: basic	stalled
Android 4.0: basic	loadeddata
Mac OSX: Chrome	canplay

====

OS/Browser	Web Audio	HTML Audio	HTML Video
IOS 5: Safari	-	✔	✔ *1
IOS 6, 7: Safari	✔	✔	✔ *1
Android 2.3: basic	-	✔	✔
Android 4.0: basic	✔ *2	✔	✔
Mac OSX: Chrome	✔	✔	✔

*1 別アプリ 起動 : NG

*2 一部機種 対応 HTMLVideo : DOMにElement追加 必須 + DOMは、映像がないものを利用する場合は、表示領域外に指定すると良い

====

OS/Browser	1 sound	2 sound	multi sound
IOS 5: Safari	✔	-	-
IOS 6, 7: Safari	✔	✔	✔
Android 2.x: basic	✔	✔	✔
Android 4.x: basic	✔	✔ *1	-
Mac OSX: Chrome	✔	✔	✔

*1 HTMLAudio/HTMLVideo 併用

Install

Download

boombox.jsまたはboombox.min.jsをダウンロードしてください。

• boombox.js
• boombox.min.js

npm

$ npm install boombox.js

Bower

$ bower install boombox.js

component

$ component install CyberAgent/boombox.js

HTML

上記のいずれかの方法でダウンロードした後、scriptタグでロードしてください。

<script type="text/javascript" src="YOUR/PATH/TO/boombox.js"></script><!-- for development -->
<script type="text/javascript" src="YOUR/PATH/TO/boombox.min.js"></script><!-- for product -->

require.js サポート

Build

ビルドにはGruntを使用します。

$ git clone https://github.com/CyberAgent/boombox.js.git
$ cd boombox
$ npm install -g grunt-cli # 初回のみ
$ npm install . # 初回のみ
$ grunt

Browser Test

テスト環境としてGruntとbeez-foundationを使用します。

$ npm install -g beez-foundation # テスト用のWebサーバをインストール(初回のみ)
$ cd boombox
$ npm install . # 初回のみ
$ grunt foundation # ローカルサーバ起動

@see beez

@see beez-foundation

ブラウザでアクセスしてください。

script タグ : http://0.0.0.0:1109/m/boombox/spec/global.html

require.js : http://0.0.0.0:1109/m/boombox/spec/requirejs.html

Usage

Setup

boombox を使うためのセットアップ

boombox.setup();

Forced use options

強制的に音源の形式を指定

{
    webaudio: {
        use: true
    },
    htmlaudio: {
        use: true
    },
    htmlvideo: {
        use: true
    }
}

Load sound file

サウンドファイルをロード

var options = {
    src: [
        {
            media: 'audio/mp4',
            path: 'http://0.0.0.0:1109/m/spec/media/sound.m4a'
        }
    ]
};
boombox.load('sound', options, function (err, audio) {
    // サウンドファイルのロード
});

srcは、複数メディアタイプを指定可能です。先頭から順に評価していき、利用可能なメディアタイプをロードします。

Play

boombox.play() // 全てのサウンド

boombox.get('sound').play() // 特定のサウンド

Restriction

スマートフォンでは、ユーザーの操作(MouseEventsなど)をトリガーとした場合のみサウンド再生が可能な端末が多数を占めます。 これはブラウザの仕様になりますので、利用する端末で確認してください。

Volume control

boombox.get.volume(0.5) // 全てのサウンド。 0 < 1の間で引数の指定

boombox.get('sound').volume(0.5) // 特定のサウンド。 0 < 1の間で引数の指定

Cut off the power

サウンドがなっている場合でも、ラジカセで電源をOFFにしたように音が止まります。

Specified sounds

boombox.get('sound').power(boombox.POWER_OFF);

All sounds.

boombox.power(boombox.POWER_OFF);

Loop play

ループ再生には、２通りあります。

• ネイティブループ(HTMLAudio WebAudio HTMLVideo がサポートする機能)
• オリジナルループ(onEndedイベントを使っての連続再生ループ)

boombox.get('sound').setLoop(boombox.LOOP_ORIGINAL);
boombox.get('sound').play();
// or

boombox.get('sound').setLoop(boombox.LOOP_NATIVE);
boombox.get('sound').play();

onEnded

サウンドが最後まで再生された時に呼び出されます。 オーバーライドして使用してください。

boombox.get('name').onEnded = function () {
    // コールバック処理
}

Use filter

サウンドファイルをロードする前に、フィルタをいれて、端末やブラウザ毎に再生するサウンドを選ぶことができます。 複数フィルタを設定することが出来ますが、一つでも NG であれば残りのフィルタは処理されません。

boombox.addFilter('chrome', function filter() {
    if (/Chrome/.test(window.navigator.userAgent)) {
        return false; // [ OK ] Chrome
    } else {
        return true;  // [ NG ] Chrome 以外
    }
});
var options = {
    src: [
        {
            media: 'audio/mp4',
            path: 'http://0.0.0.0:1109/m/spec/media/sound.m4a'
        }
    ],
    filter: ["chrome"] // 使用したいフィルタを指定
};
boombox.load('sound', options, true, function (err, audio) {
    // サウンドファイルのロード
});

ブラウザのサウンドは、ブラウザにより対応がまちまちです。フィルタを使って必ず個別に制御する必要があります。

Forced use HTMLVideo

boombox.load()の第3引数にtrueを渡すと強制的にHTMLVideoを利用します。

HTMLAudioが１音しかサポートしていない場合に利用します。

var options = {
    src: [
        {
            media: 'audio/mp4',
            path: 'http://0.0.0.0:1109/m/spec/media/sound.m4a'
        }
    ]
};
// loadの第3引数にtrueを渡す
boombox.load('sound', options, true, function (err, audio) {
    // サウンドファイルのロード
    // audioがHTMLVideoの場合は、DOMへ追加が必要です。
});

Cache

一度ロードしたサウンドファイルは、boombox.pool にインスタンスとしてキャッシュされます。

ブラウザによるキャッシュはそれぞれ挙動が異なるため、SPA(シングルページアプリケーション)であれば、boombox.poolのキャッシュは非常に有効です。

Priority

boomboxがデフォルトで使用するAPIの順番は以下の優先度になります。

WebAudio > HTMLAudio > HTMLVideo

• WebAudioとHTMLAudio両方が実装されてるブラウザの場合はWebAudioが優先されます。
• HTMLVideoはオプションで有効にしない限りは使いません。

currentTime

HTMLAudio HTMLVide のシーク設定(currentTime) が設定出来ないブラウザがある場合は 、内部でcurrentTimeが設定されても無視されます。

Inactive

ブラウザがバックグラウンドになった状態を、window.onpageshow/onpagehide window.onblur/onfocus Event.onVisibilityChange を利用して判定しています。

すべての端末で取得可能ではないので、利用している環境で確認して下さい。

Customize Events

カスタマイズ可能な関数はすべて、onXXXX の命名規則になっていますのでそのまま関数を上書きしてください。

onVisibilityChange(e)

visibilityChangeイベントの発生に合わせて実行されます。

onFocus(e)

window.onFocusイベントの発生に合わせて実行されます。

onBlur(e)

window.onBlurイベントの発生に合わせて実行されます。

onPageShow(e)

window.onpageshowイベントの発生に合わせて実行されます。

onPageHide(e)

window.onpagehideイベントの発生に合わせて実行されます。

onEnded(e)

サウンドが最後まで再生された時に実行されます。途中で停止された場合は発火しません。

// シンプルな使用法
boombox.onFocus = function (e) {
    logger.trace('onFocus');
}

// 関数のオーバーライド

var fn = boombox.onFocus;

boombox.onFocus = function () {
    console.log("override:", onFocus);
    fn.apply(boombox, arguments);
}

TODO

• AudioSprite: 音源を１ファイルにまとめる
  • Check develop branch
• localStorage: Audioのキャッシュ

====

Sample Sound File

Location path

• spec/media/sound.m4a
• spec/media/sound.wav

Creation software

Sound that was created in AudioSauna

http://www.audiosauna.com/

Contributing

• Kei FUNAGAYAMA - @fkei github
• Masaki Sueda - github
• HIRAKI Satoru - github

Copyright

CyberAgent, Inc. All rights reserved.

LICENSE

@see : LICENSE

The MIT License (MIT)

Copyright © CyberAgent, Inc. All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.