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.

The Timer interface defines the contract between the Player and an audio backend. The Player calls Timer methods to control playback and reads position to drive time-synchronized rendering. You can pass any Timer implementation to PlayerOptions.timer when constructing a Player.

​
Default timer behavior

When you do not specify a timer in PlayerOptions, the Player selects a timer automatically:
  • If songle-api is available, a SongleTimer-based timer is used (audio playback via Songle).
  • Otherwise, a basic HTML5 audio timer is used.

​
Timer interface

​
Properties

​
isPlaying
boolean
Read-only. true while the audio source is actively playing.
​
position
number
Read-only. The current playback position in milliseconds. Timer implementations must calculate this value in real time. This is the most precise position value available — more accurate than IPlayer.mediaPosition or IPlayer.videoPosition.
​
wait
number
Get or set the interval between position updates in milliseconds.

​
Methods

​
initialize
(options: TimerInitOptions) => Promise<void>
Called once during the video data loading process. Sets up the audio backend and connects it to the Player.
​
play
() => void
Starts music playback.
​
pause
() => void
Pauses music playback.
​
stop
() => void
Stops music playback — pauses and seeks back to the beginning.
​
seek
(position: number) => void
Seeks to the specified position in milliseconds.
​
dispose
() => void
Releases resources held by this Timer instance.

​
TimerInitOptions

Passed to Timer.initialize when a song is loaded.
​
player
IPlayer
The Player instance that owns this timer.
​
updater
PlayerMediaPositionUpdateFunction
A callback the timer calls periodically to update the player’s media position. The function receives the current position (ms) and returns a Promise<number> resolving to the accepted position.
​
emitter
PlayerEventListener
An event emitter the timer uses to trigger onTimeUpdate and related player events.

​
PlayerMediaPositionUpdateFunction

type PlayerMediaPositionUpdateFunction = (position: number) => Promise<number>;
A callback used by Timer implementations to report the current playback position to the Player. The Player may adjust the position and resolves the promise with the accepted value.

​
BasicTimer

BasicTimer is the built-in Timer implementation included in the SDK. It advances a clock without embedding any audio element, so no sound is played.
BasicTimer is ideal for development and debugging. You can verify that lyrics and animations advance correctly without needing an audio source or network access.

​
Constructor

new BasicTimer()
BasicTimer requires no constructor arguments and implements the full Timer interface.

​
Usage

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

const player = new Player({
  app: { token: "your-app-token" },
  timer: new BasicTimer()
});
// No audio will play, but lyrics will advance with simulated time
If you need to integrate a non-standard audio backend — such as the Web Audio API, a streaming source, or a native audio player — implement the Timer interface and pass your instance to PlayerOptions.timer. Your implementation must update position in real time and call updater periodically with the current position.

​
SongleTimer

SongleTimer is the full-featured timer implementation that embeds a Songle audio player. It is the default timer used when you do not pass timer in PlayerOptions. SongleTimer relies on the optional peer dependency songle-api. If not installed, the timer loads it automatically via dynamic import() or <script> tag injection. 
import { Player, SongleTimer } from "textalive-app-api";

const player = new Player({
  app: { token: "your-app-token" },
  timer: new SongleTimer(),
  mediaElement: document.querySelector("#media"),
});

​
Constructor

new SongleTimer(options?: SongleTimerOptions)

​
Properties

​
isPlaying
boolean
Read-only. true while Songle audio is actively playing.
​
position
number
Read-only. Current playback position in milliseconds, calculated in real time.
​
wait
number
Get or set the update interval in milliseconds.
​
songlePlayer
SonglePlayer
Read-only. The underlying Songle Player instance. Accessible after onTimerReady fires. Use this for Songle-specific APIs.
​
withSync
boolean
Read-only. true if Songle Sync is enabled (i.e., accessToken and secretToken were provided in SongleTimerOptions).

​
SongleTimerOptions

Options for instantiating a SongleTimer.
​
headless
boolean
When true, the timer operates without embedding an audio element — no sound plays. Useful for server-side or test environments.
​
accessToken
string
Songle Sync access token. Enables real-time multi-client playback synchronization via Songle Sync.
​
secretToken
string
Songle Sync secret token. Required alongside accessToken for Songle Sync.
​
songle
Songle
A pre-initialized Songle API instance (the object returned by import Songle from "songle-api"). When not provided, the timer initializes Songle automatically.

​
Songle Sync example

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

const player = new Player({
  app: { token: "your-app-token" },
  timer: new SongleTimer({
    accessToken: "your-songle-sync-access-token",
    secretToken: "your-songle-sync-secret-token",
  }),
  mediaElement: document.querySelector("#media"),
});

Build docs developers (and LLMs) love

Get started for freeTalk to us