Liveavatar Debug
This is a symptom-based troubleshooting guide for when your LiveAvatar integration breaks. It covers the most common failure modes: silent avatars (usually missing context_id in FULL mode), garbled audio (wrong PCM format in LITE), auth header mixups between endpoints, and dropped WebSocket events. The format is practical, each section starts with "most likely cause" and gives you a checklist or quick fix. Particularly useful is the side-by-side comparison of FULL vs LITE event systems, since mixing them is apparently a frequent mistake. If you're building against HeyGen's LiveAvatar API and hitting weird behavior with no clear error messages, this will save you hours of guessing.
- skills.sh installs
- 1.1K
- GitHub stars
- 16
- last updated
- Aug 21, 2026
Install
$ npx -y skills add heygen-com/liveavatar-agent-skills --skill liveavatar-debug --agent claude-codeInstalls into .claude/skills of the current project.
Files
LiveAvatar Debugging Guide
Symptom-based troubleshooting for LiveAvatar integrations. Find your symptom below and follow the fix.
Avatar is silent / not responding to speech
Most likely: Missing context_id in FULL Mode.
Without a context_id, the avatar enters restricted mode — streams video but ignores user input. No error thrown.
Fix: Create a context via POST /v1/contexts with at least a prompt field. Include the returned context_id in your session token's avatar_persona.
Other causes:
- Browser mic permissions blocked (check
allow="microphone"on iframe) - Push-to-Talk enabled but PTT events not being sent
- OS-level mic mute
Audio is garbled or distorted (LITE Mode)
Most likely: Wrong audio format.
Required: PCM 16-bit signed, 24KHz, base64. No error returned for wrong format.
Checklist:
- Sample rate is exactly 24,000 Hz
- Raw PCM (no WAV/MP3/OGG headers)
- 16-bit signed, not 8-bit or 32-bit float
- Base64 encoded
- Chunks under 1MB
Quick test: Send a known-good 440Hz test tone. If it works but your TTS doesn't, resample your TTS output.
401 error / session fails to start
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageDetails
- Repository
- github.com/heygen-com/liveavatar-agent-skills
- Categories
- Backend & APIs, AI & Agent Building, Debugging
- First seen
- Jun 3, 2026
More from heygen-com/liveavatar-agent-skills
All 3Recommended
More Backend & APIs
create-callvapiai/skillsCreate outbound phone calls, web calls, and batch calls using the Vapi API. Use when making automated calls, testing voice assistants, scheduling call campaigns1.1Kskills.sh installs
marketplace-catalog-syncvtex/skillsApply when building catalog or SKU synchronization logic for VTEX marketplace seller connectors. Covers the changenotification endpoint, SKU suggestion lifecycl1.1Kskills.sh installsmarketplace-order-hookvtex/skillsApply when implementing order integration hooks, feeds, or webhook handlers for VTEX marketplace connectors. Covers Feed v3 (pull) vs Hook (push), filter types 1.1Kskills.sh installs
runpoddigitalsamba/claude-code-video-toolkitCloud GPU processing via RunPod serverless. Use when setting up RunPod endpoints, deploying Docker images, managing GPU resources, troubleshooting endpoint issu1.1Kskills.sh installs
qiaomu-opencli-browserjoeseesun/qiaomu-opencli-skillsMake websites accessible for AI agents. Navigate, click, type, extract, wait — using Chrome with existing login sessions. No LLM API key needed.1.1Kskills.sh installspayment-provider-frameworkvtex/skillsApply when designing or implementing a Payment Connector in VTEX IO. Covers PPF implementation, TypeScript 3.9.7 builder-hub constraints and safe dependency res1Kskills.sh installs