NET OwnaudioNET API Reference

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

// Custom configuration
var config = new AudioConfig
{
    SampleRate = 44100,
    Channels = 2,
    BufferSize = 256
};
OwnaudioNet.Initialize(config);

// Shutdown
OwnaudioNet.Shutdown();

// Default async initialization
await OwnaudioNet.InitializeAsync();

// Custom async configuration
var config = new AudioConfig
{
    SampleRate = 44100,
    Channels = 2,
    BufferSize = 256
};
await OwnaudioNet.InitializeAsync(config);

// Async device enumeration
var devices = await OwnaudioNet.GetOutputDevicesAsync();
foreach (var device in devices)
{
    Console.WriteLine($"Device: {device.Name}");
}

// Async shutdown
await OwnaudioNet.ShutdownAsync();

// Route stereo output to the second pair of outputs (ch 4 and 5)
// on an 8-channel USB interface
var config = new AudioConfig
{
    SampleRate = 48000,
    Channels   = 2,                              // 2 logical channels
    OutputChannelSelectors = new[] { 4, 5 }      // physical ch 4 and 5
};

await OwnaudioNet.InitializeAsync(config);
OwnaudioNet.Start();

// AudioMixer and FileSource work normally - routing is transparent
var engine = OwnaudioNet.Engine!.UnderlyingEngine;
var mixer  = new AudioMixer(engine, bufferSizeInFrames: 512);
var music  = new FileSource("music.wav", 8192,
    targetSampleRate: 48000, targetChannels: 2);

mixer.AddSource(music);
mixer.Start();
music.Play();

var config = new AudioConfig
{
    Channels               = 2,
    OutputChannelSelectors = new[] { 4, 5 }  // physical ch 4 and 5
};
await OwnaudioNet.InitializeAsync(config);
OwnaudioNet.Start();

var engine    = OwnaudioNet.Engine!.UnderlyingEngine;
var mixer     = new AudioMixer(engine, bufferSizeInFrames: 512);

// Both sources will play on physical ch 4 and 5 (mixed together)
var music     = new FileSource("music.wav",  8192, targetSampleRate: 48000, targetChannels: 2);
var metronome = new FileSource("click.wav",  8192, targetSampleRate: 48000, targetChannels: 2);

mixer.AddSource(music);
mixer.AddSource(metronome);
mixer.Start();
music.Play();
metronome.Play();

// 8-channel interface: music on physical ch 0+1, metronome on physical ch 4+5
// AudioConfig uses 4 logical channels mapped to physical 0, 1, 4, 5
var config = new AudioConfig
{
    Channels               = 4,
    OutputChannelSelectors = new[] { 0, 1, 4, 5 }
};
await OwnaudioNet.InitializeAsync(config);
OwnaudioNet.Start();

var engine    = OwnaudioNet.Engine!.UnderlyingEngine;
var mixer     = new AudioMixer(engine, bufferSizeInFrames: 512);

var music     = new FileSource("music.wav",  8192, targetSampleRate: 48000, targetChannels: 2);
var metronome = new FileSource("click.wav",  8192, targetSampleRate: 48000, targetChannels: 2);

// Route each source to its own logical channel pair.
// The engine then maps logical → physical via OutputChannelSelectors:
//   logical 0+1 → physical 0+1  (music)
//   logical 2+3 → physical 4+5  (metronome)
music.RouteToChannels(0, 1);
metronome.RouteToChannels(2, 3);

mixer.AddSource(music);
mixer.AddSource(metronome);
mixer.Start();
music.Play();
metronome.Play();

// Create from file
var source = new FileSource("music.mp3");

// Configure playback
source.Volume = 0.8f;          // Volume (0.0-1.0)
source.Loop = true;             // Enable looping
source.Tempo = 1.2f;            // 20% faster (0.8-1.2)
source.PitchShift = -2.0f;      // 2 semitones lower (-12..+12)

// Control playback
source.Play();
source.Pause();
source.Stop();
source.Seek(30.0);  // Seek to 30 seconds

// Get info
double position = source.Position;  // Current position (seconds)
double duration = source.Duration;  // Total duration (seconds)
AudioState state = source.State;    // Playing/Paused/Stopped

// Cleanup
source.Dispose();

// Generate or load samples
float[] samples = GenerateAudioSamples();

// Create source from existing samples
var config = new AudioConfig
{
    SampleRate = 48000,
    Channels = 2
};
var source = new SampleSource(samples, config);

// OR create empty source for dynamic updates
var dynamicSource = new SampleSource(
    bufferSizeInFrames: 48000,  // 1 second buffer
    config: config
);

// Update samples dynamically
float[] newSamples = GenerateNewSamples();
dynamicSource.SubmitSamples(newSamples);

// Playback control
source.Play();
source.Loop = true;

// Initialize OwnaudioNET (engine must be running)
OwnaudioNet.Initialize();

// Create input source
var input = new InputSource(
    engine: OwnaudioNet.Engine,
    bufferSizeInFrames: 8192  // Optional, default is 8192
);

// Add to mixer and start
mixer.AddSource(input);
input.Play();

var source = new FileSource("guitar.wav");

// Create source with effects wrapper
var sourceWithFx = new SourceWithEffects(source);

// Add effects to the chain
var reverb = new ReverbEffect
{
    Mix = 0.3f,
    RoomSize = 0.7f,
    Damping = 0.5f
};
sourceWithFx.AddEffect(reverb);

var compressor = new CompressorEffect(
    threshold: 0.5f,
    ratio: 4.0f,
    attackTime: 10.0f,
    releaseTime: 100.0f,
    makeupGain: 1.0f,
    sampleRate: 48000f
);
sourceWithFx.AddEffect(compressor);

// Modify effects dynamically
reverb.Enabled = false;  // Bypass effect
sourceWithFx.RemoveEffect(compressor);
sourceWithFx.ClearEffects();

// Create mixer
var mixer = new AudioMixer(OwnaudioNet.Engine);
mixer.Start();

// Add sources
var drums = new FileSource("drums.wav");
var bass = new FileSource("bass.wav");
var guitar = new FileSource("guitar.wav");

mixer.AddSource(drums);
mixer.AddSource(bass);
mixer.AddSource(guitar);

// Control individual sources
drums.Volume = 0.8f;
bass.Volume = 0.7f;
guitar.Volume = 0.6f;

// Play sources
drums.Play();
bass.Play();
guitar.Play();

// Master controls
mixer.MasterVolume = 0.9f;

// Real-time metering
float leftPeak = mixer.LeftPeak;
float rightPeak = mixer.RightPeak;

// Recording
mixer.StartRecording("output.wav");
// ... playback ...
mixer.StopRecording();

// Cleanup
mixer.Stop();
mixer.Dispose();

// Create source and wrap with effects capability
var fileSource = new FileSource("audio.mp3");
var source = new SourceWithEffects(fileSource);

// Add effects
var compressor = new CompressorEffect(CompressorPreset.VocalGentle);
var reverb = new ReverbEffect(ReverbPreset.VocalBooth);
var limiter = new LimiterEffect(48000f, LimiterPreset.Mastering);

source.AddEffect(compressor);
source.AddEffect(reverb);
source.AddEffect(limiter);

// Control effects
reverb.Enabled = false;  // Bypass
compressor.Threshold = 0.6f;  // Adjust parameter

// Add to mixer
mixer.AddSource(source);
mixer.Start();

// Create sources
var drums = new FileSource("drums.wav");
var bass = new FileSource("bass.wav");
var guitar = new FileSource("guitar.wav");

// Add to mixer
mixer.AddSource(drums);
mixer.AddSource(bass);
mixer.AddSource(guitar);

// Attach sources to Master Clock
drums.AttachToClock(mixer.MasterClock);
bass.AttachToClock(mixer.MasterClock);
guitar.AttachToClock(mixer.MasterClock);

// Optional: Set start offsets (timeline positioning)
drums.StartOffset = 0.0;    // Starts at 0 seconds
bass.StartOffset = 0.0;     // Starts at 0 seconds
guitar.StartOffset = 2.0;   // Starts at 2 seconds (delayed)

// Start mixer
mixer.Start();

// Start all sources for playback (IMPORTANT!)
drums.Play();
bass.Play();
guitar.Play();

// All attached sources now play in perfect sync with Master Clock

// Timeline control
mixer.MasterClock.SeekTo(10.0);  // Seek all tracks to 10 seconds

// Get current timeline position
double currentTime = mixer.MasterClock.CurrentTimestamp;
long samplePosition = mixer.MasterClock.CurrentSamplePosition;

// Rendering modes
mixer.MasterClock.Mode = ClockMode.Realtime;  // Default: dropout → silence + event
mixer.MasterClock.Mode = ClockMode.Offline;   // Offline: blocking, deterministic

// Drift correction is automatic with Master Clock
// Tolerance: 10ms (~480 samples @ 48kHz)
// When drift exceeds tolerance, sources automatically resync

// Monitor dropout events (occurs when sources can't keep up)
mixer.TrackDropout += (sender, e) =>
{
    Console.WriteLine($"Track dropout: {e.TrackName}");
    Console.WriteLine($"  At time: {e.MasterTimestamp:F3}s");
    Console.WriteLine($"  Missed frames: {e.MissedFrames}");
    Console.WriteLine($"  Reason: {e.Reason}");
};

// DAW-style timeline positioning
var intro = new FileSource("intro.wav");
var verse = new FileSource("verse.wav");
var chorus = new FileSource("chorus.wav");

intro.AttachToClock(mixer.MasterClock);
verse.AttachToClock(mixer.MasterClock);
chorus.AttachToClock(mixer.MasterClock);

// Position tracks on timeline
intro.StartOffset = 0.0;      // 0:00
verse.StartOffset = 8.5;      // 0:08.5
chorus.StartOffset = 24.3;    // 0:24.3

mixer.AddSource(intro);
mixer.AddSource(verse);
mixer.AddSource(chorus);

mixer.Start();

// Start all sources
intro.Play();
verse.Play();
chorus.Play();

// Tracks play at their scheduled times based on StartOffset

// Timeline navigation
mixer.MasterClock.SeekTo(20.0);  // Jump to 20 seconds - all tracks sync