wakeword

type Config struct {
	// Enabled gates the entire wake-word system. When false, no detector is
	// loaded and no audio session is opened on its behalf. Default false —
	// wake-word is an opt-in feature in line with the dictation industry
	// norm (Wispr Flow, Superwhisper, VoiceInk all default to hotkey-only).
	Enabled bool

	// Phrase is the display label of the active wake phrase (e.g.
	// "Hey Quby"). Surfaced in the tray and status feed. Detection is
	// driven by the BPE-tokenised Keywords/KeywordsFile fields below, not
	// by this label — multiple keywords can map to the same display label.
	Phrase string

	// ModelDir is the directory holding the sherpa-onnx KWS model assets
	// (encoder/decoder/joiner ONNX + tokens.txt). The Windows reference
	// adapter resolves a default of <exe_dir>/wakeword-kws when empty.
	ModelDir string

	// KeywordsFile is the path to a sherpa-onnx keywords.txt file
	// (BPE-tokenised, one keyword per line with optional `:boost` and
	// trailing `@display-name`). Takes precedence over inline Keywords
	// when both are set. The Windows adapter ships a default file beside
	// the KWS model.
	KeywordsFile string

	// Keywords is the inline alternative to KeywordsFile — one
	// BPE-tokenised entry per slice element. Use this for programmatic
	// callers (tests, ad-hoc clients) that do not want to materialise a
	// file on disk.
	Keywords []string

	// DefaultMode is the runtime mode triggered when a keyword fires.
	// One of "dictate" | "assist" | "voice_agent".
	DefaultMode string

	// Threshold is the minimum acoustic probability for sherpa-onnx to
	// emit a keyword hit (0.0–1.0, lower = more sensitive). Each keyword
	// can override it via the `:boost` suffix in KeywordsFile; this is the
	// global default.
	Threshold float32

	// MinConsecutiveFrames is the number of decoded windows the same
	// keyword must fire in before the pipeline emits a DetectionEvent.
	// 1 = fire immediately, 2 = require two consecutive hits (default).
	MinConsecutiveFrames int

	// Cooldown is the minimum interval between two emitted DetectionEvents
	// for the same keyword. Prevents the same utterance triggering twice
	// and gives the downstream mode time to spin up before another fire.
	Cooldown time.Duration
}

type DetectionEvent struct {
	// Phrase is the configured display name (e.g. "Hey Quby").
	Phrase string

	// Keyword is the raw keyword string sherpa-onnx returned (e.g.
	// "HEY QUBY" or the @-suffix when the keywords file labelled it).
	Keyword string

	// Mode is the runtime mode the wake should trigger ("dictate" |
	// "assist" | "voice_agent"), copied from Config.DefaultMode at the
	// moment of detection so downstream consumers don't need to re-read
	// config.
	Mode string

	// Probability is informational only — sherpa-onnx KWS already applies
	// its threshold internally before reporting a keyword, so this is
	// always 1.0 from the pipeline. Kept on the surface for API stability
	// with the previous openWakeWord-based detector.
	Probability float32

	// At is the wall-clock time of the trigger.
	At time.Time
}

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

type DetectorConfig struct {
	Encoder      string   // encoder ONNX (zipformer KWS encoder-…onnx)
	Decoder      string   // decoder ONNX
	Joiner       string   // joiner ONNX
	Tokens       string   // tokens.txt (BPE token table)
	KeywordsFile string   // BPE-tokenised keywords, sherpa-onnx format
	Keywords     []string // alternative to KeywordsFile (joined with \n)

	// NumThreads bounds CPU parallelism. Zero defaults to 1 — the KWS model
	// is intentionally small (~3 M parameters) and never benefits from more
	// than a couple of threads on desktop hardware.
	NumThreads int

	// Threshold mirrors Config.Threshold; below 0 or above 1 falls back to
	// the sherpa-onnx default (~0.25).
	Threshold float32
}

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

type DispatcherOptions struct {
	// SyntheticRelease causes the dispatcher to emit a KeyUp event
	// ReleaseAfter the KeyDown. Off by default — most desktop consumers
	// want toggle/auto-stop semantics rather than a fast tap.
	SyntheticRelease bool

	// ReleaseAfter is the delay between synthesized KeyDown and KeyUp
	// when SyntheticRelease is true. Defaults to 150ms.
	ReleaseAfter time.Duration

	// Logger is used for structured logs. Defaults to slog.Default().
	Logger *slog.Logger
}

type HotkeyEvent struct {
	KeyDown bool   // true = press, false = release
	Binding string // mode name: "dictate" | "assist" | "voice_agent"
}

type HotkeySink interface {
	Submit(HotkeyEvent)
}

type HotkeySinkFunc func(HotkeyEvent)

type PhraseCatalogEntry struct {
	// ID is the stable identifier saved in [wakeword] phrase_id. Lowercase
	// snake_case. Never change after publishing — config files in the wild
	// reference it.
	ID string

	// DisplayName is the human-readable label rendered in the tray and
	// settings UI. Free-form; can include parenthetical pronunciation
	// hints (e.g. "Hey Quby (Cubi / Kubi)").
	DisplayName string

	// KeywordLabel is the @-suffix that must appear at the end of the
	// matching line in keywords.txt. The sherpa-onnx KeywordSpotter reports
	// hits via this label, which the pipeline forwards as DetectionEvent.Keyword.
	// When empty, sherpa reports the raw BPE-decoded keyword.
	KeywordLabel string

	// Notes is a one-line tradeoff summary surfaced in the settings UI
	// next to the entry. Plain text, no markup.
	Notes string
}

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

type Sink interface {
	Emit(DetectionEvent)
}

type SinkFunc func(DetectionEvent)