audio

type Backend ¶

type Backend string

const (
	BackendAuto                Backend = "auto"
	BackendWindowsWASAPIMalgo  Backend = "windows-wasapi-malgo"
	BackendWindowsWASAPINative Backend = "windows-wasapi-native"
)

type Capturer ¶

type Capturer = Session

Capturer is kept as an alias while the app migrates to the session terminology.

func NewCapturer() (Capturer, error)

func NewCapturerWithConfig(cfg Config) (Capturer, error)

type Config ¶

type Config struct {
	Backend     Backend
	DeviceID    string
	SampleRate  int
	Channels    int
	FrameSizeMs int
	LatencyHint string
}

type DeviceInfo ¶

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

DeviceInfo describes a capture device that can be presented to the user.

func ListCaptureDevices(cfg Config) ([]DeviceInfo, error)

func ListOutputDevices(cfg Config) ([]DeviceInfo, error)

type Event ¶

type Event struct {
	Type    EventType
	Backend Backend
	Message string
	Err     error
}

type EventType ¶

type EventType string

const (
	EventStarted EventType = "started"
	EventStopped EventType = "stopped"
	EventWarning EventType = "warning"
	EventError   EventType = "error"
)

type Factory ¶

type Factory func(Config) (Session, error)

type FramePool ¶ added in v0.40.1

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
}

FramePool returns recyclable byte slices for short-lived PCM frame buffers. The hot path it addresses is the malgo capture callback (internal/audio/capturer_windows_cgo.go) which used to allocate a fresh slice per callback (~33×/sec per active capture, ~3300×/sec at 100 concurrent server sessions).

Contract ¶

• Get returns a []byte with len(buf) == 0 and cap(buf) >= pool.Capacity (DefaultFrameCapacity if unset). Callers append to it; reslicing past cap will reallocate the way the language normally would.
• Put returns the buffer to the pool. After Put the caller MUST NOT read from or write to the slice — another goroutine may pick it up immediately.
• Put is idempotent on the nil slice (no-op).
• Buffers whose grown capacity exceeds 4× the configured Capacity are dropped on Put rather than retained, so pathological growth does not pin large allocations in the pool.

Concurrency ¶

FramePool wraps sync.Pool — safe for concurrent Get / Put from many goroutines. The pool may discard entries at any GC cycle; callers MUST treat Get as may-allocate-fresh.

Observability ¶

HitRatio() returns a coarse hit/miss ratio over the pool's lifetime. It is intended for occasional sanity checks and metric exports; the underlying counters use atomic adds so HitRatio is safe to call concurrently with Get and Put.

var DefaultFramePool FramePool

func (p *FramePool) Get() []byte

func (p *FramePool) HitRatio() float64

func (p *FramePool) Put(buf []byte)

func (p *FramePool) Stats() Stats

type Player ¶

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

Player plays audio through the system's default output device.

func NewPlayer() (*Player, error)

func (p *Player) Close()

func (p *Player) IsPlaying() bool

func (p *Player) OnFinished(fn func())

func (p *Player) PlayMP3(ctx context.Context, data []byte) error

func (p *Player) PlayPCM(ctx context.Context, data []byte, sampleRate int) error

func (p *Player) Stop()

type PooledPCMHandler ¶ added in v0.40.1

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

PooledPCMHandler receives one captured PCM frame with explicit buffer-ownership semantics. The release closure MUST be invoked exactly once when the handler is done with buf — either before returning, or asynchronously once any retained reference is released. The buffer MUST NOT be read or written after release.

See internal/audio.FramePool for the underlying lifecycle. The optimisation only matters for sustained capture (~33 callbacks/sec per session); short-lived recording paths can stay on the legacy SetPCMHandler API without ceremony.

type Session ¶

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 internal/audio'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
}

Session records microphone PCM and exposes both level and live-audio callbacks.

func Open(cfg Config) (Session, error)

type Stats ¶ added in v0.40.1

type Stats struct {
	Gets   uint64
	Misses uint64
}

Stats are the raw lifetime counters. Useful for OTel meter callbacks that prefer integer reports over a derived ratio.

type StreamPlayer ¶ added in v0.18.0

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

StreamPlayer plays a continuous stream of PCM audio chunks through a single playback backend. Unlike Player.PlayPCM which stops previous playback on each call, StreamPlayer buffers chunks and plays them sequentially. Designed for real-time voice agent audio output (Gemini Live, OpenAI Realtime).

func NewStreamPlayer() (*StreamPlayer, error)

func NewStreamPlayerWithOutputDevice(outputDeviceID string) (*StreamPlayer, error)

func (sp *StreamPlayer) Close()

func (sp *StreamPlayer) IsActive() bool

func (sp *StreamPlayer) Start(ctx context.Context)

func (sp *StreamPlayer) StopAndDrain()

func (sp *StreamPlayer) WriteChunk(chunk []byte)