Core Concepts

Five pieces. Learn what each one is for and the rest of the API is just detail.

OwnAudioSharp has a small vocabulary: an engine that owns the sound card, a mixer that combines audio, sources that produce it, effects that shape it, and a clock that keeps everything on the same timeline. Everything else in these docs hangs off those five.

How audio flows

Sound moves in one direction, from your sources down to the speakers. Every feature in the library plugs in somewhere on this path.

1 · The engine

OwnaudioNet is a static class and there is exactly one engine per application. It opens the audio device, starts the real-time thread, and stays out of your way after that.

Three calls make up its whole life: initialize (pick the format and device), start (audio begins to flow), shut down (release the device). Nothing else works before initialization.

await OwnaudioNet.InitializeAsync();   // 48 kHz, stereo, 512 frames
OwnaudioNet.Start();

// ... your app runs ...

await OwnaudioNet.ShutdownAsync();

2 · The mixer

AudioMixer is the bus. You hand it sources, it sums them into a single signal and pushes that to the engine. One mixer is enough for almost every app.

It also owns the things that belong to "the whole mix": master volume and pan, peak levels for your VU meters, the master effect chain, WAV recording of the output, and the master clock.

var mixer = new AudioMixer(OwnaudioNet.Engine!.UnderlyingEngine);
mixer.Start();

mixer.AddSource(track);        // hot-swappable, safe while playing
mixer.MasterVolume = 0.85f;    // 0.0 – 1.0

3 · Sources

A source is anything that produces audio. They all implement IAudioSource, so once you know one you know all of them: Play(), Pause(), Stop(), Seek(), plus Volume, Pan, Loop, Position and Duration.

// Match the engine's format so nothing has to be resampled later
int sr = OwnaudioNet.Engine!.Config.SampleRate;
int ch = OwnaudioNet.Engine!.Config.Channels;

var vocals = new FileSource("vocals.wav", targetSampleRate: sr, targetChannels: ch);
vocals.Volume = 0.9f;
vocals.Pan    = -0.2f;   // a touch to the left

mixer.AddSource(vocals);
vocals.Play();

4 · Effects

An effect is anything implementing IEffectProcessor: the 15 built-ins, SmartMaster, or a VST3 plugin. They all go in the same two places.

Order matters — effects run in the order you add them, exactly like pedals on a board.

// Compressor first, then reverb — on the vocal only
var vocalChain = new SourceWithEffects(vocals);
vocalChain.AddEffect(new CompressorEffect { Ratio = 4f, AttackTimeMs = 10f });
vocalChain.AddEffect(new ReverbEffect { RoomSize = 0.6f, Mix = 0.25f });

mixer.AddSource(vocalChain);   // add the wrapper, not the raw source

// Catch the peaks on the way out
mixer.AddMasterEffect(new LimiterEffect());

5 · The clock

Start two files at "the same time" and they will drift apart — different decoders, different buffer boundaries, different rounding. Over three minutes that becomes audible flam.

The MasterClock fixes this. Every mixer owns one, and it is the single source of truth for "where are we on the timeline". Attach a source to it and the engine continuously compares that source's position to the clock and nudges it back into line.

// Attach BEFORE Play()
vocals.AttachToClock(mixer.MasterClock);
backing.AttachToClock(mixer.MasterClock);

backing.StartOffset = 2.5;   // this one enters 2.5 s into the song

mixer.Seek(0);               // moves the clock and every attached source
vocals.Play();
backing.Play();

double now = mixer.MasterClock.CurrentTimestamp;   // seconds — what your playhead reads

What runs where

Two rules cover nearly everything you need to know about threading.

Your UI thread     →  Play / Seek / Volume / AddSource      (fast, non-blocking)
Engine thread      →  decode · mix · effects · device I/O    (native Rust, never yours)

• Never block the UI thread. InitializeAsync(), StopAsync() and ShutdownAsync() exist for exactly this reason; heavy loads belong in Task.Run.
• Never allocate in a render callback. If you write a StreamingSource generator, no new, no LINQ, no string building — it runs against a deadline.

Everything else — setting Volume, adding a source, seeking — is safe from any thread and designed to be called from a slider's event handler.

Glossary

The words that show up in every audio API, in plain terms.

Where next