Peraravatar

ブラウザだけで動く軽量PNGTuber

マイク音量に反応した口パク、自動瞬き、カスタム表情切替、OBS連携など、PNGTuberに必要な機能が1ファイルで完結します。セットアップ不要、ブラウザから直接お試しできます。

Peraravatarの動作デモ。アバターが口パク・瞬き・自動アニメーションする様子
動作デモ
触ってみる ▶ GitHub
× 主な機能 ×
  • 口パク: マイク音量に応じて段階切替（段階数・閾値・各段階の画像数すべて自由）
  • 自動アニメーション: 呼吸・瞬き・首かしげ・左右揺れ・視線のよそ見
  • おねむ状態: 一定時間無音で目を閉じる
  • 大音量への反応: 急な音量変化でリアクション
  • カスタム表情: 数に制限なし、表情ごとに動作とトリガー条件を設定
  • 動作タイプ8種類: バウンス／のけぞり／震え／揺れ／うなずき／首振り／ホップ／待機
  • 発火条件3種類: ホットキー／音量閾値／音声パターン
  • 音声パターン認識: 録音した波形に似た音声を自動検出（笑い声・泣き声など）
  • 背景オプション: 透過／チェッカー柄／単色
  • OBSモード: 起動時に設定パネルを自動非表示
  • 保存方式: localStorage + IndexedDBに自動保存、JSON書き出し/読み込み対応
× セットアップ ×

オンライン版（GitHub Pages）でも基本機能は使えますが、配信で安定動作させるならローカルHTTPサーバー経由の起動を推奨します。マイクの getUserMedia 制約上、file:// 直接開きでは動作しません。

1. ソースコードをダウンロード

GitHubリポジトリ の緑色「Code」ボタン → 「Download ZIP」で取得して任意の場所に展開。

2. ローカルHTTPサーバーを起動

展開したフォルダ直下にある起動用バッチを実行:

  • server-python.bat（Pythonが必要）
  • server-node.bat（Node.jsが必要）

どちらか一方でOK。バッチを実行するとコマンドプロンプトが開いたままになります (閉じるとサーバーも止まります)。

3. ブラウザでアクセス

http://localhost:8765/ を開く。初回はマイク許可ダイアログが出ます。

必要なソフト

  • Python（シンプル、推奨）
    • python.org からWindowsインストーラをダウンロード
    • インストール時「Add Python to PATH」にチェック
    • 確認: コマンドプロンプトで python --version
  • Node.js（代替）
    • nodejs.org からLTSインストーラをダウンロード
    • デフォルトインストールでPATH設定済み
    • 確認: node --version, npx --version
× 使い方の流れ ×
  1. ブラウザで開く: 上の「触ってみる」ボタン (GitHub Pages版) または ローカルHTTPサーバー 経由で http://localhost:8765/ を開く。初回はマイク許可ダイアログが出ます。
  2. 「画像」タブで自分のアバター画像を差し替え: 通常 / 瞬き / よそ見 (左右) / 口パク段階のスロットに画像を設定。
  3. 「動き」タブで調整: 呼吸・揺れ・瞬き間隔・口パク閾値などをスライダーまたは数値入力でリアルタイム調整。
  4. 設定をJSONで書き出し: 設定タブから peraravatar-config.json を書き出して保管。
  5. OBSに組み込む: OBSのブラウザソースに http://localhost:8765/ を設定し、書き出したJSONを読み込ませる (詳細は OBSへの組み込み 参照)。

※ 設定は URLのドメイン / ブラウザインスタンス単位で別管理 です (GitHub Pages版 / localhost版 / OBSブラウザソース はそれぞれ別のlocalStorage)。詳細は データ保存について 参照。

× 推奨画像仕様 ×
  • サイズ: 600×900〜1080×1620（縦長2:3比率）
  • 形式: 透過PNG
  • 1枚あたり: 500 KB以下推奨
  • 全画像で位置・スケールを揃えると切替時にガタつきません
× 各タブの説明 ×

画像タブ

  • 固定スロット: 通常表情、瞬き（目閉じ）、よそ見（左）、よそ見（右）
  • カスタム表情を無制限に追加（個別に動作・トリガー設定可）
  • 口パクの各段階の画像を登録

動きタブ

  • 呼吸・揺れ・瞬き間隔・口パク閾値などをスライダーまたは数値入力でリアルタイム調整
  • 時間系の値は秒単位で表示
  • おねむ状態の発動までの無音時間を設定可

設定タブ

  • 背景オプション（透過／チェッカー柄／単色）
  • OBSモード（起動時パネル非表示）
  • 全設定リセット
  • 設定のJSON書き出し/読み込み（バックアップ用）
× カスタム表情の動作 ×

表情ごとに以下の動作タイプから1つを選択:

動作説明
バウンス上下に弾むように跳ねる
のけぞり後ろに仰け反って戻る
震え細かく震える
揺れ左右にゆらゆら揺れる
うなずき頷く
首振り左右に首を振る
ホップ軽く跳ねる
待機動作なし

発火条件は3種類:

  • ホットキー: Z / X / C / V等を割り当て（OBS連携時はシーン切替経由）
  • 音量閾値: 設定値以上の音量を一定時間保持で発火
  • 音声パターン: 録音した声波形に類似した音声を検出
× 音声パターン検出 ×

「笑い声」「泣き声」など特定の音の波形パターンを録音しておき、似た音を出すと自動で表情が発動する機能です。音声認識ではなく波形マッチングのため、言葉の内容ではなく音量変化やピーク数の類似度で判定します。

録音手順

  1. 表情設定で「🎤 録音を追加」ボタンを押す
  2. 3秒のカウントダウン後、対象の音を2.5秒間発する
  3. システムが波形を記録
  4. 以後、類似パターンを検出すると1秒間その表情を表示

特性と注意

  • 感度は 0.3 〜 0.95 の範囲で調整可能
  • 波形収集に2.5秒必要なため、検出には約2.5秒のラグがある
  • OBS連携時は「オーディオの詳細プロパティ」で**+1500ms程度のオーディオ遅延**を入れると視聴側との同期が取れる

リスク軽減のコツ

  • 音声パターンは1つの表情だけに割り当てる（誤検出時の影響を局所化）
  • 同じ表情に複数パターンを登録（笑い声のバリエーション等）
  • 確実に出したい瞬間はホットキー orシーン切替で固定
× OBSへの組み込み ×
注意:

OBSブラウザソース内で 設定UIを操作する運用は想定していません。ページ内ショートカットが効かないため、設定パネルをいったん閉じると再表示できなくなります。設定は通常ブラウザ側で作り込んでJSONを書き出し、OBS側ではそれを読み込むだけにしてください。

  1. OBSブラウザソースで開くURLを決める:

    • 自前のローカルHTTPサーバー (推奨): ソースコード を取得して server-python.bat もしくは server-node.bat を実行 → http://localhost:8765/。事前準備は セットアップ 参照。
    • GitHub Pages版 : 準備不要だが、予告なく更新が入る可能性あり。

  2. 通常ブラウザで設定を作り込んでJSON書き出し: http://localhost:8765/ (または GitHub Pages版) を開き、画像差し替え・口パク閾値・カスタム表情などを調整したら、設定タブから「JSONで書き出し」(peraravatar-config.json)。OBSブラウザソースに同じ設定を反映するには、後でこのJSONを読み込ませる必要があります。

  3. OBSの起動オプションにマイク許可フラグを追加: OBSのショートカット (デスクトップ等) を右クリック → プロパティ →「リンク先」を以下のように編集。

    "C:\Program Files\obs-studio\bin\64bit\obs64.exe" --use-fake-ui-for-media-stream --autoplay-policy=no-user-gesture-required

    「作業フォルダー」が空の場合は C:\Program Files\obs-studio\bin\64bit を設定。このフラグがないとブラウザソースのマイク許可が降りません。

  4. OBSでブラウザソースを追加: ソースにブラウザを追加し、以下を設定:

    • 自前のローカルHTTPサーバー (推奨) もしくは GitHub Pages版 のURLを設定。※ 設定パネルが表示されない場合は ?panel=1 をURLの末尾に追加。
    • 幅 × 高さ: 画像のアスペクト比に合わせる (例: 600×900)
    • 「ローカルファイル」: チェックしない

  5. OBSブラウザソース側でJSONを読み込み: 初回はデフォルトのアバターが表示されるので、用意しておいた peraravatar-config.json を設定タブから読み込む。以降はOBS側のlocalStorageに保存され、毎回読み込み直す必要はありません。

?panel=1 をURLに付与していた場合は削除。

× 配信中の表情固定 ×

配信中にゲームに集中してて声で発火させづらい場面や、確実に特定の表情を出したい場合は、シーン切替で表情固定するのが確実です。

  1. 表情固定シーンを表情ごとに作る

    例:

    シーン「驚き顔」のブラウザソースURLに http://localhost:8765/?custom=z（zは「びっくり」表情に割り当てたキー）

  2. OBSのホットキー設定で、各シーンへの切替に F1, F2 等を割り当て

  3. 配信中は普段「メインシーン（自動制御）」、必要な瞬間に F1 等で固定

× デフォルトのカスタム表情 ×

初期状態で3つの表情が登録済み:

表情ホットキー動作音声トリガー
びっくりZのけぞり音量90以上の維持
笑いXバウンスなし
泣きC震えなし
× ホットキー一覧 ×
キー動作
Z, X, C, V…カスタム表情（自動順番割当、自分で変更可）
Hパネル開閉
Yよそ見を強制発火（左右ランダム）
Escapeホットキー割当中のキャンセル
× URLパラメータ ×
パラメータ動作
?custom=zキー Zに割り当てた表情を固定表示（パネルも自動非表示）
?custom=笑いラベル名で指定
?custom=id表情の内部IDで指定
?panel=0パネルを強制非表示
?panel=1パネルを強制表示 (設定タブの「OBS用に起動時パネル非表示」や ?custom=… より優先。OBSブラウザソース等で操作不能になった時の復旧用)
× データ保存について ×
  • 軽量設定（閾値・アニメーション値など）: ブラウザの localStorage に保存
  • 画像データ: IndexedDB に保存。理論上はブラウザのクォータ (Chromium系ならディスク空き容量の数割) まで格納可能。実用的には合計 数百MB あたりまでが安全圏で、それ以上はJSON書き出し時にbase64化 + メモリ展開でブラウザが固まる/落ちるリスクが上がります。
  • 分離保管: URLのドメイン / ブラウザインスタンス単位で独立 (GitHub Pages版 / localhost版 / OBSブラウザソース はそれぞれ別のlocalStorage + IndexedDB)
  • 引き継ぎ: 設定タブの JSON 書き出し / 読み込みで一括移行可能。画像は base64 dataURL としてJSON内にインライン埋め込みされるので、JSONファイル1つだけで完全に環境を再現できます (代償としてファイルサイズは画像枚数次第で数MB〜数百MB)
  • 注意: シークレットモード／プライベートウィンドウでは保存されません
× 画像をパスで書き出し (上級者向け) ×

画像を細かく差し替えながら調整したい場合、毎回 JSON を書き出し直すのは手間です。設定タブの 「画像をパスで書き出し」 にチェックを入れて書き出した JSON は、画像参照を dataURL ではなく avatar/<元のファイル名> という相対パスに変換します。あらかじめ同じファイル名の画像を avatar/ フォルダ (リポジトリ直下に空フォルダで同梱) にコピーしておけば、JSON を読み込んだ環境からそのパスで画像を表示できます。以降は avatar/ 内のファイルを上書きするだけで反映されます。

手順

  1. 通常通りファイルピッカーで画像をアップロード
  2. アップロードしたのと 同じファイル名 の画像を avatar/ フォルダにコピー
  3. 設定タブで 「画像をパスで書き出し」 にチェック → 「JSONで書き出し」
  4. OBS のブラウザソースから通常通り JSON を読み込み

注意

  • avatar/ フォルダに自分でファイルを置ける環境が必要なので、自前のローカルサーバー前提です。GitHub Pages 版では使えません
  • 元のファイル名が記録されていない画像 (旧バージョンで登録したもの等) は dataURL にフォールバックされてJSON内に埋め込まれます。チェックを入れても容量が減らない場合は画像をアップロードし直してください
× トラブルシューティング ×

マイク許可が降りない

  • OBSブラウザソース: 起動フラグ --use-fake-ui-for-media-stream 必須
  • 通常ブラウザ: アドレスバー左の鍵アイコン → マイク許可
  • debug欄に protocol=file: と出る場合は file:// で開いている → GitHub Pages版 かローカルHTTPサーバー (http://localhost) で開き直す

IndexedDB容量超過エラー

  • 既存画像をいくつか削除、またはJSON書き出しでバックアップ → デフォルトに戻す
  • 登録する画像のファイルサイズを小さくする（PNG縮小・JPEG化など）

設定が消える

  • ブラウザのキャッシュ全削除、シークレットモードでは保存されません
  • 引き継ぐならJSON経由で（画像も含めて1ファイル丸ごと移動）

アバターが表示されない

  • 「通常」スロットに画像が登録されているか確認
  • debugパネルにエラーメッセージが出ていないか確認

OBSで画像が見切れる／余白が出る

  • ブラウザソースの幅・高さを画像のアスペクト比に合わせる
  • OBSのシーン変形（Ctrl+E）で画面フィットを利用する

OBSブラウザソースで設定パネルが隠れて操作できない

OBSブラウザソース内では H キーや「対話 (Interact)」モード経由でもキー入力が届かないため、「OBS用に起動時パネル非表示」 をONにすると通常の手段では設定タブを再表示できません。

復旧:

  • OBSブラウザソースの URL 末尾に ?panel=1 を付けてリロード (既に別パラメータがある場合は &panel=1)。「OBS用に起動時パネル非表示」設定や ?custom=… を無視してパネルを強制表示します
  • 設定タブで「OBS用に起動時パネル非表示」をOFFに戻したら、URL から ?panel=1 を外して通常運用に戻す
× クレジット表記 ×

本ツールを配信や個人プロジェクトで使う場合、クレジット表記は必須ではありません。ですが、表記してもらえると制作の励みになります。

標準フォーマット

Peraravatar by Ichigyun
https://gyungyun.dev/works/peraravatar

配信概要欄向け(短縮)

アバター: Peraravatar (gyungyun.dev) / @zkmy_kuro

汎用ガイドは トップページのクレジット表記 を参照。

× Contact ×

不具合報告・機能要望

Peraravatar の不具合・機能要望はこちら。環境・再現手順を書いてもらえると助かります。

お問い合わせ ▶

感想・応援メッセージ

匿名でひとこと送れます。「使ってるよ」だけでも教えてくれると嬉しいです。

マシュマロ ▶

開発支援

サーバ代やドメイン代の足しに。新機能のモチベになります。国内は OFUSE、海外は Ko-fi をどうぞ。

OFUSE ▶ Ko-fi ▶