Phrase (IPhrase)

A timed lyrics phrase — the top-level grouping of words and characters in a TextAlive video.

IPhrase represents a single phrase of sung lyrics. It extends ITextUnit, which in turn extends IRenderingUnit, so it inherits timing, navigation, and animation properties from both.

Inheritance chain: IPhrase → ITextUnit → IRenderingUnit → TimedObject

export declare interface IPhrase extends ITextUnit {
  readonly children: IWord[];
  readonly previous: IPhrase;
  readonly next: IPhrase;
  readonly wordCount: number;
  readonly charCount: number;
  readonly firstWord: IWord;
  readonly lastWord: IWord;
  readonly firstChar: IChar;
  readonly lastChar: IChar;
  findIndex(unit: IWord | IChar): number;
}

IPhrase properties

children · IWord[]

The words that make up this phrase, in order.

previous · IPhrase

The phrase immediately before this one, or null if this is the first phrase.

next · IPhrase

The phrase immediately after this one, or null if this is the last phrase.

wordCount · number

Number of words in this phrase.

charCount · number

Total number of characters across all words in this phrase.

firstWord · IWord

The first word in this phrase.

lastWord · IWord

The last word in this phrase.

firstChar · IChar

The first character in this phrase.

lastChar · IChar

The last character in this phrase.

IPhrase methods

findIndex

Returns the index of a word or character within this phrase’s flat unit list.

unit · IWord | IChar · required

The word or character whose index you want.

Returns number

---

Inherited from ITextUnit

export declare interface ITextUnit extends IRenderingUnit {
  readonly text: string;
}

text · string

The plain text of this phrase — the concatenated text of all its words.

---

Inherited from IRenderingUnit

startTime · number

Start time of this phrase in milliseconds.

endTime · number

End time of this phrase in milliseconds.

duration · number

Duration of this phrase in milliseconds (endTime - startTime).

animate · RenderingUnitFunction

Assign a function here to override the default template animation for this phrase. The function receives (now: number, u: IRenderingUnit) on every render frame.

progress

Maps a song position to a value in [0, 1] representing how far through this phrase playback has reached.

time · number · required

Position in the song [ms].

Returns number — 0 at startTime, 1 at endTime.

getType

Returns the unit type constant.

Returns number — always 1 (UnitTypes.PHRASE) for phrases.

---

PhraseData

PhraseData is the serialization format used when constructing a video from JSON.

export declare interface PhraseData extends UnitData {
  words: WordData[];
}

export declare interface UnitData {
  startTime?: number;
  endTime?: number;
}

Show PhraseData properties

words · WordData[]

The word data objects that make up this phrase.

startTime · number

Optional override for the phrase start time [ms].

endTime · number

Optional override for the phrase end time [ms].

---

Examples

Iterate over all phrases and their words

player.addListener({
  onVideoReady(v: IVideo) {
    for (const phrase of v.phrases) {
      console.log(`Phrase [${phrase.startTime}ms]: "${phrase.text}"`);

      for (const word of phrase.children) {
        console.log(`  Word: "${word.text}" (pos: ${word.pos})`);
      }
    }
  }
});

Use findPhrase in onTimeUpdate to display the current phrase

let activePhraseEl: HTMLElement | null = null;

player.addListener({
  onTimeUpdate(position: number) {
    const phrase = player.video.findPhrase(position);

    if (phrase) {
      // Show phrase text and how far through it we are
      const progress = phrase.progress(position); // [0, 1]
      display(phrase.text, progress);
    } else {
      clearDisplay();
    }
  }
});

function display(text: string, progress: number) {
  document.getElementById('lyrics')!.textContent = text;
  document.getElementById('bar')!.style.width = `${progress * 100}%`;
}

function clearDisplay() {
  document.getElementById('lyrics')!.textContent = '';
}

Use findPhraseChange instead of findPhrase when you need to trigger enter and exit animations exactly once per phrase transition rather than re-evaluating on every frame.