Documentation
¶
Overview ¶
Package bithuman provides bitHuman avatar integration for omni-livekit voice agents.
bitHuman is a real-time avatar animation platform that creates digital avatars with lip-sync to audio at 25 FPS. It supports both realistic humans and animated characters, and can run on CPU without requiring a GPU.
Quick Start ¶
Create a bitHuman avatar session:
session, err := bithuman.NewSession(bithuman.SessionConfig{
APIKey: os.Getenv("BITHUMAN_API_KEY"),
AgentID: "your-agent-id",
})
if err != nil {
return err
}
err = session.Start(ctx, avatar.StartOptions{
Room: room,
AgentIdentity: "agent-123",
LiveKitURL: "wss://your-livekit-server.com",
LiveKitAPIKey: os.Getenv("LIVEKIT_API_KEY"),
LiveKitAPISecret: os.Getenv("LIVEKIT_API_SECRET"),
})
if err != nil {
return err
}
// Wait for avatar to join
err = session.WaitForJoin(ctx, 30*time.Second)
if err != nil {
return err
}
// Stream TTS audio to avatar
audioOut := session.AudioOutput()
audioOut.CaptureFrame(ctx, pcmFrame)
audioOut.Flush(ctx)
// Clean up
session.Close(ctx)
Configuration ¶
Required environment variables:
- BITHUMAN_API_KEY: Your bitHuman API key
Required configuration:
- AgentID: The bitHuman agent ID to use for the session
Optional configuration:
- BaseURL: Custom API URL (default: https://api.bithuman.ai)
Agents ¶
bitHuman uses agents to define avatar appearance and behavior. Agents can be realistic humans or animated characters. Create agents via the bitHuman dashboard or API.
Audio Format ¶
bitHuman expects audio at 24kHz sample rate, mono, PCM16 format. The DataStreamAudioOutput automatically handles streaming to the avatar.
Features ¶
- Realistic and animated character support
- CPU-only rendering (no GPU required)
- <100ms latency
- LiveKit native integration
- Self-hostable for privacy
Index ¶
- type Client
- func (c *Client) CreateSession(ctx context.Context, req CreateSessionRequest) (*CreateSessionResponse, error)
- func (c *Client) EndSession(ctx context.Context, sessionID string) error
- func (c *Client) GetAgent(ctx context.Context, agentID string) (*api.Agent, error)
- func (c *Client) SDK() *bithumansdk.Client
- func (c *Client) Speak(ctx context.Context, agentID string, text string) error
- type ClientConfig
- type CreateSessionRequest
- type CreateSessionResponse
- type Session
- type SessionConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps the bithuman-go SDK for avatar session management.
func NewClient ¶
func NewClient(cfg ClientConfig) (*Client, error)
NewClient creates a new bitHuman API client using the bithuman-go SDK.
func (*Client) CreateSession ¶
func (c *Client) CreateSession(ctx context.Context, req CreateSessionRequest) (*CreateSessionResponse, error)
CreateSession creates a new real-time session with the bitHuman API.
This initiates the avatar session. If LiveKitURL and LiveKitToken are provided, the avatar will connect to the specified external LiveKit room. Otherwise, bitHuman provides its own LiveKit connection details.
func (*Client) EndSession ¶
EndSession ends an active session.
This stops the avatar and cleans up resources on the bitHuman side.
func (*Client) SDK ¶
func (c *Client) SDK() *bithumansdk.Client
SDK returns the underlying bithuman-go SDK client for advanced usage.
type ClientConfig ¶
type ClientConfig struct {
// APIKey is the bitHuman API key.
// Required.
APIKey string
// BaseURL is the bitHuman API base URL.
// Default: https://api.bithuman.ai
BaseURL string
// HTTPClient is an optional custom HTTP client.
// Default: http.Client with 30s timeout
HTTPClient *http.Client
}
ClientConfig configures the bitHuman API client.
type CreateSessionRequest ¶
type CreateSessionRequest struct {
// AgentID is the bitHuman agent to use for this session.
// Required.
AgentID string
// LiveKitURL is the LiveKit WebSocket URL for the avatar to connect to.
// Optional - if provided, avatar will join the specified LiveKit room.
LiveKitURL string
// LiveKitToken is the JWT token for the avatar to join the room.
// Optional - if provided with LiveKitURL, avatar uses external LiveKit.
LiveKitToken string
}
CreateSessionRequest is the request to create a real-time session.
type CreateSessionResponse ¶
type CreateSessionResponse struct {
// SessionID is the unique identifier for the session.
SessionID string
// LiveKitURL is the LiveKit WebSocket URL (if using bitHuman's LiveKit).
LiveKitURL string
// LiveKitToken is the JWT token for the avatar (if using bitHuman's LiveKit).
LiveKitToken string
}
CreateSessionResponse is the response from creating a session.
type Session ¶
type Session struct {
*avatar.BaseSession
// contains filtered or unexported fields
}
Session implements avatar.Session for bitHuman avatars.
func NewSession ¶
func NewSession(cfg SessionConfig) (*Session, error)
NewSession creates a new bitHuman avatar session.
type SessionConfig ¶
type SessionConfig struct {
// APIKey is the bitHuman API key.
// Required.
APIKey string
// BaseURL is the bitHuman API base URL.
// Default: https://api.bithuman.ai
BaseURL string
// AgentID is the bitHuman agent to use for this session.
// Required.
AgentID string
// AudioConfig configures the audio format.
// Default: 24kHz mono PCM16
AudioConfig avatar.AudioConfig
}
SessionConfig configures a bitHuman avatar session.
Source Files