stt

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 18, 2026 License: Apache-2.0 Imports: 17 Imported by: 1

Documentation

Overview

Package stt provides a speech-to-text client for OpenAI-compatible STT APIs (ox-whisper, OpenAI Whisper, etc.) via multipart upload.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Bool 

func Bool(b bool) *bool

Bool is a helper that returns a pointer to b, for use with *bool fields in StreamParams (e.g. stt.StreamParams{VAD: stt.Bool(false)}).

Types

type ChannelStream 

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

ChannelStream wraps StreamClient with Go channels instead of callbacks.

func StreamWithChannels 

func StreamWithChannels(ctx context.Context, baseURL string, params StreamParams) (*ChannelStream, error)

StreamWithChannels creates a streaming session returning Go channels.

func StreamWithChannelsAndAPIKey 

func StreamWithChannelsAndAPIKey(ctx context.Context, baseURL string, params StreamParams, apiKey string) (*ChannelStream, error)

StreamWithChannelsAndAPIKey creates a streaming session with an API key for the Authorization: Bearer header on the WebSocket upgrade request. Pass an empty string for self-hosted endpoints that don't require auth.

func (*ChannelStream) Close 

func (cs *ChannelStream) Close() error

Close sends CloseStream and waits for the connection to end. The Events and Errors channels are closed automatically when the connection ends.

func (*ChannelStream) DroppedEvents 

func (cs *ChannelStream) DroppedEvents() int64

DroppedEvents returns the number of events that were silently dropped because the events channel buffer was full (slow consumer). The count is cumulative for the lifetime of this ChannelStream.

func (*ChannelStream) Errors 

func (cs *ChannelStream) Errors() <-chan error

Errors returns the read-only channel of streaming errors.

func (*ChannelStream) Events 

func (cs *ChannelStream) Events() <-chan StreamEvent

Events returns the read-only channel of streaming events.

func (*ChannelStream) Finalize 

func (cs *ChannelStream) Finalize() error

Finalize sends a Finalize control message to flush pending audio.

func (*ChannelStream) ForceClose 

func (cs *ChannelStream) ForceClose()

ForceClose closes the WebSocket connection immediately without sending CloseStream. Use when the context is cancelled and graceful shutdown is not possible.

func (*ChannelStream) Send 

func (cs *ChannelStream) Send(data []byte) error

Send transmits a binary PCM audio frame to the server.

type Client 

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

Client sends audio files to an OpenAI-compatible /v1/audio/transcriptions endpoint.

func New 

func New(baseURL string, opts ...Option) *Client

New creates an STT client for the given base URL (e.g. "http://127.0.0.1:8092").

func (*Client) IsAvailable 

func (c *Client) IsAvailable() bool

IsAvailable checks if the STT service is reachable. It tries /health first (ox-whisper), then falls back to /v1/models (OpenAI, Groq, and other cloud providers that don't expose /health).

func (*Client) Models 

func (c *Client) Models(ctx context.Context) (*ModelList, error)

Models fetches the list of available models from GET /v1/models.

func (*Client) Transcribe 

func (c *Client) Transcribe(ctx context.Context, audioPath string) (*Response, error)

Transcribe sends the audio file to the STT service and returns the transcription.

func (*Client) TranscribeRaw 

func (c *Client) TranscribeRaw(ctx context.Context, audioPath string) ([]byte, error)

TranscribeRaw sends the audio file and returns the raw response bytes (useful for text/srt/vtt).

func (*Client) TranscribeReader 

func (c *Client) TranscribeReader(ctx context.Context, r io.Reader, filename string) (*Response, error)

TranscribeReader accepts an io.Reader instead of a file path.

func (*Client) TranscribeURL 

func (c *Client) TranscribeURL(ctx context.Context, audioURL string) (*Response, error)

TranscribeURL downloads audio from a URL, transcribes it, and cleans up the temp file. Useful for Telegram voice messages where you have the file download URL.

func (*Client) TranscribeURLVerbose 

func (c *Client) TranscribeURLVerbose(ctx context.Context, audioURL string) (*VerboseResponse, error)

TranscribeURLVerbose is like TranscribeURL but returns verbose results.

func (*Client) TranscribeVerbose 

func (c *Client) TranscribeVerbose(ctx context.Context, audioPath string) (*VerboseResponse, error)

TranscribeVerbose sends the audio file and returns a VerboseResponse with segments and words.

type Error 

type Error struct {
	StatusCode int
	Message    string
}

Error represents an STT API error with HTTP status code.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) IsTransient 

func (e *Error) IsTransient() bool

IsTransient returns true for errors that may succeed on retry (429, 502-504).

type Model 

type Model struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	OwnedBy string `json:"owned_by"`
}

Model describes a single model entry returned by the /v1/models endpoint.

type ModelList 

type ModelList struct {
	Object string  `json:"object"`
	Data   []Model `json:"data"`
}

ModelList is the response from GET /v1/models.

type Option 

type Option func(*Client)

Option configures the Client.

func WithAPIKey 

func WithAPIKey(key string) Option

WithAPIKey sets the API key sent as "Authorization: Bearer <key>" on all HTTP requests (transcription, models, health) and on the WebSocket upgrade request. Required for OpenAI API; self-hosted ox-whisper does not need it.

func WithCircuitBreaker 

func WithCircuitBreaker(maxFails int, cooldown time.Duration) Option

WithCircuitBreaker enables a circuit breaker that stops sending requests after maxFails consecutive transient failures until the cooldown period has elapsed.

func WithCustomSpelling 

func WithCustomSpelling(m map[string]string) Option

WithCustomSpelling sets custom spelling corrections (original → corrected).

func WithDiarize 

func WithDiarize(v bool) Option

WithDiarize enables speaker diarization.

func WithDiarizeSpeakers 

func WithDiarizeSpeakers(n int) Option

WithDiarizeSpeakers sets the expected number of speakers for diarization.

func WithFormat 

func WithFormat(format string) Option

WithFormat sets the response format: "json" or "verbose_json" (default: "json").

func WithKeywords 

func WithKeywords(kw []string) Option

WithKeywords sets hint keywords to boost recognition accuracy.

func WithLanguage 

func WithLanguage(lang string) Option

WithLanguage sets the transcription language (default: "ru").

func WithModel 

func WithModel(model string) Option

WithModel sets the model name (default: "moonshine-v2").

func WithPunctuate 

func WithPunctuate(v bool) Option

WithPunctuate enables or disables automatic punctuation.

func WithRetry 

func WithRetry(maxAttempts int, baseDelay time.Duration) Option

WithRetry enables automatic retry with exponential backoff for transient errors. maxAttempts is the total number of attempts (including the first) and must satisfy 1 <= maxAttempts <= 100 (100 is a generous library ceiling; canonical SDKs use 3). baseDelay is the initial wait before the second attempt and must be > 0.

On invalid input, WithRetry panics. This follows the Go convention for programmer/configuration errors (cf. regexp.MustCompile, time.Tick) and avoids a breaking change to the Option/New signatures, which do not return errors. A panic surfaces the misconfiguration loudly at construction time rather than silently looping an unbounded number of times or silently clamping the value.

func WithRetryWithMaxDelay 

func WithRetryWithMaxDelay(maxAttempts int, baseDelay, maxDelay time.Duration) Option

WithRetryWithMaxDelay is like WithRetry but allows configuring maxDelay (the cap on exponential backoff). WithRetry uses a default of 30s. maxDelay must be > 0; it may be less than baseDelay (baseDelay is capped immediately on the first doubling).

func WithSmartFormat 

func WithSmartFormat(v bool) Option

WithSmartFormat enables or disables smart formatting (numbers, dates, etc.).

func WithTempDir 

func WithTempDir(dir string) Option

WithTempDir sets the directory used for temporary files downloaded by TranscribeURL/TranscribeURLVerbose. Defaults to os.TempDir() when unset.

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the HTTP request timeout (default: 60s).

type Response 

type Response struct {
	Text     string  `json:"text"`
	Language string  `json:"language,omitempty"`
	Duration float64 `json:"duration,omitempty"`
}

Response holds the basic transcription result.

type Segment 

type Segment struct {
	ID    int     `json:"id"`
	Start float64 `json:"start"`
	End   float64 `json:"end"`
	Text  string  `json:"text"`
}

Segment represents a timestamped chunk of transcribed text.

type StreamAlternative 

type StreamAlternative struct {
	Transcript string  `json:"transcript"`
	Confidence float32 `json:"confidence"`
	Words      []Word  `json:"words,omitempty"`
}

StreamAlternative is one recognition hypothesis.

type StreamChannel 

type StreamChannel struct {
	Alternatives []StreamAlternative `json:"alternatives"`
}

StreamChannel holds recognition alternatives for a single audio channel.

type StreamClient 

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

StreamClient manages a WebSocket connection to /v1/listen.

func NewStreamClient 

func NewStreamClient(baseURL string, params StreamParams, handler StreamHandler) *StreamClient

NewStreamClient creates a StreamClient for the given base URL and params. If baseURL cannot be converted to a valid WebSocket URL (e.g. it has no recognizable scheme), the error is captured and surfaced by Connect.

func (*StreamClient) Close 

func (sc *StreamClient) Close() error

Close sends a CloseStream control message and waits for the connection to end. If the server does not respond within defaultCloseTimeout, the connection is force-closed so the caller never blocks forever on a hung server.

func (*StreamClient) Connect 

func (sc *StreamClient) Connect(ctx context.Context) error

Connect dials the WebSocket server and starts the read goroutine. Calling Connect twice on the same StreamClient returns an error instead of starting a second readLoop (which would double-close sc.done and panic).

func (*StreamClient) Done 

func (sc *StreamClient) Done() <-chan struct{}

Done returns a channel that is closed when the connection ends.

func (*StreamClient) Finalize 

func (sc *StreamClient) Finalize() error

Finalize sends a Finalize control message to flush pending audio.

func (*StreamClient) ForceClose 

func (sc *StreamClient) ForceClose()

ForceClose closes the underlying WebSocket connection immediately without sending a CloseStream control message. Use when graceful close is not possible. It is safe to call concurrently and multiple times. Setting a zero read deadline unblocks any in-flight ReadMessage in readLoop so the goroutine exits promptly.

func (*StreamClient) Send 

func (sc *StreamClient) Send(data []byte) error

Send transmits a binary PCM audio frame to the server.

func (*StreamClient) SetAPIKey 

func (sc *StreamClient) SetAPIKey(key string)

SetAPIKey sets the API key for the Authorization: Bearer header on the WebSocket upgrade request. Must be called before Connect.

type StreamEvent 

type StreamEvent struct {
	Type           string         `json:"type"` // Metadata, Results, SpeechStarted, Error, CloseStream
	RequestID      string         `json:"request_id,omitempty"`
	Model          string         `json:"model,omitempty"`
	Channels       int            `json:"channels,omitempty"`
	IsFinal        bool           `json:"is_final,omitempty"`
	SpeechFinal    bool           `json:"speech_final,omitempty"`
	FromFinalize   bool           `json:"from_finalize,omitempty"`
	SpeechStartedS *float64       `json:"speech_started_s,omitempty"`
	TimestampS     float64        `json:"timestamp_s,omitempty"`
	Channel        *StreamChannel `json:"channel,omitempty"`
	Message        string         `json:"message,omitempty"`
}

StreamEvent is received from the server during streaming.

func StreamFile 

func StreamFile(ctx context.Context, baseURL string, audioPath string, opts ...StreamFileOption) ([]StreamEvent, error)

StreamFile streams a WAV/PCM file over WebSocket in chunks and returns all final events. It simulates real-time playback by sleeping between chunks.

func (*StreamEvent) Transcript 

func (e *StreamEvent) Transcript() string

Transcript returns the best transcript text from the event, or "" if absent.

type StreamFileOption 

type StreamFileOption func(*streamFileConfig)

StreamFileOption configures StreamFile behaviour.

func WithChunkDuration 

func WithChunkDuration(d time.Duration) StreamFileOption

WithChunkDuration sets how many milliseconds of audio per chunk (default: 100ms).

func WithInterim 

func WithInterim(v bool) StreamFileOption

WithInterim enables or disables interim results.

func WithStreamEncoding 

func WithStreamEncoding(enc string) StreamFileOption

WithStreamEncoding sets the audio encoding (default: "pcm_s16le").

func WithStreamLanguage 

func WithStreamLanguage(lang string) StreamFileOption

WithStreamLanguage sets the recognition language (default: "ru").

func WithStreamPunctuate 

func WithStreamPunctuate(v bool) StreamFileOption

WithStreamPunctuate enables or disables automatic punctuation (default: true).

func WithStreamSampleRate 

func WithStreamSampleRate(rate int) StreamFileOption

WithStreamSampleRate sets the PCM sample rate in Hz (default: 16000).

func WithStreamSmartFormat 

func WithStreamSmartFormat(v bool) StreamFileOption

WithStreamSmartFormat enables or disables smart formatting (default: false).

func WithStreamVAD 

func WithStreamVAD(v bool) StreamFileOption

WithStreamVAD enables or disables voice activity detection (default: true).

type StreamHandler 

type StreamHandler interface {
	OnEvent(event StreamEvent)
	OnError(err error)
}

StreamHandler receives streaming events from a StreamClient.

type StreamParams 

type StreamParams struct {
	Language       string // default: "en"
	VAD            *bool  // default: true (nil → true)
	InterimResults bool
	SmartFormat    bool
	Punctuate      *bool  // default: true (nil → true)
	Encoding       string // "pcm_s16le" (default) or "pcm_f32le"
	SampleRate     int    // default: 16000
}

StreamParams configures a WebSocket streaming session.

VAD and Punctuate use *bool so that the zero value (nil) can default to true (matching the server's default behavior). Use stt.Bool(true) or stt.Bool(false) to set them explicitly.

type Utterance 

type Utterance struct {
	Speaker string  `json:"speaker"`
	Start   float64 `json:"start"`
	End     float64 `json:"end"`
	Text    string  `json:"text"`
}

Utterance is a speaker-attributed block of speech (used with diarization).

type VerboseResponse 

type VerboseResponse struct {
	Text               string      `json:"text"`
	Language           string      `json:"language,omitempty"`
	Duration           float64     `json:"duration,omitempty"`
	Segments           []Segment   `json:"segments,omitempty"`
	Words              []Word      `json:"words,omitempty"`
	LanguageConfidence float64     `json:"language_confidence,omitempty"`
	Utterances         []Utterance `json:"utterances,omitempty"`
}

VerboseResponse holds the full transcription result including segments, words, and utterances.

type Word 

type Word struct {
	Word    string  `json:"word"`
	Start   float64 `json:"start"`
	End     float64 `json:"end"`
	Speaker string  `json:"speaker,omitempty"`
}

Word represents a single transcribed word with timing and speaker info.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.