- Many init/uninit functions have been changed to take a pointer to allocation callbacks.
- ma_scale_buffer_size() has been removed.
- ma_encoder_write_pcm_frames() has been updated to return a result code and output the number of
frames written via an output parameter.
- ma_noise_read_pcm_frames() has been updated to return a result code and output the number of
frames read via an output parameter.
- ma_waveform_read_pcm_frames() has been updated to return a result code and output the number of
frames read via an output parameter.
- The MA_STATE_* tokens have been reanmed to ma_device_state_* and turned into an enum.
Changes to Custom Data Sources
------------------------------
The implementation of data sources has seen some changes. Previously, you needed to only implement
the `ma_data_source_callbacks` structure and make it the first member of the data source's
structure. This has now changed. You now need to make the first member of the data source's
structure `ma_data_source_base` and initialize and uninitialize it with `ma_data_source_init()` and
`ma_data_source_uninit()` from your data source's init/uninit routines.
When you call `ma_data_source_init()` you will need to specify a config. The config includes a
pointer to a `ma_data_source_vtable` object which needs to be filled out.
The onGetDataFormat callback has been changed to output the channel map. With this change,
ma_data_source_get_data_format() has been update to accept a channel map.
The onMap and onUnmap callbacks have been removed, as has ma_data_source_map() and
ma_data_source_unmap().
Other Changes
-------------
There have also been some other smaller changes added to this release.
- Support for custom resmplers has been added. See the implementation of ma_linear_resampler for
an example on how to implement a custom resmpler.
- ma_decoder_get_data_format() has been added.
- Support has been added for disabling denormals on the audio thread. This is configured on a
per-device basis via the device config and are disabled by default. Use the noDisableDenormals
config variable to control this.
- A delay/echo effect has been added called `ma_delay`.
- A stereo pan effect has been added called `ma_panner`.
- A spataializer effect has been added called `ma_spatializer`. This is used by the engine to
achieve it's 3D spatialization effect for sounds.
- ma_free() now performs a null pointer check which means NULL should never be passed into
allocation callbacks.
- Filters, effects and data conversion no longer have a dependency on MA_MAX_CHANNELS.
- MA_MAX_CHANNELS has been increased from 32 to 254 and currently only affects devices. This may
be relaxed in a future version.
*/
/*
/*
RELEASE NOTES - VERSION 0.10.x
RELEASE NOTES - VERSION 0.10.x
==============================
==============================
...
@@ -87417,132 +87552,6 @@ issues with certain devices and configurations. These can be individually enable
...
@@ -87417,132 +87552,6 @@ issues with certain devices and configurations. These can be individually enable
```
```
*/
*/
/*
RELEASE NOTES - VERSION 0.9.x
=============================
Version 0.9 includes major API changes, centered mostly around full-duplex and the rebrand to "miniaudio". Before I go into detail about the major changes I
would like to apologize. I know it's annoying dealing with breaking API changes, but I think it's best to get these changes out of the way now while the
library is still relatively young and unknown.
There's been a lot of refactoring with this release so there's a good chance a few bugs have been introduced. I apologize in advance for this. You may want to
hold off on upgrading for the short term if you're worried. If mini_al v0.8.14 works for you, and you don't need full-duplex support, you can avoid upgrading
(though you won't be getting future bug fixes).
Rebranding to "miniaudio"
-------------------------
The decision was made to rename mini_al to miniaudio. Don't worry, it's the same project. The reason for this is simple:
1) Having the word "audio" in the title makes it immediately clear that the library is related to audio; and
2) I don't like the look of the underscore.
This rebrand has necessitated a change in namespace from "mal" to "ma". I know this is annoying, and I apologize, but it's better to get this out of the road
now rather than later. Also, since there are necessary API changes for full-duplex support I think it's better to just get the namespace change over and done
with at the same time as the full-duplex changes. I'm hoping this will be the last of the major API changes. Fingers crossed!
The implementation define is now "#define MINIAUDIO_IMPLEMENTATION". You can also use "#define MA_IMPLEMENTATION" if that's your preference.
Full-Duplex Support
-------------------
The major feature added to version 0.9 is full-duplex. This has necessitated a few API changes.
1) The data callback has now changed. Previously there was one type of callback for playback and another for capture. I wanted to avoid a third callback just
for full-duplex so the decision was made to break this API and unify the callbacks. Now, there is just one callback which is the same for all three modes
(playback, capture, duplex). The new callback looks like the following:
This callback allows you to move data straight out of the input buffer and into the output buffer in full-duplex mode. In playback-only mode, pInput will be
null. Likewise, pOutput will be null in capture-only mode. The sample count is no longer returned from the callback since it's not necessary for miniaudio
anymore.
2) The device config needed to change in order to support full-duplex. Full-duplex requires the ability to allow the client to choose a different PCM format
for the playback and capture sides. The old ma_device_config object simply did not allow this and needed to change. With these changes you now specify the
device ID, format, channels, channel map and share mode on a per-playback and per-capture basis (see example below). The sample rate must be the same for
playback and capture.
Since the device config API has changed I have also decided to take the opportunity to simplify device initialization. Now, the device ID, device type and
callback user data are set in the config. ma_device_init() is now simplified down to taking just the context, device config and a pointer to the device
object being initialized. The rationale for this change is that it just makes more sense to me that these are set as part of the config like everything
else.
Example device initialization:
ma_device_config config = ma_device_config_init(ma_device_type_duplex); // Or ma_device_type_playback or ma_device_type_capture.
config.playback.pDeviceID = &myPlaybackDeviceID; // Or NULL for the default playback device.
config.playback.format = ma_format_f32;
config.playback.channels = 2;
config.capture.pDeviceID = &myCaptureDeviceID; // Or NULL for the default capture device.
config.capture.format = ma_format_s16;
config.capture.channels = 1;
config.sampleRate = 44100;
config.dataCallback = data_callback;
config.pUserData = &myUserData;
result = ma_device_init(&myContext, &config, &device);
if (result != MA_SUCCESS) {
... handle error ...
}
Note that the "onDataCallback" member of ma_device_config has been renamed to "dataCallback". Also, "onStopCallback" has been renamed to "stopCallback".
This is the first pass for full-duplex and there is a known bug. You will hear crackling on the following backends when sample rate conversion is required for
the playback device:
- Core Audio
- JACK
- AAudio
- OpenSL
- WebAudio
In addition to the above, not all platforms have been absolutely thoroughly tested simply because I lack the hardware for such thorough testing. If you
experience a bug, an issue report on GitHub or an email would be greatly appreciated (and a sample program that reproduces the issue if possible).
Other API Changes
-----------------
In addition to the above, the following API changes have been made:
- The log callback is no longer passed to ma_context_config_init(). Instead you need to set it manually after initialization.
- The onLogCallback member of ma_context_config has been renamed to "logCallback".
- The log callback now takes a logLevel parameter. The new callback looks like: void log_callback(ma_context* pContext, ma_device* pDevice, ma_uint32 logLevel, const char* message)
- You can use ma_log_level_to_string() to convert the logLevel to human readable text if you want to log it.
- Error codes have been rearranged. If you're a binding maintainer you will need to update.
- The ma_backend enums have been rearranged to priority order. The rationale for this is to simplify automatic backend selection and to make it easier to see
the priority. If you're a binding maintainer you will need to update.
- ma_dsp has been renamed to ma_pcm_converter. The rationale for this change is that I'm expecting "ma_dsp" to conflict with some future planned high-level
APIs.
- For functions that take a pointer/count combo, such as ma_decoder_read_pcm_frames(), the parameter order has changed so that the pointer comes before the
count. The rationale for this is to keep it consistent with things like memcpy().
Miscellaneous Changes
---------------------
The following miscellaneous changes have also been made.
- The AAudio backend has been added for Android 8 and above. This is Android's new "High-Performance Audio" API. (For the record, this is one of the nicest
audio APIs out there, just behind the BSD audio APIs).
- The WebAudio backend has been added. This is based on ScriptProcessorNode. This removes the need for SDL.
- The SDL and OpenAL backends have been removed. These were originally implemented to add support for platforms for which miniaudio was not explicitly
supported. These are no longer needed and have therefore been removed.
- Device initialization now fails if the requested share mode is not supported. If you ask for exclusive mode, you either get an exclusive mode device, or an
error. The rationale for this change is to give the client more control over how to handle cases when the desired shared mode is unavailable.
- A lock-free ring buffer API has been added. There are two varients of this. "ma_rb" operates on bytes, whereas "ma_pcm_rb" operates on PCM frames.
- The library is now licensed as a choice of Public Domain (Unlicense) _or_ MIT-0 (No Attribution) which is the same as MIT, but removes the attribution
requirement. The rationale for this is to support countries that don't recognize public domain.
