sonorous
v1.0.0
Sonorous.js は、Web オーディオの操作を効率化し、Web アプリやゲームにオーディオを簡単に統合できるようにする JavaScript オーディオ ライブラリです。 WebAudio API の抽象化として、Sonorous.js は必要なユーザーにきめ細かい制御を提供し、同時にブラウザー間の問題もすべて処理します。
からのチームによる
ラジカセ
トラックミキサー
文字列マスター
ソース コードについては、リポジトリのexamples/ディレクトリを参照してください。
まず、 npm install --save sonorousを実行します。
Sonorous.js を使用するには、Sonorous.js を必須にするか、ファイルにインポートします。
ES6
import Sonorous from 'sonorous';
CommonJS
const Sonorous = require('sonorous');
Sonorous は、Sonor の追加と削除を処理するマネージャーです。 Sonor は 1 つのオーディオ ファイルのラッパーと考えることができます。各ソナーには、 play() 、 pause() 、 volumeなどの独自の機能があります。Sonorous インスタンスを介してすべてのソナーにグローバル プロパティ ( masterVolume 、 muteAllなど) を設定することもできます。
例：
let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3');
mySonor.play(); // begins to play test_sound_1.mp3
mySonor.volume = 0.5; // sets the volume of the sonor to 0.5
Sonorous.muteAll = true; // mutes all sonors
mySonor.stop(); // stops the playback of test_sound_1.mp3
詳細については、「API」セクションを参照してください。
Sonorous はシングルトンであり、すべての Sonor オブジェクトを管理します。
Sonor[] (読み取り専用)このマネージャーに追加されたすべての Sonor オブジェクトの配列。
AudioContext (読み取り専用)Sonorous によって使用される現在のオーディオ コンテキストを返します。
numberこれは読み取り/書き込みプロパティであり、すべての Sonor オブジェクトの音量を設定する masterGain ノードに接続されます。有効な値は 0 ～ 1 です。
booleanこれは、すべての Sonor オブジェクトをミュート/ミュート解除する読み取り/書き込みプロパティです。
booleanWebAudio がサポートされている場合は true を返し、サポートされていない場合は false を返します。
SonorSonor オブジェクトを作成し、成功した場合はそれを返します。
| パラム | タイプ | 説明 |
|---|---|---|
| 送信元 | string 、 string[] 、 SonorSrc 、 SonorSrc[] | このサウンドが関連付けられているメディア。さまざまな形式の配列を渡す場合、現在のブラウザで動作する最初の形式が使用されます。ソース URL に拡張子がない場合は、以下で定義されている SonorSrc オブジェクトを使用して手動で拡張子を指定できます。 |
| オプション | object | オプションの構成オブジェクト。以下のオプションを参照してください。 |
addSonor()の構成オプション:
| オプション | タイプ | デフォルト | 説明 |
|---|---|---|---|
| ID | string | ランダムに生成される | 一意の ID。渡さない場合は、このオブジェクト用に 1 つが作成されます。 |
| プリロード | boolean | true | true の場合、URL を自動的にロードしようとします。 false の場合、呼び出しコードは明示的にload()を呼び出す必要があります。 |
| 音量 | number | 1.0 | サウンドの初期音量。 |
| ループ | boolean | false | オーディオを永久にループするかどうかを決定します。 |
| 自動再生 | boolean | false | ロード時にオーディオをすぐに再生するかどうかを決定します。 |
| ミュートされた | boolean | false | 読み込まれたらミュートします。 |
| プールサイズ | number | 1 | 再生可能なオーディオセグメントの総数。この数値を増やすと、最初の再生が終了する前に、同じサウンドの同時再生を複数回開始できるようになります。 |
| 最適化 | string | 'time' | 'time'または'memory'のいずれかになります。これにより、デコードされたバッファがキャッシュされるかどうかが決まります。デフォルトでは、そうなります。メモリが懸念される場合は、これを「メモリ」に設定し、再生を開始する前にバッファをデコードする間にわずかな遅延が発生することを想定してください。 |
| 財産 | タイプ | 説明 |
|---|---|---|
| URL | string | 拡張子なしのオーディオのソース URL。 |
| 形式 | string | このオーディオ ソースに対して手動で指定された形式。 |
例：
let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3', {
id: 'myFirstSonor',
preload: false,
volume: 0.5,
poolSize: 3 });
let testSoundSonor = Sonorous.addSonor(
{
url: './test_audio/test_sound_2',
format: 'mp3'
},
{ id: 'test_sound_2'});
Sonor オブジェクトをマネージャーから削除します。これにより、サウンドがアンロードされて破棄され、このサウンドに関連するすべてのプロセスが直ちに停止されます。
既存の Sonor オブジェクトを削除し、オーディオ コンテキストをリセットします。
すべての Sonor オブジェクトを破壊します
SonorSonor オブジェクトを返す
例：
Sonorous.addSonor('./test_audio/test_sound_1.mp3', { id: 'mySonorId'});
let mySonor = Sonorous.get('mySonorId');
booleanSonorous に渡された ID と一致する Sonor がある場合は true を返します
オーディオのロックが解除されたときにトリガーされます (ページとのユーザーの対話を通じて)。一部のブラウザでは、ユーザーが何らかの方法でページを操作する前に音声を再生することができません。このイベントは、オーディオが自由に再生できるようになるとトリガーされます。
このモジュールには、音量の調整、再生、一時停止など、サウンドを制御するためのほとんどの機能が含まれています。AudioContext のロックが解除されていない場合 (ユーザー ジェスチャなどによって)、すべてのアクションがキューに入ります。これらのアクションは、AudioContext のロックが解除され、バッファがロードされるとすぐに実行されます。
string (読み取り専用)このサウンド オブジェクトの一意の ID を返す読み取り専用プロパティ。 ID は初期化中にオプションで提供されます (詳細については、Sonorous の addSonor() を参照してください)。初期化中に ID が指定されなかった場合、ランダムに生成された英数字文字列が ID として割り当てられます。 Sonorous は、 Sonorous.get(id)関数を使用して、ID によって Sonor オブジェクトを取得できます。
string (読み取り専用)このオブジェクトのソースオーディオの URL を返します。
boolean (読み取り専用)初期化中にソナーがプリロードするように設定されていた場合は true を返します。
string (読み取り専用)ソナーの負荷状態を反映します。 'loading' 、 'loaded' 、または'unloaded'のいずれかになります。
例：
let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3', { preload: false });
console.log(mySonor.state); // prints out 'unloaded'
mySonor.load();
console.log(mySonor.state); // prints out 'loading'
number (読み取り専用)ソナーの継続時間を返します。この値は、Sonor がロードされている場合にのみ使用可能であることに注意してください。ソナーがアンロードされている場合、これは 0 を返します。
boolean (読み取り専用)サウンドが現在再生中の場合は true を返し、そうでない場合は false を返します。
number (読み取り専用)サウンドがどこまで再生されるかを返します。 poolSize > 1 の場合、最初のアクティブなオーディオ セグメントを使用してこの値が返されます。
numberプール内のオーディオ セグメントの合計数を制御する読み取り/書き込みパブリック プロパティ。同じサウンドの再生を同時に開始したい場合は、プールのサイズを大きくします。デフォルトは 1 です。
プール サイズが増加すると、セッター/ゲッターは次のように動作します。 セッターはすべてのアクティブなセグメントに適用されます。すべてのゲッターは、最初のアクティブなオーディオ セグメントを使用して、要求された情報を返します。 (「アクティブ セグメント」とは、すでにプールから取得されており、現在使用されているセグメントです。)
例：
let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3');
mySonor.poolSize = 2;
mySonor.play();
setTimeout(() => { mySonor.play(); }, 1000); // will result in the same audio being played twice, with the second playback 1s behind the first one.
numberこのサウンドの再生レートを制御する読み取り/書き込みパブリック プロパティ。 poolSize > 1 の場合、最初のアクティブなオーディオ セグメントを使用してこの値が返されます。
booleanサウンドをループするかどうかを制御する読み取り/書き込みパブリック プロパティ。このプロパティを設定すると、すべてのアクティブなセグメントに適用されます。
numberこのサウンドの音量を制御する読み取り/書き込みパブリック プロパティ。このプロパティを設定すると、すべてのアクティブなセグメントに適用されます。
booleanサウンドをミュートするかどうかを制御する読み取り/書き込みパブリック プロパティ。このプロパティを設定すると、すべてのアクティブなセグメントに適用されます。
オーディオソースを再生します。ソナーがロードされていない場合は、ソナーをロードし、ロードされると再生します。オーディオ セグメントのプールが 1 より大きい場合、必要に応じてプールからセグメントを取得します。 「アクティブ セグメント」とは、すでにプールから取得されており、現在使用されているセグメントです。プレイのロジックは次のとおりです。
if there are no active segments:
retrieve one from the pool and play it.
if there are active segments:
if none are currently playing:
play all active segments
else:
retrieve/play a segment from the pool
if there are no available segments in the pool:
do nothing and report an error
すべてのアクティブなオーディオ セグメントは一時停止されますが、プールには戻りません。
すべてのアクティブなオーディオ セグメントを停止し、プールに戻します。
指定されたフェード期間の間、オーディオを現在のボリュームからターゲットボリュームまでフェードさせます。 startTime が指定されており、それが audioContext の現在時間より大きい場合、フェードはその時点で開始されます。それ以外の場合は、すぐに開始されます。フェード期間は秒単位で指定する必要があります。
は、経過した時間 (秒単位) に再生を移動します。
バッファをロードし、再生用のオーディオセグメントを準備します。
バッファを削除し、すべてのアクティブなオーディオ セグメントをプールに返します。
Sonor オブジェクトはイベント エミッター (オン/オフ/1 回) です。利用可能なイベントのリストは以下をご覧ください。
サウンドがロードされるとトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
プレイ開始時にトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
音が一時停止するとトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
サウンドの再生が停止するとトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
サウンドが持続時間の終わりに達するとトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
currentTime が手動で変更されたときにトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
| シーク位置 | 番号 | Sonor が求めたタイムコード |
音量が変化するとトリガーされます（ボリュームまたはミュート経由）
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
| 新しいボリューム | 番号 | Sonor に設定された新しいボリューム |
再生レートが変化するとトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
| 新しい再生レート | 番号 | Sonor に設定された新しい再生レート |
フェードが終了するとトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
Sonor の操作中にエラーが発生した場合にトリガーされます
| パラム | タイプ | 説明 |
|---|---|---|
| ソナーオブジェクト | ソノール | 操作された Sonor のインスタンス |
| エラー | 弦 | エラーメッセージ |
リポジトリをローカルに取得したら、 yarn installを実行して依存関係をインストールします。
npm run build Sonorous の非縮小バージョンをビルドします。npm run build:production Sonorous の縮小および gzip 圧縮されたバージョンをビルドします。npm run start-dev縮小されていない Sonorous をビルドし、オーディオ コントロールを備えた単純な HTML ページを開きます。そこを通じて、Sonorous の機能のほとんどを手動でテストできます。npm run testすべての単体テストを実行します。 (単体テストは Jest を使用して作成されます)私たちはプルリクエストやコードベースへの変更提案を積極的に歓迎します。投稿する際は、次の手順に従ってください。
developからフォークして分岐し、ローカル開発ガイドに従ってビルド可能にしてください。Sonorous は、WebAudio が存在する場所であればどこでもサポートされます。完全なリストについてはここをクリックしてください。
