ゼロから構築するAIリアルタイム配信ルーム：デジタルヒューマン、コメント制御、OBS配信の実践

プロジェクト概要

AI リアルタイム配信ルームは、AI デジタルヒューマンが自律的にライブ配信を行うオープンソースプロジェクトです。視聴者がコメントを送信すると、システムはまず内容をフィルタリングし、現在の音声と動作の状態に応じてキューに入れて処理します。これにより、発言が終わる前に次の指示が割り込むのを防ぎます。

このプロジェクトでは、Vidu S2 リアルタイムデジタルヒューマンを使って映像、音声、応答を生成します。本プロジェクトはコメントのフィルタリングと制御、キャラクタープロフィール、ワードローブ、配信ルームのオーバーレイ、ローカルワークベンチを担当し、OBS への出力または直接配信にも対応します。

コードは MIT ライセンスで公開されています。リポジトリには作者自身のキャラクター画像、設定、音声、素材ライブラリは含まれていません。そのため、導入後は独自のキャラクターアセットを用意し、コンテンツの著作権とコンプライアンスについて自ら責任を負う必要があります。

機能と制限

現在対応している機能

• カスタム設定したキャラクターに基づくチャット応答と、オープニングメッセージの設定。
• あらかじめ用意したワードローブから衣装一式を切り替え。1回の着替えには約 6 秒かかります。
• キーワードでハート、手を振る、ウインクなどの小さな動作をトリガー。
• 視聴者の発言がない場合、キャラクターの話題プールから自動的に話題を提供。1つの話題を話し終える前に同じ内容を繰り返すことを防ぎます。
• 不適切なコメントや誘導目的のコメントを自動的にフィルタリング。ギフトが割り込むことはありません。
• Vidu が途中で切断された場合の自動再配信を任意で有効化。

注意が必要な制限

• デフォルトでは背景変更、飲食、アイテムを持つ動作は有効になっていません。リアルタイム再描画によりキャラクターの衣服が変形する可能性があるためです。
• 現在、このプロジェクトは歌唱、音楽再生、立ち姿、全身動作、大きな動きのダンス、商品販売には適していません。
• 配信回をまたいで以前の視聴者を記憶することはありません。
• Douyin のコメント取得機能は内蔵していません。プラットフォーム公式の公開 API を使用し、配信ルームのウェブページをスクレイピングしないでください。

背景変更とアイテム機能はデフォルトで無効になっています。個人的なテストでのみ使用する場合は、config.json に {"safety":{"live_visual_edits":true}} を設定できます。公開配信では有効にしないことを推奨します。

実行環境の準備

開始前に、以下の環境とアカウントを準備してください。

• macOS または Linux。
• Python 3.11 以上。作者は Python 3.13 を使用しています。
• libx264 と aac を含む ffmpeg。
• Vidu オープンプラットフォームの API Key。キーは vda_ で始まり、アカウントに利用可能なクレジットがあることを確認してください。
• 任意のEvolink API Key。画像、衣服、アイテム、背景の生成や、音声クローン時の音声アップロードに使用します。
• 任意の OBS 30 以上。カメラ、オーバーレイ、配信に使用します。
• 任意の YouTube 配信キー。内蔵配信を使用する場合にのみ必要です。

Vidu リアルタイムデジタルヒューマンは時間単位で課金されます。README に記載された公式価格は 1 秒あたり 1.5 クレジットで、1 クレジットは 0.03125 元、1時間あたり約 169 元です。まずはドライランモードとローカルモックサービスでフローを検証することを推奨します。

キーを安全に保存する

キーはローカルファイルにのみ保存し、サーバー側で読み取るようにしてください。ブラウザには送信されません。まずデフォルトディレクトリを作成します。

mkdir -p ~/.deepsea/vidu ~/.deepsea/evolink && chmod 700 ~/.deepsea/vidu ~/.deepsea/evolink

macOS では、クリップボード内の Vidu Key をデフォルトパスに保存できます。

pbpaste > ~/.deepsea/vidu/api.key && chmod 600 ~/.deepsea/vidu/api.key

Evolink の Key は ~/.deepsea/evolink/api.key に保存します。YouTube の内蔵配信を使用する場合は、配信キーを ~/.deepsea/youtube/stream.key に保存します。OBS WebSocket のパスワードは ~/.deepsea/obs/ws.password に保存します。デフォルトパスは config.json で変更できます。

プロジェクトをインストールする

GitHub からリポジトリをクローンし、プロジェクトディレクトリに移動します。

git clone https://github.com/garycaogan/ai-live-avatar.git
cd ai-live-avatar

Python 仮想環境を作成し、依存関係をインストールします。

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

ステージページは Alibaba Cloud RTC Web SDK に依存しています。プロジェクトはこの SDK を再配布せず、スクリプトで公式 CDN からダウンロードして検証します。

./tools/fetch_vendor.sh

最後にサンプル設定ファイルをコピーします。

cp config.example.json config.json

ワークベンチを起動する

サービスを実行します。

.venv/bin/python server.py

サービスはデフォルトでローカルホストのみをリッスンします。起動後、ブラウザで http://127.0.0.1:28900/workbench を開くと、ワークベンチにアクセスできます。

Vidu のクレジットを消費したくない場合は、配信ルームページでドライラン配信を使用できます。このモードでは Vidu を呼び出さず、コメントのフィルタリング、キュー処理、オーバーレイのみを実演します。プロジェクトには tests/dev_mock_stack.py も用意されており、ローカルの Vidu モックに接続して制御フロー全体をテストできます。

独自のデジタルヒューマンキャラクターを作成する

1. キャラクター画像を準備する

素材ページでキャラクター画像をアップロードするか、Evolink を使って生成します。ベース画像はキャラクターの顔、衣装、部屋、常時表示される表情に影響します。README では、1人のクローズアップ、両手を机の上に置き、自然な表情の画像を推奨しています。

横長の構図は、Douyin の縦型ライブ配信ページ上部にある小さな枠に配置され、1.2:1 の比率でトリミングされます。そのため、ベース画像の構図はあらかじめ適したものにしてください。

2. キャラクタープロフィールを作成する

キャラクターページで新しいキャラクターを作成し、ベース画像としてキャラクター画像を選択したうえで、名前、キャラクター設定、オープニングメッセージを入力します。キャラクター設定では話し方を重点的に説明し、完全な例文は書かないでください。モデルが例文をそのまま読み上げる可能性があります。

3. ワードローブを追加する

ワードローブページで衣装を数セット追加します。各衣装は全身が写った1枚の写真にしてください。部屋、照明、構図はできるだけベース画像と一致させます。そうしないと、着替えの際に画面が大きく切り替わる可能性があります。

4. 音声を設定する

音声ページでシステム音声を選択するか、10～20秒のノイズのない音声をアップロードしてクローンします。Vidu の音声クローンは有料です。素材をアップロードする前に、該当する音声の使用許諾を得ていることを確認してください。

5. 動作を設定する

動作ページでは、コメントのキーワードに対応する動作を変更できます。キャラクター設定では待機中の小さな動作も編集でき、新しいコメントがないときの画面をより自然にできます。

キャラクタープロフィールは assets/avatars/profiles.json に、キャラクター設定は personas/ に保存されます。これらのファイルは .gitignore で除外されているため、リポジトリにはコミットされません。

コメント処理の流れを理解する

ワークベンチの配信ルームページでは、シミュレーションコメントを手動で送信できます。実際のコメントは、以下の API から送信できます。

curl -s -X POST http://127.0.0.1:28900/api/danmaku \
  -H 'Content-Type: application/json' \
  -d '{"user":"視聴者A","text":"服を着替えて","gift":0}'

コメントがシステムに入ると、まず moderation.json のフィルターワードを確認します。その後、live/router.py がルールに基づき、チャット、着替え、アイテム、背景、動作、復元のいずれかとして認識します。この認識処理では大規模言語モデルを呼び出さないため、追加の遅延や費用は発生しません。

デフォルトでは、アイテムと背景に関するリクエストは通常のチャットとして処理されます。コメントの認識には、配信者の身近な事柄を尋ねる、ワードローブ内の衣装名を使って着替えを指示する、1回につき1つの動作だけをリクエストするといった、簡潔で明確な表現が適しています。

通常、以下の内容は結果に影響します。1つの文に複数のタスクを含めること、リアルタイムのニュースや天気を尋ねること、歌唱や音楽再生を要求することです。複雑な要求は、複数の簡単なコメントに分けることを推奨します。

OBS に接続する

ワークベンチの配信ページで出力方式を OBS に切り替え、OBS でブラウザソースを追加します。必要に応じて以下の URL を選択してください。

• デジタルヒューマンのみ表示：http://127.0.0.1:28900/stage?obs=1&role=obs&layer=avatar
• 透明オーバーレイのみ表示：http://127.0.0.1:28900/stage?overlay=1
• デジタルヒューマンとオーバーレイを表示：http://127.0.0.1:28900/stage?obs=1&role=obs&layer=all

完全な画面には幅 1080、高さ 1920 を推奨します。ブラウザソースでは「OBS で音声を制御」を有効にしてください。サービスはローカルホストのみをリッスンするため、OBS とプロジェクトのサービスは同じコンピューター上で実行する必要があります。

OBS シーンを自動作成する場合は、tools/obs_control.py を使用できます。オーバーレイには「AI リアルタイム生成画面」という表示が常に残ります。これは AI デジタルヒューマン配信に関するプラットフォームの要件なので、削除しないでください。

Douyin の配信画面を設定する

Douyin でよく使われるデジタルヒューマン配信ルームは横長の画面で、モバイル端末では画面が上部に配置され、コメントが下部に表示されます。以下のコマンドを実行すると、「Douyin 配信ルーム」シーンを作成できます。

.venv/bin/python tools/obs_control.py setup douyin --camera FaceTime

このコマンドは OBS キャンバスを 1296×1080、つまり 1.2:1 の比率に設定し、デジタルヒューマン、説明カード、字幕、実写カメラを構成します。--camera の後にはカメラ名の一部を入力します。省略した場合は、見つかった最初の実カメラが使用されます。

初回実行時、macOS から OBS にカメラの使用を許可するよう求められる場合があります。許可した後にもう一度実行すると、カメラのトリミングが正しく適用されます。横長シーンと縦長シーンはいつでも切り替えられ、同じデジタルヒューマンレイヤーを共有するため、追加の入室枠は消費しません。

Douyin 配信コンパニオンに接続する方法は2つあります。OBS 仮想カメラを有効にして配信コンパニオンで OBS Virtual Camera を選択する方法と、配信コンパニオンでウィンドウ素材を追加し、OBS の投影ウィンドウをキャプチャする方法です。仮想カメラは映像のみを送信し、音声は送信しません。そのため、配信コンパニオンが「Douyin 配信ルーム」シーンのコンピューター音声を取得できることも確認してください。

アカウントに第三者配信権限がある場合は、OBS にプラットフォームから提供された配信 URL を直接入力することもできます。Douyin のコメントは自動的にプロジェクトへ入らないため、Douyin オープンプラットフォームのライブ配信機能 API で権限を申請し、その後データを /api/danmaku に送信する必要があります。

配信ルームの説明カードを編集する

ステージページの左右上部にある説明カードは、この配信でできること、現在できないこと、より効果的なコメントの送り方を表示するために使用します。内容は assets/stage_panel.json から読み込まれます。このファイルが存在しない場合は assets/stage_panel.example.json を使用します。

サンプルファイルをコピーした後、自分の内容に変更できます。ステージページは1分以内に自動更新され、内蔵配信のオーバーレイでは新しい内容がすぐに使用されます。outfit_hint を使うと、キャラクターごとに着替えのヒントを設定できます。

自動再配信を有効にする

Vidu は配信中に切断されることがあります。自動復旧を有効にすると、プロジェクトは 3 秒待って再配信を開始します。1時間あたり最大 6 回まで試行します。ただし、クレジット不足やコンテンツ審査による切断は自動的に再試行されません。

API で有効にします。

curl -s -X POST http://127.0.0.1:28900/api/settings \
  -H 'Content-Type: application/json' \
  -d '{"auto_recover":true}'

config.json に設定することもできます。

{"schedule":{"auto_recover":true}}

長時間配信する前に、アカウント残高、キャラクター素材、ネットワーク状態を確認し、ドライランまたはローカルモックサービスで復旧フローを検証することを推奨します。

テストとプロジェクト構成

プロジェクトのテストではローカルの Vidu モックを使用するため、費用は発生しません。以下を実行できます。

python -m unittest tests.test_logic tests.test_workbench tests.test_e2e

主なディレクトリとファイルの用途は以下のとおりです。

• server.py：サービスのエントリーポイントとデフォルト設定。
• live/：ライブ配信のスケジューリング、ViduリアルタイムAPI、コメント認識、クローゼット、素材生成、内蔵配信、ワークベンチAPI。
• static/：ワークベンチ、ステージページ、旧版コンソール。
• WORKBENCH_API.md：ワークベンチで使用するすべてのAPI。
• tests/：テストコードとローカルモックサービス。

まとめ

このプロジェクトは、Viduリアルタイムデジタルヒューマン、コメントルール、キャラクターアセット、ライブ配信出力を1つのローカルワークフローに統合します。まずはドライランモードでフィルタリング、キュー、クローゼット、レイヤーを確認し、その後、自分のビジュアル、音声、OBSシーンを設定して、最後に実際のプラットフォームへ接続することをおすすめします。

公開配信では、映像の変形を招く可能性があるリアルタイム背景や小道具の編集を無効にし、プラットフォーム公式のインタラクションAPIを使用し、AI生成であることを示す表示を残してください。また、実在する人物の音声、キャラクターのビジュアル、音楽、その他の素材については、あらかじめ使用許諾を確認してください。