capture

type Backend string

type Capturer = Session

type Config struct {
	Backend     Backend
	InputSource InputSource
	DeviceID    string
	// DeviceName is the human-readable name of the capture device. USB/UAC
	// devices can re-enumerate with a new WASAPI endpoint ID after a replug
	// or firmware update; when DeviceID no longer matches, the capturer
	// falls back to matching by this name.
	DeviceName     string
	OutputDeviceID string
	SampleRate     int
	Channels       int
	FrameSizeMs    int
	LatencyHint    string
	// CaptureThreadPriority selects the OS priority of the backend's
	// audio worker thread: "realtime" (default, TIME_CRITICAL — safe
	// because the callback only memcpys and enqueues) or "highest"
	// (malgo's own default). Ignored by backends without native thread
	// control.
	CaptureThreadPriority string
	// KeepDeviceWarm keeps the capture device initialised between
	// recordings and opens it ahead of the first one, so Start only has to
	// start a stream that already exists. Opening a WASAPI capture device
	// was measured at about 800 ms per recording (2026-09-05), which is
	// the delay between the hotkey and the first captured word. An
	// initialised device that is not started holds no stream and uses no
	// CPU. Ignored by backends that open nothing.
	KeepDeviceWarm bool
}

type DeviceInfo struct {
	ID        string `json:"deviceId"`
	Name      string `json:"label"`
	IsDefault bool   `json:"isDefault"`
}

type Event struct {
	Type    EventType
	Backend Backend
	Message string
	Err     error
	// Requested is set on an EventStopped that the session's own Stop caused.
	// Only a stop nobody asked for — unplugged device, exclusive-mode grab,
	// format change — is an interruption a host should report.
	Requested bool
}

type EventType string

type Factory func(Config) (Session, error)

type FramePool struct {
	// Capacity is the cap() of fresh buffers returned by Get. Zero
	// falls back to DefaultFrameCapacity at first use.
	Capacity int
	// contains filtered or unexported fields
}

type InputSource string

type PooledPCMHandler = func(buf []byte, release func())

type Session interface {
	Start() error
	Stop() ([]byte, error)
	IsRunning() bool
	Events() <-chan Event
	SetLevelHandler(func(float64))
	SetPCMHandler(func([]byte))
	// SetPooledPCMHandler installs the pool-aware variant of the PCM
	// callback. When set (non-nil), the capture backend leases the
	// per-frame buffer from this package's package-level FramePool
	// instead of allocating fresh, and invokes the handler with a
	// release closure. The handler MUST call release exactly once
	// before returning OR before retaining any reference to the
	// slice. Forgetting to release leaks one pool slot per frame but
	// does not corrupt data.
	//
	// When both SetPCMHandler and SetPooledPCMHandler are set, the
	// pool-aware variant wins — the legacy handler is not invoked
	// for that frame, so callers that adopt the pooled API should
	// also unset the legacy one to avoid surprise.
	//
	// Backends not yet wired to honour the pool MAY no-op this
	// setter; the legacy SetPCMHandler path remains the canonical
	// contract for all existing callers.
	SetPooledPCMHandler(PooledPCMHandler)
	Close() error
}

type Stats struct {
	Gets   uint64
	Misses uint64
}