Repetitive segments (IRepetitiveSegment)

Represents a structurally repeated section in the music such as a chorus or verse, with timing and group metadata.

TextAlive exposes two related types for structural repetition in music:

• IRepetitiveSegment — a single occurrence of a repeated section (e.g., one chorus).
• IRepetitiveSegments — a group of same-type segments (e.g., all choruses in the song).

Both come from Songle’s structural analysis. After onVideoReady, the full list of groups is at player.data.songMap.segments. Chorus-only segments can be fetched via player.getChoruses().

IRepetitiveSegment properties

TimedObject base

startTime · number

When this segment starts, in milliseconds.

endTime · number

When this segment ends, in milliseconds.

Segment-specific

duration · number

Duration of this segment in milliseconds (endTime - startTime). Read-only.

index · number

Zero-indexed position of this segment within its parent IRepetitiveSegments group.

previous · IRepetitiveSegment

The previous segment in the same group. null for the first segment in the group.

next · IRepetitiveSegment

The next segment in the same group. null for the last segment in the group.

Methods

progress(time) · number

Maps the given playback position time (in ms) to a [0, 1] value representing progress through this segment.

• 0.0 — beginning of the segment
• 1.0 — end of the segment

time · number · required

Current playback position in milliseconds.

IRepetitiveSegments properties

IRepetitiveSegments groups all occurrences of one structural type (e.g., all choruses).

chorus · boolean

true if this group represents chorus sections. false for other repetitive structures such as verses or bridges.

duration · number

The canonical duration shared by all segments in this group, in milliseconds.

segments · IRepetitiveSegment[]

The individual segment occurrences that belong to this group, sorted by startTime.

Player query methods

getChoruses

player.getChoruses(): IRepetitiveSegment[]

Returns a flat array of all chorus IRepetitiveSegment objects across all chorus groups. Returns an empty array if no chorus is detected.

findChorus

player.findChorus(time: number, options?: PlayerFindOptions): IRepetitiveSegment

Finds the chorus segment that contains (or is nearest to) the given time. Returns null if the current position is not inside any chorus.

time · number · required

Playback position in milliseconds.

options · PlayerFindOptions

Optional search parameters. PlayerFindOptions is an alias for FindTimedObjectOptions:

type PlayerFindOptions =
  | { endTime?: number }   // match a segment overlapping a range
  | { loose?: boolean };   // always return nearest binary search result

findChorusChange

player.findChorusChange(
  startTime: number,
  endTime: number
): TimedObjectsInRange<IRepetitiveSegment>

Looks for chorus transitions within the given time range. Returns a TimedObjectsInRange<IRepetitiveSegment> with entered, left, current, previous, and next.

startTime · number · required

Start of the query range in milliseconds.

endTime · number · required

End of the query range in milliseconds.

findChorusBetween(startTime, endTime) is deprecated. Use findChorusChange(startTime, endTime) or findChorus(time) instead.

Accessing all segment groups

player.data.songMap.segments holds all IRepetitiveSegments groups, not just choruses. You can inspect each group’s chorus flag to categorize them:

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

    for (const group of segments) {
      console.log(
        group.chorus ? "Chorus group" : "Non-chorus group",
        `— ${group.segments.length} occurrences,`,
        `each ~${group.duration}ms`
      );

      for (const seg of group.segments) {
        console.log(
          `  Segment ${seg.index}: ${seg.startTime}ms – ${seg.endTime}ms`
        );
      }
    }
  },
});

Example: highlight the screen during chorus

Change the background and show a label whenever a chorus section is active:

import { Player } from "textalive-app-api";

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

const overlay = document.getElementById("chorus-overlay")!;

player.addListener({
  onVideoReady() {
    const choruses = player.getChoruses();
    console.log(`Found ${choruses.length} chorus section(s)`);
  },

  onTimeUpdate(position: number) {
    const chorusChange = player.findChorusChange(
      player.videoPosition,
      position
    );

    // A chorus section just started
    for (const seg of chorusChange.entered) {
      overlay.classList.add("active");
      overlay.textContent = `Chorus ${seg.index + 1}`;
      console.log(
        `Chorus ${seg.index} started at ${seg.startTime}ms` +
        ` (progress: ${(seg.progress(position) * 100).toFixed(1)}%)`
      );
    }

    // A chorus section just ended
    for (const _seg of chorusChange.left) {
      overlay.classList.remove("active");
      overlay.textContent = "";
    }
  },
});

#chorus-overlay {
  position: fixed;
  top: 0; left: 0; right: 0;
  background: rgba(255, 200, 0, 0.3);
  padding: 8px;
  text-align: center;
  font-weight: bold;
  display: none;
  transition: opacity 0.3s;
}

#chorus-overlay.active {
  display: block;
}

Using progress() within a segment

You can use segment.progress(position) to animate elements that run through the duration of a structural section:

player.addListener({
  onTimeUpdate(position: number) {
    const chorus = player.findChorus(position);

    if (chorus) {
      // How far through the current chorus are we?
      const t = chorus.progress(position); // [0, 1]

      // E.g., move a progress bar across the chorus duration
      progressBar.style.width = `${t * 100}%`;
    }
  },
});