Songle Widget API (version 1)

概要

　Songle Widget API は Songle Widget を JavaScript から操作するための機能です。

1. 利用準備

　この機能を利用するためには、埋め込みコードに任意の文字列が設定された data-api 属性を追加するか、このサービスが提供する API スクリプトをあなたのウェブサイト上で事前に読み込んでおきます。

A. 埋め込みコードから利用する

<div data-api="songle-widget-api-example" data-url="www.youtube.com/watch?v=PqJNc9KVIZE" id="songle-widget"></div>
<script src="https://widget.songle.jp/v1/widgets.js"></script>

B. API スクリプトから利用する

<script src="https://widget.songle.jp/v1/api.js"></script>

window.onload =
  function()
  {
    var songleWidgetElement =
      SongleWidgetAPI.createSongleWidgetElement({
        api: "songle-widget-api-example",
        url: "www.youtube.com/watch?v=PqJNc9KVIZE"
      });

    document.body.appendChild(songleWidgetElement);
  }

　埋め込みコードの data-api 属性に与える任意の文字列は、複数のプレーヤを利用する際に各プレーヤを操作するために必要になるため、ユニークであることが推奨されます。

2. Hello,Songle Widget!!

　Songle Widget の準備が完了すると window.onSongleWidgetReady が実行されます。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    console.log("Hello,Songle Widget!!");
  }

3. サンプルプログラム

　音楽プレーヤの操作以外にも音楽理解技術による拍などをブラウザのイベントとして処理することができます。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.on("beatPlay",
      function(e)
      {
        switch(e.beat.position)
        {
          case 1:
            // 1 拍目の処理をここに記述
            console.log("1st beat");
            break;

          case 2:
            // 2 拍目の処理をここに記述
            console.log("2nd beat");
            break;

          case 3:
            // 3 拍目の処理をここに記述
            console.log("3rd beat");
            break;

          case 4:
            // 4 拍目の処理をここに記述
            console.log("4th beat");
            break;
        }
      });

    songleWidget.play(); // 再生開始
  }

動作要件

ウェブブラウザ	バージョン
Microsoft Internet Explorer	9,10,11
Microsoft Edge	14
Mozilla Firefox	48
Google Chrome	52 (recommended)
Safari	9
Opera	39
Android Browser	51
Google Chrome for Android	51

オプション名	説明	デフォルト値	必須
data-api	API を利用する際、任意の文字列を指定します。	""	No
data-url	配信元サイトの URL を指定します。 （例：www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
data-api-create-callback-name	DOM Element が作成された際に実行するメソッド名を指定します。	"onSongleWidgetCreate"	No
data-api-error-callback-name	API の初期化に失敗した際に実行するメソッド名を指定します。	"onSongleWidgetError"	No
data-api-ready-callback-name	API の初期化に成功した際に実行するメソッド名を指定します。	"onSongleWidgetReady"	No
data-api-beat-auto-reload	1 の場合、拍に関する音楽地図の自動更新を行います。	"0"	No
data-api-chord-auto-reload	1 の場合、和音に関する音楽地図の自動更新を行います。	"0"	No
data-api-melody-auto-reload	1 の場合、メロディに関する音楽地図の自動更新を行います。	"0"	No
data-api-chorus-auto-reload	1 の場合、サビに関する音楽地図の自動更新を行います。	"0"	No
data-api-beat-disabled	1 の場合、拍に関する音楽地図のダウンロードをスキップします。	"0"	No
data-api-chord-disabled	1 の場合、和音に関する音楽地図のダウンロードをスキップします。	"0"	No
data-api-melody-disabled	1 の場合、メロディに関する音楽地図のダウンロードをスキップします。	"0"	No
data-api-chorus-disabled	1 の場合、サビに関する音楽地図のダウンロードをスキップします。	"0"	No
data-api-beat-revision	拍に関する音楽地図のバージョンを指定のバージョンに固定します。 0 の場合、最新版の音楽地図をダウンロードします。	"0"	No
data-api-chord-revision	和音に関する音楽地図のバージョンを指定のバージョンに固定します。 0 の場合、最新版の音楽地図をダウンロードします。	"0"	No
data-api-melody-revision	メロディに関する音楽地図のバージョンを指定のバージョンに固定します。 0 の場合、最新版の音楽地図をダウンロードします。	"0"	No
data-api-chorus-revision	サビに関する音楽地図のバージョンを指定のバージョンに固定します。 0 の場合、最新版の音楽地図をダウンロードします。	"0"	No
data-song-auto-play	1 の場合、自動再生を有効にします（YouTube / mp3 のみ）。	"0"	No
data-song-auto-loop	1 の場合、自動繰返を有効にします（YouTube / mp3 のみ）。	"0"	No
data-song-start-at	初回再生時の再生位置を時刻（秒）指定します。 chorus の場合、最初の繰り返し区間（橙色）から再生します。 repeat の場合、最初の繰り返し区間（青色）から再生します。	"0"	No
data-song-volume	初期音量を 0 ~ 100 の範囲で設定します。	"auto"	No
data-songle-widget-ctrl	1 の場合、コントロールボタンを表示します。	"1"	No
data-songle-widget-ctrl-enter-color	マウスが触れた際、コントロールボタンの色を設定します。	"#e17"	No
data-songle-widget-ctrl-leave-color	マウスが離れた際、コントロールボタンの色を設定します。	"#000"	No
data-songle-widget-ctrl-link-color	リンクテキストのデザインを設定します。	"#e17"	No
data-songle-widget-size-w	Songle Widget の横幅（ピクセル）を設定します。 auto の場合、埋め込まれた親要素のサイズに自動調節します。	"275"	No
data-songle-widget-size-h	Songle Widget の縦幅（ピクセル）を設定します。 auto の場合、埋め込まれた親要素のサイズに自動調節します。	"100"	No
data-video-player-size-w	動画プレーヤの横幅（ピクセル）を設定します。 auto の場合、埋め込まれた親要素のサイズに自動調節します。	"275"	No
data-video-player-size-h	動画プレーヤの縦幅（ピクセル）を設定します。 auto の場合、埋め込まれた親要素のサイズに自動調節します。	"155"	No
data-nn-transparent	1 の場合 wmode を有効にします（ニコニコ動画のみ）。	"0"	No
data-yt-ctrl	1 の場合、動画プレーヤの制御表示を有効にします（YouTube のみ）。	"0"	No
data-yt-info	1 の場合、動画プレーヤの詳細表示を有効にします（YouTube のみ）。	"0"	No
data-yt-quality	動画プレーヤの品質を設定します（YouTube のみ）。	"small"	No

onSongleWidgetCreate

Songle Widget の DOM Element が作成されたタイミングで実行されます（このメソッドは、事前に定義しておく必要があります）。

ステータス	説明
-	このステータスは、将来のために予約されています。

window.onSongleWidgetCreate =
  function(apiKey, songleWidget)
  {
    console.log("status: " + songleWidget.status);
  }

onSongleWidgetError

Songle Widget の初期化が失敗したタイミングで実行されます（このメソッドは、事前に定義しておく必要があります）。

ステータス	説明
100	配信元の楽曲は、削除されているため埋め込むことができませんでした。
101	配信元の楽曲は、許可されてないため埋め込むことができませんでした。
200	音楽地図のダウンロードが中断しました。
201	音楽地図のダウンロードが失敗しました。
300	配信元の音源（mp3）のダウンロードに失敗しました。

window.onSongleWidgetError =
  function(apiKey, songleWidget)
  {
    console.log("status: " + songleWidget.status);
  }

onSongleWidgetReady

Songle Widget の初期化が成功したタイミングで実行されます（このメソッドは、事前に定義しておく必要があります）。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    console.log("Hello,Songle Widget!!");
  }

onSongleWidgetReload

TBD

window.onSongleWidgetReload =
  function(apiKey, songleWidget)
  {
    console.log("Songle Widget was reloaded!!");
  }

onSongleWidgetRemove

TBD

window.onSongleWidgetRemove =
  function(apiKey, songleWidget)
  {
    console.log("Songle Widget was removed!!");
  }

dataset.api

埋め込みオプションに与えられた data-api の値を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    console.log(songleWidget.dataset.api);
  }

dataset.url

埋め込みオプションに与えられた data-url の値を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    console.log(songleWidget.dataset.url);
  }

mode

起動モードを返します。

起動モード	説明
SongleWidgetAPI.MP3_MODE	音楽プレーヤモード
SongleWidgetAPI.NN_VIDEO_MODE	動画プレーヤモード（ニコニコ動画）
SongleWidgetAPI.YT_VIDEO_MODE	動画プレーヤモード（YouTube）

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    switch(songleWidget.mode)
    {
      case SongleWidgetAPI.MP3_MODE:
        console.log("Songle Widget is mp3 mode.");
        break;

      case SongleWidgetAPI.NN_VIDEO_MODE:
        console.log("Songle Widget is nn video mode.");
        break;

      case SongleWidgetAPI.YT_VIDEO_MODE:
        console.log("Songle Widget is yt video mode.");
        break;
    }
  }

uuid

UUID を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    console.log(songleWidget.uuid);
  }

videoID

動画 ID を返します（ニコニコ動画 / YouTube のみ）。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    console.log(songleWidget.videoID);
  }

rootElement

TBD

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    console.log(songleWidget.rootElement);
  }

isPlaying

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

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        if(songleWidget.isPlaying)
          console.log("Songle Widget is playing now.");
      }
    , 1000);
  }

isPaused

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

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        if(songleWidget.isPaused)
          console.log("Songle Widget is paused now.");
      }
    , 1000);
  }

isStopped

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

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        if(songleWidget.isStopped)
          console.log("Songle Widget is stopped now.");
      }
    , 1000);
  }

isSeeking

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

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        if(songleWidget.isSeeking)
          console.log("Songle Widget is seeking now.");
      }
    , 1000);
  }

bpm

現在の bpm を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.bpm + " [bpm]");
      }
    , 1000);
  }

currentBeat

現在の拍を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentBeat);
      }
    , 1000);
  }

currentChord

現在の和音を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentChord);
      }
    , 1000);
  }

currentNote

現在のメロディを返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentNote);
      }
    , 1000);
  }

currentChorusSegment

現在のサビ（橙色の繰り返し）区間情報を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentChorusSegment);
      }
    , 1000);
  }

currentRepeatSegment

現在のサビ（橙色の繰り返し・青色の繰り返し）区間情報を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentRepeatSegment);
      }
    , 1000);
  }

isPlayingChorusSegment

（橙色の繰り返し）区間を再生中の場合 true を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.isPlayingChorusSegment);
      }
    , 1000);
  }

isPlayingRepeatSegment

（橙色の繰り返し・青色の繰り返し）区間を再生中の場合 true を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.isPlayingRepeatSegment);
      }
    , 1000);
  }

duration

楽曲の再生時間を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.duration.milliseconds + " [ms]");
        console.log(songleWidget.duration.seconds + " [sec]");
        console.log(songleWidget.duration.minutes + " [min]");
      }
    , 1000);
  }

position

楽曲の再生位置を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.position.milliseconds + " [ms]");
        console.log(songleWidget.position.seconds + " [sec]");
        console.log(songleWidget.position.minutes + " [min]");
      }
    , 1000);
  }

loadedRatio

楽曲のロードされた割合を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.loadedRatio * 100 + " [%]");
      }
    , 1000);
  }

playedRatio

楽曲のプレイされた割合を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.playedRatio * 100 + " [%]");
      }
    , 1000);
  }

volume

音量を操作します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.volume = SongleWidgetAPI.MIN_VOLUME; // Min volume.

    songleWidget.volume = SongleWidgetAPI.MAX_VOLUME; // Max volume.
  }

song

楽曲情報（タイトルなど）及び、を返します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    /*
      [...].song.url

      [...].song.id
      [...].song.title
      [...].song.permalink
      [...].song.duration
      [...].song.position
      [...].song.rmsAmplitude

      [...].song.artist.id
      [...].song.artist.name

      [...].song.scene.beats
      [...].song.scene.beats[ beatIndex ].index
      [...].song.scene.beats[ beatIndex ].start
      [...].song.scene.beats[ beatIndex ].position

      [...].song.scene.chords
      [...].song.scene.chords[ chordIndex ].index
      [...].song.scene.chords[ chordIndex ].start
      [...].song.scene.chords[ chordIndex ].duration
      [...].song.scene.chords[ chordIndex ].name

      [...].song.scene.notes
      [...].song.scene.notes[ noteIndex ].index
      [...].song.scene.notes[ noteIndex ].start
      [...].song.scene.notes[ noteIndex ].duration
      [...].song.scene.notes[ noteIndex ].pitch
      [...].song.scene.notes[ noteIndex ].number

      [...].song.scene.chorusSegments
      [...].song.scene.chorusSegments[ chorusSegmentIndex ].index
      [...].song.scene.chorusSegments[ chorusSegmentIndex ].duration
      [...].song.scene.chorusSegments[ chorusSegmentIndex ].repeats
      [...].song.scene.chorusSegments[ chorusSegmentIndex ].repeats[ repeatIndex ].index
      [...].song.scene.chorusSegments[ chorusSegmentIndex ].repeats[ repeatIndex ].start
      [...].song.scene.chorusSegments[ chorusSegmentIndex ].repeats[ repeatIndex ].duration

      [...].song.scene.repeatSegments
      [...].song.scene.repeatSegments[ repeatSegmentIndex ].index
      [...].song.scene.repeatSegments[ repeatSegmentIndex ].duration
      [...].song.scene.repeatSegments[ repeatSegmentIndex ].repeats
      [...].song.scene.repeatSegments[ repeatSegmentIndex ].repeats[ repeatIndex ].index
      [...].song.scene.repeatSegments[ repeatSegmentIndex ].repeats[ repeatIndex ].start
      [...].song.scene.repeatSegments[ repeatSegmentIndex ].repeats[ repeatIndex ].duration
    */
    console.log(songleWidget.song);
  }

eventPollingInterval

拍の間隔などが極端に短い楽曲は、イベント検出が遅延することがあります。イベント検出は、ポーリングモデルにより実装されてため、タイミングにより次の検出タイミングまで遅延します。この値を小さくすることで、この問題を回避することができます。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.eventPollingInterval = 1; // 1 [ms]
  }

beatEventPriority

拍に関するイベント検出の優先度（デフォルト3）を設定します。優先度は、大きいほど優先的に処理されます。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.beatEventPriority = 3;
  }

beatEventTimingOffset

拍に関するイベントの実行タイミングのオフセットを設定します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.beatEventTimingOffset = -100; // -100 [ms]
  }

chordEventPriority

和音に関するイベント検出の優先度（デフォルト2）を設定します。優先度は、大きいほど優先的に処理されます。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.chordEventPriority = 2;
  }

chordEventTimingOffset

和音に関するイベントの実行タイミングのオフセットを設定します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.chordEventTimingOffset = -100; // -100 [ms]
  }

noteEventPriority

メロディに関するイベント検出の優先度（デフォルト1）を設定します。優先度は、大きいほど優先的に処理されます。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.noteEventPriority = 1;
  }

noteEventTimingOffset

メロディに関するイベントの実行タイミングのオフセットを設定します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.noteEventTimingOffset = -100; // -100 [ms]
  }

chorusSegmentEventPriority

サビ（橙色の繰り返し）区間に関するイベント検出の優先度（デフォルト5）を設定します。優先度は、大きいほど優先的に処理されます。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.chorusSegmentEventPriority = 5;
  }

chorusSegmentEventTimingOffset

サビ（橙色の繰り返し）区間に関するイベントの実行タイミングのオフセットを設定します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.chorusSegmentEventTimingOffset = -100; // -100 [ms]
  }

repeatSegmentEventPriority

サビ（青色の繰り返し）区間に関するイベント検出の優先度（デフォルト4）を設定します。優先度は、大きいほど優先的に処理されます。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.repeatSegmentEventPriority = 4;
  }

repeatSegmentEventTimingOffset

サビ（青色の繰り返し）区間に関するイベントの実行タイミングのオフセットを設定します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.repeatSegmentEventTimingOffset = -100; // -100 [ms]
  }

on

任意のイベントに対してイベントリスナーを登録します。

イベント	別名	説明
beatEnter	beatPlay	の開始イベントが発生した。
beatLeave	-	の終了イベントが発生した。
chordEnter	chordPlay	の開始イベントが発生した。
chordLeave	-	の終了イベントが発生した。
noteEnter	notePlay	の開始イベントが発生した。
noteLave	-	の終了イベントが発生した。
chorusSegmentEnter	chorusEnter	（橙色の繰り返し）区間の開始イベントが発生した。
chorusSegmentLeave	chorusLeave	（橙色の繰り返し）区間の終了イベントが発生した。
repeatSegmentEnter	repeatEnter	（橙色の繰り返し・青色の繰り返し）区間の開始イベントが発生した。
repeatSegmentLeave	repeatLeave	（橙色の繰り返し・青色の繰り返し）区間の終了イベントが発生した。
reload	-	Songle Widget（）が更新された。
remove	-	Songle Widget（）が削除された。
play	-	再生した。
pause	-	一時停止した。
stop	-	停止した。
seek	-	シークした。
loadingProgress	-	楽曲のロードされた割合に変化があった。
playingProgress	-	楽曲のプレイされた割合に変化があった。
finish	-	最後まで再生した。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.on("beatPlay",
      function(e)
      {
        /*
          [...].beat.prev.index
          [...].beat.prev.start
          [...].beat.prev.position

          [...].beat.index
          [...].beat.start
          [...].beat.position

          [...].beat.next.index
          [...].beat.next.start
          [...].beat.next.position
        */
        console.log(e);
      });

    songleWidget.on("chordPlay",
      function(e)
      {
        /*
          [...].chord.prev.index
          [...].chord.prev.start
          [...].chord.prev.duration
          [...].chord.prev.name

          [...].chord.index
          [...].chord.start
          [...].chord.duration
          [...].chord.name

          [...].chord.next.index
          [...].chord.next.start
          [...].chord.next.duration
          [...].chord.next.name
        */
        console.log(e);
      });

    songleWidget.on("notePlay",
      function(e)
      {
        /*
          [...].note.prev.index
          [...].note.prev.start
          [...].note.prev.duration
          [...].note.prev.pitch
          [...].note.prev.number

          [...].note.index
          [...].note.start
          [...].note.duration
          [...].note.pitch
          [...].note.number

          [...].note.next.index
          [...].note.next.start
          [...].note.next.duration
          [...].note.next.pitch
          [...].note.next.number
        */
        console.log(e);
      });

    songleWidget.on("chorusEnter",
      function(e)
      {
        /*
          [...].repeat.index
          [...].repeat.start
          [...].repeat.duration

          [...].segment.index
          [...].segment.duration
        */
        console.log(e);
      });

    songleWidget.on("repeatEnter",
      function(e)
      {
        /*
          [...].repeat.index
          [...].repeat.start
          [...].repeat.duration

          [...].segment.index
          [...].segment.duration
        */
        console.log(e);
      });
  }

off

任意のイベントに対してイベントリスナーを削除します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.off("beatPlay");

    songleWidget.off("chordPlay");

    songleWidget.off("notePlay");

    songleWidget.off("chorusEnter");

    songleWidget.off("repeatEnter");
  }

play

再生します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.play();
  }

pause

一時停止します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.pause();
  }

stop

停止します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.stop();
  }

seekTo

指定の再生位置（ミリ秒）にシークします。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.seekTo(SongleWidgetAPI.secondsToMilliseconds(30)); // Seek to 30 seconds.
  }

seekToPrevChorus

現在の再生位置より 1 つ前の（橙色の繰り返し）区間の先頭にシークします。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.seekToPrevChorus();
  }

seekToNextChorus

現在の再生位置より 1 つ先の（橙色の繰り返し）区間の先頭にシークします。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.seekToNextChorus();
  }

seekToPrevRepeat

現在の再生位置より 1 つ前の（橙色の繰り返し・青色の繰り返し）区間の先頭にシークします。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.seekToPrevRepeat();
  }

seekToNextRepeat

現在の再生位置より 1 つ先の（橙色の繰り返し・青色の繰り返し）区間の先頭にシークします。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.seekToNextRepeat();
  }

setAllEventTimingOffset

全イベントの実行タイミングのオフセットを設定します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.setAllEventTimingOffset(-100); // -100 [ms]
  }

serialize

音楽地図をシリアライズします。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.serialize();
  }

remove

確保されたリソースを解放します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.remove();
  }

DEFAULT_SONGLE_WIDGET_SIZE_W

TBD

DEFAULT_SONGLE_WIDGET_SIZE_H

TBD

DEFAULT_VIDEO_PLAYER_SIZE_W

TBD

DEFAULT_VIDEO_PLAYER_SIZE_H

TBD

MIN_SONGLE_WIDGET_SIZE_W

TBD

MIN_SONGLE_WIDGET_SIZE_H

TBD

MIN_VIDEO_PLAYER_SIZE_W

TBD

MIN_VIDEO_PLAYER_SIZE_H

TBD

MIN_VOLUME

TBD

MAX_VOLUME

TBD

MP3_MODE

TBD

NN_VIDEO_MODE

TBD

YT_VIDEO_MODE

TBD

SOURCE_SONGLE_WIDGET

TBD

SOURCE_MP3

TBD

SOURCE_NN_VIDEO

TBD

SOURCE_YT_VIDEO

TBD

computeAverageVolume

平均音量を計算します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.volume = SongleWidgetAPI.computeAverageVolume(songleWidget);
  }

computeOffsetFromRepeatSegmentBy

指定の繰り返し区間に入るの指定拍数前の時間（オフセット）を計算します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var offset =
      SongleWidgetAPI.computeOffsetFromRepeatSegmentBy(songleWidget, {
        beatCount: 4,
        repeatSegmentIndex: 0
      }); // e.g. 1600 [ms]

    songleWidget.on("chorusEnter",
      function()
      {
      }, { offset: offset });
  }

createSongleWidgetElement

埋め込みコードを生成します。

window.onload =
  function()
  {
    document.body.appendChild(
      SongleWidgetAPI.createSongleWidgetElement({
        api: "songle-widget-api-example",
        url: "www.youtube.com/watch?v=PqJNc9KVIZE",
        songAutoPlay: false,
        songAutoLoop: false,
        onCreate:
          function(songleWidget)
          {
            console.log("status: " + songleWidget.status);
          },
        onError:
          function(songleWidget)
          {
            console.log("status: " + songleWidget.status);
          },
        onReady:
          function(songleWidget)
          {
            console.log("Hello,Songle Widget!!");
          }
      }));
  }

findSongleWidgets

ページ内の制御可能な Songle Widget を検索します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var songleWidgets = SongleWidgetAPI.findSongleWidgets();
    songleWidgets[ 0 ].play(); // Start playing song.
  }

findSongleWidgetsByAPI

ページ内の制御可能な Songle Widget を dataset.api から検索します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var songleWidgets = SongleWidgetAPI.findSongleWidgetsByAPI(songleWidget.dataset.api);
    songleWidgets[ 0 ].play(); // Start playing song.
  }

findSongleWidgetsByURL

ページ内の制御可能な Songle Widget を dataset.url から検索します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var songleWidgets = SongleWidgetAPI.findSongleWidgetsByURL(songleWidget.dataset.url);
    songleWidgets[ 0 ].play(); // Start playing song.
  }

findSongleWidgetsByMode

ページ内の制御可能な Songle Widget を mode から検索します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var songleWidgets = SongleWidgetAPI.findSongleWidgetsByMode(songleWidget.mode);
    songleWidgets[ 0 ].play(); // Start playing song.
  }

findSongleWidgetsByUUID

ページ内の制御可能な Songle Widget を uuid から検索します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var songleWidgets = SongleWidgetAPI.findSongleWidgetsByUUID(songleWidget.uuid);
    songleWidgets[ 0 ].play(); // Start playing song.
  }

findSongleWidgetsByVideoID

ページ内の制御可能な Songle Widget を videoID から検索します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var songleWidgets = SongleWidgetAPI.findSongleWidgetsByVideoID(songleWidget.videoID);
    songleWidgets[ 0 ].play(); // Start playing song.
  }

findPrevRepeatSegmentRepeatBy

指定時刻より前に対して、指定範囲の最も近い繰り返し区間を探します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var chorusSegmentRepeat
      = SongleWidgetAPI.findPrevRepeatSegmentRepeatBy(songleWidget, {
        position: songleWidget.position.milliseconds,
        repeatSegmentIndexA: 0,
        repeatSegmentIndexB: 0
      });

    if(chorusSegmentRepeat)
      songleWidget.seekTo(chorusSegmentRepeat.start); // Seek to prev chorus segment.
  }

findNextRepeatSegmentRepeatBy

指定時刻より後に対して、指定範囲の最も近い繰り返し区間を探します。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    var chorusSegmentRepeat
      = SongleWidgetAPI.findNextRepeatSegmentRepeatBy(songleWidget, {
        position: songleWidget.position.milliseconds,
        repeatSegmentIndexA: 0,
        repeatSegmentIndexB: 0
      });

    if(chorusSegmentRepeat)
      songleWidget.seekTo(chorusSegmentRepeat.start); // Seek to next chorus segment.
  }

mergeRepeatSegments

指定範囲の繰り返し区間をマージします。

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    SongleWidgetAPI.mergeRepeatSegments(songleWidget, {
      repeatSegmentIndexA: 0,
      repeatSegmentIndexB: 5
    }); // [ repeat, repeat, repeat, ... ]
  }

millisecondsToSeconds

ミリ秒から秒に変換します。

console.log(SongleWidgetAPI.millisecondsToSeconds(60000));

millisecondsToMinutes

ミリ秒から分に変換します。

console.log(SongleWidgetAPI.millisecondsToMinutes(60000));

secondsToMilliseconds

秒からミリ秒に変換します。

console.log(SongleWidgetAPI.secondsToMilliseconds(1.0));

minutesToMilliseconds

分からミリ秒に変換します。

console.log(SongleWidgetAPI.minutesToMilliseconds(1.0));

version

バージョン情報を返します。

console.log(SongleWidgetAPI.version);

/api/v1/song.{json|xml}

楽曲の情報を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/song/beat.{json|xml}

拍に関する音楽地図を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
revision_id	音楽地図のバージョンを指定します。	0	No

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/song/beat_revisions.{json|xml}

拍に関する音楽地図のバージョン一覧を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/song/chord.{json|xml}

和音に関する音楽地図を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
revision_id	音楽地図のバージョンを指定します。	0	No

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/song/chord_revisions.{json|xml}

和音に関する音楽地図のバージョン一覧を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/song/melody.{json|xml}

メロディに関する音楽地図を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
revision_id	音楽地図のバージョンを指定します。	0	No

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/song/melody_revisions.{json|xml}

メロディに関する音楽地図のバージョン一覧を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/song/chorus.{json|xml}

サビに関する音楽地図を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
revision_id	音楽地図のバージョンを指定します。	0	No

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/song/chorus_revisions.{json|xml}

サビに関する音楽地図のバージョン一覧を取得します。

リクエスト

パラメータ名	説明	デフォルト値	必須
url	配信元サイトの URL を指定します。 （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

レスポンス

ステータス	説明
200	OK
404	登録されていない楽曲です。
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト

/api/v1/songs/search.{json|xml}

楽曲を検索します。

リクエスト

パラメータ名	説明	デフォルト値	必須
q	検索文字列を指定します。	""	Yes

レスポンス

ステータス	説明
200	OK
500	不明なエラーが発生しました。

サンプル

サンプルリクエスト