Songle Sync を試す

Songle Sync APIとは?

Songle Sync API (Application Programming Interface) を利用することで、楽曲を再生して演出を描画する音楽連動制御アプリを容易に開発することができます。まずは Songle SyncチュートリアルのStep 3 をご覧ください。

Songle Sync APIによるプログラミングでは、1台の機器を念頭においてアプリをプログラミングするだけで、他の多数の機器と自動的に連動できます。しかも、スマートフォンやパソコンのウェブブラウザーで動作するアプリ、照明を制御するアプリ、ロボットを制御するアプリのように、個別に開発されたさまざまな種類のアプリを、ある楽曲の再生に一緒に連動させることができます。このようにプログラマーは、通信や他の機器との連動制御を全く意識せずに、大規模な音楽連動制御を実現することができます。

この1台の機器を念頭においたプログラミングでは、小節の先頭ではこういう演出、サビに入ったらこういう演出、といったプログラム、すなわちイベント駆動なプログラムを記述するだけで、楽曲中の再生時刻が各イベントの時刻に達すると自動的にそうした演出が実行されます。しかも楽曲ごとに手作業でイベントを設定する必要がなく、Songleの解析結果(ビート、小節、サビ区間、繰り返し区間、コードなど)をイベントとして利用できます。こうしたイベント駆動プログラミングに基づく1台用のSongle Sync APIは、現在も提供中のSongle WidgetのAPI v1が発展したAPIに位置づけられるため、以下のリファレンスマニュアルでは、Songle Sync APIの説明にも関わらず、「Songle Widget」あるいはその省略形の「SW」が頻繁に登場します。

Songle sync devkit


SW.Player

Songle 外部埋め込みプレーヤを抽象化したクラスです。

アスセストークンが必要です。トークンは、ユーザページより発行することができます。

var options = {
  // アクセストークン(必須)
  accessToken: 'YOUR_ACCESS_TOKEN'
};
var player = new SW.Player(option);

Constant (static)

Name: string

SW.Player クラスの名前を表す dispatcherName の定数です。

Type: string

SW.Player クラスの種類を表す dispatcherType の定数です。

MinVolume: number

音量の最小値の定数です。

MaxVolume: number

音量の最大値の定数です。

Property (get/set)

@accessToken: string

音楽地図情報などにアクセスするための公開用のトークンのプロパティです。
トークンは、ユーザページより発行することができます。

@secretToken: string

音楽地図情報などにアクセスするための認証用のトークンのプロパティです。
トークンは、ユーザページより発行することができます。

@brandElement: string

Songle APIの使用情報を表示するためのDOMを指定します。

@mediaElement: string

media の情報を表示するためのDOMを指定します。

Property (get)

@dispatcherName: string

このクラスの名前を返します。
このメソッドは、クラスインスタンスやイベントの発生元を特定する用途で利用することが想定されています。

console.log(player.dispatcherName == SW.Player.Name); // true
@dispatcherType: string

このクラスの種類を返します。
このメソッドは、クラスインスタンスやイベントの発生元を特定する用途で利用することが想定されています。

console.log(player.dispatcherType == SW.Player.Type); // true
@media: SW.Media::SuperClass

利用中のmedia を返します。

@musicMap: object

現在読み込まれている楽曲構造にアクセスすることができます。

console.log(player.musicMap.beats);
console.log(player.musicMap.chords);
console.log(player.musicMap.chorusSections);
console.log(player.musicMap.repeatSections);
console.log(player.musicMap.variation);
@isReady: boolean

ステータスが ready の場合 true を返します。

@isPlaying: boolean

ステータスが playing の場合 true を返します。

@isPaused: boolean

ステータスが paused の場合 true を返します。

@isSeeking: boolean

ステータスが seeking の場合 true を返します。

@duration: number

楽曲の長さをミリ秒単位で返します。

@position: number

楽曲の再生位置をミリ秒単位で返します。

Function

#activate(): void

#addPlugin(...plugins: Array<SW.Plugin.SuperClass>): void

使用する plugin を追加します。

player.addPlugin(
  new SongleWidget.Plugin.SongleSync(),
  new SongleWidget.Plugin.Beat()
);
#useMedia(mediaUrl: string, options: Object): void

使用する楽曲メディアを指定します。

player.useMedia(
  'www.youtube.com/watch?v=Blc2HbNaUsg', {
    rootElement: document.querySelector('div.media')
  }
);
#play(): void

音楽を再生します。

#pause(): void

音楽を一時停止します。

#stop(): void

音楽を停止します。

#seekTo(msec: number): void

音楽を指定する時間までseekします。

#on(eventName: string, callback: (event: Event) => void): void

eventが起きたときに呼び出される関数を指定します。

player.on("play", function() {
  console.log("play event occurred");
});

Event

error

エラーが発生したときに呼び出される event です。

player.on("error", function() {
  console.log("error event occurred");
});
play

楽曲の再生が開始されたときに呼び出される event です。

player.on("play", function() {
  console.log("play event occurred");
});
pause

楽曲が一時停止されたときに呼び出される event です。

player.on("pause", function() {
  console.log("pause event occurred");
});
seek

楽曲がseekされたときに呼び出される event です。

player.on("play", function() {
  console.log("seek event occurred");
});
finish

楽曲の再生が終了したときに呼び出される event です。

player.on("play", function() {
  console.log("finish event occurred");
});

SW.Media.SuperClass

Songle で使用するメディアを抽象化したクラスです。

Constant (static)

Name: string

クラスの名前を返します。

Type: string

クラスの種類を返します。

DefaultVideoPlayerSizeW: number

動画プレーヤのデフォルトの幅を返します。

DefaultVideoPlayerSizeH: number

動画プレーヤのデフォルトの高さを返します。

Event

mediaError

エラーが発生したときに呼び出される event です。

mediaReady

メディアの再生準備が完了したときに呼び出される event です。

mediaStateChange

メディアの再生状態が変化したときに呼び出される event です。

mediaPlay

メディアが再生を開始したときに呼び出される event です。

mediaPause

メディアが再生を停止したときに呼び出される event です。

mediaSeek

メディアが再生位置をシークしたときに呼び出される event です。

mediaFinish

メディアの再生が終了したときに呼び出される event です。

SW.Media.Headless

SW.Media.SuperClass

同期のみ行ない、メディアの再生を行なわないクラスです。

SW.Media.HTMLMediaElement

SW.Media.SuperClass

HTML5 の audio 要素、video 要素を扱うクラスです。

SW.Media.NNVideo

SW.Media.SuperClass

ニコニコ動画の外部プレーヤを扱うクラスです。

SW.Media.YTVideo

SW.Media.SuperClass

YouTube の外部プレーヤを扱うクラスです。

SW.Plugin.SuperClass

プラグインの基底クラスです。SW.Player.addPlugin()に引数として与えることで、プレーヤに機能を追加することができます。

SW.Plugin.Beat

SW.Plugin.SuperClass

ビートを扱うプラグインです。

Function

constructor
plugin = new SW.Plugin.Beat();
player.addPlugin(plugin);

Event

barEnter

小節に入ったとき呼び出される event です。 小節の一拍目のビートがコールバック関数に渡されます。

player.on('barEnter', function(event) {
  console.log(event.data.beat);
  /* ビートの内容の例 */
  /* {
       bpm: 133,
       count: 4,
       index: 18,
       position: 2,
       start: 8233,
       prev: ..., // 前のビート
       next: ..., // 次のビート
     } */
});
barLeave

小節を抜けたときに呼び出される event です。 小節の一拍目のビートがコールバック関数に渡されます。

player.on('barLeave', function(event) {
  console.log(event.data.beat);
});
beatEnter

拍に入ったときに呼び出される event です。

player.on('beatEnter', function(event) {
  console.log(event.data.beat);
});
beatLeave

拍を抜けたときに呼び出される event です。

player.on('beatLeave', function(event) {
  console.log(event.data.beat);
});

SW.Plugin.Chord

SW.Plugin.SuperClass

コードを扱うプラグインです。

Function

constructor
plugin = new SW.Plugin.Chord();
player.addPlugin(plugin);

Event

chordEnter

コードに入ったときに呼び出される event です。

player.on('chordEnter', function(event) {
  console.log(event.data.chord);
  /* コードの内容の例 */
  /* {
       index: 1,
       start: 517,
       duration: 5450,
       name: "Em7",
       prev: ..., // 前のコード
       next: ..., // 次のコード
     } */
});

コードを抜けたときに呼び出される event です。

player.on('chordLeave', function(event) {
  console.log(event.data.chord);
});

SW.Plugin.Chorus

SW.Plugin.SuperClass

サビ区間を扱うプラグインです。

Function

constructor
plugin = new SW.Plugin.Chorus();
player.addPlugin(plugin);
#seekToPrevChorusSection(): void

前のサビ区間にシークします。

player.seekToPrevChorusSection();
#seekToNextChorusSection(): void

次のサビ区間にシークします。

player.seekToNextChorusSection();
#seekToPrevRepeatSection(): void

前の繰り返し区間にシークします。

player.seekToPrevRepeatSection();
#seekToNextRepeatSection(): void

次の繰り返し区間にシークします。

player.seekToNextRepeatSection();

Event

chorusSectionEnter

サビ区間に入ったときに呼び出される event です。

player.on('chorusSectionEnter', function(event) {
  console.log(event.data.section);
  /* サビ区間の内容の例 */
  /* {
       duration: 14160,
       index: 4,
       isChorus: true
     } */
});
chorusSectionLeave

サビ区間を抜けたときに呼び出される event です。

player.on('chorusSectionLeave', function(event) {
  console.log(event.data.section);
});
SW.Plugin.Chorus repeatSectionEnter event

繰り返し区間に入ったときに呼び出される event です。

player.on('repeatSectionEnter', function(event) {
  console.log(event.data.section);
});
SW.Plugin.Chorus repeatSectionLeave event

繰り返し区間を抜けたときに呼び出される event です。

player.on('repeatSectionLeave', function(event) {
  console.log(event.data.section);
});

SW.Plugin.Variation

SW.Plugin.SuperClass

バリエーション(楽曲の盛り上がりに応じて分割された区間)を扱うプラグインです。 演出パターンの選択などの用途に利用することが想定されています。

例えば、4パターンの演出パターンを楽曲中で切り替えたいときには、

groupCount: 4

にすると、楽曲の最初から最後までをあたかも4色で塗り分けた状態になります。そして、 variationEnter では、group が0~3で返ってきます。この group の値は、楽曲の内容に応じた演出ができるように、大きいほど音響的に派手な部分に対応するようになっています。そこで、4パターンの演出パターンのうち、group が0のときは静かな演出を、group が3のときは最も派手な演出を割り当てると、楽曲の再生に伴って適切な演出が可能になって便利です。

variationEnterlabel は、groupCount: 10 を設定したときの group と同一です。 この SW.Plugin.VariationをSW.Plugin.Chorus と併用して、基本的な演出は SW.Plugin.Variation で表示しておいて、サビのときだけ SW.Plugin.Chorus で派手な演出を重ねる、というような活用方法も有効です。

Function

constructor
var options = {
  // バリエーション数 (2 から 10 までの整数)
  groupCount: 5
};
plugin = new SW.Plugin.Variation(options);
player.addPlugin(plugin);

Event

variationEnter

バリエーション区間に入ったときに呼び出される event です。

player.on('variationEnter', function(event) {
  console.log(event.data.variation);
  /* バリエーション区間の内容の 例 */
  /* {
       index: 0,
       start: 520,
       duration: 28860,
       label: 5,
       group: 1,
       prev: ..., // 前の区間
       next: ...  // 次の区間
     } */
});
variationLeave

バリエーション区間を抜けたときに呼び出される event です。

SW.Plugin.SongleSync

Songle Sync による同期機能を扱うプラグインです。同期機能についてはチュートリアルを参照してください。

Property (get)

@isMaster: boolean

プレーヤがマスターの場合、true を返します。

console.log(player.isMaster);
@isSlave: boolean

プレーヤがスレーブの場合、true を返します。

console.log(player.isSlave);

Function

constructor
plugin = new SW.Plugin.SongleSync();
player.addPlugin(plugin);

Event

songleSyncNodeChange

ステージに参加しているノードの個数が変更された時に呼び出される event です。

songleSyncNodeEnter

ステージにノードが参加した時に呼び出される event です。

songleSyncNodeLeave

ステージからノードが離脱した時に呼び出される event です。