CodeBrix.Audio.MitLicenseForever 1.0.264.1197

CodeBrix.Audio

A fully managed, cross-platform audio file library for .NET. CodeBrix.Audio reads WAV, MP3, Ogg Vorbis and FLAC waveform audio, reads and writes Standard MIDI Files, reads MP3 ID3v2 and Vorbis-comment tags, plays sampled instruments in three formats, plays audio through a bundled cross-platform engine, and exposes a set of DSP primitives (FFT, biquad filters, envelope follower, voice-activity detection) for audio analysis — and it behaves properly on Windows, macOS, and Linux. CodeBrix.Audio is provided as a .NET 10 library and associated CodeBrix.Audio.MitLicenseForever NuGet package, which also bundles CodeBrix.Audio.Engine, a cross-platform audio engine with a native backend (see below). File decoding is fully managed; playback goes through that engine.

CodeBrix.Audio supports applications and assemblies that target Microsoft .NET version 10.0 and later. Microsoft .NET version 10.0 is a Long-Term Supported (LTS) version of .NET, and was released on Nov 11, 2025; and will be actively supported by Microsoft until Nov 14, 2028. Please update your C#/.NET code and projects to the latest LTS version of Microsoft .NET.

Installation

dotnet add package CodeBrix.Audio.MitLicenseForever

Note that the NuGet package ID and the namespace are different - there is no package named plain CodeBrix.Audio:

• NuGet package ID: CodeBrix.Audio.MitLicenseForever
• Assembly and primary namespace: CodeBrix.Audio - the public types live in its sub-namespaces, i.e. using CodeBrix.Audio.Wave; (readers, writers, WaveFormat, SharedAudioOutput), using CodeBrix.Audio.Playback; (the players and sound effects), and using CodeBrix.Audio.Midi; / using CodeBrix.Audio.Dsp; / using CodeBrix.Audio.Synth;.

The package has no NuGet dependencies. Everything it needs is inside it, including the second assembly it ships - CodeBrix.Audio.Engine - and that engine's native backend. Both assemblies are referenced automatically; there is no separate Engine package to add. Licence acceptance is required at install time.

XML documentation (IntelliSense) ships alongside both assemblies.

CodeBrix.Audio supports:

• Reading WAV (.wav) waveform audio files: 8/16/24/32-bit PCM and 32/64-bit IEEE float, including WAVE_FORMAT_EXTENSIBLE files, plus A-law/μ-law.
• Reading MP3 (.mp3) waveform audio files via a fully managed MPEG audio decoder (no ACM/DMO, no native code).
• Reading Ogg Vorbis (.ogg) files, with exact duration and sample-accurate seeking.
• Reading FLAC (.flac) files losslessly, at 16-, 24- and 32-bit depths.
• Writing WAV (.wav) files.
• Reading and writing Standard MIDI Files (.mid), with the General MIDI Level 1 sound set available by name (GeneralMidiProgram, GeneralMidiPercussion, GeneralMidi.DisplayName(...)).
• Reading ABC notation (.abc), the plain-text music format: one file or a whole tunebook, read to a faithful tune model — header fields, keys and modes, meters, tempos, note lengths, broken rhythm, rests, chords, ties, grace notes, tuplets, repeats with numbered endings, and multiple voices — and converted to the editable MIDI model (AbcToMidi.Convert), so a tune plays through any instrument here or saves as a standard MIDI file. That makes the package a complete ABC-to-MIDI file converter in its own right: AbcReader.Read, AbcToMidi.Convert, MidiFile.Export — three calls, a whole tunebook in one pass, with no audio device, instrument or SoundFont involved. Timing is exact: lengths and positions are carried as fractions of a whole note and rounded to ticks once, so a triplet never pushes the rest of the tune off the beat. Repeats are unrolled on conversion, voices take their own channels and instruments (including abc2midi's %%MIDI program and %%MIDI channel), and anything the notation carried that could not be honoured is reported per tune rather than thrown.
• Reading MP3 ID3v2 and Ogg/FLAC Vorbis-comment metadata tags.
• Playing audio: a media player with transport and seeking (AudioFilePlayer), and decode-once sound effects that can overlap freely (SoundEffectClip).
• Rendering SoundFonts (.sf2) and playing MIDI music: a spec-faithful SoundFont renderer with the full generator and modulator model, per-voice LFOs and filter, reverb and chorus — driven by a transport-style player (MidiMusicPlayer) or rendered offline to a WAV file (SoundFontRenderer). The player carries the controls a sequence needs and a decoded file does not: playback speed (tempo without pitch change), per-channel volume/pan/program for mixing a layered arrangement live, arbitrary MIDI messages sent safely from any thread, and two message hooks — an observe-only one for driving game events off the notes, and a modifying one for transposing or suppressing them.
• Playing MIDI music that is still being written (MidiStream): a timeline a producer appends to a bar at a time, from any thread, while the player is already sounding it. Playback runs from the head while the tail is still arriving; when it catches up it waits in silence - holding its position, letting what was sounding ring out - rather than ending, and a pre-roll says how much must be buffered before it starts and before it starts again after an underrun. An event that arrives behind the head is played at once and counted, never dropped, and a rest the producer has settled is declared rather than written, so the head plays the silence instead of waiting in it. Ticks convert to moments and back through the stream's own tempo map, defined past the point the producer has reached. The same transport as any other MIDI: the same five Load overloads, the same hooks, speed, per-channel controls and MPE, with a duration that grows until the producer says the music is finished. Everything appended is also kept as an editable event collection, so the piece that was heard saves as a standard MIDI file or converts to an ordinary sequence for looping or an offline render.
• Playing SFZ (.sfz) instruments: a fully managed SFZ engine measured against a corpus of real free instruments at zero unimplemented opcodes — region selection (key/velocity/controller/program, round robins, random layers, key switches including ranges and sw_vel, release triggers with rt_decay, exclusive off groups with fast/normal/timed chokes, polyphony limits, crossfades), the full modulation stack (amplifier envelope with shapes, vel2* and ampeg_dynamic; filter, pitch and flexible envelopes; SFZ v1 and v2 LFOs with sub-waveforms and cross-modulation; two filters plus a three-band parametric EQ; ARIA variators, stereo width, per-voice randoms), and the _onccN/_curveccN/_smoothccN CC matrix with <curve> support and the ARIA extended sources (velocity, key delta, alternate, per-voice random…). The same MidiMusicPlayer and offline renderer drive .sf2 and .sfz interchangeably; unknown opcodes are carried and reported (SfzInstrument.UnsupportedOpcodes), never fatal.
• Playing Decent Sampler instruments (.dspreset, .dslibrary, .dsbundle, or the folder holding one): the whole documented format, measured against the reference player rather than guessed at, and verified over a corpus of real libraries at zero unsupported features. The sampler (every trigger mode, round robins, tags with polyphony and voice muting, legato and glide, loops with crossfades, envelopes with curves, CC filters, release triggers, note delays and retriggers); the parameter and binding model behind a preset's knobs, so instrument.GetControl("ATTACK").SetValue(0.4) drives the sound exactly as a user turning it would; effect chains at instrument, bus and per-voice group level with sixteen buses and sixteen auxiliary stereo pairs; the seven modulator types with four behaviours and two scopes; the <midi> element with key switches, note sequences and the arpeggiator; and MPE read out of a MIDI file. Samples stream from disk under a memory budget, so a multi-gigabyte library plays inside a few hundred megabytes, and an archive is read in place rather than unpacked. Anything not honoured is reported per instrument (Problems, UnsupportedFeatures) and never thrown, and everything the engine does not implement is grouped and explained in DecentSamplerResidualTable. Oscillators and creative effects come from the add-on package below. "Decent Sampler" is Decidedly LLC's name for the format and its player, and is used here only to say what the files are.
• Playing audio that arrives as codec packets rather than as a file (PacketAudioPlayer) — the shape a media container's demultiplexer hands out. The player pulls packets from your IAudioPacketSource on the audio thread, owns the playback clock, seeks by contract (you move your source, then tell it where it now is), trims the encoder padding off the end of a track, and turns a reported gap into audio of exactly the length that was lost. Ogg Vorbis packets are built in; other codecs plug into the same packet codec seam.
• Playing a multi-track song on one transport (MultiTrackPlayer): one track per part, where a part can be a recording, a MIDI performance through a SoundFont, SFZ or Decent Sampler instrument, or both at once — switching between the two is a crossfade rather than a restart, because both are always rendered in step. Per-track gain, pan, mute, solo and signed offsets; a percussion rule for the zero-length notes drum parts are written with; optional level matching that makes a synthesized part sit where the recording sat in the mix and reports what the matched mix will peak at; offline rendering with no audio device, written out through any registered writer; and an export that merges every MIDI part into one General MIDI file. A Suno stems download loads straight into one (SunoStemsLoader) — the zip or the extracted folder, tolerant MIDI reading that reports what it could not honour rather than throwing, note counts, coverage and the notes each transcription holds so a near-empty or out-of-range part can be spotted, a measurement of how far each transcription sits from its own recording, exposed and overridable so the synthesized parts line up with the recorded ones, and one-line ways to say which instrument library a song plays through, which instrument one named part plays through, and which parts play from their transcription at all.
• Naming the instruments an application plays with (IInstrumentLibrary, InstrumentLibraryRegistry): an instrument library is a named set of instruments addressed the way MIDI addresses them — by program number, and by note number on the percussion channel — so the whole sound of an application changes by naming a different one. A library offers its instruments one part at a time (one synthesizer per voice, pinned to it, which is what a per-part gain or a layered second instrument needs) or as a single multi-timbral synthesizer that honours a file's own program changes, and reports exactly which programs, which drums and which part of the keyboard it really covers. Any .sf2 becomes a named library in one line (SoundFontInstrumentLibrary), sharing one loaded copy behind every synthesizer it creates. A MappedInstrumentLibrary starts from a library you already have and lets you replace voices one at a time — a Decent Sampler pack, an SFZ file, one program of another library, or a synthesizer of your own — leaving every voice you have not replaced exactly where it was. This package ships the seam and no instruments: registering is the application's decision, and with nothing registered the error says so.
• Playing a voiced arrangement as one synthesizer (RoutingSynthesizer): a child instrument per MIDI channel, each with its own gain and an optional layered second instrument, built eagerly or on first use. Every sequencer, player and offline renderer drives it as a single synthesizer, so the same arrangement plays live, follows a timeline that is still being written, and renders to a file through one code path. Re-voicing a part while it is sounding does not cut it off: the instrument being replaced is released and stays in the mix at its own gain until its notes and its effect tails have finished, under a settable limit, and the old behaviour is one switch away.
• Writing rendered audio by file name (AudioFileWriterRegistry), the mirror of the reader registry: .wav (32-bit IEEE float by default, 16- and 24-bit PCM on request) and .aif / .aiff are built in, and an add-on package adds its own format from the same Register() call it already uses for reading. SoundFontRenderer.RenderToFile and RenderToStream pick the writer from the file name, so bouncing a MIDI file or an ABC tune to another format is a change of extension. A writer never closes the stream it was handed, and says for itself whether it needs one that can seek.
• Audio analysis building blocks: fast Fourier transform, biquad filters, envelope follower, and voice-activity detection.

CodeBrix.Audio.Engine (bundled audio engine)

The same CodeBrix.Audio.MitLicenseForever package also ships CodeBrix.Audio.Engine, a full cross-platform audio engine: audio playback and recording, effects, editing/mixing, MIDI, synthesis, and visualization. Its types live under the CodeBrix.Audio.Engine.* namespaces (separate from CodeBrix.Audio.*).

The Engine has a native dependency: a bundled native backend, with an Ogg Vorbis decoder compiled in, shipped for seven runtime identifiers — Windows, macOS and Linux on x64 and ARM64, plus Linux on RISC-V 64. The correct native binary is selected automatically at runtime, and its licence notice travels beside it into your application's output folder. The backend is built from sources vendored in this repository and can be rebuilt from them; see tools/build_native_libraries/README.txt.

CodeBrix.Audio.ModestSynth (add-on synthesis package)

Sound that is generated rather than played back — band-limited saw, square and triangle waveforms, a sine, seeded white noise, a plucked string built as a digital waveguide, a multi-frame wavetable player, a 64-partial additive oscillator and a six-operator FM engine, together with the creative effects a synth is expected to have — ships as a separate package, CodeBrix.Audio.ModestSynth.MitLicenseForever, built from this repository and published alongside CodeBrix.Audio at the same version. It is MIT like the core, depends on nothing but the core, and is separate because synthesis is not something every application that reads a WAV file needs to carry. Use it directly; play a whole patch from MIDI through its own polyphonic synthesizer, which every player and offline renderer here accepts; or let one call at start-up hand its oscillators and effects to the Decent Sampler engine, through a parameter model that mirrors a sampler preset's oscillator settings one for one. That call is ModestSynth.Register(), and it belongs before an instrument is loaded: without it a preset whose group holds an oscillator, or whose chain names one of the creative effects, still loads and plays every sampled group, with one line in Problems naming the package.

That package also carries the instruments. GeneralMidiSynthesizer plays a .mid with no configuration at all, and GeneralMidiInstrumentLibrary.Register() — one line — puts the complete General MIDI sound set, all 128 programs and the 47-note percussion kit, into the instrument registry described above under the name ModestSynthGm. It is synthesis throughout, with no recorded sample anywhere in it, so it sounds like a good synthesizer rather than like sampled instruments; the two voice programs sing a vowel properly, through resonances that stay put while the note moves through them, with several singers to a key and no two of them holding the pitch quite the same way. For recorded instruments, name a SoundFont library or swap voices into a mapped library instead. CodeBrix.Audio registers nothing itself, so this is the call that makes the instrument seam sound.

Formats not included

Opus is deliberately not part of this package: it is BSD-3-Clause rather than MIT, so it ships separately as CodeBrix.Audio.Opus.BsdLicenseForever, which depends on this package and registers itself through the public extension points (SharedAudioOutput.RegisterCodecFactory for file playback, SharedAudioOutput.RegisterPacketCodecFactory for packet playback, and AudioFileReaderRegistry.Register for reading by file name). An Opus file opened without that package installed is recognised — duration, sample rate and channels all read — and fails with a message saying it is Opus.

Sample Code

Read an audio file into samples

using CodeBrix.Audio.Wave;

// .wav, .mp3, .ogg or .flac - the extension picks the decoder
using var reader = new AudioFileReader("track.ogg");
float[] buffer = new float[reader.WaveFormat.SampleRate * reader.WaveFormat.Channels];
int read = reader.Read(buffer);

Play a sound effect, as often as you like

using CodeBrix.Audio.Playback;

using var laser = SoundEffectClip.Load("laser.ogg");   // decoded once, into memory
laser.Play();                                          // fire and forget
laser.Play(0.4f);                                      // again, quieter, overlapping the first

Read and write a MIDI file

using CodeBrix.Audio.Midi;

var midi = new MidiFile("song.mid", strictChecking: false);
MidiFile.Export("song-copy.mid", midi.Events);

Play MIDI music through a SoundFont

using CodeBrix.Audio.Playback;
using CodeBrix.Audio.Synth;

var soundFonts = new SoundFontCache();          // a .sf2 is large - load it once, share it

var music = new MidiMusicPlayer();
music.Load(soundFonts.Get("GeneralUser.sf2"), new MidiSequence("level1.mid"));
music.IsLooping = true;
music.Play();                                   // same transport surface as AudioFilePlayer

Play MIDI music through an SFZ instrument

using CodeBrix.Audio.Playback;
using CodeBrix.Audio.Synth;
using CodeBrix.Audio.Synth.Sfz;

var instruments = new SfzInstrumentCache();     // samples decode once - load an instrument once, share it

var music = new MidiMusicPlayer();
music.Load(instruments.Get("VirtualPiano.sfz"), new MidiSequence("song.mid"));
music.Play();                                   // the same transport drives .sf2 and .sfz alike

// instruments.Get(...).UnsupportedOpcodes lists anything the file asked for that the
// engine does not implement - the first thing to check if a library sounds off.

Play MIDI music through a Decent Sampler instrument

using CodeBrix.Audio.ModestSynth;               // only if a preset generates rather than samples
using CodeBrix.Audio.Playback;
using CodeBrix.Audio.Synth;
using CodeBrix.Audio.Synth.DecentSampler;

ModestSynth.Register();                         // BEFORE any instrument is loaded

using var instrument = DecentSamplerInstrument.Load("Choir.dslibrary");
instrument.GetControl("ATTACK")?.SetValue(0.35);   // the preset's own knob

using var music = new MidiMusicPlayer();
music.Load(instrument, new MidiSequence("song.mid"));
music.Play();                                   // the same transport drives .sf2, .sfz and .dspreset

// instrument.Problems and instrument.UnsupportedFeatures say what a preset asked for
// that could not be honoured - the first thing to check if a library sounds off.

Play a stems download as one song, and swap a part to its MIDI

using CodeBrix.Audio.Playback;
using CodeBrix.Audio.Playback.Suno;

var song = SunoStemsLoader.Load("My Song Stems.zip");   // the zip, or the folder

using var player = song.CreatePlayer(new SunoPlayerOptions
{
    InstrumentLibraryName = "ModestSynthGm",            // one name changes the whole sound
    MidiStems = SunoStemSelection                       // everything with a usable
        .EverythingBut("Vocals", "Backing Vocals"),     //   transcription but the voices
    AutoSetRelativeTrackLevels = true,                  // synthesized parts sit where the recordings sat
});

var bass = player["Bass"];                              // by name, like song["Bass"]
if (bass.HasMidiSource)                                 // switching a part is a
{                                                       //   crossfade, not a restart
    bass.ActiveSource = TrackSource.Midi;
}

player.Prepare();
await player.LevelMeasurement;                          // the levels are in when this
                                                        //   returns - never null, so
                                                        //   no guard is needed
player.Play();

// Offline instead, with no audio device: measure the levels (Prepare opens the device),
// then bounce the result in whatever format the extension names.
// player.MeasureRelativeTrackLevels(48000);
// player.Volume = player.LastLevelMatch.SuggestedVolume;   // matching peaks past 1.0
// player.RenderToFile("mix.wav", new WaveFormat(48000, 16, 2));

// Or build the song yourself, one track per part:
// var mix = new MultiTrackPlayer();
// mix.Add(new AudioTrack("drums.wav", "Drums"));
// mix.Add(new MidiTrack(sequence, rate => new SoundFontSynthesizer(gm, rate), "Bass"));

React to the music, and mix a layer live

var music = new MidiMusicPlayer();
music.Load(soundFonts.Get("GeneralUser.sf2"), new MidiSequence("battle.mid"));

// Observe-only: runs on the audio thread and cannot break playback. This is the
// hook for driving something outside the audio - a screen shake on a drum hit,
// a particle on a note, a rhythm-game display.
music.MidiMessageProcessed = (channel, command, note, velocity) =>
{
    if (command == 0x90 && velocity > 0 && channel == 9)    // channel 10 = drums
        Volatile.Write(ref _drumHitPending, 1);             // your own thread reads this
};

music.Play();

music.SetChannelVolume(3, 0f);   // fade a layer out of the arrangement...
music.SetChannelVolume(3, 1f);   // ...and back in
music.Speed = 0.75f;             // slow motion, unchanged pitch

MidiMessageFilter is the other hook — it replaces delivery, so it can transpose, re-channel or suppress messages. A filter that forgets to forward the message silences the music; use MidiMessageProcessed when you only want to watch. See AGENT-README.txt.

Render MIDI music to a WAV file, with no audio device

using CodeBrix.Audio.Synth;

SoundFontRenderer.RenderToWavFile(
    new SoundFont("GeneralUser.sf2"),
    new MidiSequence("level1.mid"),
    "level1.wav",
    tail: TimeSpan.FromSeconds(2));             // let the reverb decay rather than cutting it

// The same renderer takes an SfzInstrument in place of the SoundFont.

Two SoundFont paths, on purpose. CodeBrix.Audio.Synth is the renderer of record for playing a .sf2. The bundled Engine's CodeBrix.Audio.Engine.Synthesis is a general-purpose synthesis architecture — oscillators, custom banks, MPE, arpeggiators — that can sample-play SF2 presets but has no modulators, per-voice LFO or per-voice filter. Use the first to reproduce somebody's SoundFont, the second to build an instrument. AGENT-README.txt covers the split in detail.

Play a MIDI file with no SoundFont to find, and swap one voice for your own

using CodeBrix.Audio.Instruments;
using CodeBrix.Audio.Midi;
using CodeBrix.Audio.ModestSynth;               // the synthesis add-on
using CodeBrix.Audio.Synth;

GeneralMidiInstrumentLibrary.Register();        // registers as "ModestSynthGm"

var voices = new MappedInstrumentLibrary(
    "MyVoices", "ModestSynthGm, with a few voices of my own", "ModestSynthGm");

var piece = new MidiSequence("piece.mid");

// Every voice is ModestSynthGm's, and the file's own program changes choose them.
SoundFontRenderer.RenderToFile(
    voices.CreateMultiTimbralSynthesizer(44100), piece, "take-1.wav",
    TimeSpan.FromSeconds(2));

// Replace ONE voice with a pack of your own; everything else is unchanged.
voices.SetInstrument(GeneralMidiProgram.ChoirAahs, "Whisper Choir.dspreset");

SoundFontRenderer.RenderToFile(
    voices.CreateMultiTimbralSynthesizer(44100), piece, "take-2.wav",
    TimeSpan.FromSeconds(2));

RenderToFile picks the writer from the extension, so "take-2.aiff" writes AIFF and a format registered by an add-on package is reached the same way. Nothing registers an instrument library for you — with an empty registry the exception names GeneralMidiInstrumentLibrary.Register().

Play audio that arrives as codec packets

using CodeBrix.Audio.Playback;
using CodeBrix.Audio.Wave;

SharedAudioOutput.Configure(48000);          // what media containers carry

var player = new PacketAudioPlayer();
player.PlaybackEnded += (s, e) => { /* the track finished */ };

// codecPrivate is the setup data the container carries for the track; mySource
// is your IAudioPacketSource, which the player pulls from on the audio thread.
player.Open("vorbis", codecPrivate, mySource);
player.SetTrailingTrim(TimeSpan.FromMilliseconds(12));   // drop the encoder padding
player.Volume = 0.8f;
player.Play();

TimeSpan where = player.Position;            // the audio clock; readable from any thread

Running dry is not an error: return false from TryReadPacket with EndOfStream still false and the player plays silence for that moment and keeps the voice alive. See AGENT-README.txt, "PLAYING AUDIO THAT ARRIVES AS PACKETS", for seeking, trimming and packet loss.

Documentation

The NuGet package includes AGENT-README.txt, a complete API reference and usage guide written for AI coding agents - point your agent at that file when it is writing code against this library. One file covers both bundled assemblies, because one package ships both.

Additional sample code and usage examples are available in the CodeBrix.Audio.Tests project: https://github.com/ellisnet/CodeBrix.Audio/tree/main/tests/CodeBrix.Audio.Tests

License

CodeBrix.Audio is licensed under the MIT License - see the LICENSE file.

For licensing and provenance information about the open source code included in this package, see THIRD-PARTY-NOTICES.txt.