tts

type CapabilityReporter ¶ added in v0.46.0

type CapabilityReporter interface {
	Capabilities() []speechkit.Capability
}

CapabilityReporter is an optional interface a provider can implement to self-describe its capabilities, so routing can query them instead of string-matching profile IDs. It is intentionally NOT part of Provider, so existing implementations and test doubles are unaffected.

type Deepgram ¶ added in v0.46.0

type Deepgram struct {
	BaseURL    string
	Validation netsec.ValidationOptions
	// contains filtered or unexported fields
}

Deepgram implements Provider using the Deepgram Aura-2 text-to-speech REST API (POST /v1/speak). It reuses the Deepgram API key shared with the STT and Voice Agent adapters. Aura voices are selected via the model id (e.g. "aura-2-thalia-en"); there is no separate voice parameter.

Aura REST caps a single request at 2000 characters, so longer text is split on sentence/word boundaries. Raw concatenation is correct for streaming codecs (mp3, linear16/pcm, ogg-opus). WAV is handled specially: a multi-chunk WAV request is fetched as linear16 PCM and the joined PCM is wrapped in a single RIFF header (see encodeWAV), so the result is always one valid WAV.

func NewDeepgram(opts DeepgramOpts) *Deepgram

func (d *Deepgram) CloseIdleConnections()

func (d *Deepgram) Health(ctx context.Context) error

func (d *Deepgram) Kind() ProviderKind

func (d *Deepgram) Name() string

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

type DeepgramOpts ¶ added in v0.46.0

type DeepgramOpts struct {
	APIKey string
	Model  string // Aura-2 voice id, e.g. "aura-2-thalia-en"; empty => locale default
}

DeepgramOpts configures the Deepgram Aura TTS provider.

type EnabledProviders ¶ added in v0.46.0

type EnabledProviders struct {
	OpenAI      *OpenAIOpts
	Google      *GoogleOpts
	Deepgram    *DeepgramOpts
	HuggingFace *HuggingFaceOpts
	Piper       *PiperOpts
	// PreferredProfileID optionally pins the provider matching this
	// model_selection profile to the front of the strategy order.
	PreferredProfileID string
}

EnabledProviders carries the per-provider options a host has already resolved from its own config (env secrets, model/voice defaults). Nil fields are skipped. It lets the Device- and Server-Targets share one router-assembly path (BuildRouter) while each keeps its own config-resolution specifics.

type Google ¶ added in v0.46.0

type Google struct {
	BaseURL    string
	Validation netsec.ValidationOptions
	// contains filtered or unexported fields
}

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

BaseURL is configurable for testing. It is validated against Validation on every request. Default Validation is strict (public https only).

func NewGoogle(opts GoogleOpts) *Google

func (*Google) Capabilities() []speechkit.Capability

func (g *Google) CloseIdleConnections()

func (g *Google) Health(ctx context.Context) error

func (g *Google) Kind() ProviderKind

func (g *Google) Name() string

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

type GoogleOpts ¶ added in v0.46.0

type GoogleOpts struct {
	APIKey string
	Voice  string // e.g. "de-DE-Neural2-B", "en-US-Neural2-J"
}

GoogleOpts configures the Google TTS provider.

type HuggingFace ¶ added in v0.46.0

type HuggingFace struct {
	BaseURL    string
	Validation netsec.ValidationOptions
	// contains filtered or unexported fields
}

HuggingFace implements Provider using the HuggingFace Inference API with text-to-speech models (e.g. parler-tts).

BaseURL is configurable for testing. It is validated against Validation on every request. Default Validation is strict (public https only).

func NewHuggingFace(opts HuggingFaceOpts) *HuggingFace

func (*HuggingFace) Capabilities() []speechkit.Capability

func (h *HuggingFace) CloseIdleConnections()

func (h *HuggingFace) Health(ctx context.Context) error

func (h *HuggingFace) Kind() ProviderKind

func (h *HuggingFace) Name() string

func (h *HuggingFace) Synthesize(ctx context.Context, text string, opts SynthesizeOpts) (*Result, error)

type HuggingFaceOpts ¶ added in v0.46.0

type HuggingFaceOpts struct {
	Token string // HF API token
	Model string // Model ID, e.g. "Qwen/Qwen3-TTS-12Hz-1.7B-Base"
}

HuggingFaceOpts configures the HuggingFace TTS provider.

type OpenAI ¶ added in v0.46.0

type OpenAI struct {
	BaseURL    string
	Validation netsec.ValidationOptions
	// contains filtered or unexported fields
}

OpenAI implements Provider using the OpenAI TTS API.

BaseURL is configurable for testing. It is validated against Validation on every request. Default Validation is strict (public https only).

func NewOpenAI(opts OpenAIOpts) *OpenAI

func (*OpenAI) Capabilities() []speechkit.Capability

func (o *OpenAI) CloseIdleConnections()

func (o *OpenAI) Health(ctx context.Context) error

func (o *OpenAI) Kind() ProviderKind

func (o *OpenAI) Name() string

func (o *OpenAI) Synthesize(ctx context.Context, text string, opts SynthesizeOpts) (*Result, error)

type OpenAIOpts ¶ added in v0.46.0

type OpenAIOpts struct {
	APIKey string
	Model  string // "tts-1" or "tts-1-hd"
	Voice  string // alloy, echo, fable, onyx, nova, shimmer
}

OpenAIOpts configures the OpenAI TTS provider.

type Piper ¶ added in v0.46.0

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

Piper implements Provider via the `piper` command-line binary. The binary writes a WAV PCM stream to stdout when invoked with

piper --model <voice.onnx> --output-raw < input.txt

or `--output_file -` for a WAV-wrapped stream. Phase 3 of the voice-companion roadmap uses Piper as the all-local TTS so the Voice-Companion can talk without any cloud key.

The implementation does NOT bundle voice models. Operators run `scripts/prepare-piper-voices.ps1` once to download the desired voices into PiperOpts.VoiceDir. Default voice maps to <VoiceDir>/ en_US-amy-medium.onnx; locale "de" looks up de_DE-thorsten-medium.

func NewPiper(opts PiperOpts) (*Piper, error)

func (*Piper) Capabilities() []speechkit.Capability

func (p *Piper) Health(ctx context.Context) error

func (*Piper) Kind() ProviderKind

func (*Piper) Name() string

func (p *Piper) Probe(ctx context.Context, voice, locale string) (*Result, error)

func (p *Piper) Synthesize(ctx context.Context, text string, opts SynthesizeOpts) (*Result, error)

type PiperOpts ¶ added in v0.46.0

type PiperOpts struct {
	// Binary is the absolute or PATH-relative `piper` executable.
	// Empty defaults to "piper" (must be on $PATH).
	Binary string

	// VoiceDir is the filesystem root containing the .onnx voice
	// model files. Required.
	VoiceDir string

	// DefaultVoices maps a locale code (e.g. "en", "de") to a
	// voice-model filename inside VoiceDir. Falls back to the en_US
	// Amy medium voice when an entry is missing.
	DefaultVoices map[string]string

	// Timeout caps the subprocess execution. Zero defaults to 30 s
	// — generous because Piper warm-load on CPU can take several
	// seconds for a first synthesis.
	Timeout time.Duration
}

PiperOpts configures the local Piper subprocess.

type PiperVoiceInfo ¶ added in v0.46.0

type PiperVoiceInfo struct {
	Filename string `json:"filename"`
	Locale   string `json:"locale"`  // short code, e.g. "en", "de"
	Region   string `json:"region"`  // e.g. "US", "DE"; empty when missing
	Name     string `json:"name"`    // e.g. "amy", "thorsten"
	Quality  string `json:"quality"` // e.g. "low", "medium", "high"
	SizeKB   int    `json:"size_kb"`
}

PiperVoiceInfo is one entry from a voice-directory scan. Filename is the basename inside VoiceDir (e.g. "en_US-amy-medium.onnx"). The remaining fields are best-effort parses of the rhasspy/piper-voices naming convention <lang>_<REGION>-<name>-<quality>.onnx; when the filename does not follow that pattern only Filename is populated and the other fields remain empty.

func ListPiperVoices(voiceDir string) ([]PiperVoiceInfo, error)

type Provider ¶

type Provider interface {
	Synthesize(ctx context.Context, text string, opts SynthesizeOpts) (*Result, error)
	Name() string
	Kind() ProviderKind
	Health(ctx context.Context) error
}

Provider defines the interface for text-to-speech backends.

func OrderByPreferredProvider(providers []Provider, preferred string) []Provider

type ProviderKind ¶

type ProviderKind string

ProviderKind identifies whether a provider is local, cloud-routed, or a direct external API. Router strategies use this instead of provider names.

const (
	ProviderKindLocalBuiltIn   ProviderKind = "local_built_in"
	ProviderKindLocalProvider  ProviderKind = "local_provider"
	ProviderKindCloudProvider  ProviderKind = "cloud_provider"
	ProviderKindDirectProvider ProviderKind = "direct_provider"
)

type ResolvedSynthesizeOptions ¶ added in v0.46.0

type ResolvedSynthesizeOptions struct {
	Locale    string
	Voice     string
	Speed     float64
	Format    string
	Effective provideropts.EffectiveOptions
}

func ResolveSynthesizeOptions(provider, profileID string, opts SynthesizeOpts, providerDefaults, providerOverrides provideropts.Values) ResolvedSynthesizeOptions

type Result ¶

type Result struct {
	Audio      []byte
	Format     string
	SampleRate int
	Duration   time.Duration
	Provider   string
	Voice      string
}

Result holds the output of a TTS synthesis.

type Router ¶

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

Router selects and falls back between TTS providers.

func BuildRouter(strategy Strategy, enabled EnabledProviders) (router *Router, ok bool, notes []string)

func NewRouter(strategy Strategy, providers ...Provider) *Router

func (r *Router) CloseIdleConnections()

func (r *Router) HealthCheck(ctx context.Context) map[string]error

func (r *Router) SetProviders(providers ...Provider)

func (r *Router) Synthesize(ctx context.Context, text string, opts SynthesizeOpts) (res *Result, err error)

type Service ¶

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

Service is a small stable facade over Router. It gives embedders one construction point while still letting them provide their own providers.

func NewService(router *Router, opts ...ServiceOption) (*Service, error)

func (s *Service) Router() *Router

func (s *Service) Synthesize(ctx context.Context, text string, opts ...SynthesizeOpts) (*Result, error)

type ServiceOption ¶

type ServiceOption func(*Service)

func WithDefaultOpts(opts SynthesizeOpts) ServiceOption

type Strategy ¶

type Strategy string

Strategy determines how Router selects providers.

const (
	StrategyCloudFirst Strategy = "cloud-first"
	StrategyLocalFirst Strategy = "local-first"
	StrategyCloudOnly  Strategy = "cloud-only"
	StrategyLocalOnly  Strategy = "local-only"
)

type SynthesizeOpts ¶

type SynthesizeOpts struct {
	Locale          string
	Voice           string
	Speed           float64
	Format          string
	Options         provideropts.Values
	ProviderOptions provideropts.Values
	// ProviderOptionsByProvider holds provider-keyed overrides that the Router
	// applies to the selected provider via ForProvider, so one request can
	// carry per-provider tuning without the caller knowing which provider wins.
	ProviderOptionsByProvider map[string]provideropts.Values
}

SynthesizeOpts configures a single TTS request.

func (o SynthesizeOpts) ForProvider(provider string) SynthesizeOpts