Enhance AudioEngine to Support Playing Sound Effects Directly from Binary Streams or Byte Arrays

[hlwz5735]

Is your feature request related to a problem? Please describe.
Currently, the play2d and play3d methods in AudioEngine only accept file names as parameters, which limits playback to sound files located in the local resource directory. This becomes a significant issue when audio resources are embedded within archived packages (e.g., .zip, custom asset bundles) or are downloaded from the network, as there is no way to play them directly without first extracting or saving them to disk.

Describe the solution you'd like
I would like the AudioEngine to be enhanced with overloaded versions of the play2d and play3d methods that can accept byte arrays (e.g., unsigned char*, std::vector<unsigned char>) or input streams (e.g., std::istream or a custom stream interface) as parameters. Alternatively, introducing a new class like AudioClip to wrap the audio data (similar to Unity's design) would also be an excellent solution. This would allow developers to play sounds directly from memory or network streams without the overhead of intermediate files.

Describe alternatives you've considered

1. Extracting or downloading audio resources to a temporary file before passing the file path to the existing play2d/play3d methods. This is inefficient and adds unnecessary I/O overhead, especially for frequently played sounds or network-sourced audio.
2. Modifying the resource manager to support virtual file systems that can mount archives. While this is a more comprehensive solution, it is significantly more complex and time-consuming to implement compared to adding direct byte array/stream support to the audio playback methods.

Additional context
This enhancement would greatly improve flexibility for games and applications that package assets or rely on dynamic content delivery. It aligns with modern game development practices where resources are often loaded from memory for performance and security reasons. Implementing this would make the engine more versatile for a wider range of use cases.

[rh101]

Axmol does have support for interfacing with a virtual file system, without requiring any changes to the engine code. The support for this was added years ago, and improved over time to ensure that almost all file access would work with it.

A while back I created an example of how this would be achieved here using PhysFS. You can use any VFS implementation you want, primarily by implementing ax::IFileSystem for the VFS, and then sub-classing FileUtils for each platform (platform specific stuff that may be required for the VFS).

The released app that I work on uses a modified version of PhysFS to read directly from ZIP archives, mainly for downloaded content.

Still, it would be nice to have a way to play directly from memory without having to use a VFS.

[hlwz5735]

I'm delighted and truly honored to have received your reply so quickly.

Also, I wasn’t actually aware that Axmol has already implemented a VFS system—that’s awesome. I'll give it a try right away.

By the way, it’s a real shame that Axmol doesn’t have detailed documentation. I believe there are many features already implemented in the engine that remain unknown simply because of the lack of documentation.

[rh101]

Also, I wasn’t actually aware that Axmol has already implemented a VFS system—that’s awesome. I'll give it a try right away.

Just to clarify, Axmol enables developers to add their own VFS, so it doesn't actually have a VFS implementation of its own. So, you should be able to support any VFS you want to use, with PhysFS being a common one.

By the way, it’s a real shame that Axmol doesn’t have detailed documentation. I believe there are many features already implemented in the engine that remain unknown simply because of the lack of documentation.

That's understandable. It is something that is slowly improving, so hopefully over time it will cover all areas of the engine.

[aismann]

By the way, it’s a real shame that Axmol doesn’t have detailed documentation. I believe there are many features already implemented in the engine that remain unknown simply because of the lack of documentation.

As @rh101 says, it's a question of available time. I always recommend that there should be “at least” one corresponding test in cpp-tests. Unfortunately, this is not always possible or sensible.
cpp-tests is Axmol's “second documentation".