dictation

type AudioFormat string

type AuthError struct {
	Provider string
	Message  string
}

type CloudConfig struct {
	Provider string // ProviderGroq or ProviderOpenAI, for error messages
	BaseURL  string // e.g. https://api.groq.com/openai/v1
	APIKey   string
	Model    string // e.g. whisper-large-v3-turbo, whisper-1
	// Language optionally constrains recognition (ISO-639-1). Empty = auto.
	Language string

	// HTTPClient is injectable for tests; nil uses providerio's shared,
	// stall-hardened client.
	HTTPClient *http.Client
}

type DeepgramConfig struct {
	APIKey     string
	Model      string // default "nova-3"
	Language   string
	SampleRate int // capture rate; default DefaultSampleRate (16kHz)
	// BaseURL overrides the wss endpoint (tests point it at a fake server).
	BaseURL string
}

type DownloadOptions struct {
	// DestRoot is where extracted engines/models live (e.g. ~/.config/zero/stt).
	DestRoot string
	// EngineVersion selects the sherpa-onnx release tag ("" → DefaultSherpaVersion;
	// "latest" and any tag also work).
	EngineVersion string
	// HTTPClient is injectable for tests; nil uses a plain client.
	HTTPClient *http.Client
	// APIBase overrides the GitHub API base (tests). "" → api.github.com.
	APIBase string
	// Model selection (default: the Moonshine-tiny int8 batch model). Set these
	// from a ModelVariant to download a different model.
	ModelAssetName    string
	ModelPinnedDigest string
	ModelDirName      string
	// ModelLabel is the friendly model name shown in progress ("Zipformer 20M").
	ModelLabel string
	// Progress receives live status strings for the UI, including a percentage
	// while downloading (e.g. "Engine 45% · 57/126 MB").
	Progress func(status string)
	// contains filtered or unexported fields
}

type EngineComponents struct {
	BinaryPath string // extracted sherpa-onnx-offline
	ServerPath string // extracted sherpa-onnx-online-websocket-server
	ModelPath  string // extracted model directory
}

type LocalConfig struct {
	// Binary is the sherpa-onnx-offline executable; looked up on PATH when a
	// bare name. Empty defaults to "sherpa-onnx-offline".
	Binary string
	// ModelPath is the directory holding the model's .onnx + tokens.txt files
	// (stt.localModelPath).
	ModelPath  string
	NumThreads int
	// contains filtered or unexported fields
}

type ModelVariant struct {
	ID          string
	Label       string
	Description string
	Bytes       int64
	AssetName   string
	Digest      string
	DirName     string
	Streaming   bool
	// Recommended marks a curated, checksum-pinned, validated model (shown first).
	Recommended bool
}

type OpenAIRealtimeConfig struct {
	APIKey string
	Model  string // default "gpt-4o-transcribe"
	// BaseURL overrides the wss endpoint (tests point it at a fake server).
	BaseURL string
}

type Platform string

type Recorder interface {
	Start() error
	// Stop ends a batch recording and returns the recorded audio bytes (WAV on
	// desktop, M4A on Termux — SniffFormat distinguishes them).
	Stop() ([]byte, error)
	// StartStreaming begins continuous capture of raw little-endian PCM16 mono
	// at the configured sample rate. Chunks arrive on the channel in ~50ms
	// units; the channel closes when capture ends (stop called, max duration
	// hit, or trailing-silence auto-stop). stop is idempotent.
	StartStreaming() (chunks <-chan []byte, stop func() error, err error)
}

type RecorderOptions struct {
	Platform        Platform
	SampleRate      int
	MaxDuration     time.Duration
	SilenceAutoStop bool
	// WindowsAudioDevice is the dshow capture device name; auto-detected from
	// `ffmpeg -list_devices` when empty.
	WindowsAudioDevice string
	// contains filtered or unexported fields
}

type SampleRate interface {
	SampleRate() int
}

type ServerConfig struct {
	// Binary is the streaming server executable (default
	// "sherpa-onnx-online-websocket-server"); looked up on PATH.
	Binary string
	// ModelPath is the sherpa-onnx streaming model directory (transducer:
	// encoder/decoder/joiner + tokens).
	ModelPath  string
	Port       int
	NumThreads int
	// contains filtered or unexported fields
}

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

type SetupError struct {
	Tool string
	Hint string
}

type Transcriber interface {
	// Transcribe returns the final text for one recorded clip.
	Transcribe(ctx context.Context, audio []byte) (string, error)

	// StreamTranscribe consumes PCM16 chunks and reports incremental results
	// via onPartial(text, final) as decoding proceeds, returning the complete
	// final transcript when the chunk channel closes.
	//
	// onPartial's text is the CURRENT best transcript of the utterance so far
	// (cumulative, not a delta) so the composer can replace the live region
	// wholesale; final marks a segment the provider considers settled.
	//
	// On a mid-stream failure (network drop for cloud, subprocess crash for
	// local) StreamTranscribe returns the best-effort text accumulated from
	// onPartial calls made so far PLUS a non-nil error — already-streamed text
	// is never discarded, only the untranscribed tail after the failure is lost.
	StreamTranscribe(ctx context.Context, chunks <-chan []byte, onPartial func(text string, final bool)) (string, error)
}