soniox

type Config struct {
	// APIKey is the Soniox API key, sent in the config handshake. Required.
	APIKey string `validate:"required"`
	// URL overrides the real-time endpoint; empty uses the hosted endpoint.
	URL string
	// Model is the transcription model; empty uses a current default.
	Model string
	// Language hints the spoken language; the zero value lets Soniox auto-detect.
	Language language.Language
	// SampleRate is the input audio sample rate; 0 uses the transport's rate.
	SampleRate int
	// EnableEndpointDetection emits an end-of-turn marker on detected silence;
	// nil defaults to true.
	EnableEndpointDetection *bool

	// LanguageHintsStrict confines recognition to the hinted language; nil omits
	// it and lets Soniox decide.
	LanguageHintsStrict *bool
	// Context primes the model with what the conversation is about, for the
	// models that take it; nil omits it.
	Context *Context
	// EnableSpeakerDiarization labels speakers in the transcript; nil omits it.
	EnableSpeakerDiarization *bool
	// EnableLanguageIdentification reports the language of each token; nil omits
	// it.
	EnableLanguageIdentification *bool
	// MaxEndpointDelayMs bounds how long Soniox waits before ending a turn; nil
	// omits it.
	MaxEndpointDelayMs *int
	// EndpointSensitivity tunes how readily Soniox calls a turn ended; nil omits
	// it.
	EndpointSensitivity *float64
	// EndpointLatencyAdjustmentLevel trades endpoint latency against accuracy;
	// nil omits it.
	EndpointLatencyAdjustmentLevel *int
	// ClientReferenceID labels the session in Soniox's own records; empty omits
	// it.
	ClientReferenceID string

	// TTFSP99 overrides the measured transcript latency the turn strategies
	// size their wait by; 0 uses stt.SonioxTTFSP99.
	TTFSP99 time.Duration
}

type Context struct {
	// General is structured context as key-value pairs.
	General []ContextGeneralItem `json:"general,omitempty"`
	// Text is free-form context.
	Text string `json:"text,omitempty"`
	// Terms are words the model should expect to hear.
	Terms []string `json:"terms,omitempty"`
	// TranslationTerms fix how particular terms are translated.
	TranslationTerms []ContextTranslationTerm `json:"translation_terms,omitempty"`
}

type ContextGeneralItem struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

type ContextTranslationTerm struct {
	Source string `json:"source"`
	Target string `json:"target"`
}

type Settings struct {
	settings.STT

	// LanguageHints are the languages to expect, as Soniox names them.
	LanguageHints settings.Opt[[]string] `settings:"language_hints"`
	// LanguageHintsStrict confines recognition to the languages hinted.
	LanguageHintsStrict settings.Opt[bool] `settings:"language_hints_strict"`
	// Context primes the model with what the conversation is about.
	Context settings.Opt[Context] `settings:"context"`
	// EnableSpeakerDiarization labels speakers in the transcript.
	EnableSpeakerDiarization settings.Opt[bool] `settings:"enable_speaker_diarization"`
	// EnableLanguageIdentification reports the language of each token.
	EnableLanguageIdentification settings.Opt[bool] `settings:"enable_language_identification"`
	// MaxEndpointDelayMs bounds how long Soniox waits before ending a turn.
	MaxEndpointDelayMs settings.Opt[int] `settings:"max_endpoint_delay_ms"`
	// EndpointSensitivity tunes how readily Soniox calls a turn ended.
	EndpointSensitivity settings.Opt[float64] `settings:"endpoint_sensitivity"`
	// EndpointLatencyAdjustmentLevel trades endpoint latency against accuracy.
	EndpointLatencyAdjustmentLevel settings.Opt[int] `settings:"endpoint_latency_adjustment_level"`
	// ClientReferenceID labels the session in Soniox's own records.
	ClientReferenceID settings.Opt[string] `settings:"client_reference_id"`
}

type TTSConfig struct {
	// APIKey is the Soniox API key, sent in the stream configuration. Required.
	APIKey string `validate:"required"`
	// URL overrides the synthesis WebSocket endpoint; empty uses the hosted
	// endpoint.
	URL string
	// Model is the synthesis model; empty uses a current default.
	Model string
	// Voice is a stock voice name (for example "Adrian") or the UUID of a cloned
	// voice belonging to the API key's project; empty uses a default.
	Voice string
	// Language for synthesis; the zero value leaves it unset and lets Soniox
	// decide. Soniox takes the base code, so a regional language is sent as its
	// base.
	Language language.Language
	// SampleRate is the PCM rate requested from Soniox and emitted downstream;
	// 0 uses 24 kHz. Soniox accepts 8000, 16000, 24000, 44100 and 48000.
	SampleRate int `validate:"omitempty,oneof=8000 16000 24000 44100 48000"`
	// Speed multiplies the speaking rate from 0.7 to 1.3; nil leaves it unset
	// and uses Soniox's default of 1.0.
	Speed *float64 `validate:"omitempty,min=0.7,max=1.3"`
	// WordTimestamps requests per-character timings and drives the word-aligned
	// text path: the TTS base emits a TTSTextFrame for each spoken word as its
	// audio plays, mapped back to its original written form, so the assistant
	// context records only what was actually spoken before an interruption. It
	// is on by default; set it to false to fall back to aggregated text frames.
	WordTimestamps *bool
}