SoundFlow v1.4.0 - A Temporary Farewell

[LSXPrime]

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)

---

This discussion was created from the release SoundFlow v1.4.0 - A Temporary Farewell.

[LSXPrime]

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 update is happening for a couple of reasons.

The first reason is personal and was a major catalyst:

• I have over 1200+ MP3 files, many of which contain utterly wrong or clunky file names, usually hashes or random strings generated by the download manager.
• I can often remember the lyrics, but I cannot recall the actual song titles. Standard online search methods don't help much, as these are often older indie tracks whose creators stopped making music a long time ago.
• Essentially, I desperately needed a reliable way to recognize and identify this music.

The second reason ties into my existing professional work:

• I have a stable licensing library project called Aegis, and I'm keen to collaborate on it.
• However, audio security is fundamentally different from software licensing. Trying to integrate Aegis directly for music wasn't the best option.

Because of these challenges, I decided to implement a completely new, dedicated security suite for audio. The main goal is to help creators track down leakers and secure their intellectual property and help data hoarders identify what they got.