TextAlive Template API

テンプレートの基本

文字の動きを定めたテンプレートは、JavaScriptのクラス(関数)として記述します。必ず function テンプレート名() { … } という形になっている必要があり、トップレベルに二つ function 文があったりするとエラーが表示されます。

最もシンプルな実装としては、例えば、発声が終わった文字を灰色に、今発声されている文字を赤色にするKaraokeColorがあります。

実行時のコンテキストでは、以下の定数が定義されています。なお、 width と height は実際の動画プレイヤーのサイズとは異なります。このサイズのキャンバスの上にいろいろなものが配置され、それが実際の動画プレイヤーのサイズに拡大・縮小されて表示されるイメージです。したがって、 width はほとんどの場合に変わらず 1280 です。 height は外部ウェブサイト貼り付け時などに動画プレイヤーの縦横比が変わるため、それに応じて 720 以外の値も取ります。

width	歌詞アニメーション解像度の幅 (通常は1280)
height	歌詞アニメーション解像度の高さ (通常は720)

プロパティを宣言する this.primaryColor = new Color('#ff0000') のような行の前に @ui で始まる特別なコメントを書くことで、テンプレートの内容をプログラマでない人でも調整できる直感的なユーザインタフェースを表示させることができます。この機能の詳細についてはコードエディタのページをご覧ください。

テンプレートの編集

動画のタイムラインで適当なレンダリングユニット（フレーズ、単語、文字、グラフィック）を選択、編集パネルでテンプレートを選んで「プログラミング」ボタンをクリックするとコードエディタが表示され、テンプレートの実装を編集できます。

コードエディタの詳しい使い方はコードエディタのページをご覧ください。

必須プロパティとメソッド

すべてのテンプレートは次のプロパティを持つ必要があります。

name : 名前（文字列）
type : 種類（数値、以下の定数の合計）
- PUBLIC : このテンプレートが他のテンプレートから呼ばれる（requireで参照される）ことを許す
- PHRASE : このテンプレートはフレーズに対して適用できる
- WORD : このテンプレートは単語に対して適用できる
- CHAR : このテンプレートは文字に対して適用できる
- GRAPHIC : このテンプレートはグラフィックに対して適用できる
- ALL : このテンプレートはすべての種類の文字ユニットに対して適用できる（CHAR+WORD+PHRASE）
  また、すべてのテンプレートは次のメソッドを実装する必要があります。
animate(now) : 時刻nowにおける文字ユニットの動きを定義する

2015/9/17追記; テンプレートは、通常、割り当てられたレンダリングユニット（フレーズ、単語、文字、グラフィック）の発声区間および前後 500ms のみ animate(now) が呼び出され、画面に表示することができます。ただし、演出によってはこれよりも長い時間表示させたい場合もあるでしょう。そんなときは、以下のプロパティを宣言してください。

headTime : 指定された長さだけ発声区間より前にも表示される (number)
tailTime : 指定された長さだけ発声区間より後にも表示される (number)

例えば this.headTime = 1000 とすると、発声区間より1秒前から animate(now) が呼び出されるので、発声区間より1秒前からフェードインするようなテンプレートを作ることができます。具体例はRotateAndZoomWithBackgroundなどを見てみてください。

さらに、以下のプロパティを指定すると発声区間に関わらず動画再生中ずっと animate(now) が呼び出されるようになりますが、動画再生が重くなるので利用は極力避けるようにしましょう。具体例はTileを見てみてください。

insomnia : trueならanimate(now)が毎フレーム呼ばれる (boolean)

プロパティとローカル変数

プロパティ（this.hoge）は、テンプレートの調整結果を保持するため、また、他のテンプレートからも呼び出し可能なメソッドを定義するために使われます。テンプレートの調整結果は動画のデータとして保存され、動画を読み込むときに復元されます。

テンプレートの状態（例えば計算の途中結果や初期化フラグ）を管理するためにはローカル変数（var hoge）を使ってください。ここでプロパティを使ってしまうと、計算の途中結果や初期化フラグなどが動画のデータとして保存されてしまいます。動画を読み込むときに内容が復元されるので、意図しない動作を引き起こすことがあります。

特別な関数

print(内容を確認したいオブジェクト)

オブジェクトの文字表現をブラウザのコンソールに出力します。このメソッドに限らず、インタプリタは問題発生時にコンソールへメッセージを出力することがあるので、テンプレートの開発中はコンソールを開いておくことをおすすめします。

findBeat(時刻)

指定した時刻のビート情報(Beat)を取得します。ビート情報がない場合はnullが返ります。

findChorus(時刻)

指定した時刻のサビ情報(Segment)を取得します。サビでなければnullが返ります。

イージング関数

TweenJSのイージング関数をサポートしています。以下の関数があります。

linear
…

require(“テンプレート名”)

テンプレートは、他のテンプレートを自身の中でインスタンス化して、そのメソッドを呼ぶことができます。これにより、同じようなエフェクトのコードを何度も書かずに済みます。

例えば、DefaultAlignmentテンプレートは内部でDrawCircleとKaraokeColorを使っています。

テンプレートの依存関係が循環するようなコードは無限ループになるのでご注意ください。例えば次のような2つのテンプレートは定義したとたんに無限ループになり、処理が重すぎると判断されて動きません。（この例に限らず、テンプレートのインスタンス化やanimateの処理に時間がかかりすぎると、TextAliveはそのテンプレートを一時的に利用不可にします。）

function TemplateA {
  var b = require('TemplateB');
  this.animate = function(now) { /* 略 */ }
}
function TemplateB {
  var a = require('TemplateA');
  this.animate = function(now) { /* 略 */ }
}

RenderingUnit

レンダリングユニット（文字ユニット＝フレーズ、単語、文字のいずれか、またはグラフィック）を表すクラスです。各テンプレート内で this.getAssignedUnit() を呼ぶことでインスタンスを取得できます。以下のプロパティを持っています。

startTime : 発声開始タイミング [ms] (number)
endTime : 発声終了タイミング [ms] (number)
duration : endTime – startTime [ms] (number)
rendering : レンダリングオプション (RenderingParameter)
graphics : EaselJSレンダリングコンテキスト (Graphics)
previous : 前のレンダリングユニット 最初のレンダリングユニットではnull (TextUnit)
next : 次のレンダリングユニット 最後のレンダリングユニットではnull (TextUnit)

また、以下のメソッドを持っています。

getType() : レンダリングユニットの種類を以下の定数のいずれかの値で返す (number)
- PHRASE : フレーズ
- WORD : 単語
- CHAR : 文字
- GRAPHIC : グラフィック

さらに、文字ユニットの場合は次の項目で説明するプロパティも持っています。（グラフィックの場合はいずれもundefinedのプロパティです。）

TextUnit

レンダリングユニットの子クラスで、文字ユニットを表します。以下のプロパティを持っています。

text : 表示対象となる文字 (string)
parent : 親の文字ユニット フレーズとグラフィックではnull (TextUnit)
children : 子要素の文字ユニット 文字ではnull (TextUnit[])
advance : 文字ユニットを横に隙間なく並べたときの幅 [px] (number)
ascent : 文字ユニットのアセント [px] (number)
descent : 文字ユニットのディセント [px] (number)
height : 文字ユニットの高さ=アセント+ディセント [px] (number)
color : 文字ユニットの描画色 (Color)
firstChar, lastChar : 最初と最後の文字 文字ではundefined (TextUnit)
charCount : 含まれる文字数 (number) 文字ではundefined
firstWord, lastWord : 最初と最後の単語 単語、文字ではundefined (TextUnit)
wordCount : 含まれる単語数 単語、文字ではundefined (number)

RenderingParameter

各文字のレンダリング方法を決めるパラメタを表すクラスです。文字ユニットの rendering プロパティはこのインスタンスです。以下のプロパティを持っています。

visible : 描画するか否か、falseなら他のプロパティに依らず子要素も含め何も描かない (boolean)
alpha : 透過値、0なら透明～1なら不透明 [0-1] (number)
composite : HTML Standard 4.12.4.2.17 Compositingで定義されているComposite Operation (string)
tx : 2次元の変形行列(3行3列) (Matrix2D)

Color

色を表すクラスです。文字ユニットの color プロパティはこのインスタンスです。コンストラクタには new Color("#11ff0000") のように16進数で8bitずつARGB（0が透明、0xffが不透明とした場合の透過値、赤、緑、青）を表したカラーコードを渡します。以下のプロパティとメソッドを持ちます。

value : 0xff0000 のような、色の32bit数値表現 (number)
rgb : rgb(255,0,0) のような、色の文字列表現 (string)
rgba : rgba(255,0,0,0.66) のような、透明度を含めた色の文字列表現 (string)
r, g, b : 赤、緑、青の8bit値 (number)
eq(color) : 二つの色が同じものか比較する (boolean)

Beat

ビート情報を表すクラスです。findBeat関数で取得できます。

startTime : ビートの始まりの時刻 (number)
length : ビートの数 (例えば4つ打ちなら4, number)
position : ビートの位置 (例えば4つ打ちなら1～4, number)
previous : 前のビートの情報 (Beat)
next : 次のビートの情報 (Beat)
index : 楽曲全体で見たときのビートの位置 (number)
contains(time) : 指定した時刻がこのビートから次のビートまでの間に収まっているか返す (boolean)
progress(time) : 指定した時刻がこのビートから次のビートまでの間に収まっていれば [0-1] で進捗を返すが、それ以外は-1 (number)

Segment

サビ部分の情報を表すクラスです。findChorus関数で取得できます。

startTime : サビの始まりの時刻 (number)
endTime : サビの終わりの時刻 (number)
previous : 前のサビの情報 (Segment)
next : 次のサビの情報 (Segment)
index : 楽曲全体で見たときのサビの位置 (number)
contains(time) : 指定した時刻がこのサビに含まれているか返す (boolean)
progress(time) : 指定した時刻がこのサビに含まれていれば [0-1] で進捗を返すが、それ以外は-1 (number)
overlaps(startTime, endTime) : 指定した範囲がサビと重なっているか返す (boolean)