1. 開発の始め方

TextAlive App API とは

TextAlive App API は、音楽に合わせてタイミングよく歌詞が動くWebアプリケーション（リリックアプリ）を開発できるJavaScript用のライブラリです。 script タグでWebサイトに読み込んだり、 npm パッケージ textalive-app-api をインストールすることで、楽曲のサビやビートなどの楽曲地図情報を取得したり、歌詞のタイミング情報を取得したりできるようになります。

このAPIを使うと、一曲のために作り込んだ演出はもちろんのこと、TextAliveに登録されているさまざまな楽曲に合わせて動作する演出をプログラミングできます。また、Songle Syncを使って周りの人と同期した演出をプログラミングすることも可能です。 さらに、このAPIを使って開発されたWebアプリケーションは、所定の登録プロセスを経ることで、 TextAlive 本サイト上で「スタイル」として選択可能になる予定です。

ぜひ、TextAlive App APIを活用して音楽と歌詞の魅力を引き出す多様なアプリケーションを開発してみてください。なお、 API の呼び出しには「開発者登録」 で入手できるアプリトークンが必要となります。 APIの更新履歴は TextAlive App APIの開発履歴 のページをご覧ください。

TextAlive App APIについて技術的に分からないことやバグ報告などがあれば、GitHub IssuesまたはGitter Chatまでお願いいたします。

開発者登録と最初の一歩

TextAlive App は、 textalive-app-api ライブラリがエクスポートしている Player クラスのインスタンスを作り、このインスタンスが配るイベントのハンドラを書いていけば開発できます。

ただし、 Player クラスのコンストラクタには 開発者登録 して入手したアプリトークンを渡す必要があります。もっともシンプルなコード例は以下のようになります。

JavaScript

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

// 単語が発声されていたら #text に表示する
const animateWord = function (now, unit) {
  if (unit.contains(now)) {
    document.querySelector("#text").textContent = unit.text;
  }
};

// TextAlive Player を作る
const player = new Player({ app: { token: "your token" } });
player.addListener({
  // 動画オブジェクトの準備が整ったとき（楽曲に関する情報を読み込み終わったとき）に呼ばれる
  onVideoReady: (v) => {
    // 定期的に呼ばれる各単語の "animate" 関数をセットする
    let w = player.video.firstWord;
    while (w) {
      w.animate = animateWord;
      w = w.next;
    }
  },
});

HTML

<span id="text"></span>

サンプルコード

CodePen や JSFiddle のような Web 上の開発環境を使うと、自分のパソコン上に環境をセットアップしなくてもすぐに TextAlive App API を試すことができます。

下に埋め込まれているのは script タグで TextAlive App API を読み込んでいる CodePen 上のサンプルコード です。サンプルコードの一覧は「サンプルコードを見る」ボタンをクリックしてください。

Debugger による動作チェックと「TextAlive ホスト」

TextAlive App の動作チェックをするには「TextAlive App Customizer」にアクセスして TextAlive App URL 欄に App の URL を入力してください。この場合、再生すべき楽曲の URL や再生状態を管理するコントロールは Debugger 側で決まります。 Debugger のように TextAlive App の状態を管理するものを「TextAlive ホスト」と呼びます。

TextAlive App は TextAlive ホストと接続されている場合、再生コントロールなどの実装をユーザ自身が書く必要はありません。

一方、ローカル開発では TextAlive App がホストと接続されていない（TextAlive の外側で動作する）ため、アプリケーションの振る舞いをテストするためには、サンプルとして読み込むメディアを指定したり、再生コントロールを用意したりといったコードが必要になります。これは、次のように書くことができます。

JavaScript

player.addListener({
  onAppReady: (app) => {
    if (!app.songUrl) {
      // URLを指定して楽曲をもとにした動画データを作成
      p.createFromSongUrl("your favorite media url here...");
    }
    if (!app.managed) {
      // 再生コントロールを表示
      showControls();
    }
  },
});

TextAlive App がホストと接続されているときには、 onAppReady 以外にも onAppMediaChange イベントなどが発火することがあります。これらのイベントの詳細については「4. App のライフサイクル」をご覧ください。