liveavatar-debug

사용 방법

설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.

npx skills add https://github.com/heygen-com/liveavatar-agent-skills --skill liveavatar-debug

시작 전 확인

설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.

원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

Most likely: Wrong auth header.

Endpoint	Correct auth
`POST /v1/sessions/token`	`X-API-KEY: <api_key>`
`POST /v1/sessions/start`	`Authorization: Bearer <session_token>`

Common mistakes: using API key on /start, using Bearer token on /token, putting API key in Bearer format.

Events not received (FULL Mode)

Subscribed to correct topics? Send to agent-control, receive from agent-response
LiveKit room connected? Check connection state
Parsing JSON correctly? Events have event_type, event_id, session_id

WebSocket events silently dropped (LITE Mode)

Most likely: Sending before `connected`.

Wait for {"type": "session.state_updated", "state": "connected"} before sending any commands.

Also check:

Using correct event names? LITE uses agent.*, not avatar.* (that's FULL)
WebSocket still open? 5-min inactivity timeout

Session times out

5 minutes of inactivity kills the session.

FULL: POST /v1/sessions/keep-alive with Bearer <session_token>
LITE: {"type": "session.keep_alive", "event_id": "..."} via WebSocket

Send every 2-3 minutes.

Sandbox won't start

[ ] is_sandbox: true set in session token
[ ] Avatar ID is dd73ea75-1218-4ef3-92ce-606d5f7fbc0a (sessions) or 65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0 (embeds)
[ ] Not using a different avatar with sandbox mode

~1 minute auto-termination is expected behavior.

Image avatar fails / no audio

Image avatars have no auto-generated voice. Specify voice_id in avatar_persona. Browse voices at GET /v1/voices.

Custom LLM / TTS not working

LLM checklist:

[ ] Secret: secret_type: "LLM_API_KEY"
[ ] Config: correct model, secret_id, base_url
[ ] llm_configuration_id in session token
[ ] Endpoint supports OpenAI /chat/completions protocol

TTS checklist:

[ ] Secret: secret_type: "ELEVENLABS_API_KEY"
[ ] Voice imported via POST /v1/voices/third_party
[ ] Using the returned LiveAvatar voice_id (not the ElevenLabs ID)

CORS / network errors

API calls should come from backend, not browser
Allow outbound wss:// for LiveKit and WebSocket
Allow *.livekit.cloud, api.liveavatar.com, embed.liveavatar.com

General approach

Start with sandbox mode to eliminate billing issues
Check session state: GET /v1/sessions/{id}
Check transcript: GET /v1/sessions/{id}/transcript
Check credits: GET /v1/users/credits
Verify you're not mixing FULL and LITE event systems