Song map (ISongMap)

The structured musical analysis of a song, providing beats, chords, and repetitive segments from Songle.

ISongMap contains the full musical analysis of a loaded song, generated by Songle. Once a video is ready, you can access the song map through player.data.songMap to retrieve beat grid, chord progressions, and structurally repeated sections such as choruses.

The song map is available after the onVideoReady callback fires. Do not access player.data.songMap before that point — it will be null.

Accessing the song map

const player = new Player({
  app: { token: "your-token" },
});

player.addListener({
  onVideoReady(video) {
    const songMap = player.data.songMap;

    console.log("Beats:", songMap.beats.length);
    console.log("Chords:", songMap.chords.length);
    console.log("Segment groups:", songMap.segments.length);
  },
});

ISongMap properties

beats · IBeat[]

Array of all beats detected in the song, sorted by startTime. Each element is an IBeat object.

See Beat (IBeat) for full property reference.

chords · IChord[]

Array of all chord progressions in the song, sorted by startTime. Each element is an IChord object.

See Chord (IChord) for full property reference.

segments · IRepetitiveSegments[]

Array of repetitive segment groups (e.g., chorus sections). Each IRepetitiveSegments element groups multiple individual IRepetitiveSegment objects of the same structural type.

See Repetitive segments for full property reference.

revisions · object

Revision IDs for the song map data. These values reflect which specific analysis version was loaded, and can be used to pin a song to a particular analysis revision when calling createFromSongUrl.

Show properties

chordId · number | undefined

Revision ID for the chord analysis data.

beatId · number | undefined

Revision ID for the beat analysis data.

repetitiveSegmentId · number | undefined

Revision ID for the repetitive segment analysis data.

IDataLoader properties

player.data is an IDataLoader instance. It exposes the following properties related to the loaded song and its map:

song · Song

Metadata for the currently loaded song.

Show properties

code · string

Unique string identifier for the song.

name · string

Song title.

length · number

Song duration in seconds. This value is approximate — use player.video.duration for precise timing in animations.

permalink · string

Permalink URL for this song.

artist · object

Artist info object with a name: string property.

songMap · ISongMap

The full song map object. See properties above.

lyrics · LyricsInfo

Lyrics timing estimation result from Songle.

Show properties

id · number

Lyrics timing estimation ID.

url · string

URL of the lyrics timing source.

diff · { id: number }

Lyrics diff (correction) info.

processing · boolean | undefined

Whether Songle is still analyzing the lyrics timing.

failed · boolean | undefined

Whether the Songle lyrics timing analysis failed.

lyricsBody · LyricsBody

The raw lyrics text and attribution data.

Show properties

text · string

Full lyrics text.

artist · { name: string; url?: string } | undefined

Artist name and optional URL.

name · string | undefined

Song name as listed in the lyrics source.

url · string | undefined

URL of the lyrics source.

fonts · IFontLoader

Font loading status and controls. Provides loaded, failed, isLoading(), load(), and loadAll() members.

permalink · string

The TextAlive service URL for the current video.

Overriding song map data with PartialVideoEntry

You can override which analysis revision is used when loading a song by passing a video option to createFromSongUrl. This is done via the PartialVideoEntry interface.

player.createFromSongUrl("https://www.youtube.com/watch?v=example", {
  video: {
    // Use a specific lyrics timing ID (-1 = latest, 0 = none)
    lyricId: -1,
    lyricDiffId: 0,

    // Pin the song map to specific analysis revisions
    beatId: 3,
    chordId: 2,
    repetitiveSegmentId: 1,
  },
});

lyricId · number | undefined

Specifies which lyrics timing data to load.

• -1: Use the latest available lyrics info
• 0: Do not load any lyrics info
• Any other positive integer: Load the specified lyrics ID

lyricDiffId · number | undefined

Revision ID for lyrics corrections (diff).

chordId · number | undefined

Revision ID for chord analysis data.

beatId · number | undefined

Revision ID for beat analysis data.

repetitiveSegmentId · number | undefined

Revision ID for repetitive segment analysis data.

json · VideoData | undefined

Full video data to embed directly, bypassing the server-side video fetch.

TimedObjectsInRange<T>

All findXxxChange methods on player return a TimedObjectsInRange<T> result. This structure describes what happened between the last frame and the current one:

interface TimedObjectsInRange<T extends TimedObject> {
  // The object that overlaps the end time of the queried range (currently active)
  current: T | null;
  // Objects that started within the queried range
  entered: T[];
  // Objects that ended within the queried range
  left: T[];
  // The last object before the queried range
  previous: T | null;
  // The first object after the queried range
  next: T | null;
}

Usage example

player.addListener({
  onTimeUpdate(position) {
    const beatChange = player.findBeatChange(
      player.videoPosition,
      position
    );

    for (const beat of beatChange.entered) {
      console.log("New beat entered at", beat.startTime);
    }
  },
});

Use entered to detect when a new beat, chord, or segment has just become active. Use current to check which object is active at the current moment.