Songle JavaScript API クイックスタート

はじめに

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

動作要件

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

ウェブブラウザ

Microsoft Edge 17
Mozilla Firefox 62
Google Chrome 70
Safari 12
Opera 55
iOS Safari 11.4
Chrome Android 69

Node.js

8.x / 9.x / 10.x

インストール

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

ウェブブラウザ

Example
<script src="https://api.songle.jp/v2/api.js"></script>

npm

Example
$ npm install songle-api

Hello, Songle API !!

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

サンプルプログラム1

次のサンプルプログラムは、音楽の拍子と連動するプログラムです。
サンプルからも分かるように、音楽に連動したイベント駆動のプログラムを容易に記述することができます。

プラグインについて

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

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

音楽に連動したプログラミングの雰囲気を掴むことはできたでしょうか?より詳しい機能を知りたい場合はリファレンスを参照してください。

Songle Sync の使い方

Songle Sync (ソングルシンク)とは

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

はじめに

この機能を使うためには Songle API のウェブサイトからユーザ登録を行い、トークンを取得する必要があります。取得方法の詳細は、チュートリアルのステップ3を参照してください。

チュートリアル

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

Songle Sync ステージについて

大規模音楽連動制御に参加する端末が集まる仮想的空間のことをステージと呼びます。トークンを取得することは、このステージを作ることにあたります。

Overview1

トークンの種類

トークンには、2つの種類が存在します。

認証用のトークン

ステージを管理するためのトークンです。

参加用のトークン

ステージに参加するためのトークンです。

Songle Sync マスターについて

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

Songle Sync スレーブについて

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

ステージの参加方法

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

トークンの共有範囲に注意

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

サンプルプログラム2

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

ウェブブラウザ / マスター

ウェブブラウザ / スレーブ

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

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

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

Node.js / スレーブ

Example
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 を使ったより詳細なサンプルプログラムは、公式リポジトリから探すことができます。