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.

Pass a PlayerOptions object to the Player constructor to configure how the player initializes. 
import { Player } from "textalive-app-api";

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

​
PlayerOptions

​
app
PlayerAppOptions
Lyric app configuration. When set, the player reads the song URL from query parameters on initialization and attempts to connect to a TextAlive host.
​
timer
Timer
A custom Timer instance to manage playback state. When not specified, SongleTimer is used by default, which embeds an audio player using the Songle API.Provide BasicTimer here for debugging without audio playback:
import { Player, BasicTimer } from "textalive-app-api";

const player = new Player({
  app: { token: "your-token" },
  timer: new BasicTimer(),
});
​
mediaElement
HTMLElement | string
The host element for the embedded audio player and banner. Accepts a DOM element or a CSS selector string. When not set, the player creates its own container element.
​
mediaBannerPosition
PlayerBannerPosition
Controls where the attribution banner appears relative to mediaElement. Defaults to "embed" (directly below the audio element).
​
throttleInterval
number
Interval in milliseconds for throttled time-update events. Controls how often onThrottledTimeUpdate fires when the song is playing.
​
lyricsFetchTimeout
number
Timeout in milliseconds for fetching lyrics text. Set to 0 (or omit) to disable the timeout and wait indefinitely.
​
fontFamilies
(FontInfo | string)[]
List of font families to preload. Each entry can be a font family name string or a FontInfo object.When set to null, all available TextAlive fonts are loaded. When omitted, no fonts are preloaded.
​
vocalAmplitudeEnabled
boolean
Set to true to load vocal amplitude data when a song is loaded. Required before calling getVocalAmplitude() or getMaxVocalAmplitude().
​
valenceArousalEnabled
boolean
Set to true to load valence/arousal data when a song is loaded. Required before calling getValenceArousal() or getMedianValenceArousal().

​
PlayerVideoOptions

Passed as the second argument to createFromSongUrl, createFromSongPath, createFromText, and createFromJSON. Use it to override the default TextAlive video data for a song.
​
video
PartialVideoEntry
Overrides for the video entry loaded from TextAlive. Use specific revision IDs to pin a song map or lyrics version.
​
altLyricsUrl
string
URL of an alternative source for lyrics text. Overrides the default lyrics URL associated with the song in TextAlive.

​
Complete example

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

const player = new Player({
  // Lyric app registration
  app: {
    token: "your-developer-token",
    parameters: [
      {
        name: "colorScheme",
        title: { en: "Color scheme", ja: "カラーテーマ" },
        className: "Slider",
        params: [0, 5],
        initialValue: 0,
      },
    ],
  },

  // Embed audio in a specific container
  mediaElement: document.getElementById("media-container"),

  // Place attribution banner at the bottom right
  mediaBannerPosition: "bottom right",

  // Throttle time-update events to at most once per 100 ms
  throttleInterval: 100,

  // Time out if lyrics don't load within 10 seconds
  lyricsFetchTimeout: 10000,

  // Pre-load two font families
  fontFamilies: ["Noto Sans JP", "M PLUS Rounded 1c"],

  // Enable audio feature data
  vocalAmplitudeEnabled: true,
  valenceArousalEnabled: true,
});

// Load a specific song with pinned revision IDs
player.createFromSongUrl("https://piapro.jp/t/hZ35/20240130103028", {
  video: {
    beatId: 3953,
    chordId: 2727,
    repetitiveSegmentId: 2946,
    lyricId: 59415,
    lyricDiffId: 13962,
  },
});