NET Audio Matchering API

Advanced audio spectrum analysis and EQ matching functionality for professional audio mastering. Implements FFT-based frequency analysis, intelligent EQ adjustment algorithms, and psychoacoustic optimization.

Professional Audio Processing The Matchering API provides sophisticated tools for matching audio characteristics between source and target files, with support for segmented analysis, dynamic Q-factor optimization, and playback system presets.

Overview

The Audio Matchering system enables professional-grade audio mastering by analyzing and matching spectral characteristics:

Segmented Analysis: Divides audio into overlapping segments for robust analysis
30-Band ISO EQ: Professional frequency bands from 20Hz to 16kHz
Dynamic Q Optimization: Automatic Q-factor calculation for musical results
Playback Presets: Pre-configured settings for 10 different playback systems
Psychoacoustic Processing: Intelligent scaling and spectral balance control
Outlier Detection: Statistical filtering of non-representative audio segments

Key Features

Spectral Analysis

FFT-based frequency analysis with Flat-Top windowing for accurate amplitude measurements across 30 ISO-standard bands.

Intelligent EQ Matching

Automatically calculates and applies EQ adjustments to match source audio to target characteristics with musical results.

Segmented Approach

Analyzes audio in overlapping segments with weighted averaging and outlier filtering for robust analysis.

System Presets

Pre-configured frequency response curves for concert PA, club systems, hi-fi speakers, headphones, and more.

AudioAnalyzer Class

The AudioAnalyzer partial class provides the core functionality for audio analysis and EQ matching.

AudioAnalyzer Namespace

using OwnaudioNET.Features.Matchering;

// Create analyzer instance
var analyzer = new AudioAnalyzer();

// Analyze audio file
AudioSpectrum spectrum = analyzer.AnalyzeAudioFile("input.wav");

// Perform EQ matching
analyzer.ProcessEQMatching(
    sourceFile: "source.wav",
    targetFile: "target.wav", 
    outputFile: "matched.wav"
);

Public API Methods

Method	Return	Description
`AnalyzeAudioFile(string)`	AudioSpectrum	Performs enhanced segmented audio analysis with weighted averaging
`ProcessEQMatching(string, string, string)`	void	Analyzes both files and applies optimal EQ matching to source
`ProcessWithEnhancedPreset(...)`	void	Applies playback system preset with base sample reference
`BatchProcessWithEnhancedPreset(...)`	void	Batch processes multiple files with the same preset
`GetAvailablePresets()`	Dictionary	Returns all available playback system presets

Data Classes

AudioSpectrum

Contains comprehensive audio spectrum analysis results including frequency bands, dynamics, and loudness.

AudioSpectrum Class

public class AudioSpectrum
{
    // Frequency band energy levels (30 ISO bands)
    public float[] FrequencyBands { get; set; } = new float[30];
    
    // RMS level of the audio
    public float RMSLevel { get; set; }
    
    // Peak level of the audio
    public float PeakLevel { get; set; }
    
    // Dynamic range in dB
    public float DynamicRange { get; set; }
    
    // Perceived loudness in LUFS
    public float Loudness { get; set; }
}

DynamicsInfo

Contains audio dynamics analysis information for compression and level management.

DynamicsInfo Class

public class DynamicsInfo
{
    public float RMS { get; set; }           // Root Mean Square level
    public float Peak { get; set; }          // Peak level
    public float DynamicRange { get; set; }  // Dynamic range in dB
    public float Loudness { get; set; }      // Loudness in LUFS
}

CompressionSettings

Defines compression parameters for audio dynamics processing.

CompressionSettings Class

public class CompressionSettings
{
    public float Threshold { get; set; }    // Compression threshold in dB
    public float Ratio { get; set; }        // Compression ratio
    public float AttackTime { get; set; }   // Attack time in milliseconds
    public float ReleaseTime { get; set; }  // Release time in milliseconds
    public float MakeupGain { get; set; }   // Makeup gain in dB
}

DynamicAmpSettings

Configuration for dynamic amplification processing.

DynamicAmpSettings Class

public class DynamicAmpSettings
{
    public float TargetLevel { get; set; }  // Target level in dB
    public float AttackTime { get; set; }   // Attack time in seconds
    public float ReleaseTime { get; set; }  // Release time in seconds
    public float MaxGain { get; set; }      // Maximum gain in dB
}

Analysis Methods

Spectrum Analysis

The analysis engine uses FFT with Flat-Top windowing for superior amplitude accuracy. Audio is analyzed across 30 ISO-standard frequency bands from 20Hz to 16kHz.

ISO Frequency Bands

// Standard ISO frequency bands in Hz
private readonly float[] FrequencyBands = {
    20f, 25f, 31.5f, 40f, 50f, 63f, 80f, 100f, 125f, 160f,      // Sub-bass to bass
    200f, 250f, 315f, 400f, 500f, 630f, 800f, 1000f, 1250f,     // Low-mid
    1600f, 2000f, 2500f, 3150f, 4000f, 5000f,                   // Mid to presence
    6300f, 8000f, 10000f, 12500f, 16000f                        // Brilliance to air
};

Dynamic Analysis

Calculates absolute dynamic characteristics including RMS, peak levels, and LUFS loudness measurements.

Dynamic Analysis Example

// Analyze dynamics
DynamicsInfo dynamics = AnalyzeAbsoluteDynamics(audioData);

Console.WriteLine($"RMS: {dynamics.RMS:F6}");
Console.WriteLine($"Peak: {dynamics.Peak:F6}");
Console.WriteLine($"Loudness: {dynamics.Loudness:F1} dBFS");
Console.WriteLine($"Dynamic Range: {dynamics.DynamicRange:F1} dB");

EQ Processing & Q-Factor Optimization

Intelligent EQ Adjustments

The system calculates EQ adjustments using psychoacoustic principles and intelligent scaling to maintain spectral balance and musicality.

EQ Adjustment Process

// Calculate raw spectrum differences
float[] rawAdjustments = new float[30];
for (int i = 0; i < 30; i++)
{
    float sourceLevel = 20 * Math.Log10(source.FrequencyBands[i]);
    float targetLevel = 20 * Math.Log10(target.FrequencyBands[i]);
    rawAdjustments[i] = targetLevel - sourceLevel;
}

// Apply intelligent scaling for musical results
float[] adjustments = ApplyIntelligentScaling(rawAdjustments);

Dynamic Q-Factor Calculation

Automatically calculates optimal Q factors for each frequency band based on multiple analysis techniques:

Psychoacoustic base Q: Frequency-dependent Q values based on hearing research
Gain-based adjustment: Larger corrections use narrower Q for surgical precision
Neighbor correlation: Similar adjustments in adjacent bands use wider Q
Spectral density: Sharp spectral features use narrower Q values

Q-Factor Optimization

// Calculate optimal Q factors
float[] qFactors = CalculateOptimalQFactors(
    eqAdjustments,
    sourceSpectrum,
    targetSpectrum
);

// Apply EQ with optimized Q factors
var eq = new Equalizer30BandEffect(sampleRate);
for (int i = 0; i < FrequencyBands.Length; i++)
{
    eq.SetBandGain(i, FrequencyBands[i], qFactors[i], eqAdjustments[i]);
}

Spectral Balance Control

Prevents excessive frequency range dominance with automatic balance correction:

Frequency Range	Control Method	Purpose
2.5-5kHz (Vocal Presence)	Intelligent limiting	Prevents harsh or fatiguing sound
20-125Hz (Low End)	Dominance reduction	Maintains clarity and definition
All Ranges	Proportional scaling	Overall spectral coherence

Playback System Presets

Available Presets

Ten pre-configured presets optimized for different playback systems, each with custom frequency response curves, dynamics settings, and loudness targets.

Preset	Description	Target Loudness	Dynamic Range
`ConcertPA`	Large venue sound reinforcement	-16 LUFS	18 dB
`ClubPA`	Dance music with enhanced bass	-11 LUFS	8 dB
`HiFiSpeakers`	Neutral response for critical listening	-18 LUFS	20 dB
`StudioMonitors`	Professional mixing reference standard	-20 LUFS	22 dB
`Headphones`	Over-ear headphone compensation	-16 LUFS	16 dB
`Earbuds`	In-ear monitors with bass boost	-14 LUFS	12 dB
`CarStereo`	Road noise and cabin compensation	-12 LUFS	10 dB
`Television`	Dialogue clarity focused	-15 LUFS	12 dB
`RadioBroadcast`	FM/AM transmission standards	-9 LUFS	6 dB
`Smartphone`	Small speaker midrange focus	-10 LUFS	8 dB

PlaybackPreset Class

PlaybackPreset Structure

public class PlaybackPreset
{
    public string Name { get; set; }                      // Preset name
    public string Description { get; set; }               // Detailed description
    public float[] FrequencyResponse { get; set; }        // 30-band EQ curve in dB
    public float TargetLoudness { get; set; }            // Target LUFS
    public float DynamicRange { get; set; }              // Recommended dB range
    public CompressionSettings Compression { get; set; }  // Compressor settings
    public DynamicAmpSettings DynamicAmp { get; set; }   // Dynamic amp settings
}

Using Presets

Preset Processing Example

var analyzer = new AudioAnalyzer();

// Process with specific preset
analyzer.ProcessWithEnhancedPreset(
    sourceFile: "input.wav",
    outputFile: "output.wav",
    system: PlaybackSystem.Headphones,
    eqOnlyMode: true  // Apply only EQ, no dynamics
);

// Batch process multiple files
analyzer.BatchProcessWithEnhancedPreset(
    sourceFiles: new[] { "song1.wav", "song2.wav", "song3.wav" },
    baseSampleFile: "reference.flac",
    outputDirectory: @"C:\Output",
    system: PlaybackSystem.ClubPA,
    fileNameSuffix: "_club"
);

// Get all available presets
var presets = AudioAnalyzer.GetAvailablePresets();
foreach (var preset in presets)
{
    Console.WriteLine($"{preset.Key}: {preset.Value.Name}");
}

Segmented Analysis Configuration

SegmentedAnalysisConfig

Configures the segmented analysis approach for more accurate and robust spectrum analysis. Audio is divided into overlapping segments, analyzed individually, and combined with weighted averaging.

SegmentedAnalysisConfig Class

public class SegmentedAnalysisConfig
{
    // Segment length in seconds (default: 10.0)
    public float SegmentLengthSeconds { get; set; } = 10.0f;
    
    // Overlap ratio between segments (default: 0.2 = 20%)
    public float OverlapRatio { get; set; } = 0.2f;
    
    // Outlier detection threshold in standard deviations (default: 2.5)
    public float OutlierThreshold { get; set; } = 2.5f;
    
    // Use weighted averaging for final spectrum (default: true)
    public bool UseWeightedAveraging { get; set; } = true;
    
    // Minimum energy threshold in dBFS for segment inclusion (default: -60.0)
    public float MinSegmentEnergyThreshold { get; set; } = -60.0f;
}

Segmented Analysis Process

Segment Creation: Audio divided into overlapping segments (default 10s with 20% overlap)
Individual Analysis: Each segment analyzed for frequency spectrum and dynamics
Energy Filtering: Segments below energy threshold are excluded
Outlier Detection: Statistical analysis identifies and removes non-representative segments
Weighted Averaging: Remaining segments combined with energy-based weighting

AudioSegment & SegmentAnalysis

Segment Data Classes

// Audio segment with metadata
public class AudioSegment
{
    public float[] Data { get; set; }        // Audio data
    public float StartTime { get; set; }     // Start time in seconds
    public float Duration { get; set; }      // Duration in seconds
    public float EnergyLevel { get; set; }   // Energy level in dBFS
    public int SampleRate { get; set; }      // Sample rate in Hz
}

// Segment analysis results
public class SegmentAnalysis
{
    public int SegmentIndex { get; set; }             // Segment index
    public float StartTime { get; set; }              // Start time
    public float Duration { get; set; }               // Duration
    public float EnergyLevel { get; set; }            // Energy in dBFS
    public float[] FrequencySpectrum { get; set; }    // Frequency spectrum
    public DynamicsInfo Dynamics { get; set; }        // Dynamics info
    public float Weight { get; set; }                 // Averaging weight
    public float OutlierScore { get; set; }           // Outlier score
}

Usage Examples

Basic EQ Matching

Simple EQ Matching

using OwnaudioNET.Features.Matchering;

var analyzer = new AudioAnalyzer();

// Match source audio to target characteristics
analyzer.ProcessEQMatching(
    sourceFile: @"C:\Audio\my_track.wav",
    targetFile: @"C:\Audio\reference_track.wav",
    outputFile: @"C:\Audio\my_track_matched.wav"
);

// Console output shows:
// - Segment analysis progress
// - Calculated EQ adjustments
// - Safety features active
// - Final processing status

Preset-Based Processing

Using Playback Presets

var analyzer = new AudioAnalyzer();

// Optimize for headphone playback
analyzer.ProcessWithEnhancedPreset(
    sourceFile: "original.wav",
    outputFile: "headphone_optimized.wav",
    system: PlaybackSystem.Headphones,
    tempDirectory: @"C:\Temp",
    eqOnlyMode: true
);

// Optimize for car stereo
analyzer.ProcessWithEnhancedPreset(
    sourceFile: "original.wav",
    outputFile: "car_optimized.wav",
    system: PlaybackSystem.CarStereo,
    eqOnlyMode: false  // Include dynamics processing
);

Advanced Analysis

Detailed Spectrum Analysis

var analyzer = new AudioAnalyzer();

// Analyze audio file
AudioSpectrum spectrum = analyzer.AnalyzeAudioFile("audio.wav");

// Access analysis results
Console.WriteLine($"RMS Level: {spectrum.RMSLevel:F3}");
Console.WriteLine($"Peak Level: {spectrum.PeakLevel:F3}");
Console.WriteLine($"Dynamic Range: {spectrum.DynamicRange:F1} dB");
Console.WriteLine($"Loudness: {spectrum.Loudness:F1} LUFS");

// Examine frequency bands
string[] bandNames = { 
    "20Hz", "25Hz", "31Hz", "40Hz", "50Hz", /* ... */ "16kHz" 
};

for (int i = 0; i < spectrum.FrequencyBands.Length; i++)
{
    float energyDB = 20 * (float)Math.Log10(spectrum.FrequencyBands[i]);
    Console.WriteLine($"{bandNames[i]}: {energyDB:F1} dB");
}

Batch Processing

Batch Preset Processing

var analyzer = new AudioAnalyzer();

// Process multiple tracks with club preset
string[] tracks = Directory.GetFiles(@"C:\Album", "*.wav");

analyzer.BatchProcessWithEnhancedPreset(
    sourceFiles: tracks,
    baseSampleFile: "club_reference.flac",
    outputDirectory: @"C:\Album\Club",
    system: PlaybackSystem.ClubPA,
    fileNameSuffix: "_club"
);

// Output files will be named:
// track01_club.wav
// track02_club.wav
// etc.

Performance Note Audio analysis is CPU-intensive. Processing time depends on file length, sample rate, and number of segments. Typical processing time is 2-5x real-time on modern CPUs.

Safety Features The Matchering API includes multiple safety mechanisms:

Frequency-specific boost limits to prevent distortion
Dynamic headroom calculation for clean processing
Psychoacoustic weighting for musical results
EQ curve smoothing to prevent harsh corrections
Real-time clipping detection and soft limiting
Automatic level management to prevent overload