Player

Main entry point to the TextAlive App API. Loads song maps, lyrics, and timing data, and provides APIs for multimedia performance synchronized with music playback.

Player is the primary class in the TextAlive App API. It implements the IPlayer interface and serves as the single entry point for loading songs, managing playback, and querying musical data.

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

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

Constructor

new Player(options?: PlayerOptions)

options · PlayerOptions

Initialization options for the player. See PlayerOptions for the full reference.

Properties

options

readonly options: PlayerOptions

The options object passed to the constructor. See PlayerOptions.

---

app

readonly app: IPlayerApp

Current lyric app status, including connection state, host information, and parameter values provided by the TextAlive host.

---

data

readonly data: IDataLoader

Access to loaded song data: song map, lyrics text, timing information, and font loading status.

---

video

readonly video: IVideo

The current video object containing all phrase, word, and character rendering units.

---

mediaElement

mediaElement: HTMLElement  // get / set

The DOM element that hosts the audio source. You can assign a new element at any time.

---

mediaSourceElement

readonly mediaSourceElement: HTMLElement

The direct parent DOM element for the embedded audio source element.

---

mediaBannerElement

readonly mediaBannerElement: HTMLElement

The DOM element where the player attribution banner is rendered. See banner.

---

mediaPosition

readonly mediaPosition: number

Current media playback position in milliseconds. Updated periodically by the active Timer implementation.

---

videoPosition

readonly videoPosition: number

Current video rendering position in milliseconds. Updated after each successful render frame.

---

wait

wait: number  // get / set

The interval between render frames in milliseconds. Inversely related to fps.

---

fps

fps: number  // get / set

Frames per second for video rendering. Setting this also updates wait.

---

isLoading

readonly isLoading: boolean

true while song information, lyrics, or other video data is being loaded.

---

isPlaying

readonly isPlaying: boolean

true while the song is actively playing.

---

isVideoSeeking

readonly isVideoSeeking: boolean

true during an active seek operation. While seeking:

• onTimeUpdate events are suppressed.
• mediaPosition continues to update without triggering new render frames.

Use startVideoSeek and endVideoSeek to control this state when implementing a seekbar.

---

banner

readonly banner: IPlayerBanner

The banner instance that renders attribution info (TextAlive logo, song link, lyrics link) inside mediaElement.

---

timer

readonly timer: Timer

The active Timer instance managing playback state. By default, SongleTimer is used. You can provide a custom timer via PlayerOptions.timer.

---

volume

volume: number  // get / set  [0-100]

Playback volume. Accepts values from 0 (silent) to 100 (full volume).

---

Methods

addListener

Registers an event listener to receive player callbacks.

addListener(listener: PlayerListener): void

listener · PlayerListener · required

An object implementing one or more of the callback interfaces. See Player events.

---

removeListener

Removes a previously registered event listener.

removeListener(listener: PlayerListener): boolean

listener · PlayerListener · required

The listener to remove.

returns · boolean

true if the listener was found and removed; false otherwise.

---

createFromSongUrl

Loads song map, lyrics, and timing data from a song URL, then constructs a video object.

createFromSongUrl(songUrl: string, options?: PlayerVideoOptions): Promise<IVideo>

songUrl · string · required

A full song URL (e.g., a Songle or piapro URL).

options · PlayerVideoOptions

Optional overrides for video data. See PlayerVideoOptions.

returns · Promise<IVideo>

Resolves with the constructed video object.

---

createFromSongPath

Like createFromSongUrl, but accepts a path (the URL without the https:// protocol prefix).

createFromSongPath(songPath: string, options?: PlayerVideoOptions): Promise<IVideo>

songPath · string · required

A song path string (e.g., "piapro.jp/t?id=...").

options · PlayerVideoOptions

Optional overrides for video data.

returns · Promise<IVideo>

Resolves with the constructed video object.

---

createFromText

Generates a dummy song map and video object from plain text. Useful for testing without a real song.

createFromText(text: string, options?: PlayerVideoOptions): Promise<IVideo>

text · string · required

Plain text to use as lyrics.

options · PlayerVideoOptions

Optional overrides for video data.

returns · Promise<IVideo>

Resolves with the constructed video object.

---

createFromJSON

Constructs a video object directly from a VideoData JSON object.

createFromJSON(json: VideoData, options?: PlayerVideoOptions): Promise<IVideo>

json · VideoData · required

A VideoData object describing phrases and timing.

options · PlayerVideoOptions

Optional overrides for video data.

returns · Promise<IVideo>

Resolves with the constructed video object.

---

getChoruses

Returns all chorus (repetitive) segments detected in the current song.

getChoruses(): IRepetitiveSegment[]

returns · IRepetitiveSegment[]

Array of chorus segments. Returns an empty array if none are found.

---

findChorus

Finds the chorus segment that overlaps with the specified playback position.

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

time · number · required

Position in milliseconds.

options · PlayerFindOptions

Optional search parameters (e.g., endTime for range overlap, loose for nearest-match).

returns · IRepetitiveSegment | null

The matching chorus segment, or null if none is found.

---

findChorusChange

Looks for chorus segment transitions within a time range.

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

startTime · number · required

Start of the time range in milliseconds.

endTime · number · required

End of the time range in milliseconds.

returns · TimedObjectsInRange<IRepetitiveSegment>

An object with current, entered, left, previous, and next fields describing segment transitions in the range.

---

getBeats

Returns all beats in the current song.

getBeats(): IBeat[]

returns · IBeat[]

Array of beats. Returns an empty array if the song map is not loaded.

---

findBeat

Finds the beat that overlaps with the specified position.

findBeat(time: number, options?: PlayerFindOptions): IBeat

time · number · required

Position in milliseconds.

options · PlayerFindOptions

Optional search parameters.

returns · IBeat | null

The matching beat, or null if none is found.

---

findBeatChange

Looks for beat transitions within a time range.

findBeatChange(startTime: number, endTime: number): TimedObjectsInRange<IBeat>

startTime · number · required

Start of the time range in milliseconds.

endTime · number · required

End of the time range in milliseconds.

returns · TimedObjectsInRange<IBeat>

Beat transitions in the specified range.

---

getChords

Returns all chord progressions in the current song.

getChords(): IChord[]

returns · IChord[]

Array of chord objects. Returns an empty array if the song map is not loaded.

---

findChord

Finds the chord progression that overlaps with the specified position.

findChord(time: number, options?: PlayerFindOptions): IChord

time · number · required

Position in milliseconds.

options · PlayerFindOptions

Optional search parameters.

returns · IChord | null

The matching chord, or null if none is found.

---

findChordChange

Looks for chord progression transitions within a time range.

findChordChange(startTime: number, endTime: number): TimedObjectsInRange<IChord>

startTime · number · required

Start of the time range in milliseconds.

endTime · number · required

End of the time range in milliseconds.

returns · TimedObjectsInRange<IChord>

Chord transitions in the specified range.

---

getVocalAmplitude

Returns the vocal amplitude at the specified position.

getVocalAmplitude(time: number): number

You must set vocalAmplitudeEnabled: true in PlayerOptions before loading a song for this method to return data.

time · number · required

Position in milliseconds.

returns · number

Vocal amplitude at the given time. Ranges from 0 to the value returned by getMaxVocalAmplitude().

---

getMaxVocalAmplitude

Returns the maximum vocal amplitude throughout the entire song.

getMaxVocalAmplitude(): number

Requires vocalAmplitudeEnabled: true in PlayerOptions.

returns · number

Maximum vocal amplitude value in the song.

---

getValenceArousal

Returns the valence/arousal coordinates at the specified position.

getValenceArousal(time: number): ValenceArousalValue

Requires valenceArousalEnabled: true in PlayerOptions.

time · number · required

Position in milliseconds.

returns · ValenceArousalValue

An object with v (valence) and a (arousal) properties, both in the range [-1, 1].

---

getMedianValenceArousal

Returns the median valence/arousal value across the entire song.

getMedianValenceArousal(): ValenceArousalValue

Requires valenceArousalEnabled: true in PlayerOptions.

returns · ValenceArousalValue

Median valence and arousal coordinates for the song.

---

setVideoPosition

Sets the video rendering position to the specified time.

setVideoPosition(position: number): Promise<number>

position · number · required

Target video position in milliseconds.

returns · Promise<number>

Resolves with the actual position that was set.

---

requestPlay

Starts or resumes music playback.

requestPlay(): boolean

returns · boolean

true if the play request was accepted.

---

requestStop

Stops playback and seeks to the beginning.

requestStop(): boolean

returns · boolean

true if the stop request was accepted.

---

requestPause

Pauses music playback at the current position.

requestPause(): boolean

returns · boolean

true if the pause request was accepted.

---

requestMediaSeek

Seeks the media playback to the specified position.

requestMediaSeek(position: number): boolean

position · number · required

Target media position in milliseconds.

returns · boolean

true if the seek request was accepted.

---

startVideoSeek

Begins a video seek operation. Sets isVideoSeeking to true and suppresses onTimeUpdate events.

startVideoSeek(): void

---

endVideoSeek

Ends the video seek operation. Sets isVideoSeeking to false and resumes onTimeUpdate events.

endVideoSeek(): void

---

requestStageUpdate

Forces an immediate re-render of the current video frame.

requestStageUpdate(): Promise<number>

returns · Promise<number>

Resolves with the current video position in milliseconds.

---

dispose

Destroys the player instance and releases all resources.

dispose(): void

---

Deprecated methods

The following methods are deprecated and will be removed in a future version.

Method	Replacement
setMediaElement(element: HTMLElement)	Assign to player.mediaElement directly
setMediaPosition(position: number)	Use requestMediaSeek(position) instead
findChorusBetween(startTime, endTime)	Use findChorus(time, options) instead

---

Usage example

import { Player, PlayerListener, IVideo, Timer } from "textalive-app-api";

const player = new Player({
  app: { token: "your-developer-token" },
  mediaElement: document.getElementById("media"),
});

const listener: PlayerListener = {
  onAppReady(app) {
    if (!app.managed) {
      // No host connected — load a song directly
      player.createFromSongUrl("https://piapro.jp/t/hZ35/20240130103028");
    }
  },

  onVideoReady(video: IVideo) {
    console.log("Video ready. Duration:", video.duration, "ms");
  },

  onTimerReady(timer: Timer) {
    console.log("Timer ready:", timer);
  },

  onTimeUpdate(position: number) {
    // Called every render frame
    const beat = player.findBeat(position);
    if (beat) {
      const progress = beat.progress(position); // 0.0 → 1.0 within the beat
      console.log(`Beat ${beat.index}, progress: ${progress.toFixed(2)}`);
    }
  },

  onPlay() {
    console.log("Playback started");
  },

  onStop() {
    console.log("Playback stopped");
  },
};

player.addListener(listener);