Home

OwnAudio Library - Documentation

Table of Contents

1. Overview
2. Installation & Setup
3. Quick Start
4. Core Classes
5. Audio Effects
6. Advanced Usage
7. Platform Support
8. API Reference

Overview

OwnAudio is a cross-platform audio library for .NET that provides comprehensive audio playback, recording, and processing capabilities. Built on FFmpeg and PortAudio, it offers a unified interface for audio operations across Windows, macOS, and Linux.

Key Features:

• Multi-source audio mixing and playback
• Real-time audio input/output
• Built-in audio effects library
• Cross-platform compatibility
• High-quality audio processing

Installation & Setup

Dependencies

By default, OwnAudio includes Miniaudio which works out of the box. For extended functionality, you can optionally configure FFmpeg 6 and Portaudio 2.

Windows

// Extract FFmpeg 6 and Portaudio 2 DLL to a folder, then:
OwnAudio.Initialize(@"C:\path\to\libraries\");

Linux

sudo apt update
sudo apt install portaudio19-dev ffmpeg

// Auto-detection - no path needed
OwnAudio.Initialize();

macOS

brew install portaudio
brew install ffmpeg@6

// Auto-detection - no path needed
OwnAudio.Initialize();

Basic Initialization

// Simple initialization with default settings
bool success = OwnAudio.Initialize();
// With specific host API
bool success = OwnAudio.Initialize(OwnAudioEngine.EngineHostType.WASAPI);
// With custom library path
bool success = OwnAudio.Initialize(@"C:\libraries", OwnAudioEngine.EngineHostType.ASIO);

Quick Start

Simple Playback

// Initialize library
if (!OwnAudio.Initialize()) return;
// Get SourceManager instance
var sourceManager = SourceManager.Instance;
// Configure output
SourceManager.OutputEngineOptions = new AudioEngineOutputOptions(
device: OwnAudio.DefaultOutputDevice,
channels: OwnAudioEngine.EngineChannels.Stereo,
sampleRate: 44100,
latency: OwnAudio.DefaultOutputDevice.DefaultHighOutputLatency
);
// Add and play audio file
await sourceManager.AddOutputSource("audio.mp3");
sourceManager.Play();
// Cleanup
sourceManager.Reset();
OwnAudio.Free();

Multi-Source Mixing

var sourceManager = SourceManager.Instance;
// Add multiple sources
await sourceManager.AddOutputSource("music.mp3");
await sourceManager.AddOutputSource("vocals.wav");
// Control individual volumes
sourceManager.SetVolume(0, 0.8f);  // Music at 80%
sourceManager.SetVolume(1, 1.0f);  // Vocals at 100%
sourceManager.Play();

Core Classes

OwnAudio (Static)

Main initialization and device management class.

Properties:

• IsFFmpegInitialized: FFmpeg initialization status
• IsPortAudioInitialized: PortAudio initialization status
• DefaultOutputDevice: System default output device
• DefaultInputDevice: System default input device
• OutputDevices: Available output devices
• InputDevices: Available input devices

Methods:

• Initialize(): Initialize with defaults
• Initialize(hostType): Initialize with specific host API
• Initialize(libraryPath, hostType): Initialize with custom paths
• Free(): Release resources

SourceManager (Singleton)

Central audio management system for mixing multiple sources.

Key Properties:

• Instance: Singleton access
• Sources: List of output sources
• State: Current playback state
• Volume: Master volume
• Position: Current playback position
• Duration: Total duration
• OutputLevels: Real-time output levels
• InputLevels: Real-time input levels

Essential Methods:

• AddOutputSource(url): Add audio file source
• AddRealTimeSource(volume, channels): Add real-time source
• AddInputSource(volume): Add input recording source
• Play(): Start playback
• Pause(): Pause playback
• Stop(): Stop playback
• Seek(position): Seek to position
• Reset(): Clear all sources

Source

Individual audio file player with advanced controls.

Properties:

• Duration: Audio file duration
• Position: Current position
• State: Playback state
• Volume: Source volume (0.0-1.0)
• Pitch: Pitch adjustment in semitones (-6.0 to +6.0)
• Tempo: Tempo adjustment as percentage (-20.0 to +20.0)
• CustomSampleProcessor: Custom audio processor

Methods:

• LoadAsync(url): Load from file/URL
• LoadAsync(stream): Load from stream
• ChangeState(state): Change playback state
• Seek(position): Seek to position

SourceSound

Real-time audio streaming source for live audio data.

Usage:

// Create real-time source
SourceSound source = sourceManager.AddRealTimeSource(0.4f, 1); // 40% volume, mono
// Submit audio samples
float[] samples = GetAudioSamples();
source.SubmitSamples(samples);

Audio Effects

OwnAudio includes a comprehensive effects library. All effects inherit from SampleProcessorBase.

Available Effects

Effect	Description	Key Parameters
Compressor	Dynamic range control	Threshold, Ratio, Attack, Release
Reverb	Spatial reverb effect	Room Size, Damping, Wet/Dry
Delay	Echo effect	Time, Repeat, Mix
Distortion	Overdrive/distortion	Drive, Mix, Output Gain
Chorus	Modulated delay chorus	Rate, Depth, Voices
Flanger	Jet-like sweeping effect	Rate, Depth, Feedback
Phaser	Phase shift sweeping	Rate, Depth, Stages
Equalizer	10-band parametric EQ	Frequency, Q, Gain
Enhancer	Harmonic exciter	Mix, Cut Frequency, Gain
Overdrive	Tube-style saturation	Gain, Tone, Mix
Rotary	Leslie speaker simulation	Horn/Rotor Speed, Intensity
DynamicAmp	Adaptive level control	Target Level, Attack, Release

Configuration Examples

// Windows - Professional audio
OwnAudio.Initialize(OwnAudioEngine.EngineHostType.ASIO);
// macOS - Default
OwnAudio.Initialize(OwnAudioEngine.EngineHostType.CoreAudio);
// Linux - Low latency
OwnAudio.Initialize(OwnAudioEngine.EngineHostType.JACK);
// Auto-detect best available
OwnAudio.Initialize(OwnAudioEngine.EngineHostType.None);

API Reference

Enums

SourceState

• Idle: Not playing
• Playing: Currently playing
• Paused: Playback paused
• Buffering: Loading audio data
• Recording: Recording audio

EngineHostType

• None: Auto-detect
• ASIO: Windows professional audio
• WASAPI: Windows Audio Session API
• WDMKS: Windows Driver Model
• CoreAudio: macOS audio
• ALSA: Linux audio
• JACK: Professional cross-platform

EngineChannels

• Mono: Single channel
• Stereo: Two channels

Configuration Classes

AudioEngineOutputOptions

new AudioEngineOutputOptions(
    device: AudioDevice,
    channels: EngineChannels,
    sampleRate: int,
    latency: double
);

AudioEngineInputOptions

new AudioEngineInputOptions(
    device: AudioDevice,
    channels: EngineChannels,
    sampleRate: int,
    latency: double
);

Error Handling

Most operations throw OwnaudioException on failure. Always wrap in try-catch blocks:

try
{
    await sourceManager.AddOutputSource("file.mp3");
    sourceManager.Play();
}
catch (OwnaudioException ex)
{
    Console.WriteLine($"Audio error: {ex.Message}");
}

Best Practices

1. Always initialize: Call OwnAudio.Initialize() before any operations
2. Resource cleanup: Call Reset() between sessions and Free() when done
3. Thread safety: Modify playback state from main thread
4. Error handling: Wrap operations in try-catch blocks
5. Memory management: Dispose sources when no longer needed
6. Buffer sizing: Lower EngineFramesPerBuffer reduces latency but may cause glitches

Performance Tips

• Use EngineFramesPerBuffer = 512 for balanced latency/stability
• Lower buffer sizes (256) for real-time applications
• Higher buffer sizes (1024+) for file processing
• Monitor OutputLevels/InputLevels for UI feedback
• Reset SourceManager between different audio sessions

# OwnAudio Library - Unified Documentation