Video (IVideo)

The top-level container for all lyrics and rendering units. Access it via player.video after a song loads.

IVideo is the root container for all timed rendering units in a TextAlive song — phrases, words, and characters. You access it through player.video after the onVideoReady event fires.

player.addListener({
  onVideoReady(v: IVideo) {
    console.log(v.phraseCount, 'phrases');
    console.log(v.wordCount, 'words');
    console.log(v.charCount, 'chars');
  }
});

Interface definition

export declare interface IVideo extends TimedObject {
  readonly phrases: IPhrase[];
  readonly words: IWord[];
  readonly chars: IChar[];

  duration: number;
  readonly startTime: number;
  readonly endTime: number;

  readonly phraseCount: number;
  readonly wordCount: number;
  readonly charCount: number;

  readonly firstPhrase: IPhrase;
  readonly lastPhrase: IPhrase;
  readonly firstWord: IWord;
  readonly lastWord: IWord;
  readonly firstChar: IChar;
  readonly lastChar: IChar;

  progress(time: number): number;

  getPhrase(index: number): IPhrase;
  getWord(index: number): IWord;
  getChar(index: number): IChar;

  findIndex(unit: IRenderingUnit): number;

  findPhrase(time: number, options?: FindTimedObjectOptions): IPhrase;
  findPhraseChange(startTime: number, endTime: number): TimedObjectsInRange<IPhrase>;
  findWord(time: number, options?: FindTimedObjectOptions): IWord;
  findWordChange(startTime: number, endTime: number): TimedObjectsInRange<IWord>;
  findChar(time: number, options?: FindTimedObjectOptions): IChar;
  findCharChange(startTime: number, endTime: number): TimedObjectsInRange<IChar>;
}

Properties

Collections

phrases · IPhrase[]

All phrases in the video, in chronological order.

words · IWord[]

All words across all phrases, in chronological order.

chars · IChar[]

All characters across all words, in chronological order.

Timing

startTime · number · required

The start time of the video in milliseconds. Read-only.

endTime · number · required

The end time of the video in milliseconds. Read-only.

duration · number · required

The total duration of the video in milliseconds. This property is read/write — you can set it to override the computed value.

Counts

phraseCount · number

Total number of phrases in the video.

wordCount · number

Total number of words across all phrases.

charCount · number

Total number of characters across all words.

Boundary accessors

firstPhrase · IPhrase

The first phrase in the video.

lastPhrase · IPhrase

The last phrase in the video.

firstWord · IWord

The first word in the video.

lastWord · IWord

The last word in the video.

firstChar · IChar

The first character in the video.

lastChar · IChar

The last character in the video.

Methods

progress

Maps a song position to a normalized value in [0, 1] representing how far through the entire video playback has progressed.

time · number · required

Position in the song [ms].

Returns number — a value in [0, 1].

getPhrase

Returns the phrase at the given index.

index · number · required

Zero-based phrase index.

Returns IPhrase

getWord

Returns the word at the given index.

index · number · required

Zero-based word index.

Returns IWord

getChar

Returns the character at the given index.

index · number · required

Zero-based character index.

Returns IChar

findIndex

Returns the index of a given rendering unit within the video’s flat unit list.

unit · IRenderingUnit · required

The rendering unit whose index you want.

Returns number

findPhrase

Finds the phrase active at the given time.

time · number · required

Position in the song [ms].

options · FindTimedObjectOptions

Optional search options. See FindTimedObjectOptions.

Returns IPhrase | null

findPhraseChange

Looks for phrase transitions in the given time range. Useful for detecting when a phrase starts or ends.

startTime · number · required

Start of the time range [ms].

endTime · number · required

End of the time range [ms].

Returns TimedObjectsInRange<IPhrase> — see TimedObjectsInRange.

findWord

Finds the word active at the given time.

time · number · required

Position in the song [ms].

options · FindTimedObjectOptions

Optional search options.

Returns IWord | null

findWordChange

Looks for word transitions in the given time range.

startTime · number · required

Start of the time range [ms].

endTime · number · required

End of the time range [ms].

Returns TimedObjectsInRange<IWord>

findChar

Finds the character active at the given time.

time · number · required

Position in the song [ms].

options · FindTimedObjectOptions

Optional search options.

Returns IChar | null

findCharChange

Looks for character transitions in the given time range.

startTime · number · required

Start of the time range [ms].

endTime · number · required

End of the time range [ms].

Returns TimedObjectsInRange<IChar>

---

Supporting types

TimedObjectsInRange

Returned by the find*Change methods. Describes which units entered and left during a time window — ideal for driving enter/exit animations without polling.

export declare interface TimedObjectsInRange<T extends TimedObject> {
  /** The unit active at the end of the time range, or null. */
  current: T | null;
  /** Units whose startTime falls within [startTime, endTime]. */
  entered: T[];
  /** Units whose endTime falls within [startTime, endTime]. */
  left: T[];
  /** The last unit before the time range, or null. */
  previous: T | null;
  /** The first unit after the time range, or null. */
  next: T | null;
}

entered and left are arrays because multiple short units can start or end within a single render frame.

FindTimedObjectOptions

export declare type FindTimedObjectOptions =
  | { endTime?: number }   // find a unit overlapping the [time, endTime] range
  | { loose?: boolean };   // always return the nearest unit even if it does not contain `time`

• Pass { endTime } to match any unit that overlaps a time range rather than a single instant.
• Pass { loose: true } to return the nearest unit even when no unit covers the requested time.

---

IRenderingUnit — base interface

All lyrics units (IPhrase, IWord, IChar) extend IRenderingUnit.

export declare interface IRenderingUnit extends TimedObject {
  readonly parent: IRenderingUnit;
  readonly children: IRenderingUnit[];
  readonly previous: IRenderingUnit;
  readonly next: IRenderingUnit;
  readonly duration: number;
  animate: RenderingUnitFunction;
  progress(time: number): number;
  getType(): number;
  toString(): string;
}

export declare type RenderingUnitFunction = (
  now: number,
  u: IRenderingUnit
) => void;

parent · IRenderingUnit

The parent rendering unit. null for phrases (they have no parent).

children · IRenderingUnit[]

Child rendering units. For phrases this is an array of IWord; for words, IChar[]; for chars, [].

previous · IRenderingUnit

The preceding unit of the same type.

next · IRenderingUnit

The following unit of the same type.

duration · number

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

animate · RenderingUnitFunction

When set, TextAlive calls this function on every render frame instead of the default template animation. Signature: (now: number, u: IRenderingUnit) => void.

UnitTypes

getType() returns one of the constants in UnitTypes:

export declare const UnitTypes: {
  NONE: number;    // 0
  PHRASE: number;  // 1
  WORD: number;    // 2
  CHAR: number;    // 3
  GRAPHIC: number; // 4
  ALL: number;
  PUBLIC: number;
};

---

Example: full onTimeUpdate handler

This pattern handles both continuous per-character progress and discrete enter/leave transitions:

let lastPosition = 0;

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

    // Continuous: get the character currently being sung
    const currentChar = video.findChar(position);
    if (currentChar) {
      const p = currentChar.progress(position); // 0 → 1 within this char
      renderChar(currentChar.text, p);
    }

    // Discrete: detect characters that entered or left since the last frame
    const charChange = video.findCharChange(lastPosition, position);

    for (const char of charChange.entered) {
      onCharEnter(char);
    }
    for (const char of charChange.left) {
      onCharLeave(char);
    }

    lastPosition = position;
  }
});

function renderChar(text: string, progress: number) {
  // Use progress to drive opacity, scale, colour, etc.
}
function onCharEnter(char: IChar) { /* start enter animation */ }
function onCharLeave(char: IChar) { /* start exit animation */ }