mirror/miniaudio
1
0
Fork 0
mirror of https://github.com/mackron/miniaudio.git synced 2026-04-24 01:04:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add release notes for version 0.11

Browse Source
This commit is contained in:
David Reid
2021-08-15 20:38:58 +10:00
parent 448a7c90ff
commit 2d76a9b352
1 changed files with 135 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files
miniaudio.h
+135 -126
View File
@@ -87241,6 +87241,141 @@ DRMP3_API void drmp3_free(void* p, const drmp3_allocation_callbacks* pAllocation
#endif /* miniaudio_c */ #endif /* miniaudio_c */
#endif /* MINIAUDIO_IMPLEMENTATION */ #endif /* MINIAUDIO_IMPLEMENTATION */
/*
RELEASE NOTES - VERSION 0.11.x
==============================
Version 0.11 adds some high level APIs and includes some breaking API changes.
High Level Engine API
---------------------
The engine API provides sound management, mixing and effect processing. It can be used as both an
alternative to the low level device API or as a supplementary feature depending on your needs. See
the documentation for information on how to use this API.
Resource Management
-------------------
Support for management of sound files has been added via the new `ma_resource_manager` API. This
supports loading of sounds entirely in memory with reference counting and also streaming. See the
documentation for more information on the resource manager.
Node Graphs
-----------
A node graph system has been added to support complex effect chains and mixing. The node graph is
made up of a series of connected nodes, with the output of one node being fed into the input of
another node. By connecting nodes together you can create complex effect and mixing graphs. A
number of different types of nodes are included, but custom nodes are also supported. See the
documentation for more information on the node graph system.
Breaking API Changes
--------------------
There are many breaking API changes in this release.
- ma_channel_mix_mode_planar_blend has been removed. Use ma_channel_mix_mode_rectangular instead.
- MA_MIN_SAMPLE_RATE and MA_MAX_SAMPLE_RATE have been removed. Use ma_standard_sample_rate_min
and ma_standard_sample_rate_max instead.
- The ma_device_info structure has changed. Now, an array of supported format/channels/rate
combinations are stored in an array and the old minChannels, maxChannels, etc. have been
removed.
- The shareMode parameter has been removed from ma_context_get_device_info(). Whether or not the
format relates to a shared or exclusive device is now set in a flags variables.
- The noPreZeroedOutputBuffer variable in the device config has been renamed to
noPreSilencedOutputBuffer.
- The pBufferOut parameter has been removed from the ring buffer commit functions.
- The ma_zero_pcm_frames() function has been removed. Use ma_silence_pcm_frames() instead.
- ma_clip_samples_f32() has been updated to take an input and output buffer rather than working
exclusively in-place.
- ma_clip_pcm_frames_f32() has been removed. Use ma_clip_samples_f32() or ma_clip_pcm_frames()
instead.
- ma_data_source_callbacks has been removed. If you're building a custom data source you need to
use ma_data_source_vtable instead.
- Support for mapping has been removed from data sources since it had very limited use and has
proven to not be worth the maintenance cost.
- The onLog callback has been removed from the context config. This has been replaced with a much
more flexible logging system. The context will have a `ma_log` object which can be retrieved
with `ma_context_get_log()`. From there you can register a callback with the `ma_log` object
with `ma_log_register_callback()`. An pre-allocated log can be specified in the context config.
- MA_LOG_LEVEL_VERBOSE has been removed and replaced with MA_LOG_LEVEL_DEBUG. With this change,
logs posted with MA_LOG_LEVEL_DEBUG will only be output if MA_DEBUG_OUTPUT is enabled.
- MA_LOG_LEVEL has been removed. Now all log levels are posted, except for MA_LOG_LEVEL_DEBUG
which will only be posted if MA_DEBUG_OUTPUT is enabled.
- ma_resource_format has been replaced with ma_encoding_format.
- The encoding-specific initialization functions for decoders, such as ma_decoder_init_wav(),
have been removed. Instead you should set the encodingFormat variable in the decoder config.
- ma_decoder_get_length_in_pcm_frames() has been updated to return a result code and output the
length via an output parameter. This makes it consistent with data sources.
- ma_decoder_read_pcm_frames() has been update to return a result code and output the number of
frames read via an output parameter.
- Allocation callbacks must now implement the onRealloc() callback. Previously miniaudio would
emulate this in terms of malloc and free, but for simplicity it is now required that allocation
callbacks handle this theselves.
- ma_get_standard_channel_map() has been renamed to ma_channel_map_init_standard() and now
includes a parameter specifying the capacity of the output channel map. This is useful for
initializing a channel map with a fixed capacity.
- ma_channel_map_valid() has been renamed to ma_channel_map_is_valid().
- ma_channel_map_equal() has been renamed to ma_channel_map_is_equal().
- ma_channel_map_blank() has been renamed to ma_channel_map_is_blank().
- The Speex resampler has been removed. Support for custom resamplers has been added. If you need
a Speex resampler you will need to implement a custom resampler.
- The following functions from the resampler have changed to return a result code and output
their result via an output parameter:
- ma_linear_resampler_get_required_input_frame_count()
- ma_linear_resampler_get_expected_output_frame_count()
- ma_resampler_get_required_input_frame_count()
- ma_resampler_get_expected_output_frame_count()
- 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
``` ```
*/ */
/*
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:
void data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount);
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.
- Some APIs have been renamed:
- mal_decoder_read() -> ma_decoder_read_pcm_frames()
- mal_decoder_seek_to_frame() -> ma_decoder_seek_to_pcm_frame()
- mal_sine_wave_read() -> ma_sine_wave_read_f32()
- mal_sine_wave_read_ex() -> ma_sine_wave_read_f32_ex()
- Some APIs have been removed:
- mal_device_get_buffer_size_in_bytes()
- mal_device_set_recv_callback()
- mal_device_set_send_callback()
- mal_src_set_input_sample_rate()
- mal_src_set_output_sample_rate()
- 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.
*/
/* /*
REVISION HISTORY REVISION HISTORY
================ ================