avatar

type AnamConfig struct {
	// APIKey is the Anam API key.
	APIKey string

	// PersonaID is the Anam persona to use.
	PersonaID string

	// AudioConfig configures the audio format.
	AudioConfig AudioConfig
}

type AudioConfig struct {
	// SampleRate is the audio sample rate in Hz.
	// Default: 24000 (common for avatar providers)
	SampleRate int

	// Channels is the number of audio channels.
	// Default: 1 (mono)
	Channels int

	// Encoding is the audio encoding format.
	// Default: "linear16" (PCM16 little-endian)
	Encoding string
}

type AudioDestination interface {
	// CaptureFrame sends a PCM16 audio frame to the avatar.
	//
	// The frame should be little-endian PCM16 at the configured sample rate.
	// Frames are typically 20ms of audio (e.g., 960 samples at 48kHz).
	//
	// This method may block if the underlying transport is congested.
	CaptureFrame(ctx context.Context, frame []byte) error

	// Flush marks the end of an audio segment (utterance).
	//
	// The avatar should speak all buffered audio before accepting more.
	// This closes the current ByteStream and prepares for the next utterance.
	Flush(ctx context.Context) error

	// ClearBuffer interrupts current playback.
	//
	// Use this when the user interrupts the agent. The avatar should
	// stop speaking immediately and discard any buffered audio.
	//
	// This sends an RPC to the avatar worker and waits for acknowledgment.
	ClearBuffer(ctx context.Context) error

	// SampleRate returns the expected input sample rate in Hz.
	// Common values: 16000, 24000, 48000
	SampleRate() int

	// Channels returns the expected number of audio channels.
	// Typically 1 (mono).
	Channels() int

	// OnPlayback registers a callback for playback events.
	// Multiple callbacks can be registered.
	OnPlayback(callback PlaybackCallback)

	// Close releases resources associated with this audio destination.
	// After Close(), no more frames should be sent.
	Close() error
}

type AvatarMetadata struct {
	// Kind identifies this as an avatar participant.
	Kind string `json:"kind"`

	// Provider is the avatar provider name.
	Provider string `json:"provider,omitempty"`

	// AgentIdentity is the identity of the agent this avatar represents.
	AgentIdentity string `json:"agent_identity,omitempty"`
}

type BaseSession struct {
	// contains filtered or unexported fields
}

type BitHumanConfig 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 the session.
	// Required.
	AgentID string

	// AudioConfig configures the audio format.
	// Default: 24kHz mono PCM16
	AudioConfig AudioConfig
}

type Config struct {
	// Provider selects the avatar provider.
	// Supported values: "tavus", "bithuman", "heygen", "anam", "simli", "" (none/audio-only)
	// Note: "static" is not a Session provider; handle static images separately.
	Provider string

	// Tavus contains Tavus-specific configuration.
	// Used when Provider is "tavus".
	Tavus TavusConfig

	// BitHuman contains bitHuman-specific configuration.
	// Used when Provider is "bithuman".
	BitHuman BitHumanConfig

	// HeyGen contains HeyGen LiveAvatar configuration.
	// Used when Provider is "heygen".
	HeyGen HeyGenConfig

	// Anam contains Anam-specific configuration.
	// Used when Provider is "anam".
	Anam AnamConfig

	// Simli contains Simli-specific configuration.
	// Used when Provider is "simli".
	Simli SimliConfig
}

type DataStreamAudioOutput struct {
	// contains filtered or unexported fields
}

type DataStreamConfig struct {
	// Room is the LiveKit room.
	// Required.
	Room *lksdk.Room

	// DestinationIdentity is the avatar participant identity.
	// Required.
	DestinationIdentity string

	// Audio is the audio configuration.
	// Optional, defaults to DefaultAudioConfig().
	Audio AudioConfig

	// RPCTimeout is the timeout for RPC calls.
	// Default: 5 seconds
	RPCTimeout time.Duration
}

type HeyGenConfig struct {
	// APIKey is the LiveAvatar API key.
	// Note: This is different from the HeyGen video generation API key.
	// Get your key from: https://app.liveavatar.com/developers
	// Required.
	APIKey string

	// BaseURL is the LiveAvatar API base URL.
	// Default: https://api.liveavatar.com
	BaseURL string

	// AvatarID is the UUID of the avatar to use.
	// Use liveavatar.SandboxAvatarID ("65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0") for testing.
	// Required.
	AvatarID string

	// Sandbox enables sandbox mode (60s limit, no credits).
	// Recommended for development and testing.
	Sandbox bool

	// VideoQuality sets the avatar video quality.
	// Options: "very_high", "high", "medium", "low"
	// Default: "high"
	VideoQuality string

	// AudioConfig configures the audio format.
	// Default: 24kHz mono PCM16
	AudioConfig AudioConfig
}

type LiveAvatarHelper struct {
	// contains filtered or unexported fields
}

type LiveKitSession struct {
	// contains filtered or unexported fields
}

type Metrics struct {
	// AvatarJoinLatency is the time from Start() to avatar joining the room.
	AvatarJoinLatency time.Duration

	// PlaybackLatency is the time from audio send to avatar speech start.
	// This is measured per utterance.
	PlaybackLatency time.Duration

	// Provider is the avatar provider name.
	Provider string

	// Timestamp is when the metrics were collected.
	Timestamp time.Time
}

type PlaybackCallback func(event PlaybackEvent)

type PlaybackEvent struct {
	// Type is the type of playback event.
	Type PlaybackEventType

	// Position is the playback position in seconds when the event occurred.
	// Only meaningful for PlaybackFinished events.
	Position float64

	// Interrupted indicates if playback was interrupted by ClearBuffer().
	// Only meaningful for PlaybackFinished events.
	Interrupted bool
}

type PlaybackEventType string

type ProviderError struct {
	Provider string // Provider name (e.g., "tavus", "anam")
	Op       string // Operation that failed
	Err      error  // Underlying error
}

type QueueAudioOutput struct {
	// contains filtered or unexported fields
}

type Session interface {
	// AvatarIdentity returns the participant identity of the avatar worker.
	// This is the identity that appears in the room and publishes video.
	AvatarIdentity() string

	// Provider returns the provider name (e.g., "tavus", "anam", "simli").
	Provider() string

	// Start initializes the avatar session.
	//
	// This method should:
	//  1. Create a session with the avatar provider's API
	//  2. Generate a LiveKit token for the avatar to join the room
	//  3. Configure the audio output to stream to the avatar
	//
	// The avatar will join the room asynchronously. Use WaitForJoin()
	// to wait for the avatar to be ready.
	Start(ctx context.Context, opts StartOptions) error

	// WaitForJoin blocks until the avatar participant joins the room
	// and publishes the expected tracks (typically video).
	//
	// Returns an error if the timeout is exceeded or the context is cancelled.
	WaitForJoin(ctx context.Context, timeout time.Duration) error

	// AudioOutput returns the audio destination for streaming TTS audio
	// to the avatar. Returns nil if the session is not started.
	AudioOutput() AudioDestination

	// Close disconnects the avatar and cleans up resources.
	//
	// This method should:
	//  1. End the session with the avatar provider
	//  2. Remove the avatar participant from the room
	//  3. Clean up any registered RPC handlers
	Close(ctx context.Context) error
}

type SessionCallbacks struct {
	// OnMetricsCollected is called when avatar metrics are available.
	OnMetricsCollected func(metrics Metrics)

	// OnPlaybackStarted is called when the avatar starts speaking.
	OnPlaybackStarted func()

	// OnPlaybackFinished is called when the avatar finishes speaking.
	// The position is the playback position in seconds when stopped.
	// The interrupted flag indicates if playback was interrupted by
	// a ClearBuffer() call.
	OnPlaybackFinished func(position float64, interrupted bool)

	// OnAvatarJoined is called when the avatar participant joins the room.
	OnAvatarJoined func(identity string)

	// OnAvatarLeft is called when the avatar participant leaves the room.
	OnAvatarLeft func(identity string)

	// OnError is called when an error occurs.
	// This is for non-fatal errors that don't cause the session to fail.
	OnError func(err error)
}

type SessionConstructor func(cfg Config) (Session, error)

type SetupConfig struct {
	// Provider selects the avatar type:
	//   - "" or "none": Audio-only, no avatar
	//   - "static": Static image (configure StaticImage field)
	//   - "tavus": Live Tavus avatar (configure Tavus field)
	//   - "anam", "simli": Other live avatar providers
	Provider string

	// StaticImage configures a static image avatar.
	// Used when Provider is "static".
	StaticImage StaticImageConfig

	// Tavus configures a Tavus live avatar.
	// Used when Provider is "tavus".
	Tavus TavusConfig

	// Anam configures an Anam live avatar.
	// Used when Provider is "anam".
	Anam AnamConfig

	// Simli configures a Simli live avatar.
	// Used when Provider is "simli".
	Simli SimliConfig

	// LiveKit connection settings (required for live avatars)
	LiveKitURL       string
	LiveKitAPIKey    string
	LiveKitAPISecret string
}

type SetupMode string

type SetupResult struct {
	// Mode indicates the avatar mode to use.
	Mode SetupMode

	// Session is the live avatar session (nil for static or none).
	// The caller is responsible for calling Session.Close() when done.
	Session Session

	// StaticImage contains static image configuration for the agent.
	// Only populated when Mode is SetupModeStatic.
	StaticImage *StaticImageResult
}

type SimliConfig struct {
	// APIKey is the Simli API key.
	APIKey string

	// AvatarID is the Simli avatar to use.
	AvatarID string

	// AudioConfig configures the audio format.
	AudioConfig AudioConfig
}

type StartOptions struct {
	// Room is the LiveKit room the agent has joined.
	// Required.
	Room *lksdk.Room

	// AgentIdentity is the identity of the agent participant.
	// The avatar will publish tracks on behalf of this identity
	// using the lk.publish_on_behalf attribute.
	// Required.
	AgentIdentity string

	// LiveKitURL is the LiveKit server URL for the avatar to connect to.
	// This should match the URL the agent connected to.
	// Required.
	LiveKitURL string

	// LiveKitAPIKey is used to generate tokens for the avatar.
	// Required.
	LiveKitAPIKey string

	// LiveKitAPISecret is used to generate tokens for the avatar.
	// Required.
	LiveKitAPISecret string

	// Callbacks configures optional event callbacks.
	Callbacks *SessionCallbacks
}

type StaticImageConfig struct {
	// H264Path is the path to a pre-encoded H.264 keyframe file.
	// This is the recommended approach - no CGO required at runtime.
	H264Path string

	// H264Data is pre-encoded H.264 keyframe data (alternative to H264Path).
	H264Data []byte

	// UseDefault uses the embedded default OmniAgent avatar.
	// If true, H264Path and H264Data are ignored.
	UseDefault bool
}

type StaticImageResult struct {
	// H264Path is the path to the H.264 file (if using file).
	H264Path string

	// H264Data is the H.264 data (if using embedded data).
	H264Data []byte
}

type TavusConfig struct {
	// APIKey is the Tavus API key.
	// Required.
	APIKey string

	// BaseURL is the Tavus API base URL.
	// Default: https://tavusapi.com
	BaseURL string

	// PalID is the PAL (Personalized AI Likeness) to use.
	// Default: stock avatar (provider default)
	PalID string

	// FaceID is an optional face override.
	FaceID string

	// AudioConfig configures the audio format.
	// Default: 24kHz mono PCM16 (Tavus requirement)
	AudioConfig AudioConfig
}

type TokenOptions struct {
	// APIKey is the LiveKit API key.
	// Required.
	APIKey string

	// APISecret is the LiveKit API secret.
	// Required.
	APISecret string

	// RoomName is the room the avatar will join.
	// Required.
	RoomName string

	// AvatarIdentity is the participant identity for the avatar.
	// Required.
	AvatarIdentity string

	// AvatarName is the display name for the avatar participant.
	// Optional, defaults to AvatarIdentity.
	AvatarName string

	// PublishOnBehalf is the identity of the agent participant.
	// The avatar will publish tracks that appear as if they're from this participant.
	// Required.
	PublishOnBehalf string

	// TTL is the token validity duration.
	// Default: 5 minutes
	TTL time.Duration

	// Metadata is optional participant metadata.
	Metadata string
}