kolo-audio lists audio devices, records from a microphone and plays to speakers as interleaved signed 16-bit PCM. It also resamples, converts channels, applies gain, mixes, measures levels, and encodes and decodes Opus (RFC 6716), checked against the test vectors of RFC 8251. It knows nothing about the network or about timing across tracks. The Go packages are koloaudio and opus.
From a microphone to the speakers
Samples are 16-bit PCM all the way. Only Opus makes packets, and the network between the two halves is yours.
- OpenInput opens a capture device: CoreAudio on macOS, WASAPI on Windows, and on Linux the PulseAudio protocol (PulseAudio and PipeWire) or the ALSA kernel interface. Read returns interleaved 16-bit samples.
- A Resampler converts the device rate to one Opus accepts: 8, 12, 16, 24 or 48 kHz. The backend can also convert to the Config.Format you ask for.
- The Opus encoder turns each frame of 2.5 to 60 ms, 20 ms by default, into one packet. You set the bitrate, forward error correction and DTX.
- The packets go to the other side over a transport of your own. The Opus decoder turns each one into samples; DecodeFEC rebuilds a lost packet from the next one and DecodeLost conceals it.
- A Resampler converts to the rate the speakers use, when it differs.
- OpenOutput opens a playback device and Write queues the samples. Silence played because the buffer ran empty is counted in Stats().Underruns.
Install
go get github.com/ciranda-dev/kolo-audioTo pin this release, run go get github.com/ciranda-dev/kolo-audio@v0.1.0. It needs Go 1.26 or newer. There is no cgo, no C compiler, no libopus and no sound library to install, so it builds with CGO_ENABLED=0. The Opus codec is libopus 1.6.1 and the resampler is miniaudio's, both translated to Go source that is committed in the repository. The first build of the opus package compiles about 2 MB of generated Go and peaks at about 660 MB of memory; later builds use the build cache.
Quick start
This program lists the audio devices, then encodes 20 ms of a 440 Hz tone with Opus and decodes it again. It opens no device. Devices never opens one, and a machine with no audio devices prints the reason and goes on.
package main
import (
"errors"
"fmt"
"log"
"math"
koloaudio "github.com/ciranda-dev/kolo-audio"
"github.com/ciranda-dev/kolo-audio/opus"
)
func main() {
for _, kind := range []koloaudio.Kind{koloaudio.Capture, koloaudio.Playback} {
devs, err := koloaudio.Devices(kind)
if errors.Is(err, koloaudio.ErrNoDevice) || errors.Is(err, koloaudio.ErrUnsupported) {
fmt.Printf("%s: %v\n", kind, err)
continue
}
if err != nil {
log.Fatal(err)
}
for _, d := range devs {
fmt.Printf("%s %q default=%v\n", kind, d.Name, d.Default)
}
}
enc, err := opus.NewEncoder(opus.Config{})
if err != nil {
log.Fatal(err)
}
defer enc.Close()
dec, err := opus.NewDecoder(48000, 1)
if err != nil {
log.Fatal(err)
}
defer dec.Close()
frame := make([]int16, enc.FrameSize())
for i := range frame {
frame[i] = int16(8000 * math.Sin(2*math.Pi*440*float64(i)/48000))
}
packet := make([]byte, opus.PacketBufferSize)
n, err := enc.Encode(frame, packet)
if err != nil {
log.Fatal(err)
}
pcm := make([]int16, 48000*opus.MaxPacketDuration.Milliseconds()/1000)
m, err := dec.Decode(packet[:n], pcm)
if err != nil {
log.Fatal(err)
}
peak, rms := koloaudio.Level(pcm[:m])
fmt.Printf("20 ms in %d bytes, decoded peak %.1f dBFS, rms %.1f dBFS\n", n, peak, rms)
}The device lines depend on the machine. The last line does not:
20 ms in 207 bytes, decoded peak -11.3 dBFS, rms -17.0 dBFSOn macOS, ask for microphone access before recording. AccessStatus reads it and RequestAccess(ctx) shows the system prompt when the user was not asked yet; neither opens a device. This program only prints the status and asks, so on a Mac it may show the prompt:
package main
import (
"context"
"errors"
"fmt"
"io/fs"
"log"
"time"
koloaudio "github.com/ciranda-dev/kolo-audio"
)
func main() {
status, err := koloaudio.AccessStatus() // never asks
if err != nil {
log.Fatal(err)
}
fmt.Println("microphone:", status)
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
switch err := koloaudio.RequestAccess(ctx); { // macOS: may show the system prompt
case err == nil:
fmt.Println("capture is allowed")
case errors.Is(err, koloaudio.ErrPermission):
fmt.Println("refused:", err, errors.Is(err, fs.ErrPermission))
default:
log.Fatal(err) // includes ctx.Err() when the minute ends
}
}To record, open an Input with OpenInput and call Read in a loop; to play, open an Output with OpenOutput and call Write. The repository has examples/passthrough, which plays a capture device on a playback device (use headphones), and examples/opustone, which encodes a tone, drops a packet and recovers it with forward error correction. Both take device IDs as flags and never read or write files.
API reference
The API reference is generated from the Go source and is in English.
Package koloaudio captures and plays interleaved 16-bit PCM through the system's audio devices and provides small PCM processing helpers.
It uses no cgo and needs nothing installed. Devices exist on macOS (CoreAudio), Windows (WASAPI) and Linux (a PulseAudio protocol server, or the ALSA kernel interface), on amd64 and arm64; elsewhere they return ErrUnsupported. The Resampler and the opus subpackage work everywhere.
Experimental: the API may change before v1.0.0.
Constants
const (
// MinSampleRate and MaxSampleRate bound Format.SampleRate in Hz.
MinSampleRate = 8000
MaxSampleRate = 384000
// MaxChannels bounds Format.Channels.
MaxChannels = 254
// DefaultSampleRate is used when Format.SampleRate is zero; Opus runs at 48 kHz.
DefaultSampleRate = 48000
// DefaultChannels is used when Format.Channels is zero (mono).
DefaultChannels = 1
// DefaultPeriod is the device callback period when Config.Period is zero.
DefaultPeriod = 10 * time.Millisecond
// DefaultBuffer is the stream buffer when Config.Buffer is zero; it holds
// one Opus packet of the maximum duration, 120 ms.
DefaultBuffer = 120 * time.Millisecond
// MaxBuffer bounds Config.Buffer; it is the longest default buffer
// among the supported sound servers.
MaxBuffer = 2 * time.Second
// DefaultStallTimeout is used when Config.StallTimeout is zero. It leaves
// room for platforms that delay the first callback after resume from sleep.
DefaultStallTimeout = 12 * time.Second
)Format limits and defaults.
Variables
var (
// ErrInvalidConfig means a Config field is out of range.
ErrInvalidConfig = errors.New("koloaudio: invalid config")
// ErrInvalidArgument means a buffer or value passed to a call is not valid,
// for example a sample count that is not a whole number of frames.
ErrInvalidArgument = errors.New("koloaudio: invalid argument")
// ErrNoDevice means no audio backend is available or no device matches the ID.
ErrNoDevice = errors.New("koloaudio: no such device")
// ErrUnsupportedFormat means the sample rate or channel count is not supported.
ErrUnsupportedFormat = errors.New("koloaudio: unsupported format")
// ErrDeviceLost means the device stopped or stopped calling back while in use.
ErrDeviceLost = errors.New("koloaudio: device lost")
// ErrClosed means the stream or resampler was closed.
ErrClosed = errors.New("koloaudio: closed")
// ErrBackend means the audio backend failed for another reason; the
// message holds its description.
ErrBackend = errors.New("koloaudio: audio backend failed")
// ErrUnsupported means the platform has no audio device backend.
ErrUnsupported = errors.New("koloaudio: not supported on " + runtime.GOOS + "/" + runtime.GOARCH)
// ErrPermission means the user or a policy refused microphone access, from
// RequestAccess or OpenInput. Errors that wrap it also wrap fs.ErrPermission.
ErrPermission = errors.New("koloaudio: microphone access not granted")
)Functions
func ConvertChannels
func ConvertChannels(dst, src []int16, from, to int) (int, error)ConvertChannels converts interleaved frames in src from one channel count to another into dst and returns the number of samples written. It copies when the counts match, duplicates a mono channel, and averages all channels down to mono; other conversions return ErrUnsupportedFormat. dst must hold len(src)/from*to samples and must not overlap src.
func DecodeS16LE
func DecodeS16LE(dst []int16, b []byte) ([]int16, error)DecodeS16LE appends the little-endian signed 16-bit samples in b to dst and returns the extended slice. An odd len(b) returns ErrInvalidArgument and dst unchanged.
func EncodeS16LE
func EncodeS16LE(dst []byte, pcm []int16) []byteEncodeS16LE appends pcm to dst as little-endian signed 16-bit samples and returns the extended slice.
func Gain
func Gain(pcm []int16, factor float64) errorGain multiplies every sample by factor in place, saturating at the int16 limits. factor must be finite; a negative factor also inverts the phase.
func Level
func Level(pcm []int16) (peak, rms float64)Level returns the peak and RMS level of pcm in dBFS, where 0 dBFS is a sample magnitude of 32768. A full-scale sine has an RMS of -3.01 dBFS. Silence and an empty slice return -Inf for both.
func Mix
func Mix(dst, src []int16) intMix adds src into dst sample by sample, saturating at the int16 limits, and returns the number of samples mixed, min(len(dst), len(src)).
func RequestAccess
func RequestAccess(ctx context.Context) errorRequestAccess asks for microphone access on macOS when the user has not been asked yet, and returns once access is decided. It never opens a device. A refusal returns ErrPermission. The prompt waits for the person, so bound the wait with ctx; the prompt stays until answered. An app bundle needs NSMicrophoneUsageDescription in its Info.plist and, with the hardened runtime, the com.apple.security.device.audio-input entitlement; without them macOS ends the process. Linux and Windows return nil at once, elsewhere ErrUnsupported.
Types
type Access
type Access intAccess is the microphone access the system grants this process.
const (
// AccessNotDetermined means the user has not been asked yet.
AccessNotDetermined Access = iota + 1
// AccessRestricted means a policy, such as device management, forbids access.
AccessRestricted
// AccessDenied means the user refused access.
AccessDenied
// AccessAuthorized means capture is allowed. On Linux and Windows it only
// means that there is nothing to check.
AccessAuthorized
)func AccessStatus
func AccessStatus() (Access, error)AccessStatus reports the microphone access of this process on macOS. It never asks the user and never opens a device; an unknown system status is ErrBackend. Linux and Windows have no consent step to read, so it returns AccessAuthorized, and OpenInput reports the refusals the backend returns as ErrPermission. Elsewhere it returns ErrUnsupported.
func (Access) String
func (a Access) String() stringString returns "not determined", "restricted", "denied" or "authorized".
type Config
type Config struct {
// DeviceID selects a device from Devices. Empty means the system default
// device; on macOS and Windows the stream follows it when it changes.
DeviceID string
// Format of the samples passed to Read or Write. The device converts to
// and from its native format.
Format Format
// Period is the requested device callback period. Zero means DefaultPeriod.
// The backend may round it.
Period time.Duration
// Buffer is the capacity of the stream buffer between the device and the
// application. Zero means DefaultBuffer. It must be at least Period and
// at most MaxBuffer. The buffer holds Buffer times the sample rate times
// Channels samples of 2 bytes, allocated when the stream opens.
Buffer time.Duration
// StallTimeout fails the stream with ErrDeviceLost when the device makes
// no callback for this long. Zero means DefaultStallTimeout. It must be
// longer than Period.
StallTimeout time.Duration
}Config configures OpenInput and OpenOutput. Zero fields take the defaults.
type Device
type Device struct {
// ID is opaque and stable while the system keeps the device's identifier.
ID string
// Name is the name the system shows for the device.
Name string
// Kind is Capture or Playback.
Kind Kind
// Default reports whether the device is the system default of its kind.
Default bool
}Device describes an audio device. ID and Name identify hardware on this machine (a Bluetooth ID can hold its address), so do not send them to peers.
func Devices
func Devices(kind Kind) ([]Device, error)Devices lists the devices of the given kind. It never opens a device, asks for consent or changes process-wide state.
type Format
type Format struct {
// SampleRate in Hz, MinSampleRate to MaxSampleRate. Zero means DefaultSampleRate.
SampleRate int
// Channels, 1 to MaxChannels. Zero means DefaultChannels.
Channels int
}Format is a PCM format: interleaved signed 16-bit samples.
type Input
type Input struct {
// contains filtered or unexported fields
}Input captures audio from a device. Its methods are safe for concurrent use; concurrent Reads split the captured stream between them.
func OpenInput
func OpenInput(cfg Config) (*Input, error)OpenInput opens and starts a capture device. A refusal of microphone access returns ErrPermission, which also matches ErrBackend and fs.ErrPermission. On macOS it reads AccessStatus first; call RequestAccess before it.
func (Input) Close
func (in *Input) Close() errorClose stops the device and releases it. Pending and later calls return ErrClosed. Close is idempotent and always returns nil. An Input that becomes unreachable without Close is closed by the garbage collector, which may take long; call Close.
func (Input) Format
func (in *Input) Format() FormatFormat returns the format of the samples Read returns.
func (Input) Read
func (in *Input) Read(ctx context.Context, p []int16) (int, error)Read blocks until at least one frame is captured, then copies up to len(p) samples and returns the count. len(p) must be a positive multiple of the channel count. It returns ctx.Err(), ErrClosed or ErrDeviceLost.
func (Input) Stats
func (in *Input) Stats() StatsStats returns the stream counters.
type Kind
type Kind intKind selects capture (input) or playback (output) devices.
const (
// Capture devices record audio.
Capture Kind = iota + 1
// Playback devices play audio.
Playback
)func (Kind) String
func (k Kind) String() stringString returns "capture" or "playback".
type Output
type Output struct {
// contains filtered or unexported fields
}Output plays audio on a device. Its methods are safe for concurrent use; concurrent Writes may interleave their samples.
func OpenOutput
func OpenOutput(cfg Config) (*Output, error)OpenOutput opens and starts a playback device. It plays silence until the first Write.
func (Output) Close
func (out *Output) Close() errorClose stops the device and releases it, discarding queued audio. Pending and later calls return ErrClosed. Close is idempotent and always returns nil. An Output that becomes unreachable without Close is closed by the garbage collector, which may take long; call Close.
func (Output) Format
func (out *Output) Format() FormatFormat returns the format Write expects.
func (Output) Stats
func (out *Output) Stats() StatsStats returns the stream counters.
func (Output) Write
func (out *Output) Write(ctx context.Context, p []int16) (int, error)Write queues p for playback, blocking while the buffer is full, and returns the number of samples queued. len(p) must be a positive multiple of the channel count. On ctx.Err(), ErrClosed or ErrDeviceLost the count tells how much was queued.
type Resampler
type Resampler struct {
// contains filtered or unexported fields
}Resampler converts interleaved PCM from one sample rate to another with linear interpolation and a 4th-order low-pass filter. It keeps state between calls, so a stream can be fed in chunks of any size. Its methods are safe for concurrent use. A call that fails inside the resampler returns ErrBackend, and the next call starts again from a cleared filter state.
func NewResampler
func NewResampler(channels, inRate, outRate int) (*Resampler, error)NewResampler returns a Resampler for the given channel count and rates in Hz.
func (Resampler) Close
func (r *Resampler) Close() errorClose releases the Resampler. Later calls return ErrClosed. Close is idempotent and always returns nil.
func (Resampler) Flush
func (r *Resampler) Flush(dst []int16) (int, error)Flush writes the output still held back by the filter delay, as if the input were followed by silence, then resets the Resampler. A dst of (Latency()+1)*channels samples always suffices; Flush returns the samples written.
func (Resampler) Latency
func (r *Resampler) Latency() intLatency returns the delay the filter adds, in output frames.
func (Resampler) OutputLen
func (r *Resampler) OutputLen(n int) intOutputLen returns the number of samples Process writes when it consumes n input samples, given the current state. It saturates at math.MaxInt.
func (Resampler) Process
func (r *Resampler) Process(dst, src []int16) (written, consumed int, err error)Process resamples src into dst and returns the number of samples written and consumed. It stops when dst is full or src is used up; pass the unconsumed rest of src again with the next call. dst must hold at least one frame.
func (Resampler) Reset
func (r *Resampler) Reset()Reset clears the filter state, dropping any held-back output.
type Stats
type Stats struct {
// Frames moved through the device callback.
Frames uint64
// Overruns counts captured frames dropped, oldest first, because the
// application did not read fast enough. Always zero on an Output.
Overruns uint64
// Underruns counts frames of silence played because the buffer was empty
// after the first Write. Always zero on an Input.
Underruns uint64
// Buffered is the number of frames waiting in the stream buffer.
Buffered int
}Stats counts what happened on a stream since it was opened. Counts are in frames.
Package opus
Package opus encodes and decodes Opus (RFC 6716) with libopus 1.6.1 translated to Go. It needs no cgo and no installed library. Samples are interleaved signed 16-bit PCM.
Constants
const (
// PacketBufferSize is an output buffer size for Encode that holds any
// packet, as libopus recommends.
PacketBufferSize = 4000
// MaxPacketDuration is the longest audio one packet can carry. Size
// Decode buffers for it to accept any packet.
MaxPacketDuration = 120 * time.Millisecond
)Variables
var (
// ErrInvalidConfig means a Config field or constructor argument is out of range.
ErrInvalidConfig = errors.New("koloaudio: opus: invalid config")
// ErrInvalidArgument means a buffer or value passed to a call is not valid.
ErrInvalidArgument = errors.New("koloaudio: opus: invalid argument")
// ErrFrameSize means the PCM length is not an allowed frame duration.
ErrFrameSize = errors.New("koloaudio: opus: invalid frame size")
// ErrBufferTooSmall means the output buffer cannot hold the result.
ErrBufferTooSmall = errors.New("koloaudio: opus: buffer too small")
// ErrInvalidPacket means the packet is empty or corrupt.
ErrInvalidPacket = errors.New("koloaudio: opus: invalid packet")
// ErrInternal means libopus detected an internal error or the codec
// faulted. After a fault the next call continues on a new codec
// instance with the same settings and fresh codec state.
ErrInternal = errors.New("koloaudio: opus: internal error")
// ErrUnimplemented means libopus does not implement the request.
ErrUnimplemented = errors.New("koloaudio: opus: not implemented")
// ErrInvalidState means the libopus state is invalid.
ErrInvalidState = errors.New("koloaudio: opus: invalid state")
// ErrAllocFail means libopus could not allocate memory.
ErrAllocFail = errors.New("koloaudio: opus: allocation failed")
// ErrClosed means the encoder or decoder was closed.
ErrClosed = errors.New("koloaudio: opus: closed")
)Types
type Application
type Application intApplication tunes the encoder for a kind of signal.
const (
// VoIP favors speech intelligibility. It is the default.
VoIP Application = iota
// Audio favors faithfulness to the input, for music and mixed content.
Audio
// LowDelay disables the speech modes to save a few milliseconds of delay.
LowDelay
)type Config
type Config struct {
// SampleRate is 8000, 12000, 16000, 24000 or 48000 Hz. Zero means 48000.
SampleRate int
// Channels is 1 or 2. Zero means 1.
Channels int
// Application defaults to VoIP.
Application Application
// Bitrate in bits per second, 500 to 512000. Zero lets libopus choose
// from the sample rate and channel count.
Bitrate int
// Complexity from 1 to 10 trades CPU for quality. Zero keeps the libopus
// default, 9. SetComplexity also accepts 0.
Complexity int
// FEC adds in-band forward error correction when PacketLossPercent > 0.
FEC bool
// PacketLossPercent is the expected loss, 0 to 100.
PacketLossPercent int
// DTX sends almost nothing during silence.
DTX bool
// CBR makes every packet of a frame duration the same size, so sizes do
// not reveal speech. Turn DTX off with it: DTX still sends 1 or 2 byte
// packets in silence. The default is variable bitrate.
CBR bool
// FrameDuration is 2.5, 5, 10, 20, 40 or 60 ms. Zero means 20 ms.
FrameDuration time.Duration
}Config configures an Encoder. Zero fields take the defaults.
type Decoder
type Decoder struct {
// contains filtered or unexported fields
}Decoder decodes Opus packets to PCM. Its methods are safe for concurrent use. Close releases its codec but is not required to avoid a leak.
func NewDecoder
func NewDecoder(sampleRate, channels int) (*Decoder, error)NewDecoder returns a Decoder that outputs sampleRate Hz (8000, 12000, 16000, 24000 or 48000) with 1 or 2 channels, whatever the packets hold.
func (Decoder) Close
func (d *Decoder) Close() errorClose releases the Decoder. Later calls return ErrClosed. Close is idempotent and always returns nil.
func (Decoder) Decode
func (d *Decoder) Decode(packet []byte, pcm []int16) (int, error)Decode decodes packet into pcm and returns the number of samples written, all channels together. pcm must hold the packet's duration; MaxPacketDuration always suffices. A corrupt packet, or one longer than an Opus packet can be without padding (1275 bytes per frame, 48 frames), returns ErrInvalidPacket. A codec fault returns ErrInternal.
func (Decoder) DecodeFEC
func (d *Decoder) DecodeFEC(packet []byte, pcm []int16) (int, error)DecodeFEC reconstructs a lost packet from the forward error correction data in the packet that followed it, and fills all of pcm, whose duration must be that of the lost packet: a multiple of 2.5 ms up to MaxPacketDuration. Without FEC data it conceals the loss like DecodeLost. Decode packet itself afterwards.
func (Decoder) DecodeLost
func (d *Decoder) DecodeLost(pcm []int16) (int, error)DecodeLost conceals a lost packet by filling all of pcm, whose duration must be that of the lost packet: a multiple of 2.5 ms up to MaxPacketDuration. Call it once per lost packet.
func (Decoder) DecodedLen
func (d *Decoder) DecodedLen(packet []byte) (int, error)DecodedLen returns the number of samples, all channels together, that Decode writes for packet. It reads only the packet header, so Decode can still reject the packet.
type Encoder
type Encoder struct {
// contains filtered or unexported fields
}Encoder encodes PCM frames to Opus packets. Its methods are safe for concurrent use. Close releases its codec but is not required to avoid a leak.
func NewEncoder
func NewEncoder(cfg Config) (*Encoder, error)NewEncoder returns an Encoder for cfg.
func (Encoder) Close
func (e *Encoder) Close() errorClose releases the Encoder. Later calls return ErrClosed. Close is idempotent and always returns nil.
func (Encoder) Encode
func (e *Encoder) Encode(pcm []int16, out []byte) (int, error)Encode encodes one frame of exactly FrameSize samples into out and returns the packet length. PacketBufferSize bytes always suffice; a shorter out is not an error, libopus limits the packet to len(out) bytes at the cost of quality. With DTX, a packet of 2 bytes or less carries silence and need not be sent. A codec fault returns ErrInternal.
func (Encoder) FrameSize
func (e *Encoder) FrameSize() intFrameSize returns the number of samples, all channels together, that Encode takes per call.
func (Encoder) SetBitrate
func (e *Encoder) SetBitrate(bps int) errorSetBitrate sets the target bitrate, 500 to 512000 bits per second, or 0 to let libopus choose.
func (Encoder) SetCBR
func (e *Encoder) SetCBR(on bool) errorSetCBR turns constant bitrate on or off. With it on, every packet of a frame duration has the same size, as long as out in Encode holds that size, and DTX still shortens packets in silence. Off is variable bitrate.
func (Encoder) SetComplexity
func (e *Encoder) SetComplexity(c int) errorSetComplexity sets the complexity, 0 to 10.
func (Encoder) SetDTX
func (e *Encoder) SetDTX(on bool) errorSetDTX turns discontinuous transmission on or off.
func (Encoder) SetFEC
func (e *Encoder) SetFEC(on bool) errorSetFEC turns in-band forward error correction on or off.
func (Encoder) SetPacketLossPercent
func (e *Encoder) SetPacketLossPercent(p int) errorSetPacketLossPercent sets the expected packet loss, 0 to 100.
Good to know
How audio travels
OpenInputopens a capture device andReadreturns interleaved 16-bit samples.- A
Resamplerconverts the device rate to one Opus accepts. - The
opus.Encoderturns each frame into one packet. - Your application sends the packets. kolo-audio sends nothing.
- The
opus.Decoderturns each packet into samples, orDecodeFECandDecodeLostcover a lost one. Writequeues the samples on anOutput.
Devices
Devices(kind)listsCaptureorPlaybackdevices and never opens one. ADevicehas an opaqueID, aName, itsKindandDefault, which is true for the system default of its kind.- The backends are CoreAudio on macOS (through purego), WASAPI on Windows (through COM) and, on Linux, the PulseAudio protocol first (PulseAudio and PipeWire answer on the same socket) and the ALSA kernel interface only when no sound server answers. All of them are pure Go and use no cgo.
Config.DeviceIDselects a device. Empty means the system default, and on macOS and Windows the stream follows the default when it changes. An explicit ID pins the stream. An ID thatDevicesdid not list returnsErrNoDevice.- ALSA devices are hardware PCMs: there is no
dmixorplugsharing, and a device is exclusive while open. A Linux user needs access to/dev/snd; denial wrapsfs.ErrPermission. - On macOS, capture needs the user's consent. A command-line tool inherits its terminal's permission. An app bundle needs
NSMicrophoneUsageDescriptionin itsInfo.plist; with the hardened runtime it also needs thecom.apple.security.device.audio-inputentitlement, and in the App Sandbox the Audio Input capability. Apple's documentation says that without the key or the entitlement macOS ends the app when it asks for access or uses the microphone, soRequestAccesscannot return an error then. This comes from Apple's documentation and was not tested here: no app bundle was signed or notarized. Listing devices does not ask. AccessStatusreturns anAccess(AccessNotDetermined,AccessRestricted,AccessDeniedorAccessAuthorized) without asking.RequestAccess(ctx)shows the system prompt if the user was not asked yet and returns when access is decided: nil, or an error that wrapsErrPermissionandfs.ErrPermission. The prompt waits for the person and there is no built-in timeout, so bound the wait withctx: when it ends,RequestAccessreturnsctx.Err()and the prompt stays until it is answered. Neither opens a device. Without consent,OpenInputreturns an error that wrapsErrPermission,ErrBackendandfs.ErrPermission.- On Linux and Windows there is no consent step to read or ask for:
AccessStatusreturnsAccessAuthorizedandRequestAccessreturns nil. A refusal there (the Windows microphone privacy setting, permissions on/dev/snd) shows whenOpenInputfails with an error that wrapsErrPermissionandfs.ErrPermission. Where devices are not supported, both returnErrUnsupported. Devices,OpenInputandOpenOutputtake no context, and none blocks without bound: a PulseAudio server that does not answer costs at most 30 s per step. Call them from a goroutine if the caller must not wait.
Streams
Config.Formatis the format yourReadorWritesees: 48000 Hz and 1 channel by default, from 8000 to 384000 Hz and 1 to 254 channels. The backend converts between it and the device's format; a request it cannot meet returnsErrUnsupportedFormat.Readblocks until at least one frame is captured. If the application reads too slowly the oldest frames are dropped and counted inStats().Overruns; the audio thread never waits for the application.Writequeues all of its samples and blocks while the buffer is full. The device plays silence until the firstWrite, and later silence from an empty buffer is counted inStats().Underruns.Closestops and releases the device. It is idempotent, and blocked and later calls returnErrClosed. Always call it: a stream that is not closed keeps its device running until the garbage collector finds it unreachable.- A lost stream fails every later
ReadandWritewithErrDeviceLost, and buffered capture is discarded. Open a new stream to go on. Rerouting to a new default device is not an error. InputandOutputare safe for concurrent use.
Resampling and PCM helpers
NewResampler(channels, inRate, outRate)converts rates with linear interpolation and a 4th-order low-pass filter, in chunks of any size. It is miniaudio's resampler, translated to Go, and its output is bit-identical to the original.Processreturns the samples written and consumed,Latencyis the filter delay andFlushwrites the held-back tail.ConvertChannelscopies, duplicates mono or averages to mono.Gainscales in place with saturation,Mixadds with saturation andLevelreturns peak and RMS in dBFS.EncodeS16LEandDecodeS16LEconvert to and from little-endian bytes.
Opus
opus.NewEncoder(opus.Config{...})takes the sample rate (8000, 12000, 16000, 24000 or 48000, default 48000), 1 or 2 channels, an application (VoIP,AudioorLowDelay), a bitrate from 500 to 512000 bit/s, complexity from 1 to 10, forward error correction (FEC) withPacketLossPercent,DTX, constant bitrate (CBR) and a frame duration of 2.5, 5, 10, 20, 40 or 60 ms (20 ms by default).SetBitrateand the other setters change settings between frames.Encode(pcm, out)takes exactlyFrameSize()samples and returns the packet length. AnoutofPacketBufferSize(4000 bytes) always holds a packet.NewDecoder(sampleRate, channels)andDecode(packet, pcm): sizepcmforMaxPacketDuration, 120 ms, to accept any packet.DecodeFEC(next, pcm)rebuilds a lost packet from the one after it, andDecodeLost(pcm)conceals it. In both,pcmmust cover exactly the lost duration.- Opus packets follow RFC 6716 and can be carried as RFC 7587 payloads.
- Constant bitrate. With variable bitrate the packet size follows the signal, so an observer who sees only packet sizes, for example of encrypted audio, can tell speech from silence (RFC 6562). With
opus.Config.CBR(orEncoder.SetCBR(true)) every packet of a frame duration has the same length,(bitrate * frame duration + 4) / 8bytes (at least 1), for tone, silence, noise and speech alike, at 16, 32 and 64 kbit/s, mono and stereo. The default stays variable bitrate, and packets withCBRoff are unchanged. KeepDTXoff with it: DTX still replaces silence with packets of 1 or 2 bytes, which shows when someone is quiet. Pass anoutof at least that size toEncode; a shorter one cuts the packet. Constrained variable bitrate, libopus's default, is not constant and is whatCBRturns off.
Platforms
| Platform | Device backend | What was run |
|---|---|---|
| macOS arm64 | CoreAudio through purego | Tests, real device enumeration, listener registration and a hardened-runtime build on a Mac. A playback stream with silence and a capture stream opened on the Mac's built-in devices. |
| macOS amd64 | same | Test binary under Rosetta. No native Intel Mac. |
| Windows arm64 | WASAPI through COM | Tests and real endpoint enumeration in a Windows 11 VM with virtual sound devices. No stream opened. |
| Windows amd64 | same | The same tests under the VM's x64 emulation. |
| Linux, sound server | PulseAudio protocol | Play, record and device removal against real servers in Docker, null sink only. |
| Linux, no server | ALSA kernel interface | Enumeration, negotiation and playback into recording with the snd-aloop loopback card on one real kernel. No real sound card. |
| Any | Null device | The tests use a timer-driven virtual device on every platform. |
On real sound hardware, streams were opened only on one Mac (arm64): playback of silence and capture on the built-in devices, at 16000 Hz mono, 44100 Hz stereo and 48000 Hz mono, also under -race. Windows and Linux opened no stream on real sound hardware. Tests that open real devices run only with KOLO_AUDIO_HW_TEST=1. Every other platform builds, and Devices, OpenInput and OpenOutput return ErrUnsupported; the resampler, the PCM helpers and Opus work. The Opus decoder passes the 12 RFC 8251 vectors, mono and stereo, on macOS arm64 and on Windows (arm64 natively, amd64 under emulation). CGO_ENABLED=0 always works and gives static Linux binaries.
Limits
A value outside a range returns ErrInvalidConfig, ErrInvalidArgument or ErrUnsupportedFormat. The full tables are in Limits.
Config.Period10 ms,Config.Buffer120 ms (up to 2 s) andConfig.StallTimeout12 s by default.- Nothing grows beyond
Buffer. The libopus module is linked with at most 1 MiB of memory and the resampler with 512 KiB, so a hostile stream cannot grow a codec without bound. - An Opus packet longer than 61296 bytes is
ErrInvalidPacketbefore it reaches the codec, andDecodeFECandDecodeLostare capped at 120 ms. - The number of streams and of codec instances is up to the application, and each instance costs its own memory, about 0.8 to 0.9 MB for an encoder and decoder pair.
Security
- The PulseAudio reader checks every length against what is left in the buffer, never allocates from a length, accepts frames of at most 16 MiB and times out every request. An IPv6 address of any form is refused.
- The authentication cookie is read only from
$PULSE_COOKIE,$XDG_CONFIG_HOME/pulse/cookieor~/.pulse-cookie, is sent only to the server and is never logged or put in an error. - kolo-audio loads no library of its own, extracts nothing to disk and calls
dlopenonly for system frameworks, so an application signed with the hardened runtime needs no extra entitlement for it. On macOS, importing the package loadslibobjcat start (purego's Objective-C package); it opens no device and asks nothing. - The parsers have fuzz targets, and decoding malformed packets never writes past the caller's buffer.
Status
- Done: device listing, capture and playback on macOS, Windows and Linux, resampling and PCM helpers, and Opus encoding and decoding, with fuzz targets and tests.
- Tested: on real sound hardware, only on one Mac (arm64), playback of silence and capture on the built-in devices, as the platforms table says. Windows and Linux opened no stream on real sound hardware.
AccessStatusread the real status on one Mac (authorized).RequestAccesswas run only against a fake, never on a real system, because it can prompt, and no real denial was observed. - Experimental. The API may change before v1.0.0.
Errors
| Error | Message |
|---|---|
ErrBackend | koloaudio: audio backend failed |
ErrClosed | koloaudio: closed |
ErrDeviceLost | koloaudio: device lost |
ErrInvalidArgument | koloaudio: invalid argument |
ErrInvalidConfig | koloaudio: invalid config |
ErrNoDevice | koloaudio: no such device |
ErrPermission | koloaudio: microphone access not granted |
ErrUnsupported | |
ErrUnsupportedFormat | koloaudio: unsupported format |
opus.ErrAllocFail | koloaudio: opus: allocation failed |
opus.ErrBufferTooSmall | koloaudio: opus: buffer too small |
opus.ErrClosed | koloaudio: opus: closed |
opus.ErrFrameSize | koloaudio: opus: invalid frame size |
opus.ErrInternal | koloaudio: opus: internal error |
opus.ErrInvalidArgument | koloaudio: opus: invalid argument |
opus.ErrInvalidConfig | koloaudio: opus: invalid config |
opus.ErrInvalidPacket | koloaudio: opus: invalid packet |
opus.ErrInvalidState | koloaudio: opus: invalid state |
opus.ErrUnimplemented | koloaudio: opus: not implemented |
Every error starts with koloaudio: (the opus package's errors continue with opus:) and wraps a sentinel, so errors.Is works. A refused microphone, from RequestAccess or OpenInput, wraps ErrPermission and fs.ErrPermission; from OpenInput it also wraps ErrBackend. OpenOutput errors do not wrap ErrPermission. ErrUnsupported means this GOOS and GOARCH has no device backend.
References
- RFC 6716, Definition of the Opus Audio Codec (Proposed Standard, September 2012, updated by RFC 8251).
- Takes: the packet limits (sections 3.2.1 and 3.2.5), the sample rates and the channels.
- Not implemented: nothing left out.
- RFC 8251, Updates to the Opus Audio Codec (Proposed Standard, October 2017).
- Takes: the conformance test vectors.
- Not implemented: nothing left out.
- RFC 7587, RTP Payload Format for the Opus Speech and Audio Codec (Proposed Standard, June 2015).
- Takes: the 48 kHz RTP clock; Opus packets can be carried as its payload.
- Not implemented: the RTP packetization.
- RFC 6562, Guidelines for the Use of Variable Bit Rate Audio with Secure RTP (Proposed Standard, March 2012).
- Takes: constant bitrate against size leaks.
- Not implemented: nothing left out.