render

type AudioUploader interface {
	// UploadAudio uploads audio content and returns a URL usable as
	// GenerateRequest.AudioURL with the same provider.
	UploadAudio(ctx context.Context, filename string, r io.Reader) (string, error)
}

type AvatarInfo struct {
	// ID is directly usable as GenerateRequest.AvatarID with the same
	// provider.
	ID string

	// Name is the human-readable avatar name.
	Name string

	// Gender is the avatar gender, when the provider reports it.
	Gender string
}

type AvatarLister interface {
	// ListAvatars returns avatars whose ID or name matches search
	// (case-insensitive substring; an empty search returns all).
	ListAvatars(ctx context.Context, search string) ([]AvatarInfo, error)
}

type Background struct {
	// Type is "color", "image", or "video".
	Type string

	// Value is a hex color or URL depending on Type.
	Value string
}

type GenerateRequest struct {
	// AvatarID identifies the presenter with the provider.
	// HeyGen: avatar_id; Tavus: replica_id; bitHuman: agent_id.
	AvatarID string

	// AudioURL is a fetchable URL to narration audio (.mp3/.wav).
	// Providers implementing AudioUploader can host local files.
	AudioURL string

	// Script is text for provider TTS. Providers that require a voice
	// read it from Extensions (e.g., "voice_id").
	Script string

	// Width and Height are the requested output dimensions in pixels.
	// Optional; provider defaults apply when zero.
	Width int

	// Height is the requested output height in pixels.
	Height int

	// Background requests a background treatment. Optional and
	// best-effort; support varies by provider.
	Background *Background

	// Title is a human-readable job/video name. Optional.
	Title string

	// Extensions holds provider-specific options
	// (e.g., "voice_id", "avatar_style", "test", "fast").
	Extensions map[string]any
}

type Job struct {
	// ID is the provider job/video identifier.
	ID string

	// Provider is the provider name (e.g., "heygen", "tavus", "bithuman").
	Provider string
}

type JobState string

type JobStatus struct {
	// ID is the provider job/video identifier.
	ID string

	// State is the normalized lifecycle state.
	State JobState

	// RawStatus is the provider-native status string, preserved for
	// logging and debugging.
	RawStatus string

	// VideoURL is the download URL, set when State is JobStateCompleted.
	// It may be a time-limited signed URL; use Provider.Download for a
	// fresh URL.
	VideoURL string

	// ThumbnailURL is a preview image URL, when the provider reports one.
	ThumbnailURL string

	// Duration is the video duration in seconds, when reported.
	Duration float64

	// ErrorCode is the provider error code, when State is JobStateFailed.
	ErrorCode string

	// ErrorMsg is the provider error message, when State is JobStateFailed.
	ErrorMsg string
}

type Provider interface {
	// Name returns the provider name (e.g., "heygen", "tavus", "bithuman").
	Name() string

	// Generate submits a video generation job. It returns as soon as the
	// provider accepts the job; use Status or Wait to track completion.
	Generate(ctx context.Context, req GenerateRequest) (*Job, error)

	// Status returns the current status of a job.
	Status(ctx context.Context, jobID string) (*JobStatus, error)

	// Download streams the completed video to dst.
	// Returns an error wrapping ErrJobNotCompleted if the job has not
	// completed successfully.
	Download(ctx context.Context, jobID string, dst io.Writer) error
}

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