Wallie AI虚拟主播框架

One-click setup

Clone and double-click. No Python knowledge needed.

Windows:

git clone https://github.com/Alradyin/wallie-V2.git
cd wallie-V2

start.bat auto-installs on first run — you can skip install.bat entirely.

macOS / Linux:

git clone https://github.com/Alradyin/wallie-V2.git
cd wallie-V2
chmod +x start.sh
./start.sh

That's it. Everything else happens in the browser.

Quick start

In your wallie directory, with venv active:

pip install piper-tts onnxruntime python scripts/download_piper_voice.py en_US-amy-medium ```

Then in the dashboard: Voice → provider: piper, path: voices/en_US-amy-medium.onnx. </details>

<details> <summary><strong>Vision setup (screen reactions)</strong></summary>

Requires a vision-capable LLM. In the dashboard:

1. Engine → toggle "Vision capable" ON
2. Use a vision model: claude-sonnet-4-5, gpt-4o, gemini-2.5-pro, or llama-4-scout on Groq
3. Vision section → toggle ON, adjust frame interval and sensitivity

The SKIP escape hatch is always active — no configuration needed. </details>

<details> <summary><strong>Chat platform setup</strong></summary>

Twitch: Add OAuth token from twitchtokengenerator.com (chat:read scope). Or leave empty for anonymous read-only.

YouTube: Drop client_secret.json in scripts/. First run opens browser for Google OAuth consent.

Kick: Just enter the channel slug. No auth needed (public Pusher WebSocket). </details>

<details> <summary><strong>VTube Studio avatar</strong></summary>

1. Run VTube Studio with API enabled (Settings → API → Enable)
2. In the dashboard: Avatar → toggle ON
3. First connect triggers a plugin approval popup in VTS — click Allow
4. Expression slots are auto-mapped from your model's hotkeys on connect. Override manually if needed
5. Adjust lipsync gain/ceiling for your voice. Viseme lip sync (spectral mouth shape) is enabled by default — disable it in Avatar config if your model doesn't have a ParamMouthForm parameter
6. Blink, body motion, and mood-reactive behaviour are enabled by default — tweak or disable per-feature in config

Works with any Live2D model that has standard parameters (MouthOpen, EyeOpenLeft/Right, FaceAngleX/Y/Z, BodyAngleX/Y/Z). </details>

<details> <summary><strong>OBS output routing</strong></summary>

Wallie outputs audio through your system's default audio device. To route it into OBS:

Windows: Install VB-CABLE. Set CABLE Input as default playback. In OBS: Audio Input Capture → CABLE Output.

macOS: Use BlackHole the same way.

Linux: PipeWire / PulseAudio loopback (pw-loopback). </details>

---

Troubleshooting

<details> <summary><strong>Audio becomes static</strong></summary>

Hit the reset audio button in the dashboard top bar. If it recurs, check logs — usually a TTS provider returning non-PCM data (detected and aborted automatically in most cases). </details>

<details> <summary><strong>AI describes generic UI ("I see a YouTube page")</strong></summary>

The SKIP escape hatch depends on the model. Smaller models (Llama-4 Scout, Gemini Flash) are worse at following it. Upgrade to Claude Sonnet or GPT-4o for better vision, or set commentary density to sparse. </details>

<details> <summary><strong>AI keeps asking questions to chat</strong></summary>

The question throttle is automatic (forces statements after one question-ending). If it persists, raise frequency penalty to 0.5–0.7 in Engine settings. </details>

<details> <summary><strong>Avatar mouth doesn't move</strong></summary>

Check that the MouthOpen parameter name matches your model (some use ParamMouthOpen or MouthOpenY). Override in Avatar → Parameter mapping. </details>

<details> <summary><strong>Avatar mouth moves but shape looks wrong</strong></summary>

Viseme lip sync drives ParamMouthForm for mouth shape (wide ↔ round). If your model uses a different parameter name, update it in Avatar → Parameters → Mouth form. If your model doesn't support mouth form at all, disable "Spectral mouth shape" in the Viseme section — lipsync will fall back to volume-only (open/close). </details>

<details> <summary><strong>Avatar doesn't blink</strong></summary>

Check that your model has EyeOpenLeft / EyeOpenRight parameters (some use ParamEyeLOpen / ParamEyeROpen). Override the parameter names in Avatar config. Blink can be disabled with enable_blink: false. </details>

<details> <summary><strong>Expressions don't fire</strong></summary>

Expression slots need to match VTS hotkey names or IDs. If auto-mapping didn't find your hotkeys (naming mismatch), map them manually in the dashboard or set expr_happy, expr_sad, etc. in your profile. Use the dashboard's "Discover hotkeys from VTS" to see available names. </details>

<details> <summary><strong>TTS returns 401</strong></summary>

Verify the key in API Keys — the masked preview should match your provider dashboard. Hit "test" to confirm. </details>

---