Avatar UI Core for Dify

https://github.com/sito-sikino/avatar-ui-core.git のプログラムを基に、Difyフロントとして改造したものです。

クラシックなターミナル調のUIコア。チャットUIからCLI統合まで拡張可能なプロジェクト基盤を提供します。

特徴

• ターミナルUI - グリーンオンブラックの古典的ターミナルインターフェース
• AIアバター - 発話同期型のピクセルアートアバター表示
• タイプライター効果 - 文字単位のリアルタイム表示アニメーション
• サウンドエフェクト - Web Audio APIによるタイピング音生成
• 完全な設定管理 - すべての動作パラメータを.envファイルで一元管理

基本操作

1. メッセージ送信: 画面下部の入力欄にテキストを入力してEnterキー
2. 会話履歴: 自動的にスクロールされる会話履歴を確認
3. アバター: AIの応答中はアバターが応答アニメーション

クイックスタート

必要要件

• Python 3.8以上
• Dify環境があり、APIアクセス可能な事
  • Dify Base URL
  • Dify API KEY

インストール手順

1. プロジェクトの取得

# リポジトリのクローン（またはZIPダウンロード後に解凍）
git clone https://gh.iiji.jp/y-tominaga/avatar-ui-core.git
cd avatar-ui-core

2. Python仮想環境の作成

仮想環境を使用することで、システムのPython環境を汚さずにプロジェクトを実行できます。

# 仮想環境の作成
python -m venv venv

# 仮想環境の有効化
# Linux/Mac:
source venv/bin/activate
# Windows (コマンドプロンプト):
venv\Scripts\activate
# Windows (PowerShell):
venv\Scripts\Activate.ps1

仮想環境が有効化されると、ターミナルのプロンプトに(venv)が表示されます。

3. 必要なパッケージのインストール

# requirements.txtに記載されたパッケージを一括インストール
pip install -r requirements.txt

設定

1. 環境変数ファイルの準備

# テンプレートファイルをコピーして.envファイルを作成
cp .env.example .env
# Windows: copy .env.example .env

2. APIキーの設定

テキストエディタで.envファイルを開き、必須項目を設定：

重要: .envファイルには機密情報が含まれるため、絶対にGitにコミットしないでください。

起動

# アプリケーションの起動
python app.py

起動に成功すると以下のようなメッセージが表示されます：

 * Running on http://0.0.0.0:45000

ブラウザで http://<your ip addr>:45000 にアクセスしてください。

当方では、Nginxをリバースプロキシにして利用しています。この時、特定ディレクトリ配下にこのプログラムを配置する場合、ルートディレクトリ階層の名前と深度を合わせるようにCUSTOM_PATHを合わせてください。

プロジェクト構造

avatar-ui-core/
├── app.py                  # Flaskアプリケーション本体
├── settings.py             # 設定管理モジュール
├── requirements.txt        # Python依存関係
├── .env.example           # 環境変数テンプレート
├── static/
│   ├── css/
│   │   └── style.css      # UIスタイル定義
│   ├── js/
│   │   ├── app.js         # メインエントリーポイント
│   │   ├── chat.js        # チャット機能
│   │   ├── animation.js   # アニメーション制御
│   │   ├── sound.js       # 音響効果
│   │   └── settings.js    # フロントエンド設定
│   └── images/
│       ├── idle.png       # アバター（静止）
│       └── talk.png       # アバター（発話）
└── templates/
    └── index.html         # HTMLテンプレート

systemd管理へ追加するためのファイルをsystemdディレクトリ配下に配置しています。

• avatar-ui-core-example.sh # avatar-ui-core起動スクリプト
• avatar-ui-core.service # avatar-ui-coreサービス化ファイル

カスタマイズ方法

すべての設定は.envファイルで調整できます。

0. Dify接続設定

• 事前にDifyを使用してアプリケーションを作成してください。
• Difyアプリケーションの「API」メニューを表示し、API用URLベースとAPIキーを確認してください。
• .env内の以下の設定が必要です：

AI_PROVIDER='dify'
DIFY_API_BASE=https://<dify-api-base-hostname>/v1
DIFY_API_KEY="<dify-api-key>"
DEFAULT_RESPONSE_MODE='blocking' # Streamingに関しては作成していませんのでこれで固定してください。

CUSTOM_PATH='/webapp' #こちらはサブディレクトリをNginx設定等で配下に設置する場合はそのパス構成に合わせてください。

1. アバターの変更

画像ファイルを差し替える

• static/images/idle.png: 静止時のアバター（推奨: 140x140px）
• static/images/talk.png: 発話時のアバター（推奨: 140x140px）

2. AIの人格設定

.envファイルで以下の項目を編集：

AVATAR_NAME=Spectra
AVATAR_FULL_NAME=Spectra Communicator
SYSTEM_INSTRUCTION=あなたはSpectraというAIアシスタントです。技術的で直接的なスタイルで簡潔に応答してください。回答は短く要点を押さえたものにしてください。

3. UI動作の調整

.envファイルで各種速度を調整：

# タイピング速度（ミリ秒、小さいほど高速）
TYPEWRITER_DELAY_MS=30

# 口パクアニメーション間隔（ミリ秒）
MOUTH_ANIMATION_INTERVAL_MS=100

4. サウンド設定

.envファイルで音響効果をカスタマイズ：

BEEP_FREQUENCY_HZ=600   # 音の高さ（Hz）
BEEP_VOLUME=0.1         # 音量（0.0-1.0）
BEEP_DURATION_MS=30     # 音の長さ（ミリ秒）

注意: 設定変更後はアプリケーションの再起動が必要です。

技術スタック

バックエンド

• Flask 3.0.0 - Webアプリケーションフレームワーク
• python-dotenv 1.0.0 - 環境変数管理

フロントエンド

• ES6 Modules - モジュール化されたJavaScript
• Web Audio API - ブラウザネイティブ音響生成
• CSS3 - モダンなスタイリング
• Fira Code - プログラミング用等幅フォント

ライセンス

MIT License - 詳細はLICENSEファイルを参照

クレジット

• Developed by Sito Sikino
• Modified by Yuichi Tominaga ([email protected])

使用技術

• requests
• Flask Framework
• Fira Code Font

---

注意: このプロジェクトはチャットフロントエンド開発の一環として開発したものです。本番環境での使用時は適切なセキュリティ対策を実施してください。