Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TextAliveJp/textalive-app-api/llms.txt

Use this file to discover all available pages before exploring further.

This page documents the utility functions and supporting classes exported by the TextAlive App API SDK.

findTimedObject

function findTimedObject<T extends TimedObject>(
  objects: T[],
  time: number,
  options?: FindTimedObjectOptions
): T
Binary-searches a sorted array of timed objects and returns the one that contains the given time. Returns undefined if no object contains the specified time (unless loose is set).
objects
T[]
A sorted array of TimedObject instances.
time
number
The target time in milliseconds.
options
FindTimedObjectOptions
Optional search modifiers. See FindTimedObjectOptions.

findTimedObjectsInRange

function findTimedObjectsInRange<T extends TimedObject>(
  sortedArray: T[],
  startTime: number,
  endTime: number
): TimedObjectsInRange<T>
Returns all timed objects that started or ended within the time range [startTime, endTime]. Use this in onTimeUpdate to detect transitions — for example, characters that began or finished vocalization during the last frame.
sortedArray
T[]
A sorted array of TimedObject instances.
startTime
number
Start of the query range in milliseconds.
endTime
number
End of the query range in milliseconds.

Data URL utilities

dataUrlToString

function dataUrlToString(url: string): string
Decodes a data URL that encodes a UTF-8 string in Base64 format and returns the original string.
url
string
A Base64-encoded data URL.

stringToDataUrl

function stringToDataUrl(text: string): string
Encodes a UTF-8 string in Base64 format and returns it as a data URL (the inverse of dataUrlToString).
text
string
The UTF-8 string to encode.

isStringEncodedDataUrl

function isStringEncodedDataUrl(url: string): boolean
Returns true if the given string is a Base64-encoded data URL that encodes a UTF-8 string.
url
string
The string to test.

Supporting types

TimedObject

The base interface for all time-ranged objects in the API.
startTime
number
Start of the time range in milliseconds.
endTime
number
End of the time range in milliseconds.
contains(time)
(time: number) => boolean
Returns true if the time range contains the given time (start and end inclusive).
overlaps(obj)
(obj: TimedObject) => boolean
Returns true if another TimedObject’s range overlaps this range.

TimedUnit

TimedUnit is an abstract base class you can extend to create custom timed objects compatible with the findTimedObject and findTimedObjectsInRange APIs.
abstract class TimedUnit implements TimedObject {
  abstract startTime: number;
  abstract endTime: number;
  get duration(): number;
  contains(time: number): boolean;
  overlaps(objOrStartTime: TimedObject | number, endTime?: number): boolean;
  progress(time: number): number;
}
Extend TimedUnit and provide startTime and endTime to gain duration, contains, overlaps, and progress for free:
import { TimedUnit } from "textalive-app-api";

class MyEvent extends TimedUnit {
  constructor(public startTime: number, public endTime: number) {
    super();
  }
}

const event = new MyEvent(1000, 2000);
console.log(event.duration);          // 1000
console.log(event.contains(1500));    // true
console.log(event.progress(1500));    // 0.5

ValenceArousalValue

The return type of player.getValenceArousal() and player.getMedianValenceArousal(). Both values are normalized to the range [-1, 1] and are comparable across songs (not relative to a single song).
v
number
Valence — the positivity/negativity of the music’s emotional content. Ranges from -1 (negative) to 1 (positive).
a
number
Arousal — the energy/excitement level of the music. Ranges from -1 (calm) to 1 (excited).
// Requires valenceArousalEnabled: true in PlayerOptions
const va = player.getValenceArousal(position);
console.log(`Valence: ${va.v.toFixed(2)}, Arousal: ${va.a.toFixed(2)}`);
You must set valenceArousalEnabled: true in PlayerOptions before loading a song for valence/arousal data to be available.

UnitTypes

A constant object containing the numeric type codes returned by IRenderingUnit.getType().
const UnitTypes: {
  NONE: number;     // 0
  PHRASE: number;   // 1
  WORD: number;     // 2
  CHAR: number;     // 3
  GRAPHIC: number;  // 4
  ALL: number;      // bitmask for all types
  PUBLIC: number;   // bitmask for public types (phrase + word + char)
}
Use UnitTypes to check the type of any rendering unit:
import { UnitTypes } from "textalive-app-api";

player.addListener({
  onTimeUpdate(position) {
    const unit = player.video?.findChar(position);
    if (unit && unit.getType() === UnitTypes.CHAR) {
      // handle character
    }
  }
});

FindTimedObjectOptions

Controls the behavior of findTimedObject. Provide one of the following shapes:
endTime
number (optional)
When set, findTimedObject returns an object that overlaps the range [time, endTime] rather than a single point in time.
loose
boolean (optional)
When true, the nearest result from the binary search is always returned, even if the specified time is not contained within the object’s range.

TimedObjectsInRange<T>

The return type of findTimedObjectsInRange and the findXxxChange methods on IPlayer and IVideo.
current
T | null
The timed object that overlaps with the end time of the queried range, or null.
entered
T[]
Objects whose startTime falls within the queried range.
left
T[]
Objects whose endTime falls within the queried range.
previous
T | null
The last timed object that ends before the queried range, or null.
next
T | null
The first timed object that starts after the queried range, or null.

DecomposedProps

The result of decomposing a Matrix2D into its component transform values.
x
number (optional)
Horizontal translation.
y
number (optional)
Vertical translation.
scaleX
number (optional)
Horizontal scale factor.
scaleY
number (optional)
Vertical scale factor.
skewX
number (optional)
Horizontal skew in degrees.
skewY
number (optional)
Vertical skew in degrees.
rotation
number (optional)
Rotation in degrees.

Matrix2D

Matrix2D represents a 3x3 affine transformation matrix in the form:
[ a  c  tx
  b  d  ty
  0  0  1  ]
All mutating methods return this, making them chainable.

Constructor

new Matrix2D(a?: number, b?: number, c?: number, d?: number, tx?: number, ty?: number)

Static members

Matrix2D.identity
Matrix2D
A shared identity matrix representing a null transformation. Do not mutate this instance.
Matrix2D.DEG_TO_RAD
number
Multiplier for converting degrees to radians (Math.PI / 180).

Instance properties

a
number
Position (0, 0) in the matrix.
b
number
Position (0, 1) in the matrix.
c
number
Position (1, 0) in the matrix.
d
number
Position (1, 1) in the matrix.
tx
number
Horizontal translation (position (2, 0)).
ty
number
Vertical translation (position (2, 1)).

Methods

setValues
(a?, b?, c?, d?, tx?, ty?) => Matrix2D
Sets all matrix values at once. Returns this.
append
(a, b, c, d, tx, ty) => Matrix2D
Appends raw matrix properties: equivalent to this * specified. Returns this.
prepend
(a, b, c, d, tx, ty) => Matrix2D
Prepends raw matrix properties: equivalent to specified * this. Returns this.
appendMatrix
(matrix: Matrix2D) => Matrix2D
Appends another Matrix2D: equivalent to this * matrix. Returns this.
prependMatrix
(matrix: Matrix2D) => Matrix2D
Prepends another Matrix2D: equivalent to matrix * this. Returns this.
appendTransform
(x, y, scaleX, scaleY, rotation, skewX, skewY, regX?, regY?) => Matrix2D
Generates matrix values from display-object transform properties and appends them to this matrix. Returns this.
rotate
(angle: number) => Matrix2D
Applies a clockwise rotation. angle is in degrees; multiply by Matrix2D.DEG_TO_RAD to use radians. Returns this.
scale
(x: number, y: number) => Matrix2D
Applies a scale transformation. Returns this.
translate
(x: number, y: number) => Matrix2D
Translates the matrix on the x and y axes. Returns this.
skew
(skewX: number, skewY: number) => Matrix2D
Applies a skew transformation. Both arguments are in degrees. Returns this.
identity
() => Matrix2D
Resets the matrix to the identity transformation. Returns this.
invert
() => Matrix2D
Inverts the matrix so it performs the opposite transformation. Returns this.
isIdentity
() => boolean
Returns true if this is an identity matrix.
equals
(matrix: Matrix2D) => boolean
Returns true if all property values equal those of matrix.
decompose
(target?: DecomposedProps) => DecomposedProps
Decomposes the matrix into x, y, scaleX, scaleY, skewX, skewY, and rotation. If target is provided, properties are written to it; otherwise a new object is returned.
transformPoint
(x: number, y: number, pt?: IPoint) => IPoint
Transforms a point according to this matrix. If pt is provided, the result is written into it; otherwise a new object is returned.
clone
() => Matrix2D
Returns a new Matrix2D with the same values.
copy
(matrix: Matrix2D) => Matrix2D
Copies all properties from matrix into this instance. Returns this.
toString
() => string
Returns a string representation of this matrix.

Point

Point represents a coordinate on a 2D x/y plane.

Constructor

new Point(x?: number, y?: number)

Properties

x
number
The x coordinate.
y
number
The y coordinate.

Methods

setValues
(x?: number, y?: number) => Point
Sets x and y. Returns this.
clone
() => Point
Returns a new Point with the same coordinates.
copy
(point: Point) => Point
Copies coordinates from point into this instance. Returns this.
toString
() => string
Returns a string representation of this point.

Other exports

PlayerLogoImage

const PlayerLogoImage: string
SVG markup string for the TextAlive logo. The SVG uses two CSS classes you can target for theming:
  • .bg — background fill (default: #1f4391)
  • .fg — foreground fill (default: #fff)

RegionalText

type RegionalText = { [lang: string]: string };
A multi-language string type used for human-readable labels in the TextAlive UI (for example, parameter titles). Use the "ja" key for Japanese and the "en" key for English.
const title: RegionalText = {
  en: "Speed",
  ja: "速度",
};

Build docs developers (and LLMs) love