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 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
}

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
}