Wizard Notes

Python, JavaScript を使った音楽信号分析の技術録、作曲活動に関する雑記

wavesurfer.js:簡単に音声ファイルの再生と波形描画が実装できるJavaScriptライブラリ

f:id:Kurene:20220224010617p:plain:w500
https://wavesurfer-js.org より

ユーザが音楽を再生する Web アプリでは、音の出力するだけでなく、

波形描画などで音を可視化したり、操作が分かりやすいGUIを設計する必要があります。

原理的には、Web Audio API において音波形の信号値が格納されている Audio Buffer を利用して、canvasWebGLなどで波形を描画するという手順になります。

しかし、各ライブラリを理解する必要がある上に、実装するコードが多くなります

今回は音再生と波形描画、波形上での操作を手軽に実現できる非常に便利なライブラリ wavesurfer.js の使い方・実装例を紹介します。

公式Webサイト

wavesurfer-js.org

github.com

ライセンス

BSD-3-Clauseライセンス

ソースコード形式かバイナリ形式か、変更するかしないかを問わず、以下の条件を満たす場合に限り、再頒布および使用が許可されます。

ソースコードを再頒布する場合、上記の著作権表示、本条件一覧、および下記免責条項を含めること。

・バイナリ形式で再頒布する場合、頒布物に付属のドキュメント等の資料に、上記の著作権表示、本条件一覧、および下記免責条項を含めること。

・書面による特別の許可なしに、本ソフトウェアから派生した製品の宣伝または販売促進に、<組織> の名前またはコントリビューターの名前を使用してはならない。

https://licenses.opensource.jp/BSD-3-Clause/BSD-3-Clause.html

使い方

HTMLでのwavesurfer.jsrライブラリの読み込み

まずは、HTMLページ等で wavesurfer.js ライブラリを読み込む必要があります。

手軽に利用する方法として、以下のようにunpkg.comホスティングされている最新バージョンを読み込むのがお勧めです。

また、wavesurferの波形表示を表示する箇所を指定するため <div id="waveform"></div>をbodyの中に入れます。

<html>
<head>
<script src="https://unpkg.com/wavesurfer.js"></script>
...
</head>
  <body>
  ...
  <div id="waveform"></div>
  ...
  </body>
</html>

javascript

次に、JavaScriptのコードで、WaveSurferオブジェクトのインスタンスを作成します。

var wavesurfer = WaveSurfer.create({
    container: '#waveform'

ここで、containerには波形表示をする<div>タグのIDを記載します。

なお、次のセクションで説明するオプションやプラグインWaveSurfer.create({})の引数である連想配列の要素として与えることとなります。

インスタンス生成後、オーディオファイルを読み込みます。

wavesurfer.load('../audio/song.mp3');

その後、ユーザのボタン操作等のインタラクションに基づいて、再生 wavesurfer.play() や停止 wavesurfer.pause() などの操作を行います。

実装例

以下は、ボタンで再生・停止をする最も簡単な実装例です。

このように、非常に少量の実装で音の再生と波形描画ができてしまいます

See the Pen wavesurfer.js example by Kurene (@_kurene) on CodePen.

代表的なAPI

wavesurfer.js を操作するための代表的なAPIを列挙します。

  • wavesurfer.play()
    • 再生停止
  • wavesurfer.pause()
    • 再生一時停止
  • wavesurfer.playPause()
    • 一時停止中なら再生、再生中なら一時停止
  • wavesurfer.stop()
    • 停止して最初に戻る
  • wavesurfer.isPlaying()
    • 返り値がtrueなら再生中
  • wavesurfer.toggleMute()
    • muteのon/off
  • wavesurfer.loadBlob(url)
    • Blob or Fileオブジェクトからオーディオをロード
  • wavesurfer.on(eventName, callback)
  • wavesurfer.getCurrentTime()
    • 現在の進行状況(秒単位)
  • wavesurfer.seekTo(progress)
    • 再生位置セット
    • progress==0: 開始、progress==1: 終了
  • wavesurfer.setVolume(newVolume)
    • newVolume に 0~1の値を入れることで、音量を設定
  • wavesurfer.backend.setFilter(webAudioNodes)
    • WebAudioNodeもしくはリストをセット
    • よって自作フィルタを導入することが可能

APIについてより詳しく知りたい場合は、以下のWebページが参考になります。

wavesurfer.js - methods

Home | wavesurfer.js

よく使うオプション

WaveSurfer Options

audioContext

既にAudioContextを取得済みの場合、このオプションにセットして利用することもできます。

WaveSurferCreate()の実行時ではないですが、ChromeではAudioContextの生成にはユーザジェスチャーが必要なので、例えばボタンクリック時に

wavesurfer.audioContext=audioContext

のようにセットする、というような使い方をします。。

audioRate: 再生速度の変更

1より小さい値をセットすることで再生速度を遅くできます。

逆に、1より大きい値をセットすることで再生速度を速くできます。

この数字は倍率を表しており、例えばaudioRate: 2であれば2倍速再生となります。

var wavesurfer = WaveSurfer.create({
    ...
    audioRate: 10,
    ...
});

splitChannel: 各チャンネルの波形表示

splitChannel: trueとすると、以下の画像のように、チャンネルごとに波形を表示することができます、 f:id:Kurene:20220224230847p:plain

var wavesurfer = WaveSurfer.create({
    ...
    splitChannel: true
    ...
});

normalize: 波形の正規化

normalize: trueすると、読み込んだ波形の最大振幅が1.0となるように正規化します。

色関係

色名・色コードを与えることで、それぞれの色を制御できます。

  • waveColor: 波形の未再生部分の色
  • progressColor: 波形の再生済みの部分の色
  • backgroundColor: 背景色

backend

wavesurferのバックエンドとしてWebAudioかMediaElement / MediaElementWebAudio, すなわち<video><audio>の利用を選択できます。

wavesurfer.js | MediaElementWebAudio backend Example

wavesurfer-js.org

プラグイン

導入方法

プラグインを使うには、まずプラグインライブラリをHTMLで読み込みます。

<script src="https://unpkg.com/wavesurfer.js"></script>
<script src="https://unpkg.com/wavesurfer.js/dist/plugin/wavesurfer.regions.min.js"></script>

次に、WaveSurfer.create()の宣言時に、プラグインの構成を記述します。

この時、pluginsはリストなので、複数のプラグインを含むことができます。

var wavesurfer = WaveSurfer.create({
    container: '#waveform',
    plugins: [
        WaveSurfer.regions.create({})
    ]
});

Regions plugin

Regions plugin

描画されている波形上で、自由に領域を作成し、ループ再生等を制御することができます。

f:id:Kurene:20220224233358p:plain
https://wavesurfer-js.org/plugins/regions.html より

<script src="https://unpkg.com/wavesurfer.js/dist/plugin/wavesurfer.regions.min.js" type="text/javascript"></script>

Marker

Marker Plugin

波形にマーカーを付けることができます。

マーカーをクリックすると、再生位置にジャンプできます。

f:id:Kurene:20220224233834p:plain
https://wavesurfer-js.org/plugins/markers.html

<script src="https://unpkg.com/wavesurfer.js/dist/plugin/wavesurfer.markers.min.js" type="text/javascript"></script>

Timeline

Timeline Plugin

タイムライン(時間軸)を表示することができます。

f:id:Kurene:20220224233707p:plain
https://wavesurfer-js.org/plugins/timeline.html より

<script src="https://unpkg.com/wavesurfer.js/dist/plugin/wavesurfer.timeline.min.js" type="text/javascript"></script>

Spectrogram

Spectrogram Plugin

スペクトログラムを表示することができます。

f:id:Kurene:20220224234053p:plain
https://wavesurfer-js.org/plugins/spectrogram.html

<script src="https://unpkg.com/wavesurfer.js/dist/plugin/wavesurfer.spectrogram.min.js" type="text/javascript"></script>

その他

Reactとの組み合わせ方は以下の記事を参考にしてください。

www.wizard-notes.com

まとめ

音再生と波形描画、波形上での操作を手軽に実現できるライブラリ wavesurfer.js の使い方・実装例を紹介しました。

短いコードで音の再生と波形描画ができるだけでなく、さまざまなオプションやプラグインを使うことで、高度な音響処理や操作も可能になるライブラリです。

まずは wavesurfer.js のWebサイトを訪れて、いろいろサンプルを実際に触ったり聞いたりするのがよいと思います。