SoundFlow v1.4.0 - A Temporary Farewell

Release Notes - SoundFlow v1.4.0

The Security, Performance & Goodbye Update.

SoundFlow v1.4.0 is a milestone release that expands the framework's capabilities into the critical domain of audio security, introducing a professional-grade suite for content protection, identification, and authentication.

Alongside these transformative new features, this version delivers crucial core engine enhancements, improved performance, better NativeAOT compatibility, and important bug fixes, solidifying SoundFlow as a mature and robust solution for .NET audio development.

---

🌟 Key Highlights

• ✨ Introducing a Comprehensive Security Suite: A unique, professional-grade toolkit for audio content protection. Protect your work with military-grade AES-256 encryption, authenticate it with ECDSA digital signatures, embed robust ownership watermarks, and identify audio clips with acoustic fingerprinting.
• 🚀 Enhanced Core Engine & Performance: Fine-tune the balance between audio quality and CPU usage with new configurable Time-Stretching presets (from Fast to Audiophile). Enjoy full NativeAOT compatibility for blazing-fast, self-contained applications.
• 🎧 High-Quality MP3 Encoding & Modernized APIs: Create high-quality MP3s with the newly integrated LAME encoder. The core Recorder API has also been updated to use the Result pattern for safer, more robust error handling.
• 🎓 Six New Sample Projects: Get started quickly with comprehensive examples for every new security feature, from encryption and signing to watermarking and fingerprinting.

---

A Final Update Paired with the Long Goodbye

In the last release, I spoke of a "very long goodbye" due to mandatory military service. I also hoped I could squeeze in one final push.

This is it.

Built on borrowed time, this isn't just a patch. It's my commitment to leaving SoundFlow in a state I'm proud of, complete with the security suite I always envisioned, a few reasons for it is explained in #105.

This project was once an abandoned component I nearly shelved. It was your engagement—the stars, the bug reports, and seeing people actually build things with it—that gave it a new purpose. This final release is my thank you for giving my work a life I never expected.

My service begins January 11, 2026, with an expected return in February/March 2027. Until then, the project enters hibernation, More details explained in this Announcement.

Thank you for everything. I hope this serves you well.

— Ahmed Abdallah (SoundFlow's Maintainer)

---

✨ Major New Features: The Security Suite

SoundFlow now provides a complete, integrated toolkit for securing and identifying your audio content.

🔐 Content Encryption & Digital Signatures

• Robust Encryption: Protect your audio with seekable AES-256-CTR stream encryption. We've introduced a new secure audio container format (.sfa) that wraps your audio data securely.
• Authenticity & Integrity: Ensure your files haven't been tampered with using ECDSA-P384 digital signatures. Signatures can be embedded directly into the secure audio container or saved as detached .sig files. This feature is also available for .sfproj project files!
• High-Level API: Use the new AudioEncryptor and FileAuthenticator static classes for easy, high-level access to encryption and signing workflows.

💧 Audio Watermarking

• Robust Ownership Watermarking: Embed inaudible ownership information (like a copyright string) directly into an audio signal using Direct-Sequence Spread Spectrum (DSSS). This watermark is designed to be robust and survive common transformations like re-encoding, format changes, and volume adjustments.
• Fragile Integrity Watermarking: Detect tampering with a fragile watermark that uses block-chained LSB hashing. Any modification to the audio file will break the chain, allowing you to verify its integrity.
• Automatic Tuning: The new WatermarkTuner can analyze an audio file and automatically determine the optimal strength and spread factor for the most robust and inaudible result.

👂 Acoustic Fingerprinting

• Identify Audio Content: Generate robust acoustic fingerprints based on spectral peak analysis. This allows you to identify a short, unknown audio clip by matching it against a database of known tracks.
• Extensible Storage: We've introduced an IFingerprintStore interface and a reference InMemoryFingerprintStore to make it easy to integrate with any database backend (SQL, NoSQL, etc.).

---

🚀 Core Engine & Performance Enhancements

• Configurable Time-Stretching: The WSOLA time-stretcher is now fully configurable with performance presets (Fast, Balanced, HighQuality, Audiophile). You can now fine-tune the balance between audio quality and CPU performance for time-stretching operations.
• NativeAOT Safety: Introduced a TypeRegistry and a source-generated SoundFlowJsonContext to ensure that all built-in and custom modifiers/analyzers are preserved during NativeAOT compilation, preventing runtime errors caused by code trimming.
• High-Quality MP3 Encoding: We now bundle and statically link the LAME library with our FFmpeg codec, providing high-quality MP3 encoding capabilities out of the box.
• Improved Recorder API: The Recorder component now uses the Result pattern for better error handling and integrates directly with the new digital signing feature for creating authenticated recordings.
• More Performant Logging: The logging system has been refactored to use a LogEntry struct, reducing heap allocations and providing more structured data (caller, timestamp) to subscribers.
• Robust FFmpeg Encoder: The native FFmpeg encoder has been rewritten to use an audio FIFO buffer, allowing it to reliably handle audio input of any size and feed it correctly to codecs that require fixed-size frames (like MP3).

---

⚠️ Breaking Changes

• The Log.OnLog event signature has changed from Action<LogLevel, string> to Action<LogEntry>. Subscribers must be updated to handle the new LogEntry struct for more structured logging data.
• The Filter.FilterType enum has been moved from a nested class to the global namespace SoundFlow.Enums.FilterType. You will need to update your using statements or fully qualify the type name.
• Methods on the Recorder component, such as StartRecording and StopRecordingAsync, now return Result or Task<Result> instead of void or Task. You must now handle the returned result object for error checking.

If you are migrating from v1.3.x, please check the detailed migration guide:

https://lsxprime.github.io/soundflow-docs/#/docs/1.4.0/migration-guide

---

📚 Learning Resources & Samples

To help you get started with these powerful new features, we've added six new sample projects:

• SoundFlow.Samples.Security.Encryption: Demonstrates end-to-end file encryption, decryption, and real-time playback of secure audio.
• SoundFlow.Samples.Security.Authentication: Illustrates creating digital signatures, verifying file authenticity, and detecting tampering.
• SoundFlow.Samples.Security.OwnershipWatermarking: Shows how to embed a robust watermark that survives a simulated audio attack.
• SoundFlow.Samples.Security.IntegrityWatermarking: Demonstrates using a fragile watermark to detect even minor modifications to an audio file.
• SoundFlow.Samples.Security.Fingerprinting: Shows how to index a full audio track and then identify an unknown clip from it.
• SoundFlow.Samples.Recording: Demonstrates a clean recording flow with metadata and digital signing.

---

🛠️ Bug Fixes & Minor Improvements

• Fix: The FFmpeg decoder now correctly flushes buffered samples from the resampler, preventing truncated audio at the end of streams.
• Fix: Re-enabled the miniaudio build for Windows ARM64 and included the binary.
• Refactor: The SoundFlow.Samples.SimplePlayer project has been completely refactored into a clean, service-oriented architecture, making it a much better learning resource.
• Build: Updated GitHub Actions workflows to use newer, more stable runners (e.g., macos-15-intel).

---

Get Started with v1.4.0

📦 NuGet Packages

You can download the latest packages from NuGet:

• SoundFlow v1.4.0
• SoundFlow.Codecs.FFMpeg v1.4.0
• SoundFlow.Midi.PortMidi v1.4.0
• SoundFlow.Extensions.WebRtc.Apm v1.4.0

📚 Documentation

The official documentation has been fully updated for v1.4.0, with detailed guides and API references for all the new security features and core enhancements.

View the v1.4.0 Documentation

---

Thank you again for being part of this journey.
— Ahmed Abdallah (SoundFlow's Maintainer)

SoundFlow v1.3.0

Release Notes - SoundFlow v1.3.0

1480 Hours of Development - 1480 Hours of Goodbye.
That is the effort poured into this release. Version 1.3.0 is not just an update; it is a complete transformation of the library from a playback engine into a comprehensive creative audio framework.

This release introduces a pluggable codec architecture (FFmpeg), a complete MIDI sequencing and routing engine, a polyphonic synthesizer with SoundFont support, and a comprehensive metadata reading/writing API.

---

🌟 Key Highlights

• FFmpeg Codecs: Native support for decoding and encoding major formats (MP3, AAC, OGG, Opus, FLAC, ALAC) via a new pluggable extension.
• MIDI & Synthesis: A complete MIDI I/O backend, a built-in polyphonic Synthesizer, and SoundFont (.sf2) playback capability.
• Advanced Metadata: Read and write metadata tags (ID3v2, Vorbis Comments, MP4 Atoms) across all supported formats.
• MIDI Mapping: A reflection-based system to bind MIDI controllers to any audio parameter (Volume, Cutoff, etc.) in real-time.

---

📢 An Update, and a Very Long Goodbye

So, this update is finally out. It took 1480 hours of actual work to get here, a true labor of love (at the current moment, I am sure I am just a shut-in nerd). Hope you enjoy it, because... things are about to get interesting...

And now, for the main event: I have a mandatory engagement coming up. I’m heading off for a little vacation known as forced military service. This "vacation" lasts either 1 year (if the cosmos smiles upon me), or 3 years (which is, well, my actual suicide trigger).

The best part? No internet-enabled phone, no computer access. Total blackout.

So, this is almost certainly the last update you’ll see for a very long time. I might manage to squeeze one final push out before my mandatory long goodbye, but don't count on it.

I did the best I could with the time I had left. Enjoy it.

And to everyone who starred SoundFlow and actually used it - thank you. Seriously. Maybe someday I'll be that legendary unpaid open-source developer who finally breaks the entire modern infrastructure, too.

Oh, and Check out my other project, LSXPrime/ProseFlow. It's a system-wide, privacy-focused Copilot that's actually helpful, and I’m sure it will be a great assist to some of you.

---

🚀 New Features

🎧 Codecs & Formats (SoundFlow.Codecs.FFMpeg)

• Pluggable Architecture: AudioEngine now supports ICodecFactory registration, allowing dynamic addition of format support.
• New Extension: Introduced SoundFlow.Codecs.FFMpeg.
  • Decoders: MP3, AAC, OGG Vorbis, Opus, FLAC, ALAC, AC3, WAV, AIFF, and more.
  • Encoders: Write audio streams to MP3, AAC/M4A, FLAC, and WAV.
• Automatic Format Detection: AssetDataProvider and StreamDataProvider now probe streams to determine the correct codec automatically based on file headers.

🎹 MIDI & Synthesis (SoundFlow.Midi & SoundFlow.Synthesis)

• PortMidi Backend: Cross-platform MIDI I/O support via SoundFlow.Midi.PortMidi.
• MidiManager: A central hub for routing MIDI messages between physical devices and internal components.
• Synthesizer Component:
  • Multi-timbral, polyphonic synthesis engine.
  • Support for SoundFonts (.sf2) via SoundFontBank.
  • MPE (MIDI Polyphonic Expression) support for per-note pitch bend, pressure, and timbre.
  • Built-in ADSR envelopes, LFOs, and Filter modulation.
• MIDI Modifiers: Real-time MIDI effects including:
  • ArpeggiatorModifier (Up, Down, Random patterns).
  • HarmonizerModifier (Chord generation).
  • RandomizerModifier (Velocity/Pitch randomization).
  • VelocityModifier (Curves and scaling).
  • TransposeModifier.

📝 Metadata API (SoundFlow.Metadata)

• Unified Reader/Writer: Static SoundMetadataReader and SoundMetadataWriter classes.
• Format Support:
  • MP3: ID3v1 and ID3v2.3/2.4 reading and writing.
  • FLAC/OGG: Vorbis Comments and embedded pictures.
  • MP4/M4A: iTunes-style metadata atoms (moov/udta/ilst).
  • WAV/AIFF: RIFF INFO chunks and ID3 chunks.
• Cue Sheets: Support for parsing embedded Cue Sheets in FLAC and WAV.

🎛️ Core & Audio Processing

• Composition Overhaul:
  • Split responsibilities into CompositionEditor, CompositionRecorder (MIDI recording), and CompositionRenderer.
  • Added MidiTrack and MidiSegment alongside existing Audio tracks.
  • Project serialization now saves MIDI data, mappings, and tempo maps.
• ChannelMixer: New SIMD-accelerated (AVX/SSE) utility for efficient Mono/Stereo/Surround upmixing and downmixing.
• ResamplerModifier: Real-time variable speed/pitch resampling effect.
• MIDI Mapping: Use [ControllableParameter] attribute on properties to expose them to the new MidiMappingManager. Bind physical knobs to software parameters with Linear or Logarithmic scaling.

---

📚 Learning Resources & Samples

The documentation website has been fully updated to reflect the v1.3.0 API changes and new features.

We have also added three new sample projects to help you get started with the new capabilities:

• SoundFlow.Samples.Midi.BasicSequencing: Demonstrates how to programmatically create MIDI tracks, notes, and playback via the Synthesizer.
• SoundFlow.Samples.Midi.PropertyMapping: Shows how to map external MIDI controllers to software parameters (like Filter Cutoff) using the MidiMappingManager.
• SoundFlow.Samples.Midi.SynthesisModifiers: Illustrates how to use the Arpeggiator and Harmonizer modifiers to generate complex performances from simple input.

---

🛠 Improvements

• SIMD Math: Updated MathHelper and ChannelMixer to leverage hardware intrinsics for faster mixing and FFT operations.
• Logging: Replaced Console.WriteLine calls with a centralized SoundFlow.Utils.Log class. Subscribe to Log.OnLog to redirect internal engine logs to your own logging framework.
• Native Builds: Completely restructured the native C/C++ layer with dedicated CMake projects for miniaudio, portmidi, and ffmpeg-codec, including automated NuGet packaging via .targets.

---

📦 New & Updated NuGet Packages

All SoundFlow packages have been updated to version 1.3.0 and are available for download. This release introduces two major extensions required to unlock the new MIDI and Codec capabilities.

New Packages

• SoundFlow.Codecs.FFMpeg
  • Adds support for decoding and encoding MP3, AAC, OGG, Opus, FLAC, ALAC, and more.
• SoundFlow.Midi.PortMidi
  • Provides the cross-platform backend for MIDI I/O, device management, and synchronization.

Updated Packages

• SoundFlow (Core Library)
• SoundFlow.Extensions.WebRtc.Apm (Echo Cancellation & Noise Suppression)

---

⚠️ Breaking Changes

Version 1.3.0 introduces significant structural changes. If you are migrating from v1.2.x, please check the detailed migration guide:

https://lsxprime.github.io/soundflow-docs/#/docs/1.3.0/migration-guide

V1.2.1

SoundFlow v1.2.1 Release Notes

This release focuses on improving the reliability of network audio playback and introduces side performance optimization for a smoother, more resilient experience. The highlight is a new background buffering system that isolates the audio engine from network instability, preventing common playback failures and crashes.

---

✨ Improvements & Performance Gains

• Optimized Audio Device Enumeration to Reduce Memory Usage: The process of enumerating audio devices (EnumerateDevices) has been updated to reuse its internal device list buffer instead of allocating a new array on every call. This significantly reduces memory allocations and garbage collector pressure, improving overall performance in applications that frequently poll for device changes.

---

🐛 Bug Fixes

• Network & Streaming
  • Fixed Audio Engine Crashes from Unstable Network Streams: Resolved a critical issue where an unstable network connection or a stream that closed prematurely could throw an HttpIOException directly on the sensitive audio processing thread. This would cause an unrecoverable crash of the audio device callback, stopping all playback. The DirectStreamProvider now utilizes a new BufferedNetworkStream which downloads and caches audio in a background task. This buffering strategy decouples the audio thread from network volatility, allowing it to handle sudden connection drops gracefully by treating it as the end of the stream, rather than a fatal error. This makes all network audio playback significantly more robust and reliable.
• Core Audio
  • Restoring Loop Points Functionality: The core audio engine now proactively checks for loop boundaries before audio generation. This addresses an issue where specific loop end points were not consistently respected, ensuring that audio loops as intended, even in scenarios with custom loop ranges.

V1.2.0

SoundFlow v1.2.0 Release Notes: The Multi-Device Evolution

---

We are thrilled to announce SoundFlow v1.2.0, a landmark release that introduces a major architectural refactoring designed to fundamentally enhance how you interact with audio devices. This version moves away from a singleton-based model to a device-centric, instance-based architecture, enabling true multi-device input and output. You can now manage and switch between multiple playback and capture devices simultaneously and independently, opening up a world of new possibilities for complex audio applications.

This release not only revolutionizes device management but also integrates several new features, performance improvements, and critical bug fixes, building on the stable foundation of recent patches.

---

🚀 Key Highlights of v1.2.0

• True Multi-Device Architecture: Manage multiple independent audio playback, capture, and full-duplex devices simultaneously.
• Enhanced Control & Flexibility: Explicit control over audio contexts and seamless device switching APIs.
• New VoiceIsolationEffect: An experimental audio modifier for isolating human speech frequencies.
• Integrated Critical Fixes: Includes the significant memory reduction and recording bug fixes first introduced in v1.1.2.
• 🚨 BREAKING CHANGE: This is a fundamental architectural shift that requires adapting your existing SoundFlow API calls.

---

✨ New Features & Architectural Changes

• Multi-Device Architecture Revolution:
  • The global AudioEngine.Instance and Mixer.Master have been removed. The new design introduces explicit AudioPlaybackDevice, AudioCaptureDevice, and FullDuplexDevice abstractions.
  • Each device now manages its own independent audio graph and MasterMixer, allowing for isolated control and parallel operations.
  • This enables true multi-channel and multi-device applications, e.g., capturing from one device while playing back to another, or even operating multiple playback devices concurrently.
• Granular Native Device Configuration:
  • The native device configuration layer now utilizes a comprehensive Data Transfer Object (DTO), enabling more granular control over backend-specific settings (e.g., WASAPI, ALSA, etc.), improving low-level compatibility and tuning.
• Explicit Context & Dependency Injection:
  • Core components (such as SoundComponent, ISoundDataProvider, SoundModifier, and AudioAnalyzer derivatives) now receive AudioEngine and AudioFormat context directly via their constructors.
  • This change removes implicit dependencies on global state, leading to a cleaner, more testable, and more robust codebase.
• Robust Device Switching API:
  • A new, powerful Engine.SwitchDevice() API allows for seamless hot-swapping of active audio devices without losing state. Components, event subscribers, and other configurations are preserved during the switch.
• New VoiceIsolationEffect (Experimental):
  • Introduced an experimental audio modifier that acts as a band-pass filter. This effect is designed to help isolate and enhance human speech frequencies within an audio stream, useful for applications like voice chat or transcription.
• New MultiEngines Sample Project:
  • A new sample project has been added to the codebase specifically to demonstrate and test the new multi-device capabilities, serving as an excellent starting point for developers.

---

🔧 Improvements & Bug Fixes (Integrated from v1.1.2 and more)

This release incorporates and builds upon the critical fixes and optimizations previously introduced in SoundFlow v1.1.2, ensuring that v1.2.0 provides the most stable and performant experience.

• Massive Memory Reduction for Network Data Provider:
  • The NetworkDataProvider has been refactored to use a chunked streaming and decoding model. This resolves excessive memory usage, drastically reducing memory consumption for long audio files (e.g., from ~1GB down to ~20MB for a 15-minute audio file).
• Critical Audio Recording Bug Fixed:
  • Corrects a severe audio format conversion bug that previously produced garbled or corrupted audio when recording to formats other than F32. Recording to all supported PCM formats (U8, S16, S24, S32) is now reliable and accurate.
• Improved FFT Consistency & Accuracy:
  • Unified the FFT implementations in MathHelper for Scalar, SSE, and AVX paths to ensure consistent behavior across different CPU architectures. SIMD paths are now toggleable via static properties for easier debugging.

---

🚨 Breaking Changes: Action Required!

This release introduces a fundamental architectural change that affects the entire public API of SoundFlow. Please review the following changes carefully:

• AudioEngine.Instance Removed: The global singleton AudioEngine.Instance has been removed. You must now explicitly instantiate an AudioEngine (e.g., new MiniAudioEngine()).
• Audio Playback Model Shift: Audio is no longer played by adding components to Mixer.Master. You must now first initialize a device (e.g., engine.InitializePlaybackDevice(...)) and then add components to that specific device's MasterMixer.
• Constructor Changes for Core Components: The constructors for nearly all SoundComponent, ISoundDataProvider, SoundModifier, and AudioAnalyzer derivatives have changed. They now require an AudioEngine and/or AudioFormat instance to be passed in.
• AudioEngine.OnAudioProcessed Event Removed: The global AudioEngine.OnAudioProcessed event is no longer available. Events for processed audio are now tied to specific devices (e.g., AudioCaptureDevice.OnAudioProcessed).
• SwitchDevice API Overhaul: The previous SwitchDevice API is replaced with new, more explicit methods on the AudioEngine instance that return a new device object.

We highly recommend reviewing the fully updated documentation website, which now reflects all v1.2.0 changes: https://lsxprime.github.io/soundflow-docs/, and exploring the new MultiEngines sample project to adapt your existing code to the new architecture.

---

This release marks a significant milestone for SoundFlow, providing unprecedented flexibility, robustness, and scalability for your audio applications. We are excited to see what you build with these new capabilities!

As always, we welcome your feedback and contributions. Thank you for being a part of the SoundFlow community.

V1.1.2

SoundFlow v1.1.2 Release Notes

---

Important Note for Users

This release, SoundFlow v1.1.2, is a critical maintenance patch specifically designed for users who are unable to upgrade to the new device-centric architecture introduced in SoundFlow v1.2.0.

If you can upgrade to v1.2.0, we strongly recommend doing so, as it represents a significant architectural leap with new features and further optimizations that supersede the fixes in this version. For all other users, v1.1.2 delivers a host of essential bug fixes and crucial stability improvements for the v1.1.x codebase.

---

This patch is packed with vital corrections that address core audio processing, memory management, and format conversion issues, significantly enhancing the stability and reliability of SoundFlow v1.1.x.

Key Highlights:

• Critical Audio Recording Bug Fixed: Resolved a severe bug that previously resulted in garbled audio when recording to formats other than F32.
• Massive Memory Consumption Reduction: Eliminated excessive memory usage for long audio files, reducing consumption from ~1GB to a mere ~20MB for a 15-minute file.
• Enhanced Audio Processing Accuracy & Consistency: Corrected inaccuracies and inconsistencies in core FFT operations, leading to more reliable and precise audio analysis.
• Comprehensive Audio Format Conversion Fixes: Implemented robust and accurate conversions for various PCM formats, addressing previous limitations and ensuring correct handling during capture and playback, including full 24-bit support.

---

🐛 Critical Bug Fixes & Stability Improvements

This release focuses heavily on resolving stability issues and correcting erroneous behavior across the audio engine.

• Memory Management
  • Resolved Excessive Memory Usage: The NetworkDataProvider has been thoroughly refactored to eliminate memory leaks. This critical change resolves the issue of excessive memory consumption, drastically reducing the memory footprint (e.g., from ~1GB down to ~20MB for a 15-minute audio file).
• Audio Core & FFT Processing
  • Corrected FFT Inconsistencies: Unified the FFT implementations across Scalar, SSE, and AVX paths in MathHelper to ensure consistent and predictable behavior regardless of the CPU instruction set used. These SIMD paths are now toggleable for easier debugging.
  • Fixed FFT Accuracy Issues: Enhanced the accuracy of Fast Fourier Transform (FFT) and Inverse FFT (IFFT) operations by improving window function generation, refining cosine approximations, and implementing proper IFFT scaling, resolving previous precision issues.
• Audio Format Conversion & Recording
  • FIXED: Garbled Audio Recording: Corrected a critical audio format conversion bug that previously produced garbled or corrupted audio when recording to formats other than F32 (float 32-bit). Recording to all supported PCM formats (U8, S16, S24, S32) is now reliable and accurate.
  • Improved & Centralized Format Conversion Robustness:
    • Introduced a ProcessingDirection enum to provide clear guidance to the central ProcessAudio method, improving the predictability and control of audio flow.
    • Centralized buffer management and format conversion dispatch within ProcessAudio, now leveraging ArrayPool for efficient handling of temporary buffers, eliminating previous inefficiencies.
    • Replaced previous, less robust format-specific conversion methods with generic ConvertFloatTo<T> and ConvertFrom<T> for common integer PCM formats (U8, S16, S32), fixing inflexibility.
    • Added specific ConvertFloatToS24 and ConvertFromS24 methods, providing full and accurate support for 24-bit PCM, addressing a previous capability gap.
    • Resolved 8-bit Audio Quality Degradation: Added dithering to unsigned 8-bit (U8) input conversions to significantly improve audio quality and prevent quantization noise when down-converting.
    • Ensured full and reliable support for converting various PCM formats (S16, S24, S32, U8) to/from internal float buffers for both audio input (capture) and output (playback), addressing prior conversion limitations.

---

✨ Performance Enhancements

• Optimized Core FFT Operations: Core FFT operations, including bit reversal and complex multiplication, have been optimized for improved processing performance and efficiency.

---

We encourage all users who can upgrade to SoundFlow v1.2.0 to do so to benefit from its new architecture and features. For those remaining on the v1.1.x branch, this update provides essential stability and performance enhancements.

V1.1.1

SoundFlow v1.1.1 Release Notes

This is a significant stability and performance release. We have addressed several edge-case bugs in the audio processing pipeline, improved performance for standard playback, and enhanced support for live audio streaming. The native library loading mechanism has also been completely overhauled for greater reliability across all supported platforms.

---

✨ Improvements & Performance Gains

• Optimized Playback at Normal Speed: The audio processing pipeline is now bypassed when playback speed is set to the default 1.0x. This significantly reduces CPU overhead for standard playback, leading to better performance and lower resource consumption in common use cases.
• More Robust Native Library Loading: The method for locating and loading the miniaudio native library has been rewritten for improved reliability. The system now first attempts to load the library using the operating system's standard search paths before falling back to the packaged runtimes directory. This resolves potential DllNotFoundException errors in various deployment scenarios (e.g., framework-dependent vs. self-contained) and improves compatibility across Windows, macOS, and Linux.

---

🐛 Bug Fixes

• Audio Core & Processing

  • Corrected Mono Panning Logic: Fixed a flaw in how volume is calculated for mono sound sources during stereo panning. The new implementation uses a "constant power" formula, which prevents the noticeable dip in volume that previously occurred when a sound was panned to the center.
  • Improved Seek Stability and Time-Stretching Reliability: Resolved a critical bug in the buffer management logic for the time-stretching engine (WSOLA) that could lead to an ArgumentOutOfRangeException during frequent seeks or specific playback speed changes. The input buffer is now correctly compacted and refilled, preventing potential audio artifacts, stuttering, or crashes during playback at speeds other than 1.0x, especially after seeking.
  • Prevented Audio Clipping Artifacts: Implemented a final safety check that clamps audio samples to the valid range (-1.0 to 1.0) before they are sent to the output buffer. This prevents harsh digital distortion that could occur in rare edge cases of audio processing.

• Network & Streaming

  • Fixed Premature Stoppage of Live Streams: The playback engine now correctly handles audio streams of unknown or infinite length (e.g., HLS live radio). Previously, a temporary network buffer underrun could be misinterpreted as the end of the stream, causing playback to stop. The player will now correctly wait for more data, making live streaming reliable.
  • Prevented Application Hangs on Stalled Network Streams: Introduced a timeout mechanism in the network data provider. If a stream provides no data for an extended period (~5 seconds), the player will gracefully stop waiting instead of hanging indefinitely. This improves the stability and responsiveness of the application when dealing with unreliable network connections.

V1.1.0

SoundFlow v1.1.0 Release Notes

This is a landmark release for SoundFlow, introducing a powerful Non-Destructive Audio Editing and Persistence Engine. This update provides developers with a complete framework for building sophisticated audio editing applications, from simple clip arrangement to complex multi-track projects with effects, time-stretching, and project saving/loading capabilities.

✨ Major New Features

1. The SoundFlow.Editing Module: A Full-Featured Audio Editing Engine

We are thrilled to introduce a comprehensive, non-destructive editing module. This suite of tools allows you to build complex audio timelines programmatically.

• Composition as a Canvas: The new Composition class acts as your main project container, holding multiple Track objects.
• Multi-Track Support: Mix and manage several audio Tracks simultaneously. Each track has its own settings for volume, pan, mute, and solo.
• Audio Segments (Clips): The AudioSegment is the core building block. Place segments on a track's timeline, specifying a start time and duration from any audio source.
• Advanced Segment Controls: Each segment comes with a rich AudioSegmentSettings object, allowing for:
  • Independent volume, pan, and speed adjustments.
  • Segment-level effects and analyzers.
  • Reversing: Play audio clips backward with a simple IsReversed = true flag.
  • Looping: Repeat segments a specific number of times or to fill a target duration using LoopSettings.
  • Fades: Apply smooth FadeIn and FadeOut effects with Linear, Logarithmic, and S-Curve shapes.

2. Pitch-Preserved Time Stretching & Advanced Speed Control

Manipulating the timing of audio is now more powerful than ever.

• WSOLA Time Stretching: A new TimeStretchFactor property on AudioSegment allows you to change the duration of an audio clip without altering its pitch. This is perfect for fitting dialogue or music to a specific time slot. Internally, this is powered by a new, high-quality WsolaTimeStretcher component.
• Target Duration Stretching: You can now set a TargetStretchDuration on a segment, and SoundFlow will automatically calculate the required stretch factor to make it fit perfectly.
• Classic Speed Control: The SpeedFactor property remains, allowing for classic varispeed effects that adjust both tempo and pitch (like a tape machine).

3. Project Persistence: Save and Load Your Compositions

A complete SoundFlow.Editing.Persistence system has been added, allowing you to save and load entire compositions to and from a file (.sfproj).

• Save & Load: Use CompositionProjectManager.SaveProjectAsync and LoadProjectAsync to manage your projects.
• Media Consolidation: When saving, you can opt to "consolidate" all audio assets into a single Assets folder within your project directory, making your projects portable and self-contained.
• Embed Small Media: For convenience, small audio files (under 1MB) can be embedded directly into the project file as Base64 strings, eliminating the need for external files for short sound effects or jingles.
• Missing Media Relinking: If a project is loaded and an audio file is missing, the API reports the missing source and provides a RelinkMissingMediaAsync function to point the project to the file's new location.

4. New Sample Project: SoundFlow.Samples.EditingMixer

To showcase these powerful new features, a comprehensive new sample project has been added. Run it to see interactive examples of:

• Stitching, trimming, and editing a dialogue between two speakers.
• Replacing and layering audio with generated tones and music.
• Applying time stretching, speed changes, looping, and fades.
• Saving a project with media consolidation, loading it back, and relinking missing files.

🚀 Enhancements & Improvements

• Stream-Based Encoding & Recording: The Recorder and ISoundEncoder interfaces now operate on Stream objects instead of file paths. This is a major flexibility improvement, allowing you to record or encode directly to a MemoryStream, NetworkStream, or any other stream type.
• Improved Playback Engine: SoundPlayerBase has been significantly refactored to support the new time-stretching and advanced playback capabilities, resulting in more robust and flexible audio playback.
• Enhanced RawDataProvider: This provider is now significantly more versatile, with new constructors that can accept float[], int[], short[], and byte[] arrays directly, in addition to streams.
• Robust Resource Management: The core Mixer component is now IDisposable and uses a ConcurrentDictionary for its components, improving thread safety and ensuring proper cleanup of audio resources.
• Effect Toggling: SoundModifier and AudioAnalyzer classes now have an Enabled property, allowing you to non-destructively toggle effects on and off at any level (segment, track, or master).
• Performance Optimizations: The audio conversion pipeline for final output has been optimized for better performance.
• Updated Native Libraries: The underlying native libraries for WebRTC APM and MiniAudio have been updated to their latest versions across all supported platforms.

⚠️ Breaking Changes

This release includes several API changes to improve flexibility and consistency.

1. Encoder API Uses Stream:

   • AudioEngine.CreateEncoder and the MiniAudioEncoder constructor now require a Stream instead of a string filePath.
   • Before: new MiniAudioEncoder("output.wav", ...)
   • After: new MiniAudioEncoder(new FileStream("output.wav", ...), ...)
   • Reason: This allows encoding to any type of stream, not just files.

2. Recorder API Uses Stream:

   • The Recorder constructor now takes a Stream instead of a string filePath.
   • Before: new Recorder("recording.wav", ...)
   • After: new Recorder(new FileStream("recording.wav", ...), ...)
   • Reason: Consistent with the Encoder API change, enabling recording to any stream.

3. ISoundDataProvider.SampleRate Property:

   • The SampleRate property on ISoundDataProvider is now a non-nullable, get-only int (public int SampleRate { get; }). It was previously a settable int?.
   • Reason: The sample rate is an intrinsic property of the audio source and should not be changed after creation. It is now inferred from the audio source or the engine, ensuring more reliable behavior.

4. Provider Constructor Signatures:

   • Reflecting the change above, constructors for ChunkedDataProvider, NetworkDataProvider, and AssetDataProvider no longer accept a sampleRate parameter.

🌐 New Platform Support

• FreeBSD: SoundFlow now includes native binaries for FreeBSD on x64 and ARM64 architectures (freebsd-x64 and freebsd-arm64).

What's Changed

• refactor: Raw audio sample support for AssetDataProvider by @patrick-hovsepian in #43
• fix: GC hole in MiniAudioDecoder by @Windows10CE in #47
• feat: Implement advanced audio editing, WSOLA time stretching & project I/O by @LSXPrime in #48
• feat: Implement stream-based audio encoding by @LSXPrime in #49
• feat: Add FreeBSD support, refine cross-platform builds, and enhance audio processing by @LSXPrime in #50

New Contributors

• @patrick-hovsepian made their first contribution in #43
• @Windows10CE made their first contribution in #47
• @LSXPrime made their first contribution in #48

Full Changelog: V1.0.4...V1.1.0

V1.0.4

SoundFlow 1.0.4 Release Notes

I am excited to announce the release of SoundFlow 1.0.4! This release introduces a major new extension for advanced audio processing and includes several significant improvements and fixes across the core library and its backend.

⭐ New Features

• WebRTC Audio Processing Module (APM) Extension:
  A brand new extension package, SoundFlow.Extensions.WebRtc.Apm, is now available. This integrates the high-quality WebRTC Audio Processing Module into SoundFlow, providing advanced real-time and offline audio processing capabilities:

  • Acoustic Echo Cancellation (AEC)
  • Noise Suppression (NS)
  • Automatic Gain Control (AGC - v1 & v2)
  • High Pass Filter (HPF)
  • Pre-Amplifier
    This extension includes the WebRtcApmModifier for real-time processing within the audio graph and the NoiseSuppressor component for convenient offline/batch audio file cleanup. Native binaries for Windows (x86, x64, arm64), macOS (x64, arm64), Linux (arm, arm64, x64), Android (x64, arm64), and iOS (arm64) are included.

• Comprehensive Audio Device Enumeration: You can now reliably enumerate all available playback and capture audio devices on the system using AudioEngine.Instance.UpdateDevicesInfo(). Access the lists via AudioEngine.Instance.PlaybackDevices and AudioEngine.Instance.CaptureDevices. This provides detailed information about each device, including its name, ID, and whether it's the system default.

• Flexible Audio Device Switching: Switching the audio engine's active playback and/or capture device is now fully supported.

  • Use AudioEngine.Instance.SwitchDevice(deviceInfo, DeviceType.Playback/Capture) to switch a single device type.
  • Use the new AudioEngine.Instance.SwitchDevices(playbackDeviceInfo, captureDeviceInfo) method to switch both playback and capture devices simultaneously or independently (by passing null for the device you don't want to change). This allows seamless transitions between audio input and output sources.

✨ Improvements and Enhancements

• Improved Playback Speed: The SoundPlayerBase (and derived players like SoundPlayer, SurroundPlayer) now uses proper linear interpolation for playback speed adjustments, providing significantly smoother audio when changing speed and fixing the audio distortions. This refactoring also includes more robust seeking and looping logic.
• Enhanced Audio Device Management: Added a new SwitchDevices method to AudioEngine to allow switching both playback and capture devices simultaneously.
• MiniAudio Backend Optimizations: Updated the native MiniAudio wrapper (miniaudio.dll, libminiaudio.so, libminiaudio.dylib) with low-latency performance profile and shared capture mode (on Windows WASAPI) for potentially better real-time audio performance and compatibility.
• Unified IDisposable on ISoundDataProvider: The ISoundDataProvider interface now inherits from IDisposable, and all standard provider implementations (AssetDataProvider, ChunkedDataProvider, MicrophoneDataProvider, NetworkDataProvider, RawDataProvider, StreamDataProvider) correctly implement Dispose(). This improves resource management.
• Refined SIMD Processing: Improved volume/panning and mixing logic within SoundComponent using SIMD instructions for potentially better performance and accuracy.
• Encoder/Decoder Access: CreateEncoder and CreateDecoder methods on AudioEngine.Instance are now public for easier access to backend-specific implementations.

🐛 Bug Fixes

• Corrected native library loading issues for libminiaudio across various platforms and deployment scenarios, resolving System.DllNotFoundException. #1
• Fixed issues related to crackling and distorted audio playback, particularly noticeable with shorter files and specific configurations. #6
• Fixed issues in AlgorithmicReverbModifier related to parameter clamping, filter reinitialization, and LFO phase handling. #20
• Fixed issue where adjusting volume could lead to incorrect panning, resulting in audio playing only on one channel. #31
• Addressed potential issues in SoundComponent SIMD operations related to buffer handling and remainders.
• Corrected device enumeration logic in the MiniAudio backend for cases where no devices are found.
• Ensured loop points are clamped to valid sample boundaries within the data provider length.

⚠️ Breaking Changes

• ISoundDataProvider now requires IDisposable implementation: If you have created custom implementations of ISoundDataProvider in your projects, they must now implement the IDisposable interface and provide a Dispose() method.
• WebRTC APM Sample Rate Requirement: When using the new SoundFlow.Extensions.WebRtc.Apm extension, the AudioEngine must be initialized with one of the supported sample rates (8000, 16000, 32000, or 48000 Hz). Using other sample rates with the APM modifier/component will result in an error.

📚 Sample and Documentation Updates

• Documentation Updated: The official documentation site at SoundFlow Docs has been updated to reflect all changes and new features introduced in this release.
• New 'Noise Suppression' Sample: A new sample project SoundFlow.Samples.NoiseSuppression has been added, demonstrating how to use the WebRTC APM for both real-time microphone processing and offline audio file cleanup.
• Sample Projects Reorganized: All sample projects (SimplePlayer, SwitchDevices, NoiseSuppression) have been moved into a dedicated Samples/ directory at the repository root for better organization.
• Licensing Clarification: The README for the WebRTC APM extension clarifies the licensing requirements for both the C# wrapper (MIT) and the underlying native library (BSD 3-Clause).

⚙️ Internal / Build Updates

• Updated CMake build scripts for the native MiniAudio wrapper to improve platform targeting and native library output naming conventions.
• Implemented a more robust NativeLibraryResolver and included .targets files to ensure correct loading and packaging of native libraries for all supported runtimes within the NuGet package.

New Contributors

• @sandreas made their first contribution in #11

Full Changelog: V1.0.3...V1.0.4

V1.0.3

New Features:

• Raw PCM Data Support: RawDataProvider now supports U8, S16, S24, S32, F32 PCM formats by specifying sample rate and channel count.
• Loop Points for Players: Added loop points support to both Players for looping playback.
• Experimental Advanced VAD: Introduced an experimental Voice Activity Detector as analyzer in Experimental namespace with noise gate and combined detection mode. Not stable, under development.
• Recorder Modifier/Analyzer Management: Improved management of modifiers and analyzers in the Recorder component for more flexible audio processing.

Bug Fixes:

• DllNotFoundException Fix: Resolved DllNotFoundException on Windows by static linking native dependencies.
• iOS Framework Path Correction: Fixed incorrect iOS framework path for proper configuration.
• FFT Calculation Crash Fix (AVX): Corrected a crashing issue in FFT calculations when using AVX under certain conditions.

Improvements:

• Simplified Recorder & VAD:
  • Removed VAD integration from Recorder.
  • Simplified VoiceActivityDetector for basic energy detection.
• Optimized FFT Algorithm: Improved FFT performance, especially for smaller sizes, with scalar and AVX implementations.
• Platform-Specific Miniaudio Configuration: Configured miniaudio in CMakeLists.txt for Linux, macOS, iOS, and Android:
  • Platform checks added.
  • Static linking flags for Linux/Windows (GNU).
  • Platform-specific libraries linked (dl, pthread, m, CoreFoundation, CoreAudio, AudioToolbox, AVFoundation, OpenSLES).
  • MA_NO_RUNTIME_LINKING defined for macOS, iOS, Android.
  • Framework properties/code signing for macOS/iOS frameworks.
  • OBJCXX language for iOS library.cpp.
• Build Workflow Enhancement: Workflow updated to parse dependencies during build.
• Code Modernization:
  • Modernized collection initialization syntax.
  • Sealed classes not intended for inheritance.
• Math Helper Utilities: Added MathHelper.IsPowerOfTwo and MathHelper.Lerp.
• NoiseReductionModifier Moved: Moved NoiseReductionModifier to Experimental namespace and marked as unstable.

New Contributors

• @Lehonti made their first contribution in #3

Full Changelog: V1.0.1...V1.0.3

V1.0.1

Fixed NuGet package export issue causing runtime path corruption.