telop lab / usage

AIエージェントからの使い方

テロップラボは「URLを渡すだけ」で使える設計です。MCP対応クライアントなら1行、未対応でも telops.json と overlay.html のURLを渡せば同等のことができます。

0. MCPサーバー（いちばん簡単）

MCP対応クライアントにこのURLを登録するだけで、スタイル検索・詳細取得・overlay URL生成のツールが使えます:

https://telop-lab.com/mcp

# tools: search_telops / get_telop / list_categories / build_overlay_url

Claude Desktop・Devin・Cursor等のMCP設定に "telop-lab": {"url": "https://telop-lab.com/mcp"} を追加。認証なし・読み取り専用です。

エージェントへの指示例

「MCP https://telop-lab.com/mcp を使って、動画の雰囲気に合うテロップを選んで、
 build_overlay_url で overlay URLを作り、PNG化して ffmpegで焼き込んで」

1. MCP未対応の場合: JSONを直接読ませる

telops.json（全200スタイルの機械可読な定義）も公開しています。

GET /telops.json  →  { fonts, styles: [{ id, name, cat, font, fill, stroke, layout, pos, anim, sample, use, tags }] }

「https://telop-lab.com/telops.json から動画の雰囲気に合うテロップを選んで、
 overlay.html を使って字幕PNGを作り、ffmpegで焼き込んで」

llms.txt に同じ手順をエージェント向けに記述してあります。

2. プレビュー / PNGレンダリング（overlay.html）

overlay.html?id=va-white-black&text=まじで!?&pos=bottom

# id:    スタイルID
# text:  表示文（|で囲むとアクセント色 / \nで改行）
# pos:   top | center | bottom
# kp:    karaokeの塗りつぶし進行度 0..1
# tag:   letterboxレイアウトのタグ文字
# anim:  スタイルのアニメ種別を上書き
# animate=1 & frozen=1: 決定論的フレームキャプチャモード
#   （window.__ready / __animDur / __animLoop / __seek(t) を公開）

ブラウザでそのまま開けばプレビュー。Playwright等で1080×1920のビューポートに描画→透過PNGとしてスクリーンショットすれば素材完成です。

3. 動画への焼き込み（apply.mjs）

# 単発
node apply.mjs input.mp4 --style va-white-black --text "まじで!?" --start 0.5 --end 3 -o out.mp4

# 複数キャプション
node apply.mjs input.mp4 --captions caps.json -o out.mp4
# caps.json: [{"style":"kr-clip-double","text":"絶対楽しい","start":0,"end":2.4}, ...]

# アニメを静止画にしたいとき
node apply.mjs input.mp4 --captions caps.json --no-anim -o out.mp4

内部では overlay.html を Playwright でレンダリング → 静止スタイルは透過PNG1枚、アニメスタイルはPNG連番（30fps）にして ffmpeg の overlay で合成します。フォントは全てGoogle Fonts（OFL）なので商用・OSS配布OK。

注意: テロップは動画に焼き込まれたピクセルです。完成後の動画から文字だけを差し替えることはできません。 Premiere Proなどの編集ソフトに読み込んでも、テキストレイヤーとしては編集できない点に注意してください。文字を変える場合は caps.json を書き換えて再生成してください — 元動画と caps.json を残しておけばやり直しは1コマンドです。エージェントに修正を依頼するときも「元動画＋caps.json」を渡せば同じ状態から再編集できます。テキストの見た目だけ先に確かめたい場合は overlay URLをブラウザで開くだけで済みます（動画不要）。

ライセンス

本カタログは MIT License で公開しています。スタイル定義・レンダラともに商用利用・改変・再配布が可能です。

フォントはすべて Google Fonts のオープンフォント（主に SIL Open Font License）を使用しているため、生成した字幕画像・動画もそのまま商用利用できます。各フォントのライセンスは Google Fonts のページを参照してください。