stt

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

type Provider interface {
	// Name returns the provider name.
	Name() string

	// Transcribe converts audio to text (batch mode).
	Transcribe(ctx context.Context, audio []byte, config TranscriptionConfig) (*TranscriptionResult, error)

	// TranscribeFile transcribes audio from a file path.
	TranscribeFile(ctx context.Context, filePath string, config TranscriptionConfig) (*TranscriptionResult, error)

	// TranscribeURL transcribes audio from a URL.
	TranscribeURL(ctx context.Context, url string, config TranscriptionConfig) (*TranscriptionResult, error)
}

type Segment struct {
	// Text is the transcribed text for this segment.
	Text string

	// StartTime is when the segment starts.
	StartTime time.Duration

	// EndTime is when the segment ends.
	EndTime time.Duration

	// Confidence is the average confidence for this segment.
	Confidence float64

	// Speaker is the speaker identifier (if diarization enabled).
	Speaker string

	// Words contains word-level details (if enabled).
	Words []Word

	// Language is the detected language for this segment.
	Language string
}

type StreamEvent struct {
	// Type is the event type.
	Type StreamEventType

	// Transcript is the current transcript (partial or final).
	Transcript string

	// IsFinal indicates if this is a final (non-interim) result.
	IsFinal bool

	// Segment contains segment details for final results.
	Segment *Segment

	// SpeechStarted indicates voice activity started.
	SpeechStarted bool

	// SpeechEnded indicates voice activity ended.
	SpeechEnded bool

	// Error contains any error that occurred.
	Error error
}

type StreamEventType string

type StreamingProvider interface {
	Provider

	// TranscribeStream starts a streaming transcription session.
	// Returns a writer for sending audio and a channel for receiving events.
	TranscribeStream(ctx context.Context, config TranscriptionConfig) (io.WriteCloser, <-chan StreamEvent, error)
}

type Transcript struct {
	// Schema is the JSON Schema URL for validation.
	Schema string `json:"$schema"`

	// Version is the format version (e.g., "1.0").
	Version string `json:"version"`

	// Text is the complete transcription text.
	Text string `json:"text"`

	// Language is the detected or specified language (BCP-47 code).
	Language string `json:"language,omitempty"`

	// LanguageConfidence is the confidence score for language detection (0.0-1.0).
	LanguageConfidence float64 `json:"language_confidence,omitempty"`

	// Duration is the audio duration (marshals as milliseconds in JSON).
	Duration duration.DurationMilliseconds `json:"duration_ms"`

	// Segments contains the transcript broken into segments.
	Segments []TranscriptSegment `json:"segments,omitempty"`

	// Metadata contains information about how the transcript was generated.
	Metadata TranscriptMetadata `json:"metadata"`
}

type TranscriptMetadata struct {
	// Provider is the STT provider used (e.g., "deepgram", "openai").
	Provider string `json:"provider"`

	// Model is the provider-specific model used (if specified).
	Model string `json:"model,omitempty"`

	// CreatedAt is the ISO 8601 timestamp when the transcript was created.
	CreatedAt string `json:"created_at"`

	// AudioFile is the original audio file path or URL (if available).
	AudioFile string `json:"audio_file,omitempty"`

	// Options contains the transcription options that were used.
	Options *TranscriptOptions `json:"options,omitempty"`
}

type TranscriptOptions struct {
	// Language is the requested language (if specified).
	Language string `json:"language,omitempty"`

	// EnablePunctuation indicates if punctuation was enabled.
	EnablePunctuation bool `json:"enable_punctuation,omitempty"`

	// EnableWordTimestamps indicates if word timestamps were enabled.
	EnableWordTimestamps bool `json:"enable_word_timestamps,omitempty"`

	// EnableSpeakerDiarization indicates if speaker diarization was enabled.
	EnableSpeakerDiarization bool `json:"enable_speaker_diarization,omitempty"`
}

type TranscriptSegment struct {
	// Text is the transcribed text for this segment.
	Text string `json:"text"`

	// Start is the start time (marshals as milliseconds in JSON).
	Start duration.DurationMilliseconds `json:"start_ms"`

	// End is the end time (marshals as milliseconds in JSON).
	End duration.DurationMilliseconds `json:"end_ms"`

	// Speaker is the speaker identifier (if diarization is enabled).
	Speaker string `json:"speaker,omitempty"`

	// Confidence is the average confidence score for this segment (0.0-1.0).
	Confidence float64 `json:"confidence,omitempty"`

	// Language is the detected language for this segment (if different from overall).
	Language string `json:"language,omitempty"`

	// Words contains word-level details (if word timestamps are enabled).
	Words []TranscriptWord `json:"words,omitempty"`
}

type TranscriptWord struct {
	// Text is the transcribed word.
	Text string `json:"text"`

	// Start is the start time (marshals as milliseconds in JSON).
	Start duration.DurationMilliseconds `json:"start_ms"`

	// End is the end time (marshals as milliseconds in JSON).
	End duration.DurationMilliseconds `json:"end_ms"`

	// Speaker is the speaker identifier (if diarization is enabled).
	Speaker string `json:"speaker,omitempty"`

	// Confidence is the recognition confidence (0.0-1.0).
	Confidence float64 `json:"confidence,omitempty"`
}

type TranscriptionConfig struct {
	// Language is the BCP-47 language code (e.g., "en-US").
	// Leave empty for automatic detection.
	Language string

	// Model is the provider-specific model identifier (optional).
	Model string

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

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

	// Encoding is the audio encoding ("pcm", "mp3", "wav", "opus", "flac").
	Encoding string

	// EnablePunctuation adds punctuation to transcription.
	EnablePunctuation bool

	// EnableWordTimestamps includes word-level timestamps.
	EnableWordTimestamps bool

	// EnableSpeakerDiarization identifies different speakers.
	EnableSpeakerDiarization bool

	// MaxSpeakers is the maximum number of speakers to detect (for diarization).
	MaxSpeakers int

	// Keywords are words/phrases to boost recognition accuracy.
	Keywords []string

	// VocabularyID is a provider-specific custom vocabulary ID.
	VocabularyID string

	// Extensions holds provider-specific settings.
	// Keys should be namespaced by provider (e.g., "deepgram.tier", "elevenlabs.num_speakers").
	// Use provider-specific helper functions for type-safe access.
	Extensions map[string]any

	// Hook provides observability for STT operations.
	// If nil, no hooks are called.
	Hook observability.STTHook
}

type TranscriptionResult struct {
	// Text is the full transcription text.
	Text string

	// Segments contains segment-level details.
	Segments []Segment

	// Language is the detected language.
	Language string

	// LanguageConfidence is the confidence in language detection.
	LanguageConfidence float64

	// Duration is the audio duration.
	Duration time.Duration
}

type Word struct {
	// Text is the transcribed word.
	Text string

	// StartTime is when the word starts.
	StartTime time.Duration

	// EndTime is when the word ends.
	EndTime time.Duration

	// Confidence is the recognition confidence (0.0 to 1.0).
	Confidence float64

	// Speaker is the speaker identifier (if diarization enabled).
	Speaker string
}