Songle JavaScript API リファレンス

Window: class

ここでは window グローバル変数から利用できる、ウィンドウインタフェースについて説明しています。
ウェブブラウザから Songle JavaScript API を利用している場合、このウィンドウインタフェースが自動的に拡張されます。

Constants
Static constant variables of this class
Static methods
Static methods of this class

Songle: any

ウィンドウインタフェースに追加される Songle JavaScript API のクラスメソッドが定義されたオブジェクトです。
このオブジェクトが確実に利用できることを保証する必要がある場合は onSongleAPIReady を利用することが推奨されます。

サンプルコード
const player =
  new window.Songle.Player({
    mediaElement: "#songle"
  });

player.on("ready",
  function(ev) {
    player.play();
  });

player.useMedia("https://www.youtube.com/watch?v=6j7VwJ7sM_k");

onSongleAPIReady: function

ウェブブラウザから Songle JavaScript API を利用している場合 Songle JavaScript API の初期化処理が完了すると自動的に呼び出される、予約されたメソッドです。
このメソッドは Songle JavaScript API 読み込み前に定義しておく必要があります。

サンプルコード
window.onSongleAPIReady =
  function(Songle) {
    const player =
      new Songle.Player({
        mediaElement: "#songle"
      });

    player.on("ready",
      function(ev) {
        player.play();
      });

    player.useMedia("https://www.youtube.com/watch?v=6j7VwJ7sM_k");
  }

Player: class

音楽プレイヤーを抽象化したクラスです。

Constructor
1st arg options of the constructor

名前初期値説明
accessTokenstringnull

Songle Sync API (Plugin.SongleSync) を利用する際に使用する公開用のトークンを指定します。
トークンは、ユーザページより発行することができます。

secretTokenstringnull

Songle Sync API (Plugin.SongleSync) を利用する際に使用する認証用のトークンを指定します。
トークンは、ユーザページより発行することができます。

mediaElementHTMLElement | stringdocument.body外部埋め込みプレーヤーを埋め込む先の DOM を指定します。
サンプルコード
const player =
  new Songle.Player({
    mediaElement: "#songle"
  });

MinVolume: number

設定可能な最小音量です。

MaxVolume: number

設定可能な最大音量です。

accessToken: string

Songle Sync API の公開用のトークンです。

secretToken: string

Songle Sync API の認証用のトークンです。

mediaElement: HTMLElement | string

メディアを埋め込む先の DOM です。

volume: number

音量(パーセンテージ)です。

サンプルコード
console.log(player.volume);

player.volume += 10; // + 10 %

player.volume -= 10; // - 10 %

media: Songle.Media.SuperClass

読み込まれているメディアです。

musicMap: any

読み込まれている音楽地図です。
サンプルコード
console.log(player.musicMap);

/**
{
  beat: any
  chord: any
  melody: any
  chorus: any
  variation: any
}
*/

isReady: boolean

アクティベート状態です。

isPlaying: boolean

再生状態です。

isPaused: boolean

停止状態です。

isSeeking: boolean

シーク状態です。

duration: number

メディアの再生時間(ミリ秒)です。

position: number

メディアの再生位置(ミリ秒)です。

addPlugin: void

プラグインクラスをインストールします。
ワンポイント

プラグインについて

このメソッドを利用することで Player クラスの機能を必要に応じて拡張していくことができます。
例えば、音楽の拍子に連動させたい場合は Plugin.Beat をインストールすることで、拍子に連動したプログラムを作成することができます。初期状態では、何もインストールされていない一般的な音楽プレイヤーとして機能します。

原則として、プラグインのインストールはメディアを設定する前に完了しておく必要があります。

サンプルコード
const player =
  new Songle.Player({
    mediaElement: "#songle"
  });

player.on("ready",
  function() {
    player.play();
  });

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

player.useMedia("https://www.youtube.com/watch?v=6j7VwJ7sM_k");

useMedia: void

メディアを設定します。

Args
Args of this method

名前必須初期値説明
第1引数string | Media.SuperClasstruenull

Songle に登録されている楽曲の配信元 URL を指定します。

第2引数objectfalsenull

オプション

ワンポイント

メディアについて

Songle API では、インターネット上に公開された楽曲のことを「メディア」と呼ばれる抽象化された概念として扱います。メディアとして扱うことができる楽曲の種類の詳細については、こちらのヘルプページをご確認ください。

サンプルコード
const player =
  new Songle.Player({
    mediaElement: "#songle"
  });

player.on("ready",
  function() {
    player.play();
  });

player.useMedia("https://www.youtube.com/watch?v=6j7VwJ7sM_k");

activate: void

アクティベートします。
ワンポイント

アクティベートについて

使用しているメディア及び端末によっては、初回再生時に配信元のプレイヤーをユーザの意思によりクリックもしくはタップをさせた上で再生する(アクティベートさせる)必要があります。これは、自動再生による意図しない通信圧迫を防ぐ目的で導入されている技術です。

play: void

再生します。

pause: void

一時停止します。

stop: void

停止します。

seekTo: void

シークします。

on: void

イベンドハンドラを設定します。
サンプルコード
player.on("ready",
  function()
  {
    player.play();
  });

error

例外処理が発生した場合に呼び出されるイベントです。

ready

準備処理が完了した場合に呼び出されるイベントです。

play

再生された場合に呼び出されるイベントです。

pause

停止された場合に呼び出されるイベントです。

seek

シークされた場合に呼び出されるイベントです。

finish

最後まで再生された場合に呼び出されるイベントです。

mediaError

メディアに関する例外処理が発生した場合に呼び出されるイベントです。

mediaReady

メディアに関する準備処理が完了した場合に呼び出されるイベントです。

mediaStateChange

メディアの状態が変化した場合に呼び出されるイベントです。
ワンポイント

接頭辞に media が付くイベントと付かないイベントについて

これらの違いは「メディア側の都合によりメディアの状態が変化したか否か」です。ユーザが Player.play などの Songle API メソッドを介してメディアを再生させた場合は mediaPlayplay が呼び出されます。逆にメディアが何らかの要因で自動再生した場合は mediaPlay のみが呼び出されます。カジュアルにプログラミングをする場合は、接頭辞のない方のイベントを使うと良いでしょう。

mediaPlay

メディアが再生された場合に呼び出されるイベントです。

mediaPause

メディアが停止された場合に呼び出されるイベントです。

mediaSeek

メディアがシークされた場合に呼び出されるイベントです。

mediaFinish

メディアが最後まで再生された場合に呼び出されるイベントです。

SyncPlayer: class

音楽プレイヤーを抽象化したクラスです。
このクラスを利用して初期化された Player は、次のコードと同じ意味になります。

サンプルコード
const player =
  new Songle.Player({
    mediaElement: "#songle"
  });

player.addPlugin(Songle.Plugin.SongleSync());

WidgetPlayer: class

音楽プレイヤーを抽象化したクラスです。
このクラスを利用して初期化された Player は、次のコードと同じ意味になります。

サンプルコード
const player =
  new Songle.Player({
    mediaElement: "#songle"
  });

player.addPlugin(Songle.Plugin.SongleWidget());

Media.SuperClass: abstract class

メディアクラスのスーパークラスです。
全てのメディアクラスは、このスーパークラスのメソッド・プロパティを呼び出すことができます。

ワンポイント

メディアクラスの役割

メディアクラスは、音源となる様々な配信元の音楽プレイヤーを抽象化する役割を担っています。例えば、再生や停止、音量の調節など、使用する音楽プレイヤー毎にその利用方法が異なりますが、このクラスを利用することで、その差異を意識することなく制御することができるようになります。

Name: string

メディアクラスに設定された名称の定数です。
この値は継承先のメディアクラスによって変化することがあります。

Type: string

メディアクラスに設定された種類の定数です。
この値は継承先のメディアクラスによって変化することがあります。

dispatcherName: string

メディアクラスのインスタンスに設定された名称です。
この値は継承先のメディアクラスによって変化することがあります。

dispatcherType: string

メディアクラスのインスタンスに設定された種類です。
この値は継承先のメディアクラスによって変化することがあります。

name: string

メディアの楽曲名です。

artistId: number

メディアのアーティストIDです。

artistName: string

メディアのアーティスト名です。

medianSeekTime: number

メディアのシーク処理にかかった時間(ミリ秒)の中央値です。

originalDuration: number

メディアの再生時間(ミリ秒)です。
この値は、メディアの種類(実装の差異)及び再生環境によって値が揺らぐため、特別な理由がなければ Player.duration を使うことを推奨します。

originalPosition: number

メディアの再生位置(ミリ秒)です。
この値は、メディアの種類(実装の差異)及び再生環境によって値が揺らぐため、特別な理由がなければ Player.position を使うことを推奨します。

Media.Headless: class

音楽の再生を必要としない場合に利用するメディアクラスです。
例えば、スピーカーを持たない端末などから、音楽地図のみを利用したい場合に利用します。

サンプルコード
const media =
  new Songle.Media.Headless("https://www.youtube.com/watch?v=6j7VwJ7sM_k");

player.useMedia(media);

Media.HTMLMediaElement: class

マルチメディアファイルを利用するメディアクラスです。
サンプルコード
const media =
  new Songle.Media.HTMLMediaElement(audioElement);

player.useMedia(media);

Media.NnVideo: class

外部の動画サービスの外部埋め込みプレーヤを利用するメディアクラスです。
サンプルコード
const media =
  new Songle.Media.NnVideo(nnVideoInstance);

player.useMedia(media);

Media.YtVideo: class

外部の動画サービスの外部埋め込みプレーヤを利用するメディアクラスです。
サンプルコード
const media =
  new Songle.Media.YtVideo(ytVideoInstance);

player.useMedia(media);

Plugin.SuperClass: abstract class

プラグインクラスのスーパークラスです。
全てのプラグインクラスは、このスーパークラスのメソッド・プロパティを呼び出すことができます。

Constants
Static constant variables of this class
Properties (Getter)
Get only properties of this class instance

Name: string

プラグインクラスに設定された名称の定数です。
この値は継承先のプラグインクラスによって変化することがあります。

Type: string

プラグインクラスに設定された種類の定数です。
この値は継承先のプラグインクラスによって変化することがあります。

dispatcherName: string

プラグインクラスのインスタンスに設定された名称です。
この値は継承先のプラグインクラスによって変化することがあります。

dispatcherType: string

プラグインクラスのインスタンスに設定された種類です。
この値は継承先のプラグインクラスによって変化することがあります。

Plugin.Beat: class

音楽地図の拍子を扱うプラグインクラスです。

Constructor
1st arg options of the constructor

名前初期値説明
revisionIdnumber0使用する音楽地図のリビジョン番号です。
offsetnumber0イベントのオフセット値(ミリ秒)です。
pollingIntervalnumber50イベントのポーリング値(ミリ秒)です。
サンプルコード
player.addPlugin(new Songle.Plugin.Beat());

player.on("beatEnter",
  function(ev) {
    // do someting ...
  });
ワンポイント

リビジョンについて

リビジョンとは、音楽理解技術による自動解析の誤りを人間が訂正した際に残る編集履歴のことです。この番号を指定することで、アプリケーションで使用する音楽地図の訂正状態を固定することができます。これは、音楽地図が第三者により編集された場合に発生する不整合を防ぐ場合に役立ちます。リビジョン番号は、楽曲ページ編集履歴より確認することができます。

ワンポイント

オフセットについて

オフセットでは、イベントの実行タイミングにオフセットを与えることができます。これは、アプリケーションの処理負荷などの要因によって、イベントの実行タイミングが前後にズレる場合に役立ちます。また、オフセットはイベント毎に個別に与えることもできます。

サンプルコード
player.addPlugin(new Songle.Plugin.Beat({
  offset: -100,
});

player.on("beatEnter",
  function(ev) {
    // this event will be run faster 100ms than the original beat event
  });

player.on("beatEnter",
  function(ev) {
    // this event will be run faster 200ms than the original beat event
  }, { offset: -100 });

player.on("beatEnter",
  function(ev) {
    // this event will be run faster 300ms than the original beat event
  }, { offset: -200 });
Properties (Getter/Setter)
Properties of this class instance
Properties (Getter)
Get only properties of this class instance
Methods
Methods of this class instance
Events
Related events of this class

BarEnterTrapName: string

小節の開始で呼び出されるイベント名の定数です。

BarLeaveTrapName: string

小節の終了で呼び出されるイベント名の定数です。

BeatEnterTrapName: string

拍子の開始で呼び出されるイベント名の定数です。

BeatLeaveTrapName: string

拍子の終了で呼び出されるイベント名の定数です。

offset: number

イベントのオフセット値(ミリ秒)です。

pollingInterval: number

イベントのポーリング値(ミリ秒)です。

revisionId: number

使用する音楽地図のリビジョン番号です。

seekToPrevBar: void

現在の再生位置から後方に対して、最も近い小節にシークします。
このメソッドは Player クラスに同名のメソッド名がプラグイン読み込み前に定義されていない場合は Player クラスから呼び出すことができます。

サンプルコード
player.addPlugin(new Songle.Plugin.Beat());

player.on("ready",
  function() {
    player.seekToPrevBar();
  });

seekToNextBar: void

現在の再生位置から前方に対して、最も近い小節にシークします。
このメソッドは Player クラスに同名のメソッド名がプラグイン読み込み前に定義されていない場合は Player クラスから呼び出すことができます。

サンプルコード
player.addPlugin(new Songle.Plugin.Beat());

player.on("ready",
  function() {
    player.seekToNextBar();
  });

barEnter

小節の開始で呼び出されるイベントです。
サンプルコード
player.on("barEnter",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        beat: Beat
      }
    }
    */

    /**
    // 拍子構造
    type Beat = {
      index: number,               // インデックス
      startTime: number,           // 拍子の開始位置(ミリ秒)
      startTimeSec: number,        // 拍子の開始位置(秒)
      numberOfBeatsPerBar: number, // 現在の小節の拍子の数
      number: number,              // 現在の小節の拍子の位置
      bpm: numbeer,                // BPM
      prev: Beat,                  // 前の拍子構造の参照
      next: Beat                   // 次の拍子構造の参照
    }
    */
  });

barLeave

小節の終了で呼び出されるイベントです。
サンプルコード
player.on("barLeave",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        beat: Beat
      }
    }
    */

    /**
    // 拍子構造
    type Beat = {
      index: number,               // インデックス
      startTime: number,           // 拍子の開始位置(ミリ秒)
      startTimeSec: number,        // 拍子の開始位置(秒)
      numberOfBeatsPerBar: number, // 現在の小節の拍子の数
      number: number,              // 現在の小節の拍子の位置
      bpm: numbeer,                // BPM
      prev: Beat,                  // 前の拍子構造の参照
      next: Beat                   // 次の拍子構造の参照
    }
    */
  });

beatEnter

拍子の開始で呼び出されるイベントです。
サンプルコード
player.on("beatEnter",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        beat: Beat
      }
    }
    */

    /**
    // 拍子構造
    type Beat = {
      index: number,               // インデックス
      startTime: number,           // 拍子の開始位置(ミリ秒)
      startTimeSec: number,        // 拍子の開始位置(秒)
      numberOfBeatsPerBar: number, // 現在の小節の拍子の数
      number: number,              // 現在の小節の拍子の位置
      bpm: numbeer,                // BPM
      prev: Beat,                  // 前の拍子構造の参照
      next: Beat                   // 次の拍子構造の参照
    }
    */
  });

beatLeave

拍子の終了で呼び出されるイベントです。
サンプルコード
player.on("beatLeave",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        beat: Beat
      }
    }
    */

    /**
    // 拍子構造
    type Beat = {
      index: number,               // インデックス
      startTime: number,           // 拍子の開始位置(ミリ秒)
      startTimeSec: number,        // 拍子の開始位置(秒)
      numberOfBeatsPerBar: number, // 現在の小節の拍子の数
      number: number,              // 現在の小節の拍子の位置
      bpm: numbeer,                // BPM
      prev: Beat,                  // 前の拍子構造の参照
      next: Beat                   // 次の拍子構造の参照
    }
    */
  });

Plugin.Chord: class

音楽地図の和音を扱うプラグインクラスです。

Constructor
1st arg options of the constructor

名前初期値説明
revisionIdnumber0使用する音楽地図のリビジョン番号です。
offsetnumber0イベントのオフセット値(ミリ秒)です。
pollingIntervalnumber50イベントのポーリング値(ミリ秒)です。
サンプルコード
player.addPlugin(new Songle.Plugin.Chord());

player.on("chordEnter",
  function(ev) {
    // do someting ...
  });
ワンポイント

リビジョンについて

リビジョンとは、音楽理解技術による自動解析の誤りを人間が訂正した際に残る編集履歴のことです。この番号を指定することで、アプリケーションで使用する音楽地図の訂正状態を固定することができます。これは、音楽地図が第三者により編集された場合に発生する不整合を防ぐ場合に役立ちます。リビジョン番号は、楽曲ページ編集履歴より確認することができます。

ワンポイント

オフセットについて

オフセットでは、イベントの実行タイミングにオフセットを与えることができます。これは、アプリケーションの処理負荷などの要因によって、イベントの実行タイミングが前後にズレる場合に役立ちます。また、オフセットはイベント毎に個別に与えることもできます。

サンプルコード
player.addPlugin(new Songle.Plugin.Chord({
  offset: -100,
});

player.on("chordEnter",
  function(ev) {
    // this event will be run faster 100ms than the original chord event
  });

player.on("chordEnter",
  function(ev) {
    // this event will be run faster 200ms than the original chord event
  }, { offset: -100 });

player.on("chordEnter",
  function(ev) {
    // this event will be run faster 300ms than the original chord event
  }, { offset: -200 });
Constants
Static constant variables of this class
Properties (Getter/Setter)
Properties of this class instance
Properties (Getter)
Get only properties of this class instance
Events
Related events of this class

ChordEnterTrapName: string

和音の開始で呼び出されるイベント名の定数です。

ChordLeaveTrapName: string

和音の終了で呼び出されるイベント名の定数です。

offset: number

イベントのオフセット値(ミリ秒)です。

pollingInterval: number

イベントのポーリング値(ミリ秒)です。

revisionId: number

使用する音楽地図のリビジョン番号です。

chordEnter

和音の開始で呼び出されるイベントです。
サンプルコード
player.on("chordEnter",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        chord: Chord
      }
    }
    */

    /**
    // 和音構造
    type Chord = {
      index: number,           // インデックス
      startTime: number,       // 和音の開始位置(ミリ秒)
      startTimeSec: number,    // 和音の開始位置(秒)
      endTime: number,         // 和音の終了位置(ミリ秒)
      endTimeSec: number,      // 和音の終了位置(秒)
      durationTime: number,    // 和音の再生時間(ミリ秒)
      durationTimeSec: number, // 和音の再生時間(秒)
      name: string,            // 和音の名前
      prev: Chord,             // 前の和音構造の参照
      next: Chord              // 次の和音構造の参照
    }
    */
  });

chordLeave

和音の終了で呼び出されるイベントです。
サンプルコード
player.on("chordLeave",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        chord: Chord
      }
    }
    */

    /**
    // 和音構造
    type Chord = {
      index: number,           // インデックス
      startTime: number,       // 和音の開始位置(ミリ秒)
      startTimeSec: number,    // 和音の開始位置(秒)
      endTime: number,         // 和音の終了位置(ミリ秒)
      endTimeSec: number,      // 和音の終了位置(秒)
      durationTime: number,    // 和音の再生時間(ミリ秒)
      durationTimeSec: number, // 和音の再生時間(秒)
      name: string,            // 和音の名前
      prev: Chord,             // 前の和音構造の参照
      next: Chord              // 次の和音構造の参照
    }
    */
  });

Plugin.Melody: class

音楽地図のメロディを扱うプラグインクラスです。

Constructor
1st arg options of the constructor

名前初期値説明
revisionIdnumber0使用する音楽地図のリビジョン番号です。
offsetnumber0イベントのオフセット値(ミリ秒)です。
pollingIntervalnumber50イベントのポーリング値(ミリ秒)です。
サンプルコード
player.addPlugin(new Songle.Plugin.Melody());

player.on("melodyEnter",
  function(ev) {
    // do someting ...
  });
ワンポイント

ピッチ(音高)取り扱いについて

このプラグインを利用して、ピッチ(音高)を取得することはできません。ここで扱うことのできるメロディとは、メロディの発音タイミングや音符・休符の判別フラグのみとなります。

ワンポイント

リビジョンについて

リビジョンとは、音楽理解技術による自動解析の誤りを人間が訂正した際に残る編集履歴のことです。この番号を指定することで、アプリケーションで使用する音楽地図の訂正状態を固定することができます。これは、音楽地図が第三者により編集された場合に発生する不整合を防ぐ場合に役立ちます。リビジョン番号は、楽曲ページ編集履歴より確認することができます。

ワンポイント

オフセットについて

オフセットでは、イベントの実行タイミングにオフセットを与えることができます。これは、アプリケーションの処理負荷などの要因によって、イベントの実行タイミングが前後にズレる場合に役立ちます。また、オフセットはイベント毎に個別に与えることもできます。

サンプルコード
player.addPlugin(new Songle.Plugin.Melody({
  offset: -100,
});

player.on("melodyEnter",
  function(ev) {
    // this event will be run faster 100ms than the original melody event
  });

player.on("melodyEnter",
  function(ev) {
    // this event will be run faster 200ms than the original melody event
  }, { offset: -100 });

player.on("melodyEnter",
  function(ev) {
    // this event will be run faster 300ms than the original melody event
  }, { offset: -200 });
Constants
Static constant variables of this class
Properties (Getter/Setter)
Properties of this class instance
Properties (Getter)
Get only properties of this class instance
Events
Related events of this class

MelodyEnterTrapName: string

メロディの開始で呼び出されるイベント名の定数です。

MelodyLeaveTrapName: string

メロディの終了で呼び出されるイベント名の定数です。

offset: number

イベントのオフセット値(ミリ秒)です。

pollingInterval: number

イベントのポーリング値(ミリ秒)です。

revisionId: number

使用する音楽地図のリビジョン番号です。

melodyEnter

メロディの開始で呼び出されるイベントです。
サンプルコード
player.on("melodyEnter",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        melody: Melody
      }
    }
    */

    /**
    // メロディ構造
    type Melody = {
      index: number,           // インデックス
      startTime: number,       // メロディの開始位置(ミリ秒)
      startTimeSec: number,    // メロディの開始位置(秒)
      endTime: number,         // メロディの終了位置(ミリ秒)
      endTimeSec: number,      // メロディの終了位置(秒)
      durationTime: number,    // メロディの再生時間(ミリ秒)
      durationTimeSec: number, // メロディの再生時間(秒)
      isNote: boolean,         // 音符の判別フラグ
      isRest: boolean,         // 休符の判別フラグ
      prev: Melody,            // 前のメロディ構造の参照
      next: Melody             // 次のメロディ構造の参照
    }
    */
  });

melodyLeave

メロディの終了で呼び出されるイベントです。
サンプルコード
player.on("melodyLeave",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        melody: Melody
      }
    }
    */

    /**
    // メロディ構造
    type Melody = {
      index: number,           // インデックス
      startTime: number,       // メロディの開始位置(ミリ秒)
      startTimeSec: number,    // メロディの開始位置(秒)
      endTime: number,         // メロディの終了位置(ミリ秒)
      endTimeSec: number,      // メロディの終了位置(秒)
      durationTime: number,    // メロディの再生時間(ミリ秒)
      durationTimeSec: number, // メロディの再生時間(秒)
      isNote: boolean,         // 音符の判別フラグ
      isRest: boolean,         // 休符の判別フラグ
      prev: Melody,            // 前のメロディ構造の参照
      next: Melody             // 次のメロディ構造の参照
    }
    */
  });

Plugin.Chorus: class

音楽地図のサビを扱うプラグインクラスです。

Constructor
1st arg options of the constructor

名前初期値説明
revisionIdnumber0使用する音楽地図のリビジョン番号です。
offsetnumber0イベントのオフセット値(ミリ秒)です。
pollingIntervalnumber50イベントのポーリング値(ミリ秒)です。
サンプルコード
player.addPlugin(new Songle.Plugin.Chorus());

player.on("chorusSectionEnter",
  function(ev) {
    // do someting ...
  });
ワンポイント

サビ区間と繰り返し区間について

サビ
繰り返し
繰り返し
繰り返し
繰り返し
...

この図は、楽曲訂正インタフェースにおける、サビ及び繰り返し構造の可視化を模倣したものです。サビ区間は、楽曲訂正インタフェースにおける橙色の区間を指し、繰り返し区間は、楽曲訂正インタフェースにおける橙色と青色の区間を指します。

ワンポイント

リビジョンについて

リビジョンとは、音楽理解技術による自動解析の誤りを人間が訂正した際に残る編集履歴のことです。この番号を指定することで、アプリケーションで使用する音楽地図の訂正状態を固定することができます。これは、音楽地図が第三者により編集された場合に発生する不整合を防ぐ場合に役立ちます。リビジョン番号は、楽曲ページ編集履歴より確認することができます。

ワンポイント

オフセットについて

オフセットでは、イベントの実行タイミングにオフセットを与えることができます。これは、アプリケーションの処理負荷などの要因によって、イベントの実行タイミングが前後にズレる場合に役立ちます。また、オフセットはイベント毎に個別に与えることもできます。

サンプルコード
player.addPlugin(new Songle.Plugin.Chorus({
  offset: -100,
});

player.on("chorusSectionEnter",
  function(ev) {
    // this event will be run faster 100ms than the original chorus event
  });

player.on("chorusSectionEnter",
  function(ev) {
    // this event will be run faster 200ms than the original chorus event
  }, { offset: -100 });

player.on("chorusSectionEnter",
  function(ev) {
    // this event will be run faster 300ms than the original chorus event
  }, { offset: -200 });

ChorusSectionEnterTrapName: string

サビ区間の開始で呼び出されるイベント名の定数です。

ChorusSectionLeaveTrapName: string

サビ区間の終了で呼び出されるイベント名の定数です。

RepeatedSectionEnterTrapName: string

繰り返し区間の開始で呼び出されるイベント名の定数です。

RepeatedSectionLeaveTrapName: string

繰り返し区間の終了で呼び出されるイベント名の定数です。

offset: number

イベントのオフセット値(ミリ秒)です。

pollingInterval: number

イベントのポーリング値(ミリ秒)です。

revisionId: number

使用する音楽地図のリビジョン番号です。

seekToPrevChorusSection: void

現在の再生位置から後方に対して、最も近いサビ区間にシークします。
このメソッドは Player クラスに同名のメソッド名がプラグイン読み込み前に定義されていない場合は Player クラスから呼び出すことができます。

サンプルコード
player.add(new Songle.Plugin.Chorus());

player.on("ready",
  function()
  {
    player.seekToPrevChorusSection();
  });

seekToNextChorusSection: void

現在の再生位置から前方に対して、最も近いサビ区間にシークします。
このメソッドは Player クラスに同名のメソッド名がプラグイン読み込み前に定義されていない場合は Player クラスから呼び出すことができます。

サンプルコード
player.add(new Songle.Plugin.Chorus());

player.on("ready",
  function()
  {
    player.seekToNextChorusSection();
  });

seekToPrevRepeatedSection: void

現在の再生位置から後方に対して、最も近い繰り返し区間にシークします。
このメソッドは Player クラスに同名のメソッド名がプラグイン読み込み前に定義されていない場合は Player クラスから呼び出すことができます。

サンプルコード
player.add(new Songle.Plugin.Chorus());

player.on("ready",
  function()
  {
    player.seekToPrevRepeatedSection();
  });

seekToNextRepeatedSection: void

現在の再生位置から前方に対して、最も近い繰り返し区間にシークします。
このメソッドは Player クラスに同名のメソッド名がプラグイン読み込み前に定義されていない場合は Player クラスから呼び出すことができます。

サンプルコード
player.add(new Songle.Plugin.Chorus());

player.on("ready",
  function()
  {
    player.seekToNextRepeatedSection();
  });

chorusSectionEnter

サビ区間の開始で呼び出されるイベントです。
区間が重なっている場合は、インデックスの値が小さい順に呼び出されます。

サンプルコード
player.on("chorusSectionEnter",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        section: ChorusSection,
        sectionItem: ChorusSectionItem
      }
    }
    */

    /**
    // サビ区間構造
    type ChorusSection = {
      index: number,                  // インデックス
      isChorus: boolean,              // サビの判別フラグ
      durationTime: number,           // 区間の再生時間(ミリ秒)
      durationTimeSec: number,        // 区間の再生時間(秒)
      items: Array<ChorusSectionItem>
    }
    */

    /**
    // サビ区間の要素構造
    type ChorusSectionItem = {
      index: number,                  // インデックス
      startTime: number,              // 区間の開始位置(ミリ秒)
      startTimeSec: number,           // 区間の開始位置(秒)
      endTime: number,                // 区間の終了位置(ミリ秒)
      endTimeSec: number,             // 区間の終了位置(秒)
      durationTime: number,           // 区間の再生時間(ミリ秒)
      durationTimeSec: number,        // 区間の再生時間(秒)
      prev: ChorusSectionItem,        // 前のサビ区間の要素構造の参照
      next: ChorusSectionItem         // 次のサビ区間の要素構造の参照
    }
    */
  });

chorusSectionLeave

サビ区間の終了で呼び出されるイベントです。
サンプルコード
player.on("barLeave",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        section: ChorusSection,
        sectionItem: ChorusSectionItem
      }
    }
    */

    /**
    // サビ区間構造
    type ChorusSection = {
      index: number,                  // インデックス
      isChorus: boolean,              // サビの判別フラグ
      durationTime: number,           // 区間の再生時間(ミリ秒)
      durationTimeSec: number,        // 区間の再生時間(秒)
      items: Array<ChorusSectionItem>
    }
    */

    /**
    // サビ区間の要素構造
    type ChorusSectionItem = {
      index: number,                  // インデックス
      startTime: number,              // 区間の開始位置(ミリ秒)
      startTimeSec: number,           // 区間の開始位置(秒)
      endTime: number,                // 区間の終了位置(ミリ秒)
      endTimeSec: number,             // 区間の終了位置(秒)
      durationTime: number,           // 区間の再生時間(ミリ秒)
      durationTimeSec: number,        // 区間の再生時間(秒)
      prev: ChorusSectionItem,        // 前のサビ区間の要素構造の参照
      next: ChorusSectionItem         // 次のサビ区間の要素構造の参照
    }
    */
  });

repeatedSectionEnter

拍子の開始で呼び出されるイベントです。
サンプルコード
player.on("chorusSectionEnter",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        section: ChorusSection,
        sectionItem: ChorusSectionItem
      }
    }
    */

    /**
    // サビ区間構造
    type ChorusSection = {
      index: number,                  // インデックス
      isChorus: boolean,              // サビの判別フラグ
      durationTime: number,           // 区間の再生時間(ミリ秒)
      durationTimeSec: number,        // 区間の再生時間(秒)
      items: Array<ChorusSectionItem>
    }
    */

    /**
    // サビ区間の要素構造
    type ChorusSectionItem = {
      index: number,                  // インデックス
      startTime: number,              // 区間の開始位置(ミリ秒)
      startTimeSec: number,           // 区間の開始位置(秒)
      endTime: number,                // 区間の終了位置(ミリ秒)
      endTimeSec: number,             // 区間の終了位置(秒)
      durationTime: number,           // 区間の再生時間(ミリ秒)
      durationTimeSec: number,        // 区間の再生時間(秒)
      prev: ChorusSectionItem,        // 前のサビ区間の要素構造の参照
      next: ChorusSectionItem         // 次のサビ区間の要素構造の参照
    }
    */
  });

repeatedSectionLeave

拍子の終了で呼び出されるイベントです。
サンプルコード
player.on("chorusLeave",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        section: ChorusSection,
        sectionItem: ChorusSectionItem
      }
    }
    */

    /**
    // サビ区間構造
    type ChorusSection = {
      index: number,                  // インデックス
      isChorus: boolean,              // サビの判別フラグ
      durationTime: number,           // 区間の再生時間(ミリ秒)
      durationTimeSec: number,        // 区間の再生時間(秒)
      items: Array<ChorusSectionItem>
    }
    */

    /**
    // サビ区間の要素構造
    type ChorusSectionItem = {
      index: number,                  // インデックス
      startTime: number,              // 区間の開始位置(ミリ秒)
      startTimeSec: number,           // 区間の開始位置(秒)
      endTime: number,                // 区間の終了位置(ミリ秒)
      endTimeSec: number,             // 区間の終了位置(秒)
      durationTime: number,           // 区間の再生時間(ミリ秒)
      durationTimeSec: number,        // 区間の再生時間(秒)
      prev: ChorusSectionItem,        // 前のサビ区間の要素構造の参照
      next: ChorusSectionItem         // 次のサビ区間の要素構造の参照
    }
    */
  });

Plugin.Variation: class

音楽地図のバリエーションを扱うプラグインクラスです。

Constructor
1st arg options of the constructor

名前初期値説明
offsetnumber0イベントのオフセット値(ミリ秒)です。
pollingIntervalnumber50イベントのポーリング値(ミリ秒)です。
groupCountnumber2分割するグループ数です。
サンプルコード
player.addPlugin(new Songle.Plugin.Variation());

player.on("variationEnter",
  function(ev) {
    switch(ev.data.variation.group) {
      case 0:
        // do someting ...
        break;
      case 1:
        // do someting ...
        break;
      case 2:
        // do someting ...
        break;
      case 3:
        // do someting ...
        break;
    }
  });
ワンポイント

バリエーションについて

バリエーションとは、楽曲の盛り上がりに応じて分割された区間のことです。楽曲に応じた演出の選択などの用途で利用することが想定されています。例えば、分割するグループ数を4とした場合、楽曲全体を4つのグループ(バリエーション区間)に分割します。

Group 0
Group 2
Group 3
Group 1

バリエーションでは、再生位置に応じた区間の開始・終了でイベントが発生します。イベント発生時に返されるグループ番号は、音響的に派手である区間に対応しており、値が小さほど静かな区間、値が大きい程派手な区間であるとラベリングされています。

ワンポイント

オフセットについて

オフセットでは、イベントの実行タイミングにオフセットを与えることができます。これは、アプリケーションの処理負荷などの要因によって、イベントの実行タイミングが前後にズレる場合に役立ちます。また、オフセットはイベント毎に個別に与えることもできます。

サンプルコード
player.addPlugin(new Songle.Plugin.Variation({
  offset: -100,
});

player.on("variationEnter",
  function(ev) {
    // this event will be run faster 100ms than the original variation event
  });

player.on("variationEnter",
  function(ev) {
    // this event will be run faster 200ms than the original variation event
  }, { offset: -100 });

player.on("variationEnter",
  function(ev) {
    // this event will be run faster 300ms than the original variation event
  }, { offset: -200 });
Properties (Getter/Setter)
Properties of this class instance
Events
Related events of this class

MinGroupCount: number

分割するグループ数に設定できる最小値の定数です。

MaxGroupCount: number

分割するグループ数に設定できる最大値の定数です。

VariationEnterTrapName: string

バリエーションの開始で呼び出されるイベント名の定数です。

VariationLeaveTrapName: string

バリエーションの終了で呼び出されるイベント名の定数です。

offset: number

イベントのオフセット値(ミリ秒)です。

pollingInterval: number

イベントのポーリング値(ミリ秒)です。

variationEnter

バリエーションの開始で呼び出されるイベントです。
サンプルコード
player.on("variationEnter",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        variation: Variation
      }
    }
    */

    /**
    // バリエーション構造
    type Variation = {
      index: number,           // インデックス
      startTime: number,       // バリエーションの開始位置(ミリ秒)
      startTimeSec: number,    // バリエーションの開始位置(秒)
      endTime: number,         // バリエーションの終了位置(ミリ秒)
      endTimeSec: number,      // バリエーションの終了位置(秒)
      durationTime: number,    // バリエーションの再生時間(ミリ秒)
      durationTimeSec: number, // バリエーションの再生時間(秒)
      group: number,           // バリエーションのグループ番号
      prev: Variation,         // 前のバリエーション構造の参照
      next: Variation          // 次のバリエーション構造の参照
    }
    */
  });

variationLeave

バリエーションの終了で呼び出されるイベントです。
サンプルコード
player.on("variationLeave",
  function(ev) {
    console.log(ev);

    /**
    {
      data: {
        variation: Variation
      }
    }
    */

    /**
    // バリエーション構造
    type Variation = {
      index: number,           // インデックス
      startTime: number,       // バリエーションの開始位置(ミリ秒)
      startTimeSec: number,    // バリエーションの開始位置(秒)
      endTime: number,         // バリエーションの終了位置(ミリ秒)
      endTimeSec: number,      // バリエーションの終了位置(秒)
      durationTime: number,    // バリエーションの再生時間(ミリ秒)
      durationTimeSec: number, // バリエーションの再生時間(秒)
      group: number,           // バリエーションのグループ番号
      prev: Variation,         // 前のバリエーション構造の参照
      next: Variation          // 次のバリエーション構造の参照
    }
    */
  });

Plugin.SongleSync: class

Properties (Getter/Setter)
Properties of this class instance
Properties (Getter)
Get only properties of this class instance
Methods
Methods of this class instance

message: string

isMaster: boolean

isSlave: boolean

play: void

pause: void

stop: void

seekTo: void

songleSyncMediaChange

songleSyncMessage

songleSyncNodeChange

songleSyncNodeEnter

songleSyncNodeLeave

songleSyncStateChange

Plugin.SongleWidget: class

外部埋め込みプレイヤーを表示するプラグインクラスです。

Constructor
1st arg options of the constructor

名前必須初期値説明
elementstring | HTMLElementtruenull埋め込み先の DOM 要素を指定します。
widgetnumber256外部埋め込みプレイヤーの横幅です。この値を設定した場合、後述する横幅に関するオプションが自動的に計算されます。
heightnumber100外部埋め込みプレイヤーの縦幅です。この値を設定した場合、後述する縦幅に関するオプションが自動的に計算されます。
responsivebooleanfalse埋め込み先の親要素サイズに応じて自動的にリサイズします。
showControllerbooleantrue操作に関する情報を表示します。
showOriginalSiteLinkbooleantrue配信サイトに関する情報を表示します。
showMusicMapbooleantrue音楽地図に関する情報を表示します。
showSongleJpSiteLinkbooleantrue訂正サイトに関する情報を表示します。
controllerWidthnumber256操作に関するインタフェースの横幅です。
controllerHeightnumber30操作に関するインタフェースの縦幅です。
controllerMouseEnterColorstring#e17操作ボタンにマウスポインタが触れている場合のカラー設定です。
controllerMouseLeaveColorstring#222操作ボタンにマウスポインタが触れてない場合のカラー設定です。
languagestringauto表示する言語です。
musicMapWidthnumber256音楽地図に関するインタフェースの横幅です。
musicMapHeightnumber40音楽地図に関するインタフェースの縦幅です。
musicMapOuterBackgroundColorstring#999音楽地図に関するインタフェースのカラーです。
musicMapInnerBackgroundColorstring#eee音楽地図に関するインタフェースのカラーです。
musicMapChorusSectionColorstring#f84音楽地図に関するインタフェースの繰り返し区間に関するカラーです。
musicMapRepeatedSectionColorstring#48f音楽地図に関するインタフェースの繰り返し区間に関するカラーです。
musicMapCursorColorstring#e17音楽地図に関するインタフェースの再生位置に関するカラーです。
サンプルコード
const plugin =
  new Songle.Plugin.SongleWidget({ element: "#sw" });

player.addPlugin(plugin);
Methods
Methods of this class instance

render: void

明示的に再描画を実行します。

System: class

Songle JavaScript API のシステムクラスです。
Static properties (Getter/Setter)
Static properties of this class

showDebugLog: boolean

開発ログを開発者コンソールに表示するための設定です(デフォルト:無効)。
サンプルコード
Songle.System.showDebugLog = true;

showErrorLog: boolean

例外ログを開発者コンソールに表示するための設定です(デフォルト:無効)。
サンプルコード
Songle.System.showErrorLog = true;

showLicense: boolean

ライセンスの表示設定です(デフォルト:有効)。
サンプルコード
Songle.System.showLicense = false;
ワンポイント

ライセンス表示の無効化について

このメソッドは、ウェブサイトを構築する際に「デザイン上、止むを得ずライセンス表示を削除したい」場合を想定して用意されたものです。本システム Songle API は非商用利用に限り、どなたでも無料・無保証で利用することができます。ただし、原則として Songle API を利用している旨を本サイトにハイパーリンクした上で、利用しているシステムもしくは外部サイト等に表示する必要があります。