Songle JavaScript API クイックスタート

このクイックスタートは、プログラミング言語 JavaScript を対象としたものです。
API の利用を開始するためには Songle API モジュールをウェブサイトまたはシステムにインストールする必要があります。

Songle API モジュールは、次の環境で動作することが確認されています。

Microsoft Edge 18
Mozilla Firefox 68
Google Chrome 75
Safari 12.1
Opera 62
iOS Safari 12.2
Chrome Android 75
Node.js 8.x
Node.js 9.x
Node.js 10.x
Node.js 11.x
Node.js 12.x

Songle API モジュールは script タグもしくは npm などのパッケージマネージャからインストールすることができます。

ウェブブラウザ

サンプルコード
<script src="https://api.songle.jp/v2/api.js"></script>

Node.js

サンプルコード
$ npm install songle-api

ウェブブラウザから Songle API モジュールを利用した場合、その利用準備の完了を通知する onSongleAPIReady が Songle API モジュールによって自動的に呼び出されます。

次のサンプルプログラムは、再生している音楽の拍子とコンソール出力を連動させるプログラムです。
サンプルから分かるように「1拍目が再生されたら〜を実行する」といった、音楽に連動したイベント駆動(音楽連動制御)のプログラムが Songle API を使うことで容易に記述することができます。

ワンポイント

プラグインについて

サンプルプログラムに記述されているプラグインは、利用する機能に応じて追加することができます。例えば、音楽の和音に連動させる場合は Songle API モジュールの和音プラグイン Plugin.Chord を追加することで、和音に連動したプログラムを作成することができます。

次のサンプルプログラムは、音楽の様々な要素とウェブコンテンツを組み合わせた実例になります。
まずは音楽を再生してみて、音楽連動制御のイメージを掴んでみましょう。

より詳しい Songle JavaScript API の機能を知りたい場合はリファレンスを参照してください。

ウェブ上の音楽の再生に合わせて多種多様な機器を同時制御することで、一体感のある演出ができる大規模音楽連動制御プラットフォームです。誰でも自分のスマートフォンやパソコン等の機器を自由自在に組み合わせて、好きな楽曲の再生に合わせて光ったり動いたりする演出を作ることができます。

この機能を使うためには Songle API のウェブサイトからユーザ登録を行い、トークンを取得する必要があります。

チュートリアルサイトでは、より実践的な使い方を実際に体験しながら学ぶことができます。
チュートリアルの内容は、アプリケーション開発者をメインターゲットとしていますが、途中までは、プログラミングの知識がない方でもより高度な大規模音楽連動制御を楽しみながら体験できます。

大規模音楽連動制御に参加する端末が集まる仮想的空間のことを「ステージ」と呼びます。
トークンを取得することは、このステージを作ることにあたり、ステージは目的に応じていくつでも作ることができます。

トークンには、3つのタイプが存在します。

アプリトークン
ステージを作成・削除するためのトークンです。
例えば、ユーザの目的毎にステージを分けたいなどの理由で、ステージをいくつも用意する必要がある場合に使用するトークンです。
認証用トークン
ステージを管理するためのトークンです。
参加用トークン
ステージに参加するためのトークンです。

ステージに参加する端末には2つのタイプが存在します。

Songle Sync マスター
ステージに参加する端末のうち、音楽の再生・停止などの制御が許可されてる端末のことを「マスター」と呼びます。
マスターとして参加する端末は、認証用トークンを知っている必要があります。
Songle Sync スレーブ
ステージに参加する端末のうち、音楽の再生・停止などの制御が許可されない端末のことを「スレーブ」と呼びます。
スレーブとして参加する端末は、参加用トークンを知っている必要があります。

各端末は、何らかの共有方法(例えば電子メールや QR コードなど)で事前に知った参加用トークンを使ってステージに参加します。
参加した端末は、マスターの再生状態に従って大規模音楽連動制御が開始されます。

ワンポイント

トークンの共有範囲について

参加用トークンは、アプリケーションを利用する全員が知る可能性のあるトークンですが、認証用トークンは、多くの場合、アプリケーション開発者や音楽の再生・停止を制御するユーザーのみが知るトークンとなります。このトークンが意図しない第三者に知られると、音楽を勝手に切り替えたり、再生・停止させることができるため、共有には注意が必要です。

次のサンプルプログラムは、サンプルプログラム1を大規模音楽連動制御に対応させたプログラムです。
取得したトークンに書き換えた後、複数のブラウザからマスターとスレーブを実行して、大規模音楽連動制御のイメージを掴んでみましょう。

次のサンプルプログラムは Node.js 上で動作するスレーブ(ヘッドレスモード)のサンプルです。

ワンポイント

ヘッドレスモードについて

ヘッドレスモードとは、音源再生の機能を持たない端末などで大規模音楽連動制御を使うための仕組みことです。スレーブのプログラムを記述する際にメディアの設定を省略した場合、自動的にヘッドレスモードがになります。ヘッドレスモードは、明示的に指定することでマスターをヘッドレスモードで実行することもできます。

Node.js / スレーブ

サンプルコード
var Songle = require("songle-api");

var player =
  new Songle.SyncPlayer({
    accessToken: "YOUR-ACCESS-TOKEN-HERE", // please edit your access token
  });

player.addPlugin(new Songle.Plugin.Beat());

player.on("beatPlay",
  function(ev) {
    switch(ev.data.beat.position) {
      case 1:
        console.log("1st beat !!");
        break;

      case 2:
        console.log("2nd beat !!");
        break;

      case 3:
        console.log("3rd beat !!")
        break;

      case 4:
        console.log("4th beat !!");
        break;
    }
  });

Songle Sync API を使ったより詳細なサンプルプログラムは GitHub 公式リポジトリから探すことができます。