Installation Guide

AI Avatar Installation Guide

Follow these steps to run the AI Avatar project on your machine. It takes about ten minutes.

Prerequisites

• Node.js version 18 or higher installed
• A Groq API key from the Groq Console
• A VRM 1.0 avatar model file (.vrm)
• Google Chrome or Microsoft Edge for full voice support

Step 1: Open the project folder

Unzip the downloaded project, then open a terminal inside the folder.

cd ai-avatar

Step 2: Install dependencies

Run the following command and wait for it to finish.

npm install

Step 3: Create the environment file

Copy the example environment file to a new local file.

cp .env.example .env.local

Step 4: Add your API keys

Open .env.local in any editor and paste your keys.

GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile

Step 5: Add your avatar model

Place your VRM 1.0 file at the path below. You can download free models from VRoid Hub or Booth.pm, or build one with VRoid Studio.

public/models/avatar.vrm

Step 6: Start the app

Run the development server.

npm run dev

Step 7: Open it in your browser

Visit the address below in Chrome or Edge.

http://localhost:3000

Step 8: Start talking

1. Select a language: English, Hindi or Hinglish.
2. Allow microphone and camera access when the browser asks.
3. Just speak. The avatar listens, replies by voice, and lip-syncs to the audio.

Troubleshooting

• No voice output: click anywhere on the page once, since browsers block autoplay audio.
• Avatar stuck in a T-pose: your VRM file is missing proper humanoid bone mappings.
• Microphone not working: allow microphone permission in your browser settings.
• Voice sounds robotic: the server fell back to browser speech, so check the console for errors.
• Clock deprecation warning in console: harmless on three.js r183 and above, it does not affect the app.