vnctst-audio4 demo

目次

• 前書き
• 前準備
• 基本操作
• 設定項目
• 高度な操作
• 補助機能
• ファイル一覧の取得
• 必要知識
• FAQ

• これは、ゲーム向けの音響ファイル再生ライブラリである「vnctst-audio4」のオンラインデモです。
• vnctst-audio4についての概要はvnctst-audio4のgithubリポジトリを参照してください。
• vnctst-audio4には「cljs版」と「js版」があります。サンプルコードの表記を変更したい場合は上の方にあるボタンを押してください。
• サンプルボタンに書いてある以外の操作も可能です。ブラウザのデバッグコンソールを開き、サンプルボタンの表記を参考にjs式を入力してください。
• このデモでは、ページのロード時にdebug?フラグ(詳細は「設定項目」を参照)を有効化している為、再生や停止等の操作を行うとデバッグコンソールにログが表示されます。これを確認したい場合もデバッグコンソールを開いておくとよいでしょう。

このセクションで紹介している機能だけでも大体なんとかなります

BGMを鳴らす

"bgm/va32.ogg"もしくは"bgm/va32.mp3"もしくは"bgm/va32.m4a"をループBGMとして再生する。

この引数は"bgm/va32.ogg"のように拡張子を普通に付けて指定してもよいのだが、そうすると当然、ogg再生のできないブラウザでは音が出ない事になる。

そこで"bgm/va32.*"形式で指定する事で、oggが再生可能ならoggを、そうでなければmp3やm4aを再生する事ができる。ただし、もちろん各拡張子のファイルを予め設置しておく必要がある(ogg/mp3/m4aの三種類全てを設置する必要はなく、mp3かm4aのどちらかは省略できる。当ライブラリではm4aを省略してoggとmp3の二つだけ設置しておくのを推奨)。

引数は"http://..."のようなurlも指定可能だが、その場合はCORSの設定が必要になる場合がある事に注意。

「指定した拡張子の再生をブラウザがサポートしていない」「ファイルが存在しない」等の理由で再生できなかった場合は何も行われない(例外も投げられない。ただし後述のdebug?フラグが有効ならコンソールにエラーメッセージが出力される)。

"bgm/cntr.ogg"もしくは"bgm/cntr.mp3"もしくは"bgm/cntr.m4a"をループBGMとして再生する。

もし既に別のBGMが再生中の場合は、そのBGMのフェードアウトを開始し、フェードアウトが完了してから再生が開始される。

この再生/停止回りは雑に操作しても適切にフェードアウト/フェードイン処理が行われるので、この辺りの再生/停止ボタンを素早く押しまくっても問題は出ない。実運用時も雑に扱ってよい。

"bgm/ny2017.ogg"もしくは"bgm/ny2017.mp3"もしくは"bgm/ny2017.m4a"を非ループBGMとして再生する。

ループしない点以外は前述のBGM再生と同じ。

"bgm/cntr.ogg"もしくは"bgm/cntr.mp3"もしくは"bgm/cntr.m4a"をループBGMとして再生するが、再生開始時にフェードインがかかるようにする。

フェードイン開始する事以外は前述のBGM再生と同じ。

BGMを止める

現在再生中のBGMをデフォルト秒数(1秒)かけてフェード終了させる。

再生中でない場合は何も起きない。

この「デフォルト秒数」は後述の「設定項目」から変更可能。

現在再生中のBGMを3秒かけてフェード終了させる。

現在再生中のBGMを即座に停止させる。

SEを鳴らす

"se/launch.ogg"もしくは"se/launch.mp3"もしくは"se/launch.m4a"をSEとして再生する。

SEとしての再生では、音源の多重再生が可能となる(ボタンを連打しても前の音が途切れたりしない。ただし一部の古い環境では非対応)。

"se/kick.ogg"もしくは"se/kick.mp3"もしくは"se/kick.m4a"をSEとして再生する。

現在再生中のSE全てをデフォルト秒数(0秒)かけてフェード終了させる(0秒の時は即座に終了する)。

再生中でない場合は何も起きない。

この「デフォルト秒数」は後述の「設定項目」から変更可能。

現在再生中のSE全てを0.5秒かけてフェード終了させる。

項目は多いですが、実際にいじる必要があるのは音量設定とデバッグ出力ぐらいです

現在の設定項目の値を取得する

各種の設定値を取得する。

このボタンで指定しているvolume-masterは「マスター音量」の現在値(詳細については次の「音量設定」の項目を参照)。

引数を変更する事で様々な設定値の取得が行えるが、項目数が多いので以下ではボタン化を省略している。確認したい場合は実際にコンソールから実行してみるとよい。

音量設定

マスター音量を設定する(音量値は0.0～1.0の範囲、初期値は0.6)。

マスター音量はBGMとSEの両方に影響する。

BGM音量を設定する(音量値は0.0～1.0の範囲、初期値は0.6)。

実際のBGMの再生音量は、この項目とマスター音量から決定される。

初期状態ではマスター音量0.6(60%)かつBGM音量0.6(60%)なので、実際のBGMの再生音量は0.36(36%)相当となる。

このデフォルト音量では小さすぎると思うなら、もっと大き目の値を設定するとよい。

SE音量を設定する(音量値は0.0～1.0の範囲、初期値は0.6)。

詳細は上のBGM音量の解説文と大体同じ。

デバッグ出力

デバッグログをコンソールへ出力したい場合はtrueを設定する(初期値はfalse、ただしこのデモでは最初からtrueにしてある)。

このvnctst-audio4では「雑に扱っても問題が起こらない」事を方針としているので、ファイルのロードに失敗したりしていても再生時に例外は投げられない。単に何も再生されないだけとなる。しかしこれでは開発時に不便な為、この設定をtrueにする事で、エラー等が起こった際に、その内容をコンソールへと出力するようにできる。

些細なデバッグログもコンソールへ出力したい場合はtrueを設定する(初期値はfalse、ただしこのデモでは最初からtrueにしてある)。

この設定は前述のdebug?が有効な時にしか意味を持たない。

これを有効にする事で、前述のエラー以外に、「このBGMの再生が開始された」「このSEの再生が停止された」といった、些細な情報までコンソールに出力されるようになる。しかしほとんどの場合は邪魔にしかならないので、開発時であっても普段はfalseにしておき、再生/停止タイミング等をきちんと調べたい時のみtrueにするとよい。

あまり使われない項目

ここは読み飛ばしても問題ありません

デフォルトのBGMフェード秒数を設定する(初期値は1)。0を設定するとフェードなしで即座に停止するようになる。

デフォルトのSEフェード秒数を設定する(初期値は0)。0を設定するとフェードなしで即座に停止するようになる。

vnctst-audio4は、ブラウザのタブをバックグラウンドにした際にBGMを自動的に一時停止する機能を持っている(非対応ブラウザあり。また既に再生中のSEは停止されず、新たに再生されようとしたSEのみ無音化される)。

この項目にtrueを設定する事で、その機能を無効化できる(初期値はfalse)。

同一SE連打防止機能の閾値(秒)を設定する(初期値は0.05)。

0を設定すると無効化できる。

ゲームでは同じSEが特定タイミングで複数同時に発生する事がよくあるが、何も考えずにこれを行うと音が重なって音量の増幅が起こり、爆音や音割れの原因となってしまう(例えば、「艦これ」での爆撃シーンや雷撃シーンなどで顕著)。vnctst-audio4ではこの問題を防ぐ為に、この設定秒数以内での同一SEの再生は一つだけになるように内部で制限している。

「"filename.*"」指定による拡張子自動選択機能(autoext)の拡張子の候補リストを設定する。

autoext指定した音源ファイルのロード時には、このリストの順でトライされる(ブラウザが対応していない拡張子はスキップされる)。

なお ogg, mp3, m4a 以外の拡張子を指定する際には、上記のwavのように、一緒にmime-typeも指定する必要があるので注意。

初期値は["ogg" "mp3" "m4a"]。

この値を変更した場合は内部状態をリセットする必要がある為、全ての再生中音源は停止され、また全てのロード済音源もアンロードされる(ロード/アンロードについては後述)。

trueを設定する事で、モバイル環境での音源再生の一切を禁止する(初期値はfalse)。

非モバイル環境では何も起こらない。

trueを設定する事で、WebAudioによる音源再生を禁止する(初期値はfalse)。

初期状態では、WebAudioが利用可能ならWebAudioを使い、そうでなければHtmlAudioが利用可能ならHtmlAudioを使い、どちらも使えなければ再生は無効化される、という優先順位になっている。

通常はこのままで適切に機能するが、「HtmlAudioでの動作確認を取りたい」等の時はこの設定項目を有効にするとよい。

この値を変更した場合は内部状態をリセットする必要がある為、全ての再生中音源は停止され、また全てのロード済音源もアンロードされる。

trueを設定する事で、HtmlAudioによる音源再生を禁止する(初期値はfalse)。

概要については上のdisable-webaudio?の項目を参照。

この値を変更した場合は内部状態をリセットする必要がある為、全ての再生中音源は停止され、また全てのロード済音源もアンロードされる。

ここにキャッシュ防止用の文字列を設定する事で、音源ロード時のurlの末尾にQUERY_STRINGとして、その文字列が設定される(初期値はnil)。

音響ファイル指定はページのurlからの相対位置で指定するが、この相対位置を変化させたい場合にこれを設定する(初期値は"")。

なお、「音源のロードよりも先に設定しておく」、「設定する場合は末尾に/を必ず付ける」、この二つを厳守する事。

プリロード / アンロード

BGMやSEの音響ファイルの初回再生時は、実は内部でファイルのロードを行いそれが完了してから再生している。その為、初回再生時のみ実際に再生されるまでタイムラグがある(ファイルサイズが小さかったりブラウザキャッシュがなされていれば目立たないが)。このタイムラグをなくすには、再生するよりずっと前の段階でロードを行っておけばよい。

この関数はそのロードをバックグラウンドで行わせる。

一度に大量のファイルのロード要求が来た場合でも、同時にロードを実行せずに一つずつ順番にロードを実行していく為、大量のhttpコネクションを消費してしまう事はない。雑にロード要求を投げてよい。

指定したファイルが既にロード中だったりロードが完了している場合は何も行われない。

音響ファイルのロードはバックグラウンドで非同期に実行される。この関数は、そのロード処理が正常終了/異常終了のどちらにせよ完了しているかどうかを真偽値で返す。

ローディング画面等では、定期的にこの関数を呼んでロードが完了したかを確認するとよい。

前述のloaded?/isLoadedではロードの完了は分かるものの、正常にロードできたかまでは分からない。

ロード時にエラーが起こったかどうかを調べたい時は、真偽値としてそれを返すこの関数が使える。

なお、エラーの起こったファイルを再生しようとしても何も起こらないので、雑に扱っても問題ない(もちろん、debug?フラグを有効にしていればコンソールへのエラー通知は行われる)。

ただし上記について例外があり、別のBGMの再生中のみ、再生中BGMのフェードアウト終了が開始される仕様としている。これはBGM変更の状況では、エラーの起こったファイルの再生が無視されて元のBGMが鳴り続けるよりも、元のBGMは普通に終わらせておいた方がまだマシであると考え、この仕様とした。

音響ファイルの数が非常に多い場合やサーバで動的に生成した音響ファイルを扱う場合、ロード済の音源が多くなりメモリを圧迫してしまう事がある。その場合はこの関数を使い、再生しない音源をアンロードするとよい。

もしアンロード時にまだその音響ファイルが再生中だった場合、その再生は強制停止される。

アンロードを行った音響ファイルを再度再生しようとした場合は内部でファイルのロードが実行し直されるので、効率は悪いものの再生自体に支障が出る事はない。

アンロード後は、前述のloaded?/isLoadedが、falseを返すように戻る。

そもそもロードしていない音響ファイルをアンロードしようとしても何も起こらない(エラーも投げられない)ので、雑に実行しても問題ない。

ロード最中の音響ファイルのアンロードも問題なく行える。

ロード済の全ての音響ファイルをアンロードする。

BGMの再生オプション

"bgm/va32.ogg"もしくは"bgm/va32.mp3"もしくは"bgm/va32.m4a"をBGMとして再生する。

volumeは個別の音量。通常 0.0 ～ 1.0 の数値。指定しない場合は 1.0 が指定された事になる。volumeに1.0以上の数値を指定する事も可能だが、マスターボリュームとBGMボリュームの設定によっては効果が出ない(「volume * マスターボリューム * BGMボリューム」の値を1.0以上にする事はできない為)。

pitchは再生レート。 0.1 ～ 10.0 の数値。指定しない場合は 1.0 が指定された事になる。この数値が1.0より小さいと再生速度と音程が低下し、1.0より大きいと再生速度と音程が上昇する。ブラウザによっては常に1.0固定となる為、この数値に依存するような処理は避けた方が無難。

panはステレオでの左右への寄りの値。 -1.0 ～ 1.0 の数値。-1.0が最も左寄り、0なら中央、1.0が最も右寄りに再生される。指定しない場合は 0 が指定された事になる。ブラウザによっては常に中央固定になる為、この数値に依存するような処理は避けた方が無難。

"bgm/va32.ogg"もしくは"bgm/va32.mp3"もしくは"bgm/va32.m4a"をBGMとして再生する。

各オプションの詳細については前述の説明を参照。

cljs版では、追加の引数は一つのmapで指定してもよいし、複数のkey-value値として指定してもよい(js版ではObject形式での指定のみ可能)。

"bgm/va32.ogg"もしくは"bgm/va32.mp3"もしくは"bgm/va32.m4a"をBGMとして再生する。

オプションの詳細については前述の説明を参照。

"bgm/ny2017.ogg"もしくは"bgm/ny2017.mp3"もしくは"bgm/ny2017.m4a"をBGMとして再生する。

oneshot?に真値を指定する事により、非ループ再生となる。前述のbgm-oneshot!/bgmOneshotは、内部でこのパラメータを設定している。

fadeinにフェードイン秒数を指定する事により、再生開始時にフェードインが適用されるようになる。前述のbgm-fadein!/bgmFadeinは、内部でこのパラメータを設定している。

"bgm/ny2017.ogg"もしくは"bgm/ny2017.mp3"もしくは"bgm/ny2017.m4a"の1.2秒目の位置から、BGMとして再生する。

positionで秒数を指定する。

なお、同時にpitchを指定した場合であっても pitch=1 の前提で再生位置が反映される。

"bgm/noise.ogg"もしくは"bgm/noise.mp3"もしくは"bgm/noise.m4a"を「background-sound」という名前のBGM再生チャンネルにて、ループBGMとして再生する。

BGM再生チャンネルは必要な数だけ作成でき、違うBGM再生チャンネルは同時に再生される。これは「BGMと同時に雨の音などの環境音を再生したい」ような用途に利用できる。

BGM再生チャンネル名には、cljs版では任意のキーワードが、js版では任意の文字列が指定できる。

BGM再生チャンネル名が省略された場合はデフォルト値として「BGM」が指定されたものとして扱われる。

BGM再生チャンネル名以外にも、前述の他のオプションも同時に指定可能。

第二引数で指定した「BGM再生チャンネル名」で再生中のBGMだけを、第一引数で指定したフェード秒数かけて終了する。

第一引数に nil / null を指定した場合は、設定されたデフォルト値がフェード秒数として適用される(デフォルト値の詳細については「設定項目」セクションを参照)。

第二引数省略時は全てのBGMチャンネルに対して停止処理が行われる。

この例では「background-sound」だけが停止される。

第二引数で指定した「BGM再生チャンネルID」で再生中のBGMだけを、第一引数で指定したフェード秒数かけて終了する。

この例では「BGM」、つまりチャンネル無指定でのBGM再生だけが停止される。

SEの再生オプション

"se/launch.ogg"もしくは"se/launch.mp3"もしくは"se/launch.m4a"をSEとして再生する。

volumeは個別の音量。通常 0.0 ～ 1.0 の数値。指定しない場合は 1.0 が指定された事になる。volumeに1.0以上の数値を指定する事も可能だが、マスターボリュームとBGMボリュームの設定によっては効果が出ない(「volume * マスターボリューム * SEボリューム」の値を1.0以上にする事はできない為)。

pitchは再生レート。 0.1 ～ 10.0 の数値。指定しない場合は 1.0 が指定された事になる。この数値が1.0より小さいと再生速度と音程が低下し、1.0より大きいと再生速度と音程が上昇する。ブラウザによっては常に1.0固定となる為、この数値に依存するような処理は避けた方が無難。

panはステレオでの左右への寄りの値。 -1.0 ～ 1.0 の数値。-1.0が最も左寄り、0なら中央、1.0が最も右寄りに再生される。指定しない場合は 0 が指定された事になる。ブラウザによっては常に中央固定になる為、この数値に依存するような処理は避けた方が無難。

"se/launch.ogg"もしくは"se/launch.mp3"もしくは"se/launch.m4a"をSEとして再生する。

各オプションの詳細については前述の説明を参照。

cljs版では、追加の引数は一つのmapで指定してもよいし、複数のkey-value値として指定してもよい(js版ではObject形式での指定のみ可能)。

"se/launch.ogg"もしくは"se/launch.mp3"もしくは"se/launch.m4a"をSEとして再生する。

オプションの詳細については前述の説明を参照。

SE再生関数は、返り値として「SE再生チャンネルID」を返す。これについての詳細は次の項目を参照。

第二引数で指定した「SE再生チャンネルID」に対応するSEだけを、第一引数で指定したフェード秒数かけて終了する。

「SE再生チャンネルID」は、SE再生関数の返り値として得られる(「SE再生チャンネルID」はこの個別の停止指定の為の存在なので、個別停止を行わないのであれば、そのまま捨てても全く問題ない)。

第二引数で指定した「SE再生チャンネルID」に対応するSEの再生が既に完了している場合は何も起きない。

第一引数に nil / null を指定した場合は、設定されたデフォルト値がフェード秒数として適用される(詳細については既出の「設定項目」内「音量設定」の項目を参照)。

第二引数省略時は全てのSEに対して停止処理が行われる。

この機能は、登場キャラクタがボイスを発生するような内容のゲームでの利用を想定している。

"se/kick.ogg"もしくは"se/kick.mp3"もしくは"se/kick.m4a"をSEとして再生する。

ただしバックグラウンドタブであっても強制的に再生が行われる(通常はバックグラウンドタブ時はSEの再生が行われない)。

通常のSE再生と同様に、追加の引数を取る事もできる(詳細は上記参照)。

その他

現在BGMとして再生中の音源の現在の再生位置を秒数で取得する。追加引数としてBGMチャンネルを指定可能。何も再生していない場合は nil / null が返る。

再生時にpitchを指定していても、常に pitch=1 での秒数として返される。また、再生時にpositionを指定していても、常に音源の先頭からの秒数として返される。

※この機能はまだ動作検証が不十分であり、不具合のある可能性がある。

プリロード済の"bgm/ny2017.ogg"もしくは"bgm/ny2017.mp3"もしくは"bgm/ny2017.m4a"の音源としての全体の秒数を取得する。

プリロード済でない場合は nil / null が返る。

旧版互換インターフェース

旧版であるvnctst-audio3由来のインターフェースです

"se/launch.ogg"もしくは"se/launch.mp3"もしくは"se/launch.m4a"を非ループBGMとして再生する。

前述のbgm-oneshot!/bgmOneshotと全く同じ。

分かりづらいのでobsoletedとする。

"bgm/noise.ogg"もしくは"bgm/noise.mp3"もしくは"bgm/noise.m4a"を「BGS」という名前のBGM再生チャンネルで再生する。

分かりづらいのでobsoletedとする。

キーワードでpathを指定する機能はcljs版のみ対応しており、js版では対応していない。

引数にキーワードを指定した場合、:fooなら"foo.*"へと、:bar/bazなら"bar/baz.*"へと、自動的に展開されて扱われる。

キーワード構文の仕様上、二段以上深いディレクトリ内にあるファイルをキーワード構文で指定する事はできない。この制約により、利用できる場面はかなり限定される。

便利関数類です

vnctst-audio4のライブラリとしてのバージョン文字列。js版のみ提供。

oggが再生可能なら真値を返す。

mp3が再生可能なら真値を返す。

m4aが再生可能なら真値を返す。

引数として渡したmime-typeが再生可能なら真値を返す。

この環境が引数として渡した端末タイプなら真値を返す。

端末タイプはtablet mobile android ios chrome firefoxが指定可能。ただしこれは User-Agent による判定の為、誤判定する場合もある事に注意。

これはjs版では関数だが、cljs版では単なるsetでありset向けの各種の操作を適用する事ができる。

各ボリューム設定は0.0～1.0の小数値で指定するが、これを0～100のパーセント値へと変換する単純なユーティリティ関数。

上記 float->percent / floatToPercent の逆変換を行うユーティリティ。

当ライブラリ内部での再生デバイス名を文字列として返す。

具体的に返される値は以下のいずれか。

• web-audio : WebAudio
• html-audio-multi : HtmlAudio。SE多重再生サポートあり
• html-audio-single : HtmlAudio。SE多重再生サポートなし
• dumb : 無音

エンジン音、プロペラ回転音、機関銃音のような「動作中は定期的に再生する」タイプのSEの為に、「動作中は定期的に実行するが、実行が集中しないように、指定したsec間隔以内での再生を抑制する」関数を生成する高階関数。

最初の引数として「抑制する秒数」を渡す。

これは「エンジンが加速中の間は毎フレーム鳴らす(再生関数を実行する)が、(ユーザの入力次第で)加速が停止したら鳴らさない」ような状況で利用するとよい(もしそうではなく、終了時に明示的に停止させる方が望ましい場合は、専用チャンネルでループBGMとして再生させた方がより良い)。

再生するSEのパラメータは、高階関数のオプショナル引数として渡してもよいし、生成された関数の方の引数として渡してもよい(生成された方に何も渡されなかった場合は、高階関数のオプショナル引数が適用される)。

再生されたか抑制されたかは、返り値として nil / null が返るか、SEチャンネルID値が返るかで判定できる。

一人のキャラが複数のボイスを再生するような場合は、同時再生を一つだけに抑制したいケースがほとんど。これを実現する関数を、再生元(この例ではキャラ)ごとに生成する高階関数。

具体的には、あるボイスを再生中に別のボイスの再生を行おうとしたタイミングで、先に再生していたボイスが自動的に停止させられるようになる。

高階関数の引数として、自動停止時のフェード秒数が指定可能(無指定の場合は通常のSEのデフォルトフェード秒数が適用される)。

生成された関数の引数には、通常のSE再生用の引数を渡す。

これはcljs版専用の機能です。js版では利用できません

これは何？

実際のゲームで利用する場合、「最初のローディング画面で音源ファイルのプリロードを行う」みたいな事がよくある。しかし、いちいちゲーム中で使っている音源ファイル全てを手で列挙していくのはとても面倒なので、例えば"se/"ディレクトリを指定したら["se/launch.*" "se/kick.*"]のような形式でファイルの一覧を取得できる機能を用意した。

重要な注意点

ブラウザ上で「ファイルの一覧を取得」するような事は通常できない為、この機能は「マクロの展開フェーズにローカルファイルの一覧を取得」する事によって実現している。その為「ローカルのpathとブラウザ上でのpathの二つを引数に指定する必要がある」「引数は即値の文字列でないといけない」「マクロ展開後に音源ファイルを追加しても、再コンパイルするまでは認識されない」という制約がある。

(ns foo.bar (:require [vnctst.audio4.prefetch :include-macros true]))

このファイル一覧取得機能はvnctst.audio4.prefetchに入っているので、別途requireしておく。
ここには書いてないが:asを指定して短い別名を付けておくとよい。
この機能はマクロで実装されている為:include-macros trueを必ず付ける事。

(vnctst.audio4.prefetch/pathlist-from-directory "resources/public/se/" "se/")

第一引数は、ファイル一覧を取得するローカルディレクトリ。マクロの制約により、これは即値の文字列でなくてはならない。変数や式を指定した場合はコンパイルエラーが投げられる。末尾のスラッシュはあってもなくてもよい。
第二引数は、httpサーバ上でのディレクトリ。第一引数に対応するものを指定する事。末尾のスラッシュはあってもなくてもよい。
この式はコンパイルフェーズに評価され、["se/launch.*" "se/kick.*"]のようなvecとしてソースに埋め込まれる。このvecを適当な変数にdefしておき、早いタイミングでdoseq等を使ってload!にかけておくとよい。
なお、第一引数で指定したローカルディレクトリ内には音響ファイルだけを入れておく事(そうしないと音響ファイル以外もこのリストに追加されてしまう為)。
この際に、ドットはじまりのファイル名は自動的に除外される(.htaccessや.DS_Storeへの対策としての挙動)。

(vnctst.audio4.prefetch/pathlist-from-directory "resources/public/se/" "se/" true)

第三引数に即値の真値を指定すると、autoext変換が行われなくなる。
具体的には、上ではマクロの展開結果が["se/launch.*" "se/kick.*"]のようになるが、こちらでは["se/launch.ogg" "se/launch.mp3" "se/kick.ogg" "se/kick.mp3"]のようになる。autoext指定をしない運用をする場合はこちらを使う必要がある。

html5上の音響システム固有の前提知識。ライブラリレベルでは吸収できないバッドノウハウ類です

「この拡張子なら全ブラウザで再生できる」という万能ファイル形式は存在しない

• なので、なるべく多くのブラウザでの再生をサポートしたい場合複数種類の拡張子のファイルを用意する必要があります。
• 再生回りでのトラブルの少なさは「ogg、mp3、m4a、他」の順なので、この優先順位で二つほど選ぶと良いでしょう(「oggとmp3をセットで配置」もしくは「oggとm4aをセットで配置」あたりが安定)。
• どうしても一つに絞る場合は、「oggを採用し、ieとsafariでの再生を切り捨てる」「mp3を採用し、一部os向けfirefoxを切り捨て、一部モバイル環境で出る不具合には目をつぶる」「m4aを採用し、一部os向けfirefoxを切り捨て、一部モバイル環境で出る不具合には目をつぶる」のどれかを選択する事になります。
• なお、「oggは内部コーデックが通常のvorbisのもののみ対応」「可変ビットレートでエンコードしたmp3は、一部環境で読み込みに失敗する」「m4aは内部コーデックがaacのもののみ対応」という制約もあるので、音源ファイルのエンコード時にはこの辺りにも気を付けておくとよいでしょう(特にmp3は、エンコーダのデフォルト設定で可変ビットレートが有効になっている事が多いので注意)。

無音であっても支障が出ないようにする

• 前述の拡張子対応をどんなにがんばっても、古いモバイル端末では、音源の一部/全部が再生されないものもあります。
• またそもそも、ハード側の音量を0にした状態で使われる事もよくあります。なので、「音が出なくても利用できる」ようになっているのがベターでしょう。

違うドメインにあるファイルを再生する場合はCORS設定が必要

• 詳細はリンクから自分で調べてください

その他の質問など

音が出ない

• debug?フラグを有効にして、コンソールにエラーが出ていないか確認してみよう
• 多くのブラウザでは、ローカルファイル(file:///...形式のurl)からの再生はできません。対応しているブラウザで動作確認するか、httpサーバを用意してその中に配置して動作確認しよう
• 対応環境マトリックスを確認してみよう

音が小さい

• デフォルトの音量は36%相当です。オンラインデモのサンプルコードを確認して、マスターボリューム、BGMボリューム、SEボリュームを大き目に設定してみよう

pitchの効果が出ない

• pitchとpanは機能しない環境があります(WebAudio非対応環境および一部のモバイル環境)。pitch指定が効かない場合でもそれなりに聴けるようにしておくとベターです

特定の環境でのみ、特定のmp3ファイルがロードエラーを起こす

• ブラウザによってはmp3の特定のエンコードオプション(abr等)を解釈できずにエラーになるものがあるようです。問題の出るmp3ファイルは、abr等のオプションなしの固定ビットレートでエンコードし直すとよいでしょう。

再生環境によっては、BGMのループの際に少しだけ無音の時間がはさまる

• HtmlAudioモードで動作する古いモバイル環境で、この問題が起こるようです。
  再生環境側の問題なので、ライブラリレベルでの対応は厳しいです。

再生開始までにものすごく時間のかかる時がある

• モバイル環境および2018年以降の多くのブラウザでは「インタラクションイベントを実行するまでは再生できない」という仕様が主流となりつつあるようです。画面のどこかをクリック/タッチしたり、キーボード入力する事で再生が開始された場合は、この仕様に引っかかっています。
  「タイトル画面は無音にする」等、この仕様を意識した作りにするとよいでしょう

いちいちvnctst.audio4.js.bgm("hoge.ogg")って書くのは長くて面倒

• 最初にvar va4 = vnctst.audio4.js;を実行しておけば、以降はva4.bgm("hoge.ogg")ですみます

いちいちva4.bgm("foo/bar/hoge.ogg")って毎回pathを指定するのは微妙

• 変数やhash-mapを使いましょう。
  
  他の音響再生ライブラリには「ロードした音源を自分で指定したキーワードに割り当て、再生したい時にはそのキーワードで指定する」ような機構を持つものが多く、またvnctst-audioの過去のバージョンでも類似の仕組みを採用していました。
  このキーワード割り当てを行う方式は「再生する事前に必ずロードを実行して完了させておく」制約のあるシステム上では確かに有用なのですが(キーワードに割り当てられている＝事前に再生する対象であると指定された事が保証されている)、「雑に扱える」事をポリシーとするvnctst-audio4では前述の制約のない実装にできたので、結果として「いちいちキーワードに割り当てる手間」というデメリットだけが残った為、キーワード割り当て方式は廃止されました。
  もちろんキーワード的な管理をした方がよいケースは普通に存在しますが、その場合は自分で変数やhash-mapを使って管理した方が扱いやすいでしょう

このオンラインデモのサンプルBGM/SEについて

• これらのBGM/SEは当プロジェクトのメンテナであるayamadaが作成したものです。
  これらのライセンスはCC0とします

vnctstってなんて読むの

• 作者は頭の中で「ぶいえぬしーてぃーえすてぃー」と読んでいます。
  これは「VNCTST games」というインディーズゲーム作成ブランドの名前から来ています。しかしあまりに人間には発音しづらいので、このブランド名はもっと読みやすい名前に変更したいと考えています。
  ただし、将来にゲーム作成ブランド名を変更しても、この vnctst-audio4 の名前はこのままにする予定です。

なんかおかしい / バグ報告したい

• githubリポジトリのissueから可能です。日本語でokです