Core Ownaudio.Core API Reference

using Ownaudio.Core;
using Ownaudio.Decoders;

// Create and initialize engine
using var engine = AudioEngineFactory.CreateDefault();

// Start the engine
engine.Start();

// Load and decode audio file
using var decoder = AudioDecoderFactory.Create(
    "music.mp3",
    targetSampleRate: 48000,
    targetChannels: 2
);

// Read and play audio
var buffer = new byte[4096 * 2 * sizeof(float)];
while (true)
{
    var result = decoder.ReadFrames(buffer);
    if (result.IsEOF) break;
    
    if (result.FramesRead > 0)
    {
        int bytesRead = result.FramesRead * 2 * sizeof(float);
        var samples = System.Runtime.InteropServices.MemoryMarshal
            .Cast(buffer.AsSpan(0, bytesRead));
        engine.Send(samples);
    }
}

// Stop the engine
engine.Stop();

public interface IAudioEngine : IDisposable
{
    // Properties
    int FramesPerBuffer { get; }
    
    // Lifecycle
    int Initialize(AudioConfig config);
    int Start();
    int Stop();
    int OwnAudioEngineActivate();
    int OwnAudioEngineStopped();
    
    // Audio I/O
    void Send(Span samples);
    int Receives(out float[] samples);
    IntPtr GetStream();
    
    // Device Management
    List GetOutputDevices();
    List GetInputDevices();
    int SetOutputDeviceByName(string deviceName);
    int SetOutputDeviceByIndex(int deviceIndex);
    int SetInputDeviceByName(string deviceName);
    int SetInputDeviceByIndex(int deviceIndex);
    
    // Events
    event EventHandler OutputDeviceChanged;
    event EventHandler InputDeviceChanged;
    event EventHandler DeviceStateChanged;
}

public interface IAudioDecoder : IDisposable
{
    AudioStreamInfo StreamInfo { get; }
    
    // Zero-allocation reading (recommended)
    AudioDecoderResult ReadFrames(byte[] buffer);
    
    // Seeking
    bool TrySeek(TimeSpan position, out string error);
}

// Create decoder
using var decoder = AudioDecoderFactory.Create(
    "music.mp3",
    targetSampleRate: 48000,
    targetChannels: 2
);

var info = decoder.StreamInfo;
Console.WriteLine($"Duration: {info.Duration}");
Console.WriteLine($"Sample Rate: {info.SampleRate} Hz");
Console.WriteLine($"Channels: {info.Channels}");

// Create reusable buffer
int bufferSize = 4096 * info.Channels * sizeof(float);
var buffer = new byte[bufferSize];

// Decode frames efficiently
while (true)
{
    var result = decoder.ReadFrames(buffer);
    if (result.IsEOF) break;
    
    if (result.FramesRead > 0)
    {
        int bytesRead = result.FramesRead * info.Channels * sizeof(float);
        var samples = System.Runtime.InteropServices.MemoryMarshal
            .Cast(buffer.AsSpan(0, bytesRead));
        
        // Process audio samples
        ProcessAudio(samples);
    }
}

// Default configuration
using var engine1 = AudioEngineFactory.CreateDefault();

// Low latency
using var engine2 = AudioEngineFactory.CreateLowLatency();

// Custom configuration
var config = new AudioConfig
{
    SampleRate = 44100,
    Channels = 2,
    BufferSize = 256,
    EnableInput = true
};
using var engine3 = AudioEngineFactory.Create(config);

// From file path (auto-detect format)
using var decoder1 = AudioDecoderFactory.Create(
    "music.mp3",
    targetSampleRate: 48000,
    targetChannels: 2
);

// From stream with explicit format
using var stream = File.OpenRead("audio.wav");
using var decoder2 = AudioDecoderFactory.Create(
    stream,
    AudioFormat.Wav,
    targetSampleRate: 48000,
    targetChannels: 2
);

// Detect format
using var fileStream = File.OpenRead("unknown.audio");
var format = AudioDecoderFactory.DetectFormat(fileStream);
Console.WriteLine($"Detected format: {format}");

// Use predefined config
var config1 = AudioConfig.Default;

// Custom configuration
var config2 = new AudioConfig
{
    SampleRate = 44100,
    Channels = 1,           // Mono
    BufferSize = 256,       // Low latency
    EnableInput = true,
    EnableOutput = true
};

// Validate configuration
if (config2.Validate())
{
    Console.WriteLine("Configuration is valid");
}

using var engine = AudioEngineFactory.CreateDefault();

// List output devices and their channel counts
var devices = engine.GetOutputDevices();
foreach (var device in devices)
{
    Console.WriteLine($"Device: {device.Name}");
    Console.WriteLine($"  ID: {device.DeviceId}");
    Console.WriteLine($"  Default: {device.IsDefault}");
    Console.WriteLine($"  Max Input Channels: {device.MaxInputChannels}");
    Console.WriteLine($"  Max Output Channels: {device.MaxOutputChannels}");
}

// Route stereo output to physical channels 4 and 5 (e.g. second pair of a multi-output interface)
var config = new AudioConfig
{
    Channels = 2,
    OutputChannelSelectors = new[] { 4, 5 }  // physical channel indices (0-based)
};
using var engine2 = AudioEngineFactory.Create(config);

// ASIO with native hardware channel selection
var asioConfig = new AudioConfig
{
    HostType = EngineHostType.ASIO,
    Channels = 2,
    OutputChannelSelectors = new[] { 4, 5 }  // native ASIO channel selectors
};
using var asioEngine = AudioEngineFactory.Create(asioConfig);

// 8-channel interface: stereo music on ch 0-1, click track on ch 4-5
// Logical channels:  0   1   2   3
// Physical channels: 0   1  (skip 2,3)  4   5
var config = new AudioConfig
{
    SampleRate = 48000,
    Channels   = 4,                             // 4 logical channels
    OutputChannelSelectors = new[] { 0, 1, 4, 5 } // mapped to physical 0,1,4,5
};

using var engine = AudioEngineFactory.Create(config);
engine.Start();

// Build an interleaved 4-channel buffer per frame:
// [frame0_ch0, frame0_ch1, frame0_ch2, frame0_ch3, frame1_ch0, ...]
var buffer = new float[frameCount * 4];
for (int i = 0; i < frameCount; i++)
{
    buffer[i * 4 + 0] = musicLeft[i];     // → physical ch 0
    buffer[i * 4 + 1] = musicRight[i];    // → physical ch 1
    buffer[i * 4 + 2] = clickLeft[i];     // → physical ch 4
    buffer[i * 4 + 3] = clickRight[i];    // → physical ch 5
}

engine.Send(buffer.AsSpan());

[Flags]
public enum AudioDeviceState
{
    Active      = 0x00000001,  // Device is active and available
    Disabled    = 0x00000002,  // Device is disabled
    NotPresent  = 0x00000004,  // Device is not present
    Unplugged   = 0x00000008,  // Device is unplugged
    All         = 0x0000000F   // All device states
}

public enum AudioFormat
{
    Unknown,  // Unknown format
    Wav,      // WAV format (PCM, IEEE Float, ADPCM)
    Mp3,      // MP3 format (MPEG-1/2/2.5 Layer III)
    Flac      // FLAC format (Free Lossless Audio Codec)
}

public enum EngineHostType
{
    None = 0,           // Use platform default
    DirectSound = 1,    // Windows DirectSound
    MME = 2,            // Windows MME
    ASIO = 3,           // Windows ASIO
    WASAPI = 13,        // Windows WASAPI (recommended)
    CoreAudio = 5,      // macOS Core Audio
    ALSA = 8,           // Linux ALSA
    JACK = 12           // Linux JACK
}