サンプルを選ぶ
PNGTuber 2D / 最速で試せる
2D PNG 差し替え方式のアバター。画像がなくても SVG フォールバックで起動するため、LLM プロバイダの API キーさえあれば最短で動きます。初めての方におすすめ。
AITuber 配信環境のテンプレート「react-pngtuber-app」（2D PNG 差し替えアバター方式のサンプル）を、このマシンに構築してください。
## ゴール
`https://github.com/shinshin86/aituber-onair` をローカルに clone し、`packages/core/examples/react-pngtuber-app` の開発サーバを起動して、ブラウザで `http://localhost:5173` にアクセスできる状態にする。
## 前提条件
- Node.js（LTS 推奨）と npm が使えること
- git が使えること
- ブラウザは Chrome または Edge を想定（Web Speech API を使うため）
不足しているものがあれば、そこで止まってユーザーに知らせてください。
## 実行手順
1. 現在の作業ディレクトリに `aituber-onair/` が無ければ clone してください。
git clone https://github.com/shinshin86/aituber-onair.git
既に存在する場合は再利用して構いません。
2. サンプルアプリのディレクトリに移動してください。
cd aituber-onair/packages/core/examples/react-pngtuber-app
3. 依存をインストールしてください。
npm install
4. 開発サーバを起動してください。
npm run dev
このコマンドはフォアグラウンドで動き続けます。あなたのツールでバックグラウンド実行ができるならそれで構いません。できない場合は「別ターミナルでこのコマンドを実行してください」とユーザーに案内してください。
5. ユーザーにブラウザで `http://localhost:5173` を開くよう伝えてください。
## ユーザーに任せる作業（あなたが勝手にやらないこと）
以下は API キーや手元の素材が必要なので、ユーザー自身に行ってもらってください。手順だけ案内すれば OK です。
- 使いたい LLM プロバイダの API キーを取得する（OpenAI / Gemini / Claude / OpenRouter / xAI / zAI / Kimi のいずれか1つ）
- ブラウザで画面右上の「Settings」を開き、選んだプロバイダの API キーを貼り付け、モデルを選択する
- 設定は `localStorage`（キー: `react-pngtuber-app-settings`）に保存される
- （任意）アバター画像を `public/avatar/` に配置する:
- mouth_close_eyes_open.png
- mouth_close_eyes_close.png
- mouth_open_eyes_open.png
- mouth_open_eyes_close.png
- 未配置でも SVG のフォールバックアバターで動作する
## 参考ドキュメント（詳細が必要なときに参照）
- サンプル README: https://github.com/shinshin86/aituber-onair/blob/main/packages/core/examples/react-pngtuber-app/README.md
- 3種類のアバター方式をまとめたセットアップガイド（日本語、AIエージェント向け詳細資料）: https://start-aituber-with-ai-agent.aituberonair.com/docs/setup-guide
## 注意事項（ユーザーに必ず伝えること）
- このサンプルは開発者向けです。API キー類はブラウザの `localStorage` に平文で保存されます。本番権限のクレデンシャルは入れず、共有・公開オリジンにそのままデプロイしないでください。
- 共有端末で使った場合は、使用後に API キーをローテーションすることを推奨します。
最初のつまずきポイント：起動後、Settings で API キーを設定しないと LLM は応答しません。動作確認だけしたい場合は無料で始めやすい openrouter の Fetch free models か、ローカル実行の gemini-nano（Chrome 138+）がおすすめです。
VRM 3D / VRM アバター
3D VRM アバター方式。VRM 表情にリアルタイムの口パクが乗り、カメラ操作（ドラッグで回転 / ホイールでズーム）にも対応します。起動には miko.vrm（または任意の VRM）を用意する必要があります。
AITuber 配信環境のテンプレート「react-vrm-app」（3D VRM アバター方式のサンプル）を、このマシンに構築してください。
## ゴール
`https://github.com/shinshin86/aituber-onair` をローカルに clone し、`packages/core/examples/react-vrm-app` の開発サーバを起動して、ブラウザで `http://localhost:5173` にアクセスできる状態にする。
## 前提条件
- Node.js（LTS 推奨）と npm が使えること
- git が使えること
- ブラウザは Chrome または Edge を想定（Web Speech API を使うため）
不足しているものがあれば、そこで止まってユーザーに知らせてください。
## 実行手順
1. 現在の作業ディレクトリに `aituber-onair/` が無ければ clone してください。
git clone https://github.com/shinshin86/aituber-onair.git
既に存在する場合は再利用して構いません。
2. サンプルアプリのディレクトリに移動してください。
cd aituber-onair/packages/core/examples/react-vrm-app
3. 依存をインストールしてください。
npm install
4. 開発サーバを起動してください。
npm run dev
このコマンドはフォアグラウンドで動き続けます。あなたのツールでバックグラウンド実行ができるならそれで構いません。できない場合は「別ターミナルでこのコマンドを実行してください」とユーザーに案内してください。
5. ユーザーにブラウザで `http://localhost:5173` を開くよう伝えてください。
## ユーザーに任せる作業（あなたが勝手にやらないこと）
以下は API キーや外部素材（VRM モデル）が必要なので、ユーザー自身に行ってもらってください。手順だけ案内すれば OK です。
- 使いたい LLM プロバイダの API キーを取得する（OpenAI / Gemini / Claude / OpenRouter / xAI / zAI / Kimi のいずれか1つ）
- ブラウザで画面右上の「Settings」を開き、選んだプロバイダの API キーを貼り付け、モデルを選択する
- 設定は `localStorage`（キー: `react-vrm-app-settings`）に保存される
- VRM モデルを配置する（必須）:
- 推奨は `miko.vrm` を https://miko.aituberonair.com/ からダウンロードして、`packages/core/examples/react-vrm-app/public/avatar/miko.vrm` に配置
- 配置しない場合、アバターステージに読み込みエラーが表示されます（開発サーバ自体は起動します）
- （任意）待機アニメーション `idle_loop.vrma` を `public/avatar/idle_loop.vrma` に配置
- pixiv/ChatVRM（https://github.com/pixiv/ChatVRM）の資産が流用できます
- 配置しない場合はアニメーションだけスキップされ、他の機能は動作します
- （任意）背景画像は Settings からアップロード可能（メモリ保持のみ、リロードで初期化）
## 参考ドキュメント（詳細が必要なときに参照）
- サンプル README: https://github.com/shinshin86/aituber-onair/blob/main/packages/core/examples/react-vrm-app/README.md
- 3種類のアバター方式をまとめたセットアップガイド（日本語、AIエージェント向け詳細資料）: https://start-aituber-with-ai-agent.aituberonair.com/docs/setup-guide
## 注意事項（ユーザーに必ず伝えること）
- このサンプルは開発者向けです。API キー類はブラウザの `localStorage` に平文で保存されます。本番権限のクレデンシャルは入れず、共有・公開オリジンにそのままデプロイしないでください。
- 共有端末で使った場合は、使用後に API キーをローテーションすることを推奨します。
起動後にやること：VRM モデル（miko.vrm など）を public/avatar/ に配置する必要があります。未配置でも開発サーバは起動しますが、アバターは表示されません。
Live2D Live2D モデル読み込み
Live2D モデル方式。Cubism Core（Live2D 公式）のダウンロードにはライセンス同意が必要で、モデル本体もご自身で用意する必要があります。3種類の中で最も手動作業が多いので、Live2D モデルを既にお持ちの方向けです。
AITuber 配信環境のテンプレート「react-live2d-app」（Live2D モデル読み込み方式のサンプル）を、このマシンに構築してください。
## ゴール
`https://github.com/shinshin86/aituber-onair` をローカルに clone し、`packages/core/examples/react-live2d-app` の開発サーバを起動して、ブラウザで `http://localhost:5173` にアクセスできる状態にする。
## 前提条件
- Node.js（LTS 推奨）と npm が使えること
- git が使えること
- ブラウザは Chrome または Edge を想定（Web Speech API を使うため）
不足しているものがあれば、そこで止まってユーザーに知らせてください。
## 実行手順
1. 現在の作業ディレクトリに `aituber-onair/` が無ければ clone してください。
git clone https://github.com/shinshin86/aituber-onair.git
既に存在する場合は再利用して構いません。
2. サンプルアプリのディレクトリに移動してください。
cd aituber-onair/packages/core/examples/react-live2d-app
3. 依存をインストールしてください。
npm install
4. 開発サーバを起動してください。
npm run dev
このコマンドはフォアグラウンドで動き続けます。あなたのツールでバックグラウンド実行ができるならそれで構いません。できない場合は「別ターミナルでこのコマンドを実行してください」とユーザーに案内してください。
5. ユーザーにブラウザで `http://localhost:5173` を開くよう伝えてください。
## ユーザーに任せる作業（あなたが勝手にやらないこと）
以下はライセンス同意やユーザー所有の素材が絡むため、**あなた（AIエージェント）が自動ダウンロードしてはいけません**。手順だけ案内してユーザーに実施してもらってください。
- 使いたい LLM プロバイダの API キーを取得する（OpenAI / Gemini / Claude / OpenRouter / xAI / zAI / Kimi のいずれか1つ）
- ブラウザで画面右上の「設定」を開き、選んだプロバイダの API キーを貼り付け、モデルを選択する
- **Cubism Core for Web を Live2D 公式からダウンロード（必須・ライセンス同意あり）**:
- 公式ダウンロードページ: https://www.live2d.com/sdk/download/web/
- `Cubism Core for Web` または `Cubism SDK for Web` を入手
- 含まれている `live2dcubismcore.min.js` を以下に配置:
`packages/core/examples/react-live2d-app/public/scripts/live2dcubismcore.min.js`
- このサンプルは Cubism 4 系前提のため `live2d.min.js` は不要
- **Live2D モデルフォルダを配置（必須）**:
- `.model3.json` 単体ではなく、参照先アセット（textures/ や motions/）も含むフォルダ全体を配置
- 配置先: `packages/core/examples/react-live2d-app/models/<モデル名>/`
- 例:
models/Hiyori/
Hiyori.model3.json
Hiyori.moc3
Hiyori.physics3.json
textures/texture_00.png
motions/idle.motion3.json
- **モデルを追加したら dev サーバを再起動する**:
- `models/` 配下はサーバ起動時に一覧解決されるため、モデルを後から追加した場合は `npm run dev` を再起動してください
- 起動後、ブラウザで「設定」を開き、モデル一覧から対象を選び「読み込む」を押す
- モデルデータはメモリ保持のみで、ページリロードで消えます（LLM / TTS 設定は `localStorage` に保存）
## 参考ドキュメント（詳細が必要なときに参照）
- サンプル README: https://github.com/shinshin86/aituber-onair/blob/main/packages/core/examples/react-live2d-app/README.md
- 3種類のアバター方式をまとめたセットアップガイド（日本語、AIエージェント向け詳細資料）: https://start-aituber-with-ai-agent.aituberonair.com/docs/setup-guide
- Live2D Cubism SDK (Web): https://www.live2d.com/sdk/download/web/
## 注意事項（ユーザーに必ず伝えること）
- **Live2D の Cubism Core / SDK は Live2D 社のライセンスに従う必要があります。あなた（AIエージェント）が公式サイト以外から取得したり、リポジトリに同梱したりしないでください。** 必ずユーザー自身に公式サイトでダウンロードしてもらってください。
- このサンプルは開発者向けです。API キー類はブラウザの `localStorage` に平文で保存されます。本番権限のクレデンシャルは入れず、共有・公開オリジンにそのままデプロイしないでください。
- 共有端末で使った場合は、使用後に API キーをローテーションすることを推奨します。
起動後にやること：Live2D 公式から Cubism Core をダウンロードし public/scripts/live2dcubismcore.min.js に配置、さらに Live2D モデルフォルダを models/ 配下に置く必要があります。モデル追加後は dev サーバの再起動が必要です。
