tts

type AudioChunk struct {
	// Data is the raw audio bytes.
	Data []byte

	// Index is the chunk sequence number (0-indexed).
	Index int

	// Final indicates this is the last chunk.
	Final bool

	// Error is set if an error occurred during synthesis.
	Error error
}

type AudioFormat struct {
	// Name is the format identifier ("mp3", "opus", "pcm", "aac", "flac").
	Name string

	// MIMEType is the content type (e.g., "audio/mpeg").
	MIMEType string

	// SampleRate is the audio sample rate in Hz.
	SampleRate int

	// BitDepth is the bits per sample (for PCM formats).
	BitDepth int

	// Channels is the number of audio channels (1=mono, 2=stereo).
	Channels int
}

type CartesiaOption func(*CartesiaService)

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

type ElevenLabsOption func(*ElevenLabsService)

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

type Factory func(spec ProviderSpec) (Service, error)

type OpenAIOption func(*OpenAIService)

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

type ProviderSpec struct {
	// ID is a stable identifier; informational only at this layer.
	ID string
	// Type selects the implementation: openai, elevenlabs, cartesia.
	Type string
	// Model overrides the provider's default voice/model. Empty uses
	// the per-provider default.
	Model string
	// BaseURL overrides the provider's default API endpoint.
	BaseURL string
	// Credential carries the resolved API key.
	Credential credentials.Credential
	// AdditionalConfig carries provider-specific extras (cartesia
	// websocket URL, etc.). Unknown keys are ignored.
	AdditionalConfig map[string]any
}

type RetryConfig struct {
	// MaxAttempts is the total number of attempts including the initial
	// call. 3 means "initial + up to 2 retries". Values < 1 are
	// treated as 1 (no retry).
	MaxAttempts int
	// InitialDelay is the base backoff before the first retry.
	InitialDelay time.Duration
	// MaxDelay caps the per-attempt backoff.
	MaxDelay time.Duration
}

type Service interface {
	// Name returns the provider identifier (for logging/debugging).
	Name() string

	// Synthesize converts text to audio.
	// Returns a reader for streaming audio data.
	// The caller is responsible for closing the reader.
	Synthesize(ctx context.Context, text string, config SynthesisConfig) (io.ReadCloser, error)

	// SupportedVoices returns available voices for this provider.
	SupportedVoices() []Voice

	// SupportedFormats returns supported audio output formats.
	SupportedFormats() []AudioFormat
}

type StreamingService interface {
	Service

	// SynthesizeStream converts text to audio with streaming output.
	// Returns a channel that receives audio chunks as they're generated.
	// The channel is closed when synthesis completes or an error occurs.
	SynthesizeStream(ctx context.Context, text string, config SynthesisConfig) (<-chan AudioChunk, error)
}

type SynthesisConfig struct {
	// Voice is the voice ID to use for synthesis.
	// Available voices vary by provider - use SupportedVoices() to list options.
	Voice string

	// Format is the output audio format.
	// Default is MP3 for most providers.
	Format AudioFormat

	// Speed is the speech rate multiplier (0.25-4.0, default 1.0).
	// Not all providers support speed adjustment.
	Speed float64

	// Pitch adjusts the voice pitch (-20 to 20 semitones, default 0).
	// Not all providers support pitch adjustment.
	Pitch float64

	// Language is the language code for synthesis (e.g., "en-US").
	// Required for some providers, optional for others.
	Language string

	// Model is the TTS model to use (provider-specific).
	// For OpenAI: "tts-1" (fast) or "tts-1-hd" (high quality).
	Model string
}

type SynthesisError struct {
	// Provider is the TTS provider that returned the error.
	Provider string

	// Code is the provider-specific error code.
	Code string

	// Message is the error message.
	Message string

	// Cause is the underlying error (if any).
	Cause error

	// Retryable indicates if the error is transient and retry may succeed.
	Retryable bool
}

type Voice struct {
	// ID is the provider-specific voice identifier.
	ID string

	// Name is a human-readable voice name.
	Name string

	// Language is the primary language code (e.g., "en", "es", "fr").
	Language string

	// Gender is the voice gender ("male", "female", "neutral").
	Gender string

	// Description provides additional voice characteristics.
	Description string

	// Preview is a URL to a voice sample (if available).
	Preview string
}