Songle Widget API (version 1)

Summary

Songle Widget API allows the programmer to create and control Songle Widgets by writing a simple piece of JavaScript code.

1. Basics

By inserting the script tag and adding data-api and data-url attributes to any block elements, Songle Widgets are automatically initialized upon page loading.

A. Embed by HTML Code

<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. Embed by JavaScript Code

<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);
  }

　Since data-api attribute of embed code is used to distinguish each Songle Widget, its value is recommended to be unique for each widget.

2. Hello,Songle Widget!!

In the following example, a pop-up dialog appears when Songle Widget API is ready to be used.

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

3. Example

Songle Widget API enables your program to react to a music-related event (such as beats and chords) by using the event handler of JavaScript.

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    songleWidget.on("beatPlay",
      function(e)
      {
        switch(e.beat.position)
        {
          case 1:
            // You can write code for the 1st beat ...
            console.log("1st beat");
            break;

          case 2:
            // You can write code for the 2nd beat ...
            console.log("2nd beat");
            break;

          case 3:
            // You can write code for the 3rd beat ...
            console.log("3rd beat");
            break;

          case 4:
            // You can write code for the 4th beat ...
            console.log("4th beat");
            break;
        }
      });

    songleWidget.play(); // Start playing song.
  }

動作要件

Web browser	Version
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

Option name	Explanation	Default value	Required?
data-api	Specifies unique string when using the API.	""	No
data-url	Specifies the URL of the original song or video. (e.g. www.youtube.com/watch?v=PqJNc9KVIZE)	""	Yes
data-api-create-callback-name	Specifies the name of the callback method, called when the Songle Widget DOM element is created.	"onSongleWidgetCreate"	No
data-api-error-callback-name	Specifies the name of the callback method, called when the initialization of the API fails.	"onSongleWidgetError"	No
data-api-ready-callback-name	Specifies the name of the callback method, called when the initialization of the API succeeds.	"onSongleWidgetReady"	No
data-api-beat-auto-reload	Enables auto-update of the beat (pulse) information when 1 is specified.	"0"	No
data-api-chord-auto-reload	Enables auto-update of the chord information when 1 is specified.	"0"	No
data-api-melody-auto-reload	Enables auto-update of the melody information when 1 is specified.	"0"	No
data-api-chorus-auto-reload	Enables auto-update of the chorus part information when 1 is specified.	"0"	No
data-api-beat-disabled	Skips loading the beat (pulse) information when 1 is specified.	"0"	No
data-api-chord-disabled	Skips loading the chord information when 1 is specified.	"0"	No
data-api-melody-disabled	Skips loading the melody information when 1 is specified.	"0"	No
data-api-chorus-disabled	Skips loading the chorus part information when 1 is specified.	"0"	No
data-api-beat-revision	Forces the widget to load the specified revision of the beat (pulse) information. If 0 is specified, load the newest revision.	"0"	No
data-api-chord-revision	Forces the widget to load the specified revision of the chord information. If 0 is specified, load the newest revision.	"0"	No
data-api-melody-revision	Forces the widget to load the specified revision of the melody information. If 0 is specified, load the newest revision.	"0"	No
data-api-chorus-revision	Forces the widget to load the specified revision of the chorus part information. If 0 is specified, load the newest revision.	"0"	No
data-song-auto-play	Enables auto-play (automatically starts playing the music or video) if 1 is specified. This option is only available for a YouTube video and MP3 file.	"0"	No
data-song-auto-loop	Enables auto-loop (automatically restarts playing the music or video when reaching its end) if 1 is specified. This option is only available for a YouTube video and MP3 file.	"0"	No
data-song-start-at	Specifies the starting position of playing the music or video. [seconds] If chorus is specified, playing starts at the first chorus part highlighted in orange. If repeat is specified, playing starts at the first repeat segment highlighted in blue.	"0"	No
data-song-volume	Specifies the initial volume. [0 - 100]	"auto"	No
data-songle-widget-ctrl	Shows the playback control if 1 is specified.	"1"	No
data-songle-widget-ctrl-enter-color	Specifies the color of the playback control when the mouse is hoverred.	"#e17"	No
data-songle-widget-ctrl-leave-color	Specifies the color of the playback control when the mouse is left.	"#000"	No
data-songle-widget-ctrl-link-color	Specifies the color of the information text.	"#e17"	No
data-songle-widget-size-w	Specifies the width of the Songle Widget. [px] If auto is specified, the widget automatically fits to the parent element.	"275"	No
data-songle-widget-size-h	Specifies the height of the Songle Widget. [px] If auto is specified, the widget automatically fits to the parent element.	"100"	No
data-video-player-size-w	Specifies the width of the video player. [px] If auto is specified, the player automatically fits to the parent element.	"275"	No
data-video-player-size-h	Specifies the height of the video player. [px] If auto is specified, the player automatically fits to the parent element.	"155"	No
data-nn-transparent	If 1 is specified, enables wmode. This option is only available for Niconico videos.	"0"	No
data-yt-ctrl	If 1 is specified, shows playback controls of the video player. This option is only available for YouTube videos.	"0"	No
data-yt-info	If 1 is specified, shows detailed information of the video player. This option is only available for YouTube videos.	"0"	No
data-yt-quality	Specifies the quality of the video. This option is only available for YouTube videos.	"small"	No

Executed when a DOM element of a Songle Widget is instantiated. (The method needs to be defined prior to loading Songle Widget library.)

Status code （Type:Number）	Explanation
-	This status code is reserved for future usage.

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

Executed when a Songle Widget fails to initialize. (The method needs to be defined prior to loading Songle Widget library.)

Status code （Type:Number）	Explanation
100	Original song is deleted and could not be embedded.
101	Original song is not allowed to be embedded in an external website.
200	Music structure loading has been suspended.
201	Music structure could not be loaded.

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

Executed when a Songle Widget has been successfully initialized. (The method needs to be defined prior to loading Songle Widget library.)

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

dataset.api

Returns the value of data-api provided to embed code.

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

dataset.url

Returns the value of data-url provided to embed code.

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

mode

Returns the execution mode.

Execution mode （Type:String）	Explanation
mp3	Music player mode
nn-video	Video player mode (Niconico video)
yt-video	Video player mode (YouTube)

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

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

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

uuid

Returns the UUID of the Songle Widget.

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

videoID

Returns the video ID. (only available when hosting Niconico and YouTube videos)

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

isPlaying

Returns true when the status is playing.

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

isPaused

Returns true when the status is paused.

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

isStopped

Returns true when the status is stopped.

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

isSeeking

Returns true when the status is seeking.

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

bpm

Returns the current tempo.

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

currentBeat

Returns the current pulse.

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentBeat);
      }
    , 1000 / 30); // 30 [FPS]
  }

currentChord

Returns the current chord.

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentChord);
      }
    , 1000 / 30); // 30 [FPS]
  }

currentNote

Returns the current note.

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentNote);
      }
    , 1000 / 30); // 30 [FPS]
  }

currentChorus / currentChorusSegment

Returns the current chorus (highlighted in orange).

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentChorusSegment);
      }
    , 1000 / 30); // 30 [FPS]
  }

currentRepeat / currentRepeatSegment

Returns the current repeating segment (highlighted in orange or blue).

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.currentRepeatSegment);
      }
    , 1000 / 30); // 30 [FPS]
  }

isPlayingChorus / isPlayingChorusSegment

Returns true if the chorus part is being played.

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.isPlayingChorusSegment);
      }
    , 1000 / 30); // 30 [FPS]
  }

isPlayingRepeat / isPlayingRepeatSegment

Returns true if the repeating segment is being played.

window.onSongleWidgetReady =
  function(apiKey, songleWidget)
  {
    setInterval(
      function()
      {
        console.log(songleWidget.isPlayingRepeatSegment);
      }
    , 1000 / 30); // 30 [FPS]
  }

duration

Returns the duration of the music.

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 / 30); // 30 [FPS]
  }

position

Returns the current playback position of the music.

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 / 30); // 30 [FPS]
  }

loadedRatio

Returns the proportion of music being loaded. [0 to 1]

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

playedRatio

Returns the proportion of music being played.

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

volume

Returns the current volume; set the volume.

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

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

    songleWidget.volume *= 0.9; // - 10 [%]

    songleWidget.volume *= 1.1; // + 10 [%]
  }

song

Returns the music structure.

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

Callback functions sometimes fail to be called in a timely manner. This typically happens when there are too many beats (pulses) in a short amount of time. Shortening the polling interval (default 200 milliseconds) could potentially solve the issue.

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

beatEventPriority

Specifies the priority of event detection for beats (pulses). The default value is 3. Setting a larger value results in the higher priority.

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

beatEventTimingOffset

Specifies the timing offset for calling beat (pulse) event callbacks. The default value is -175 milliseconds.

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

chordEventPriority

Specifies the priority of event detection for chords. The default value is 2. Setting a larger value results in the higher priority.

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

chordEventTimingOffset

Specifies the timing offset for calling chord event callbacks. The default value is -175 milliseconds.

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

noteEventPriority

Specifies the priority of event detection for melodies. The default value is 1. Setting a larger value results in the higher priority.

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

noteEventTimingOffset

Specifies the timing offset for calling melody event callbacks. The default value is -175 milliseconds.

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

chorusSegmentEventPriority

Specifies the priority of event detection for chorus parts (highlighted in orange). The default value is 5. Setting a larger value results in the higher priority.

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

chorusSegmentEventTimingOffset

Specifies the timing offset for calling chorus part (highlighted in orange) event callbacks. The default value is -175 milliseconds.

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

repeatSegmentEventPriority

Specifies the priority of event detection for repeating segments. The default value is 4. Setting a larger value results in the higher priority.

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

repeatSegmentEventTimingOffset

Specifies the timing offset for calling repeating segment event callbacks. The default value is -175 milliseconds.

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

on(trapName, trapFunction, options)

Bind an event listener to the specified event type.

Event （Type:String）	Synonym （Type:String）	Explanation
beatEnter	beatPlay	Called at the beginning of a beat (pulse).
beatLeave	-	Called at the end of a beat (pulse).
chordEnter	chordPlay	Called at the beginning of a chord event.
chordLeave	-	Called at the end of a chord event.
noteEnter	notePlay	Called at the beginning of a melody event.
noteLave	-	Called at the end of a melody event.
chorusSegmentEnter	chorusEnter	Called at the beginning of a chorus part highlighted in orange.
chorusSegmentLeave	chorusLeave	Called at the end of a chorus part highlighted in orange.
repeatSegmentEnter	repeatEnter	Called at the beginning of a repeat segment highlighted in orange or blue.
repeatSegmentLeave	repeatLeave	Called at the end of a repeat segment highlighted in orange or blue.
reload	-	Called when the music structure information is updated.
remove	-	Called when the music structure information is deleted.
play	-	Called when the playback begins.
pause	-	Called when the playback is paused.
stop	-	Called when the playback is stopped.
seek	-	Called when the playback position is changed.
loadingProgress	-	Called when there is a progress in loading the music or video.
playingProgress	-	Called when there is a progress in playing the music or video.
finish	-	Called when the playback reaches the end.

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(trapName)

Removes an event listener for the specified event type.

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

    songleWidget.off("chordPlay");

    songleWidget.off("notePlay");

    songleWidget.off("chorusEnter");

    songleWidget.off("repeatEnter");
  }

play()

Start playing the music or video.

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

pause()

Pause playing the music or video.

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

stop()

Stop playing the music or video.

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

seekTo(milliseconds)

Moves the current playback position to the specified time.

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

seekToPrevChorus()

Moves the current playback position to the beginning of the previous closest chorus part.

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

seekToNextChorus()

Moves the current playback position to the beginning of the next closest chorus part.

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

seekToPrevRepeat()

Moves the current playback position to the beginning of the previous closest repeat segment.

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

seekToNextRepeat()

Moves the current playback position to the beginning of the next closest repeat segment.

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

setAllEventTimingOffset(milliseconds)

Specifies the timing offset for calling all event callbacks. The default value is -175 milliseconds.

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

remove()

Removes the Songle Widget and releases all resources allocated for the widget.

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

computeAverageVolume(songleWidget)

Calculate the average volume of the song.

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

computeOffsetFromRepeatSegmentBy(songleWidget, options)

Calculate the offset time in milliseconds before the specified repeat segment.

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(options)

Create a Songle Widget instance.

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()

Look for a Songle Widget within the current web page.

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

findSongleWidgetsByAPI(api)

Look for a Songle Widget within the current web page by specifying dataset.api.

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

findSongleWidgetsByURL(url)

Look for a Songle Widget within the current web page by specifying dataset.url.

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

findSongleWidgetsByMode(mode)

Look for Songle Widgets within the current web page by specifying mode.

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

findSongleWidgetsByUUID(uuid)

Look for a Songle Widget within the current web page by specifying the UUID.

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

findSongleWidgetsByVideoID(videoID)

Look for a Songle Widget within the current web page by specifying the videoID.

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

findPrevRepeatSegmentRepeatBy(songleWidget, options)

Look for the closest repeat segment before the specified position.

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(songleWidget, options)

Look for the closest repeat segment after the specified position.

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(songleWidget, options)

Merge two repeat segments.

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

millisecondsToSeconds(milliseconds)

Convert the specified time from milliseconds to seconds.

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

millisecondsToMinutes(milliseconds)

Convert the specified time from milliseconds to minutes.

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

secondsToMilliseconds(seconds)

Convert the specified time from seconds to milliseconds.

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

minutesToMilliseconds(minutes)

Convert the specified time from minutes to milliseconds.

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

version

Returns the version number.

console.log(SongleWidgetAPI.version); // x.x.x

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

Retrieves the song information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Retrieves the song structure regarding the beat information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
revision_id	Returns the version number of the song structure.	0	No

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Returns the list of revisions of the song structure regarding the beat information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Retrieves the song structure regarding the chord information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
revision_id	Returns the version number of the song structure.	0	No

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Returns the list of revisions of the song structure regarding the chord information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Retrieves the song structure regarding the melody information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
revision_id	Returns the version number of the song structure.	0	No

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Returns the list of revisions of the song structure regarding the melody information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Retrieves the song structure regarding the chorus information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes
revision_id	Returns the version number of the song structure.	0	No

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Returns the list of revisions of the song structure regarding the chorus information.

Request

Parameter name	Explanation	Default value	Required?
url	Specifies the URL of the original song or video. （例: www.youtube.com/watch?v=PqJNc9KVIZE）	""	Yes

Response

Status	Explanation
200	OK
404	The song is not registered yet.
500	An unknown server error has occurred.

Example

Example request

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

Search songs.

Request

Parameter name	Explanation	Default value	Required?
q	Specifies the search query.	""	Yes

Response

Status	Explanation
200	OK
500	An unknown server error has occurred.

Example

Example request