hypersonic-heygen 2.0.4

Hypersonic HeyGen v2 — LiveAvatar (WebRTC) teaching & demo toolkit

hypersonic-HayGen-Version-2.0

hya stands for hypersonic (hy) avatar (a)

---

Overview

Hypersonic-HeyGen Version 2.0 demonstrates how to build and run a LiveAvatar (real-time, WebRTC-based AI avatar) using HeyGen’s LiveAvatar API.

This version is designed primarily for:

• Teaching / classroom demonstrations
• Technical walkthroughs
• API experimentation
• Proof-of-concept development

The demo is intentionally kept minimal, explicit, and educational, using:

• A Jupyter Notebook as the control plane
• A standard browser window (LiveKit Meet) as the interaction plane

---

What’s New in Version 2.x

Version	Description
1.x	Demo of HeyGen Interactive Avatar (legacy, non-LiveAvatar)
2.x	Demo of HeyGen LiveAvatar (real-time, WebRTC, GPT-integrated)

Version 2.x introduces:

• LiveAvatar sessions
• Context-based personas
• Real-time audio/video via LiveKit
• GPT-integrated conversational flow
• Explicit session lifecycle control (start / stop)

---

High-Level Architecture (Teaching View)

Jupyter Notebook
│
├─ Create LiveAvatar session
├─ Start session
├─ Obtain LiveKit URL + token
├─ Construct LiveKit Meet link
├─ Print + auto-open link
│
└─ (User interacts in browser)
       ├─ Camera
       ├─ Mic
       ├─ Avatar (June HR)
       ├─ GPT reasoning
       └─ Command events

This separation makes it very clear what happens on the backend vs what happens in the browser.

---

Step-by-Step Demo Flow (Version 2.0)

1. Get your LiveAvatar API key

In the LiveAvatar UI, go to:

👉 Developers → API Key 👉 URL: https://app.liveavatar.com/developers

Copy your API key.

📌 The API key is never stored in notebook outputs.

Reference (Figure-1):

![App Key](./images/app-key.png)

---

2. Run the demo notebook

Open and run:

LiveAvatar_v2_demo_mode.ipynb

The notebook will prompt you to enter the API key securely.

Alternative: environment variables

Instead of typing the key interactively, you may store it as an environment variable:

Windows (PowerShell):

setx LIVEAVATAR_API_KEY "your_api_key_here"

macOS / Linux (bash/zsh):

export LIVEAVATAR_API_KEY="your_api_key_here"

The notebook automatically checks for this variable if present.

---

3. Select a Context (persona / knowledge base)

The notebook calls:

GET https://api.liveavatar.com/v1/contexts

This returns the list of available Contexts, which define:

• Persona
• Knowledge
• Tone
• Behavioral instructions

You may also manually inspect contexts here:

👉 https://api.liveavatar.com/v1/contexts

In the demo notebook:

• You select a context by name
• The corresponding context_id is automatically resolved and fixed for the session

---

4. Avatar (Demo Using: June HR)

This demo uses a fixed avatar for clarity and repeatability.

• Avatar Name: June HR

• Avatar UUID:

  65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0
  

You can swap in any public or user-defined avatar by changing this UUID.

How to find avatar IDs

1. Visit: 👉 https://labs.heygen.com/interactive-avatar?tab=public
2. Browse Public Avatars
3. Click the three-dot menu (⋯) on an avatar
4. Choose Copy ID

(UI screenshot referenced in documentation; not embedded here)

---

5. Voice (Hard-coded for Demo Simplicity)

To keep the teaching flow simple, the voice is fixed in Version 2.0.

• Voice Name: June – Lifelike

• Voice ID:

  62bbb4b2-bb26-4727-bc87-cfb2bd4e0cc8
  

• Language: English

• Gender: Female

Voice IDs are obtained via:

GET https://api.liveavatar.com/v1/voices

You may also manually explore voices here:

👉 https://api.liveavatar.com/v1/voices

This avoids accidental mismatches (e.g., male voice on a female avatar).

---

6. Create Session Token

The notebook creates a session token using:

POST /v1/sessions/token

This binds together:

• Context
• Avatar
• Voice
• Mode (FULL)

Reference: https://docs.liveavatar.com/reference/create_session_token_v1_sessions_token_post

---

7. Start the LiveAvatar session

The session is started using:

POST /v1/sessions/start

The response returns:

• livekit_url
• livekit_client_token

These are required for real-time audio/video.

Reference: https://docs.liveavatar.com/reference/start_session_v1_sessions_start_post

---

8. Launch the LiveKit Meet demo (external browser)

The notebook constructs a URL of the form:

https://meet.livekit.io/custom?liveKitUrl=...&token=...

This link is:

• Printed clearly
• Automatically opened in your default browser

⚠️ WebRTC requires a top-level browser window. For reliability, the demo is not embedded inside Jupyter.

---

9. Interact with the Avatar

In the browser:

• Enable camera and microphone

• Speak or type messages

• Observe:

  • Avatar video
  • Synthesized voice
  • Real-time GPT responses

You may see three tiles:

• You (client)
• The avatar (heygen)
• The AI agent backend (agent-…)

This is normal for LiveAvatar FULL mode.

---

10. Stop / cleanup (Important)

When finished, return to the notebook and run Stop Session:

POST /v1/sessions/stop

Why this matters:

• LiveAvatar sessions are billable
• If you do not stop the session, credits will continue to be consumed

Reference: https://docs.liveavatar.com/reference/stop_session_v1_sessions_stop_post

---

Reference Documentation (HeyGen / LiveAvatar)

• Quick Start https://docs.liveavatar.com/docs/quick-start-guide
• LiveAvatar Configuration https://docs.liveavatar.com/docs/configuring-your-liveavatar
• FULL Mode https://docs.liveavatar.com/docs/full-mode-configurations
• Session Lifecycle https://docs.liveavatar.com/docs/live-avatar-session-lifecycle
• Command Events https://docs.liveavatar.com/docs/command-events#/
• Recommended Architecture https://docs.liveavatar.com/docs/recommended-architecture
• Migration Guide https://docs.liveavatar.com/docs/interactive-avatar-migration-guide

---

Legacy Version (Preserved)

⚠️ Do not remove this section.

The original Version 1.x documentation (Interactive Avatar demo) is preserved below unchanged.

⚠️ To run Version 1.x:

• You must explicitly install:

  hypersonic-eda==0.1.2
  

All previous content below this point remains intact for backward reference.

---

(Original README.md content continues here without modification)