tts

Documentation

Index

• type AWS
  • func NewAWS(region string, log *slog.Logger) *AWS
  • func (a *AWS) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)
• type AWSConfig
• type Azure
  • func NewAzure(apiKey, region string, log *slog.Logger) *Azure
  • func (a *Azure) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)
• type Cache
  • func NewCache(dir string, includeAPIKey bool, log *slog.Logger) (*Cache, error)
  • func (c *Cache) Len() int
  • func (c *Cache) WrapProvider(p Provider, providerName string) Provider
• type Category
  • func Categorize(err error) Category
• type Deepgram
  • func NewDeepgram(apiKey string, log *slog.Logger) *Deepgram
  • func (d *Deepgram) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)
• type ElevenLabs
  • func NewElevenLabs(apiKey string, log *slog.Logger) *ElevenLabs
  • func (e *ElevenLabs) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)
• type Google
  • func NewGoogle(log *slog.Logger) *Google
  • func (g *Google) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)
• type Options
• type Provider
  • func NewRetrying(inner Provider, name string, log *slog.Logger) Provider
• type Result

Types

type AWS

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

AWS implements Provider using Amazon Polly.

func NewAWS

func NewAWS(region string, log *slog.Logger) *AWS

NewAWS creates an AWS Polly TTS provider.

func (*AWS) Synthesize

func (a *AWS) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)

type AWSConfig

type AWSConfig struct {
	Region    string
	AccessKey string
	SecretKey string
}

AWSConfig holds optional AWS credentials for per-request overrides.

type Azure

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

Azure implements Provider using the Azure Cognitive Speech Services REST API.

func NewAzure

func NewAzure(apiKey, region string, log *slog.Logger) *Azure

NewAzure creates an Azure TTS provider.

func (*Azure) Synthesize

func (a *Azure) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)

type Cache

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

Cache is a disk-backed TTS result cache. Each entry is stored as a single file whose name is the SHA-256 of the cache key. File format:

<mime-type>\n<raw audio bytes>

The cache is safe for concurrent use. Entries persist across restarts.

func NewCache

func NewCache(dir string, includeAPIKey bool, log *slog.Logger) (*Cache, error)

NewCache creates a Cache that stores entries under dir, creating the directory if it does not exist. When includeAPIKey is true, the API key is part of the cache key — use this when different keys map to different accounts with distinct voice clones or quotas.

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of cached entries on disk.

func (*Cache) WrapProvider

func (c *Cache) WrapProvider(p Provider, providerName string) Provider

WrapProvider returns a Provider that transparently caches synthesis results on disk. providerName is included in the cache key to prevent cross-provider collisions.

type Category

type Category string

Category classifies a synthesis failure so callers can tell a permanent misconfiguration apart from a transient upstream blip. It is published on the tts.error event, and the value set is open: consumers must treat an unrecognised value as "unknown" rather than rejecting the event.

const (
	// CategoryPermanentAuth is a rejected or missing credential (401, 403).
	CategoryPermanentAuth Category = "permanent_auth"
	// CategoryPermanentInput is a request the upstream will never accept
	// (400, 404, 422) — a bad voice name, malformed text, wrong model.
	CategoryPermanentInput Category = "permanent_input"
	// CategoryRateLimited is a 429.
	CategoryRateLimited Category = "rate_limited"
	// CategoryServiceUnavailable is an upstream 5xx.
	CategoryServiceUnavailable Category = "service_unavailable"
	// CategoryRetryable is a transient failure that is neither a 429 nor a
	// 5xx: a request timeout (408), a deadline, a transport error.
	CategoryRetryable Category = "retryable"
	// CategoryCanceled means the caller went away — the leg or room context
	// was cancelled. Terminal: there is nobody left to hear the audio.
	CategoryCanceled Category = "canceled"
	// CategoryUnknown is a failure with no status and no recognised transport
	// shape: SDK errors from AWS Polly and Google, and the providers' own
	// "no API key provided" guards.
	CategoryUnknown Category = "unknown"
	// CategoryPlayback is set by the API layer for failures raised after
	// synthesis succeeded, while streaming the audio to the leg or room
	// (internal/api/tts.go, the two playback-error publish sites). Categorize
	// never returns it.
	CategoryPlayback Category = "playback"
)

func Categorize

func Categorize(err error) Category

Categorize classifies a Synthesize error. It returns "" for a nil error.

The order is load-bearing. context.Canceled and context.DeadlineExceeded are checked before the transport arms because http.Client.Do returns a *url.Error wrapping the context error on cancellation, and every provider wraps that with %w — so checking *url.Error first would classify a hung-up caller as a retryable transport blip and keep calling the upstream.

type Deepgram

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

Deepgram implements Provider using the Deepgram TTS API.

func NewDeepgram

func NewDeepgram(apiKey string, log *slog.Logger) *Deepgram

NewDeepgram creates a Deepgram TTS provider.

func (*Deepgram) Synthesize

func (d *Deepgram) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)

type ElevenLabs

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

ElevenLabs implements Provider using the ElevenLabs streaming TTS API.

func NewElevenLabs

func NewElevenLabs(apiKey string, log *slog.Logger) *ElevenLabs

NewElevenLabs creates an ElevenLabs TTS provider.

func (*ElevenLabs) Synthesize

func (e *ElevenLabs) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)

type Google

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

Google implements Provider using Google Cloud Text-to-Speech.

func NewGoogle

func NewGoogle(log *slog.Logger) *Google

NewGoogle creates a Google Cloud TTS provider.

func (*Google) Synthesize

func (g *Google) Synthesize(ctx context.Context, text string, opts Options) (*Result, error)

type Options

type Options struct {
	Voice    string // provider-specific voice identifier
	ModelID  string // optional, provider-specific model
	Language string // optional, language code (e.g. "en-US", "pl-pl")
	Prompt   string // optional, style/tone instruction (Google Gemini TTS)
	APIKey   string // per-request API key override
}

Options controls TTS synthesis parameters.

type Provider

type Provider interface {
	Synthesize(ctx context.Context, text string, opts Options) (*Result, error)
}

Provider synthesizes text into an audio stream.

func NewRetrying

func NewRetrying(inner Provider, name string, log *slog.Logger) Provider

NewRetrying wraps inner so transient synthesis failures are retried under the package retry policy. name is the provider name, used only for logging.

type Result

type Result struct {
	Audio    io.ReadCloser
	MimeType string // "audio/mpeg", "audio/wav", etc.
}

Result holds the synthesized audio stream.