Dashboard/Haygen/Wiki/README.md
Haygen

Wiki/README.md

heygen-avatar

A plug-n-play npm + Python package that wraps HeyGen LiveAvatar and can be dropped into any app with a 2-file integration.

Status: Code-complete — manual smoke test pending (requires HEYGEN_API_KEY) Last updated: 2026-05-05 GitHub: https://github.com/arijitchowdhury80/heygen-avatar

What it does

heygen-avatar makes HeyGen's streaming interactive avatar reusable across projects. Instead of wiring WebRTC, token proxies, event handlers, and LLM loops from scratch for every app, you npm install heygen-avatar, run npx heygen-avatar init to build your persona, and drop <HeygenAvatar> into your page.

It ships two modes: Full (HeyGen's built-in GPT-4o-mini handles everything) and Lite (you bring your own LLM — the package manages the conversation loop). Both use the same component API.

Key use cases

  1. Drop-in avatar component — import <HeygenAvatar>, pass a persona config and a backend token URL, and the avatar is live in one component.
  2. Headless integration — import useHeygenAvatar hook, own 100% of the UI, use the hook's speak, interrupt, startVoiceChat APIs directly.
  3. CLI persona builder — npx heygen-avatar init walks through an interactive wizard and writes a typed heygen.config.ts file to your project.
  4. Python backend — from heygen_avatar import fastapi_route wires a FastAPI token-proxy endpoint in one line, with PDF/URL ingestion as a bonus.

What makes it different

HeyGen's SDK is low-level: you get a WebRTC stream and a class. This package is the opinionated wrapper — it handles the token proxy pattern (API key stays server-side), the persona + knowledge prompt construction, the Lite mode conversation loop, and the 2-phase SDK initialization required to keep tests fast.

Where it fits

Haygen is a reusable infrastructure layer for any app Arijit builds that needs a live avatar:

Your App (PRISM / LENS / Algolia Central / any Next.js app)
  └─ heygen-avatar  ← THIS PACKAGE
       ├─ npm: React component + hook + server handler + CLI
       └─ pip: Python token proxy + knowledge ingestion

Its sibling project RE-Avatar (Projects/RE-Avatar) uses this package to instantiate Arijit's digital twin persona — RE-Avatar is a persona config ON TOP of heygen-avatar, not a separate avatar stack.

Document Purpose
Architecture Component map, modules, build pipeline
UserFlows Integration flows step by step
Decisions ADR index — key decisions and why
Constraints What it does NOT do (Phase 2 scope)
Status What's built, what's next
Engineering-Specs/00-Index.md Full technical spec index
Research/01-heygen-sdk-api.md HeyGen SDK API reference notes

Repository

  • Local: /Users/arijitchowdhury/AI-Development/Haygen
  • Worktree: .worktrees/feature-heygen-avatar-package
  • Branch: feature/heygen-avatar-package
  • GitHub: https://github.com/arijitchowdhury80/heygen-avatar (private)