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);

// Mock engine for testing (no hardware required)
OwnaudioNet.Initialize(config, useMockEngine: true);

// 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);

// With cancellation token
var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
await OwnaudioNet.InitializeAsync(config, useMockEngine: false, cts.Token);

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

// Async shutdown
await OwnaudioNet.ShutdownAsync();

// 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.5-2.0)
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
);
// dynamicSource.AllowDynamicUpdate is automatically true

// Update samples dynamically (only works if AllowDynamicUpdate is enabled)
float[] newSamples = GenerateNewSamples();
dynamicSource.SubmitSamples(newSamples);

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

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

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

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

// Create ghost track with duration
var ghost = new GhostTrackSource(
    durationInSeconds: 180.0,  // 3 minutes
    sampleRate: 48000,         // Optional, default is 48000
    outputChannels: 2          // Optional, default is 2 (stereo)
);

// Use for sync timing
var syncGroup = mixer.CreateSyncGroup(track1, track2, ghost);

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
sourceWithFx.AddEffect(new DelayEffect());
sourceWithFx.RemoveEffect(reverb);
sourceWithFx.SetEffectEnabled(0, false);  // Disable first effect
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();

var reverb = new ReverbEffect
{
    RoomSize = 0.7f,       // Room size (0-1)
    Damping = 0.5f,        // High frequency damping (0-1)
    Width = 1.0f,          // Stereo width (0-1)
    WetLevel = 0.33f,      // Wet signal level (0-1)
    DryLevel = 0.7f,       // Dry signal level (0-1)
    Gain = 0.015f,         // Input gain
    Mix = 0.5f             // Wet/dry mix (0-1)
};

// Load preset
reverb.SetPreset(ReverbPreset.LargeHall);

// Create compressor with constructor parameters
var compressor = new CompressorEffect(
    threshold: 0.5f,      // Threshold level (0-1, where 1.0 = 0dB, 0.5 = -6dB)
    ratio: 4.0f,          // Compression ratio (1:1 - 100:1)
    attackTime: 100f,     // Attack time in ms (0.1-1000)
    releaseTime: 200f,    // Release time in ms (1-2000)
    makeupGain: 1.0f,     // Makeup gain as linear multiplier (0.1-10.0)
    sampleRate: 48000f
);

// Or use a preset
var compressor2 = new CompressorEffect(CompressorPreset.VocalGentle, sampleRate: 48000f);

var eq = new Equalizer30BandEffect();

// Set individual bands (-12 to +12 dB)
eq[0] = 3.0f;              // Boost first band (20Hz) by 3dB
eq[10] = -2.0f;            // Cut band 10 (200Hz) by 2dB

// Or use SetBandGain method with frequency and Q
eq.SetBandGain(15, 1000f, 1.0f, 2.0f);  // band, frequency, Q, gain in dB

// Use a preset
eq.SetPreset(Equalizer30Preset.Rock);

// Get all current gains
float[] gains = eq.GetAllGains();

var delay = new DelayEffect
{
    Time = 375,            // Delay time in ms (1-5000)
    Repeat = 0.35f,        // Feedback amount (0-1)
    Mix = 0.3f,            // Wet/dry mix (0-1)
    Damping = 0.25f        // High-frequency damping (0-1)
};

// Or use a preset
delay.SetPreset(DelayPreset.ClassicEcho);

var chorus = new ChorusEffect
{
    Rate = 1.0f,           // LFO rate in Hz (0.1-10.0)
    Depth = 0.5f,          // Modulation depth (0-1)
    Mix = 0.5f,            // Wet/dry mix (0-1)
    Voices = 3             // Number of voices (2-6)
};

// Or use a preset
chorus.SetPreset(ChorusPreset.VocalLush);

var distortion = new DistortionEffect
{
    Drive = 2.0f,          // Drive amount (1.0-10.0)
    Mix = 1.0f,            // Wet/dry mix (0-1)
    OutputGain = 0.5f      // Output gain compensation (0.1-1.0)
};

// Or use a preset
distortion.SetPreset(DistortionPreset.ClassicRock);

// Create limiter with constructor parameters
var limiter = new LimiterEffect(
    sampleRate: 48000f,
    threshold: -3.0f,     // Threshold in dB (-20 to 0)
    ceiling: -0.1f,       // Output ceiling in dB (-2 to 0)
    release: 50.0f,       // Release time in ms (1-1000)
    lookAheadMs: 5.0f     // Look-ahead time in ms (1-20)
);

// Or use a preset
var limiter2 = new LimiterEffect(sampleRate: 48000f, preset: LimiterPreset.Mastering);

// Check if limiting is active
bool isLimiting = limiter.IsLimiting;
float gainReduction = limiter.GetGainReductionDb();

var flanger = new FlangerEffect
{
    Rate = 0.5f,           // LFO rate in Hz (0.1-5.0)
    Depth = 0.8f,          // Modulation depth (0-1)
    Feedback = 0.6f,       // Feedback amount (0-0.95)
    Mix = 0.5f             // Wet/dry mix (0-1)
};

// Or use a preset
flanger.SetPreset(FlangerPreset.Classic);

var phaser = new PhaserEffect
{
    Rate = 0.5f,           // LFO rate in Hz (0.1-10.0)
    Depth = 0.7f,          // Modulation depth (0-1)
    Feedback = 0.5f,       // Feedback amount (0-0.95)
    Mix = 0.5f,            // Wet/dry mix (0-1)
    Stages = 4             // Number of stages (2-8)
};

// Or use a preset
phaser.SetPreset(PhaserPreset.Vintage);

var autoGain = new AutoGainEffect
{
    TargetLevel = 0.25f,         // Target level (0.01-1.0)
    AttackCoefficient = 0.99f,   // Attack coefficient (0.9-0.999)
    ReleaseCoefficient = 0.999f, // Release coefficient (0.9-0.9999)
    GateThreshold = 0.001f,      // Gate threshold (0.0001-0.01)
    MaximumGain = 4.0f,          // Maximum gain (1.0-10.0)
    MinimumGain = 0.25f          // Minimum gain (0.1-1.0)
};

// Or use a preset
autoGain.SetPreset(AutoGainPreset.Voice);

var enhancer = new EnhancerEffect
{
    Mix = 0.2f,                  // Mix amount (0-1)
    Gain = 2.5f,                 // Pre-saturation gain (0.1-10)
    CutoffFrequency = 4000f      // High-pass cutoff in Hz (100-20000)
};

// Or use a preset
enhancer.SetPreset(EnhancerPreset.VocalClarity);

var overdrive = new OverdriveEffect
{
    Gain = 2.0f,           // Input gain (1.0-5.0)
    Tone = 0.5f,           // Tone control (0=dark, 1=bright)
    Mix = 1.0f,            // Wet/dry mix (0-1)
    OutputLevel = 0.7f     // Output level (0.1-1.0)
};

// Or use a preset
overdrive.SetPreset(OverdrivePreset.Blues);

var rotary = new RotaryEffect
{
    HornSpeed = 6.0f,      // Horn rotation speed in Hz (2.0-15.0)
    RotorSpeed = 1.0f,     // Rotor rotation speed in Hz (0.5-5.0)
    Intensity = 0.7f,      // Effect intensity (0-1)
    Mix = 1.0f,            // Wet/dry mix (0-1)
    IsFast = false         // Fast/slow speed switch
};

// Or use a preset
rotary.SetPreset(RotaryPreset.Hammond);

var dynamicAmp = new DynamicAmpEffect
{
    TargetLevel = -9.0f,         // Target RMS level in dB (-40 to 0)
    AttackTime = 0.2f,           // Attack time in seconds (min 0.001)
    ReleaseTime = 0.8f,          // Release time in seconds (min 0.001)
    NoiseGate = 0.005f,          // Noise threshold (0-1)
    MaxGain = 10.0f              // Maximum gain (> 0)
};

// Or use a preset
dynamicAmp.SetPreset(DynamicAmpPreset.Music);

// 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);

// Create sync group
var syncGroup = mixer.CreateSyncGroup(drums, bass, guitar);

// Start all sources in perfect sync
mixer.StartSyncGroup(syncGroup.Id);

// Stop sync group
mixer.StopSyncGroup(syncGroup.Id);

// Remove sync group
mixer.RemoveSyncGroup(syncGroup.Id);

// Enable automatic drift correction
mixer.EnableAutoDriftCorrection = true;

// Drift correction monitors timing differences between sources
// and automatically adjusts to maintain perfect synchronization

public interface IAudioSource : IDisposable
{
    // Properties
    Guid Id { get; }
    AudioState State { get; }
    float Volume { get; set; }
    bool Loop { get; set; }
    double Position { get; }
    double Duration { get; }
    bool IsEndOfStream { get; }
    float Tempo { get; set; }
    float PitchShift { get; set; }
    
    // Methods
    void Play();
    void Pause();
    void Stop();
    bool Seek(double positionInSeconds);
    int ReadSamples(Span buffer, int frameCount);
    
    // Events
    event EventHandler StateChanged;
    event EventHandler BufferUnderrun;
    event EventHandler Error;
}

public interface IEffectProcessor
{
    bool IsEnabled { get; set; }
    void Process(Span buffer, int frameCount);
    void Reset();
}

public interface ISynchronizable
{
    void PrepareForSync();
    void StartSync();
    void ResyncTo(double targetPosition);
    double GetSyncPosition();
}