| name | aituber-onboarding |
| description | AITuberぶつぶつシステム（z-aituber）を初めてセットアップするときに使う。「初めて使う」「セットアップして」「環境構築を手伝って」「ゼロから動かしたい」「初回起動まで導いて」「インストール手順は?」などのとき。前提ソフト導入→clone→poetry install→.env 作成→AivisSpeech/OBS/仮想オーディオ準備→設定検証→初回起動、までを初心者向けに順番に案内する。 |
はじめてのセットアップ（オンボーディング）
このシステムを初めて動かす人を、前提ソフトの導入から初回起動まで一本道で案内する skill。各ステップは「やること → 確認方法 → つまずいたら」の順で進める。詰まったら [[aituber-diagnose]]、起動できたら日々の操作は [[aituber-run]] へ。
Claude へ: ユーザーの OS（Windows / Mac / Linux）を確認し、各ステップを 1つずつ 提示して、その都度「できたか」を確認してから次へ進む。一気に全部流さない。
全体像（必要なもの）
| 種類 | 何 | 必須 | 用途 |
|---|
| ランタイム | Python 3.11 以上 | ✅ | 本体 |
| パッケージ管理 | Poetry | ✅ | 依存インストール・aituber コマンド |
| 取得 | Git | ✅ | リポジトリ取得 |
| 音声合成 | AivisSpeech Engine + 蒼月ハヤテ ボイスモデル | ✅ | しゃべる声 |
| API | OpenAI API キー | ✅ | 文章生成 |
| 配信 | OBS Studio（WebSocket 有効化＋テキストソース） | ✅ | 字幕・配信 |
| 音声経路 | 仮想オーディオ（Windows: VB-CABLE 等 / Mac: BlackHole 等） | ✅ | 声を OBS へ送る |
| 配信先 | YouTube ライブ（ビデオ ID） | コメント応答に必要 | 視聴者コメント取得 |
まず外部接続を減らしたテストモードで起動確認し（ステップ7）、その後に OBS・YouTube を本接続する流れが安全。
ステップ1: 前提ソフトを入れる
- Python 3.11+:
python --version（または python3 --version）で 3.11 以上を確認。環境に応じて python / python3 を使い分ける（以降のコマンドも同様）。
- Poetry: 公式手順でインストール。
poetry --version で確認。
- Git:
git --version で確認。
- AivisSpeech Engine / OBS Studio / 仮想オーディオ は後のステップで設定するので、ここではインストールだけ済ませる。
確認: 上の 3 コマンドがすべてバージョンを返せば OK。
ステップ2: 取得して依存をインストール
git clone https://github.com/YasunaCoffee/AITuberMurmurSystem.git
cd AITuberMurmurSystem
poetry install
確認: poetry run aituber --help がサブコマンド一覧（run / stop / status / shutdown / character）を表示すれば OK。
ステップ3: .env を作って鍵を入れる
API キーなどの実値は .env に書く。config.yaml の api_keys は環境変数名だけを書く欄なので触らない（既定で openai: OPENAI_API_KEY のように対応付けてある）。
cp .env.template .env
.env を編集して設定する（.env.template のコメントに従う）:
OPENAI_API_KEY（必須）… https://platform.openai.com/api-keys で取得。YOUTUBE_VIDEO_ID（必須）… ライブ配信 URL https://www.youtube.com/watch?v=XXXXXXXXXXX の v= 以降 11 文字。validate_config() は必須扱いなので未設定だと警告が出るが、テストモード（ステップ9）はダミーコメントを使うため、動作確認だけなら実在するライブ ID でなくてよい。OBS_WS_PASSWORD / OBS_WS_HOST（既定 127.0.0.1）/ OBS_WS_PORT（既定 4455）（必須）… ステップ5 の OBS 設定値に合わせる。AIVIS_SPEECH_API_KEY（任意・空でよい）。
.env は秘密情報。Git にコミットしないこと（.gitignore 済み）。
確認: ステップ6 の検証コマンドで読めているか確かめる。
ステップ4: 必須ディレクトリを作る
クローン直後は summary/ が存在しない。 一方 config.validate_config() は prompts / txt / summary の実在を要求するので、起動前に必ず作成する（prompts/ txt/ は同梱済み）。
mkdir -p summary conversation_history
確認: ls -d prompts txt summary がすべて表示されれば OK。
ステップ5: AivisSpeech（声）を準備
- AivisSpeech Engine を起動する。
- 蒼月ハヤテ ボイスモデルを Engine にインポートする: https://hub.aivis-project.com/aivm-models/eefe1fbd-d15a-49ae-bc83-fc4aaad680e1（既定キャラ
characters/hayate.yaml、speaker_id 1）。
- 本体は
config.yaml の audio.synthesis.aivis_url（既定 http://127.0.0.1:10101）へ接続する。Engine のアドレスがこれと一致しているか確認。
確認: ブラウザ等で http://127.0.0.1:10101/version が応答すれば Engine は起きている。別キャラを使うなら [[aituber-character]] を参照。
ステップ6: OBS（字幕・配信）を準備
- OBS で WebSocket Server を有効化（「ツール → WebSocket サーバー設定」）。パスワード/ポートを控え、
.env の OBS_WS_* と一致させる。
- 字幕用に テキスト（GDI+）ソースを追加し、ソース名を
Answer にする（本体は set_input_settings(name="Answer", ...) で更新する。大文字始まりに注意）。
- 最小構成は
Answer テキストソース1つでよい。 Question / SelectedComment / Summary というソース名も実装にあり（murmur/obs_adaper.py）、対応機能を使うときに追加する。
- 字幕連携の有効/無効は
config.yaml の obs_subtitles.enabled（既定 true）。
ステップ7: 音声を OBS へ流す（仮想オーディオ）
- 仮想オーディオデバイス（Windows: VB-CABLE / Mac: BlackHole など）をインストール。
- それをシステムの音声出力デバイスに設定（AivisSpeech の再生先が OBS に届くようにする）。
- OBS の「音声入力キャプチャ」で同じ仮想デバイスを取り込む。
- 再生先デバイスは
config.yaml の audio.playback.default_output_device_id（既定は固定値 3）で指定する。自分の環境のデバイス ID と一致しないことが多いので、声が出ない／違うデバイスに出るときはこの値を見直す。
確認: 「ローカルでは聞こえるのに OBS に乗らない」ときは、再生先デバイスと OBS の取り込みデバイスが一致しているかを見る。
ステップ8: 設定を検証する
poetry run aituber character validate characters/hayate.yaml
poetry run aituber character info
poetry run python -c "from config import config; print(config.validate_config() or 'All OK')"
poetry run python scripts/check_youtube_config.py
確認: character validate が OK: 蒼月ハヤテ (...) を返し、validate_config() が All OK を返せば設定はそろっている。問題が出たら指摘どおりに .env／ディレクトリを直す。詳しい切り分けは [[aituber-diagnose]]。
ステップ9: 初回起動
まず外部接続を減らしたテストモードで配線を確認すると安全（YouTube はダミーコメント、OpenAI/音声はモックに切り替わる）。
CHAT_TEST_MODE=true poetry run aituber run
Windows では環境変数の付け方が異なる（または .env に CHAT_TEST_MODE=true を書く）:
# PowerShell
$env:CHAT_TEST_MODE="true"; poetry run aituber run
:: コマンドプロンプト
set CHAT_TEST_MODE=true && poetry run aituber run
イベントが流れて落ちないことを確認できたら、本番起動する。
poetry run aituber run
poetry run aituber run --theme prompts/poem.txt
停止は別ターミナルで poetry run aituber stop（強制は --force）。起動・停止・状態・バックグラウンドの詳しい運用は [[aituber-run]]。
つまずいたら / 次のステップ
- 動かない・接続できない・音や字幕が出ない → [[aituber-diagnose]]（症状別の対応表あり）。
- 日々の起動・停止・状態確認 → [[aituber-run]]。
- 自分のキャラを作る → [[aituber-character]]。
- 配信テーマを作る → [[aituber-theme]]。
関連
- [[aituber-run]] — 起動・停止・状態・バックグラウンド運用
- [[aituber-diagnose]] — 環境・設定の不調の切り分け
- [[aituber-character]] — キャラクター定義 YAML
- [[aituber-theme]] — テーマファイル
- 参照:
README.md（セットアップ）, doc/quick_setup_guide.md（YouTube 設定）, .env.template, config.yaml, aituber/cli.py
