wakeword

type AutoEndConfig struct {
	// SilenceCutoff: Dauer ohne User-Audio-Aktivitaet, nach der die Session
	// automatisch endet. Zero disables silence-based auto-end.
	SilenceCutoff time.Duration

	// ExitPhrases: case-insensitive Substring-Matcher gegen User-Transkript-
	// Snippets. Match feuert sofortiges Session-Ende. Empty slice disables
	// exit-phrase auto-end.
	//
	// Funktioniert nur wenn der gewaehlte Voice-Agent-Provider User-Transkripte
	// liefert (Gemini Live mit EnableInputAudioTranscription, OpenAI Realtime
	// mit Input-Transcription, Local Cascaded immer). Ohne Transkripte bleibt
	// SilenceCutoff allein die End-Garantie.
	ExitPhrases []string
}

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

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

	// AutoEnd steuert das automatische Beenden von Sessions die durch
	// dieses Wake-Word getriggert wurden. Provider-agnostisch — gilt fuer
	// Gemini Live, OpenAI Realtime und Local-Cascaded gleichermassen. Wenn
	// der Zero-Value verwendet wird (SilenceCutoff=0 + len(ExitPhrases)=0),
	// faellt die Pipeline auf DefaultAutoEndConfig zurueck. Siehe
	// AutoEndPolicy + DefaultAutoEndConfig fuer die Framework-Baseline.
	AutoEnd AutoEndConfig
}

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

	// Debug enables sherpa-onnx's verbose C++ logging (ModelConfig.Debug = 1).
	// Output goes to the C++ runtime's stderr — the sidecar's slog stderr pump
	// fans it into the host's log feed. Use only while tuning; the C++ side
	// is chatty.
	Debug bool
}

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 EndReason string

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

	// Source identifies the origin of the synthesized event. The wake-word
	// Dispatcher always sets this to "wakeword". Client adapters use this
	// to distinguish wake-word-triggered activations from real hotkey
	// presses — e.g. to attach an AutoEndPolicy to wake-word-origin
	// sessions but leave hotkey-origin sessions on their existing
	// hold-to-talk / toggle semantics.
	Source string
}

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)

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

type TrainingCaptureConfig struct {
	// Enabled is the master switch. When false NewTrainingCapture
	// still returns a non-nil capture but Ingest/Trigger become
	// no-ops so the sidecar can wire the same call sites
	// regardless of user opt-in state.
	Enabled bool

	// Dir is the filesystem root where captures land. Must already
	// exist (the constructor does NOT create it). Each capture
	// writes two files: <prefix>.wav and <prefix>.json.
	Dir string

	// PreRollMs and PostRollMs determine how much audio gets
	// captured before and after a trigger. Internally converted to
	// samples at the canonical SampleRate.
	PreRollMs  int
	PostRollMs int

	// Backend identifies the detector backend that produced the
	// trigger ("livekit_openwakeword" / "sherpa_kws" /
	// "stt_phrase"). Echoed into the JSON sidecar so labelers
	// know which detector to test against.
	Backend string

	// OnWrite is an optional callback invoked once per completed
	// capture flush. Nil is allowed.
	OnWrite TrainingRecordHandler

	// TimeSource overrides time.Now for tests.
	TimeSource func() time.Time
}

type TrainingRecord struct {
	ID         string    `json:"id"`
	PhraseID   string    `json:"phrase_id"`
	Phrase     string    `json:"phrase"`
	Backend    string    `json:"backend"`
	Score      float32   `json:"score"`
	CapturedAt time.Time `json:"captured_at"`
	PreRollMs  int       `json:"pre_roll_ms"`
	PostRollMs int       `json:"post_roll_ms"`
	SampleRate int       `json:"sample_rate"`
	AudioPath  string    `json:"audio_path"`
	AudioBytes int       `json:"audio_bytes"`
	Label      string    `json:"label,omitempty"`
	Uploaded   bool      `json:"uploaded"`
}

type TrainingRecordHandler func(TrainingRecord)

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

type TrainingUploaderConfig struct {
	// Dir is the local capture directory that TrainingCapture writes
	// into (one .wav + .json pair per activation).
	Dir string

	// ServerURL is the base URL of the SpeechKit server, e.g.
	// "https://speechkit.example.com" or "http://localhost:8080".
	// The uploader appends "/v1/wakeword/activations" itself.
	ServerURL string

	// BearerToken authenticates the upload requests. Pulled from the
	// configured env var by the caller (we never read env vars
	// directly to keep secrets handling in one place).
	BearerToken string

	// Interval between scans. Zero is rejected by NewTrainingUploader;
	// production should pass at least 30 s.
	Interval time.Duration

	// OnlyLabeled — when true, only records whose sidecar JSON has a
	// non-empty `label` field are uploaded. Lets the user gate
	// sharing behind explicit review.
	OnlyLabeled bool

	// HTTPClient overrides the default *http.Client (tests use a
	// custom transport). When nil a 30 s-timeout client is used.
	HTTPClient *http.Client

	// Logger is optional; defaults to slog.Default.
	Logger *slog.Logger
}