OwnaudioNet

The static entry point for all audio operations. Namespace: OwnaudioNET

Properties

Property	Type	Description
`IsInitialized`	`bool`	Whether the audio system has been initialized.
`IsRunning`	`bool`	Whether the audio engine is actively processing.
`Engine`	`AudioEngineWrapper?`	The active engine wrapper. `null` before initialization. Access `UnderlyingEngine` for the `IAudioEngine`.
`Version`	`Version`	Library version (3.1.7).

Initialization & Lifecycle

⚠️

On Linux, Initialize() can block up to 5 seconds waiting for PulseAudio. Always use InitializeAsync() in UI applications.

C# — Synchronous (console apps / services)

// Default config: 48kHz, stereo, 512 frames
OwnaudioNet.Initialize();

// Custom config
OwnaudioNet.Initialize(config);

// Unit testing — no hardware required
OwnaudioNet.Initialize(config, useMockEngine: true);

// Heavy DSP load: 8+ sources or 2+ VST master effects (~170 ms headroom)
OwnaudioNet.Initialize(config, bufferMultiplier: 16);

// Start and stop
OwnaudioNet.Start();
OwnaudioNet.Stop();

// Full release of all resources
OwnaudioNet.Shutdown();

C# — Asynchronous (recommended for UI apps)

// Default config
await OwnaudioNet.InitializeAsync();
await OwnaudioNet.InitializeAsync(cancellationToken);

// Custom config
await OwnaudioNet.InitializeAsync(config);
await OwnaudioNet.InitializeAsync(config, useMockEngine: false, cancellationToken: cancellationToken);

// Heavy DSP load: 8+ sources or 2+ VST master effects
await OwnaudioNet.InitializeAsync(config, bufferMultiplier: 16, cancellationToken: cancellationToken);

// Pre-created engine (custom platform implementations)
await OwnaudioNet.InitializeAsync(engine, config, bufferMultiplier: 16, cancellationToken: cancellationToken);

// Stop / Shutdown
await OwnaudioNet.StopAsync(cancellationToken);
await OwnaudioNet.ShutdownAsync(cancellationToken);

ℹ️

bufferMultiplier controls the size of the internal CircularBuffer between the mix thread and the audio hardware. Default 8 provides ~85 ms headroom at 48 kHz / 512 frames. Use 16 when running 8 or more simultaneous sources or 2 or more VST master effects, so the mix thread has time to complete heavy DSP without causing audio dropouts. Pair with AudioMixer.Create() to route output through this buffer.

Configuration Factories

// 48kHz · stereo · 512 frames (~10.6ms)
AudioConfig config = OwnaudioNet.CreateDefaultConfig();

// 48kHz · stereo · 128 frames (~2.7ms)
AudioConfig config = OwnaudioNet.CreateLowLatencyConfig();

// 48kHz · stereo · 2048 frames (~42.7ms)
AudioConfig config = OwnaudioNet.CreateHighLatencyConfig();

Device Management

// Enumerate devices
List<AudioDeviceInfo> outputs = OwnaudioNet.GetOutputDevices();
List<AudioDeviceInfo> inputs  = OwnaudioNet.GetInputDevices();

// Async variants
List<AudioDeviceInfo> outputs = await OwnaudioNet.GetOutputDevicesAsync();
List<AudioDeviceInfo> inputs  = await OwnaudioNet.GetInputDevicesAsync();

// Use a specific device
var device = outputs.First(d => d.Name.Contains("Focusrite"));
config.OutputDeviceId = device.DeviceId;

// Hot-plug monitoring — pause when opening VST editors
OwnaudioNet.PauseDeviceMonitoring();
// ... open editor ...
OwnaudioNet.ResumeDeviceMonitoring();

AudioDeviceInfo Properties

Property	Type	Description
`DeviceId`	`string`	Unique identifier — pass to `AudioConfig.OutputDeviceId`.
`Name`	`string`	Human-readable device name.
`EngineName`	`string`	Backend: `Wasapi`, `CoreAudio`, `PulseAudio`, etc.
`IsInput` / `IsOutput`	`bool`	Device direction.
`IsDefault`	`bool`	System default device for its type.
`MaxInputChannels` / `MaxOutputChannels`	`int`	Hardware channel limits.
`DefaultSampleRate`	`double`	Native sample rate reported by the platform at enumeration time. `0` = not available. Check `> 0` before using. Available on PortAudio and MiniAudio backends. Added in v3.1.7.
`State`	`AudioDeviceState`	`Active`, `Disabled`, `NotPresent`, `Unplugged`.

C# — Device selection with native sample rate

// Find a device and use its native rate to open without resampling
var outputs = OwnaudioNet.GetOutputDevices();
var device  = outputs.First(d => d.Name.Contains("Focusrite"));

var config = new AudioConfig
{
    OutputDeviceId = device.DeviceId,
    SampleRate     = device.DefaultSampleRate > 0 ? (int)device.DefaultSampleRate : 48000
};

ℹ️

v3.1.7: AudioConfig.OutputDeviceId is now honoured at initialization time on both MiniAudio and PortAudio backends. Previously the device was applied only after a post-init SetOutputDevice call; initialization always opened the system default first. If the requested device fails, the engine automatically falls back to the default device and clears the stored ID.

Direct Audio I/O

These methods bypass the mixer. Prefer AudioMixer + sources for most use cases.

// Send interleaved samples to output
OwnaudioNet.Send(ReadOnlySpan<float> samples);

// Receive from input — ALWAYS return the buffer!
float[]? buffer = OwnaudioNet.Receive(out int sampleCount);
if (buffer != null)
{
    // process buffer[0..sampleCount-1]
    OwnaudioNet.ReturnInputBuffer(buffer); // returns buffer to pool (zero-allocation)
}

🚫

Never discard a buffer returned by Receive() without calling ReturnInputBuffer(). The buffer comes from a pool and leaking it causes memory growth.

AudioMixer Registry

The last created AudioMixer is automatically registered for NetworkSync. You can override this:

// Set the primary mixer explicitly (e.g. if you have multiple mixers)
OwnaudioNet.SetPrimaryAudioMixer(mixer);

// Get the currently registered mixer
AudioMixer? active = OwnaudioNet.GetRegisteredAudioMixer();

AudioConfig

Configuration object describing the audio stream format and hardware selection. Namespace: Ownaudio.Core

Property	Type	Default	Description
`SampleRate`	`int`	`48000`	Sample rate in Hz. Common values: 44100, 48000, 96000.
`Channels`	`int`	`2`	`1` = mono, `2` = stereo.
`BufferSize`	`int`	`512`	Desired frames per buffer. Actual size negotiated with driver.
`EnableOutput`	`bool`	`true`	Enable audio output (playback).
`EnableInput`	`bool`	`false`	Enable audio input (recording / microphone).
`OutputDeviceId`	`string?`	`null`	Output device ID from `AudioDeviceInfo.DeviceId`. `null` = system default.
`InputDeviceId`	`string?`	`null`	Input device ID. `null` = system default.
`HostType`	`EngineHostType`	`None`	Audio backend: `WASAPI`, `ASIO`, `CoreAudio`, `ALSA`, `Miniaudio`, `Portaudio`.
`OutputChannelSelectors`	`int[]?`	`null`	Physical output channels to use. `null` = sequential from 0.
`InputChannelSelectors`	`int[]?`	`null`	Physical input channels to use.
`FallbackToDefaultOnDisconnect`	`bool`	`true`	When the configured device disconnects, automatically switch to the system default device and continue playback. Switches back when the original device reconnects. Set `false` to wait for the original device instead.

C# — Common configurations

// Standard stereo output
var config = new AudioConfig { SampleRate = 48000, Channels = 2, BufferSize = 512 };

// Windows WASAPI, specific device, input disabled
var config = new AudioConfig
{
    SampleRate     = 48000,
    Channels       = 2,
    BufferSize     = 512,
    HostType       = EngineHostType.WASAPI,
    OutputDeviceId = myDevice.DeviceId,
    EnableInput    = false
};

// 8-channel multi-output device
var config = new AudioConfig
{
    Channels               = 8,
    OutputChannelSelectors = new[] { 0, 1, 2, 3, 4, 5, 6, 7 }
};