audio

package
v0.30.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 7, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Audio playback via ebitengine/oto only requires cgo on Linux (ALSA/PulseAudio); the Windows and Darwin backends are pure-Go via purego. The build tag lets plain-Go cross-compiles for Linux skip this file, which is relevant when developer machines don't have a Linux C toolchain. Production server builds (Dockerfile.server) enable cgo, so this file compiles in — even though the Server-Target never plays audio locally, transitive imports from internal/stt must stay safe.

Streaming audio player — see player.go for the rationale behind the build tag.

Index

Constants

View Source 
const (
	SampleRate     = 16000
	Channels       = 1
	BitsPerSample  = 16
	BytesPerSample = BitsPerSample / 8
)

Variables

View Source 
var (
	ErrUnsupportedBackend = errors.New("unsupported audio backend")
	ErrBackendUnavailable = errors.New("audio backend unavailable in this build")
)

Functions

func PCMDurationSecs 

func PCMDurationSecs(pcm []byte) float64

PCMDurationSecs returns the duration of PCM audio in seconds.

func PCMLevel 

func PCMLevel(pcm []byte) float64

PCMLevel estimates a normalized RMS level from 16-bit PCM samples.

func PCMToWAV 

func PCMToWAV(pcm []byte) []byte

PCMToWAV wraps raw 16kHz S16 Mono PCM data in a WAV header.

func RegisterBackend 

func RegisterBackend(name Backend, factory Factory) error

Types

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 

func NewCapturer() (Capturer, error)

func NewCapturerWithConfig 

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 

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

ListCaptureDevices returns the available microphone devices for the selected backend.

func ListOutputDevices added in v0.22.1 

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

ListOutputDevices returns the available speaker devices for the selected backend.

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 Player 

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

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

func NewPlayer 

func NewPlayer() (*Player, error)

NewPlayer creates an audio player for TTS output. Call once at app startup; reuse for all playback.

func (*Player) Close 

func (p *Player) Close()

Close releases audio resources. Call on app shutdown.

func (*Player) IsPlaying 

func (p *Player) IsPlaying() bool

IsPlaying returns true if audio is currently being played.

func (*Player) OnFinished 

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

OnFinished sets a callback that fires when playback completes naturally (not when stopped via Stop()).

func (*Player) PlayMP3 

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

PlayMP3 decodes and plays MP3 audio data. Blocks until playback completes or Stop() is called.

func (*Player) PlayPCM 

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

PlayPCM plays raw PCM audio (16-bit signed int, little-endian, mono). IMPORTANT: The oto context is initialized at 24kHz. Audio with a different sample rate will play at the wrong pitch/speed. Callers must resample to 24kHz before calling this method, or use PlayMP3 which handles decoding.

func (*Player) Stop 

func (p *Player) Stop()

Stop immediately stops current playback (for barge-in support).

type Session 

type Session interface {
	Start() error
	Stop() ([]byte, error)
	IsRunning() bool
	Events() <-chan Event
	SetLevelHandler(func(float64))
	SetPCMHandler(func([]byte))
	Close() error
}

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

func Open 

func Open(cfg Config) (Session, error)

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 added in v0.18.0 

func NewStreamPlayer() (*StreamPlayer, error)

NewStreamPlayer creates a StreamPlayer using the system default output device.

func NewStreamPlayerWithOutputDevice added in v0.22.1 

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

NewStreamPlayerWithOutputDevice creates a StreamPlayer for the selected output device. An empty device ID uses the system default output device.

func (*StreamPlayer) Close added in v0.18.0 

func (sp *StreamPlayer) Close()

func (*StreamPlayer) IsActive added in v0.18.0 

func (sp *StreamPlayer) IsActive() bool

func (*StreamPlayer) Start added in v0.18.0 

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

func (*StreamPlayer) StopAndDrain added in v0.18.0 

func (sp *StreamPlayer) StopAndDrain()

func (*StreamPlayer) WriteChunk added in v0.18.0 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.