Audio Core Changelog (Legacy)

v0.9.0 - 2023-12-08

Added

  • Added fallback_state_change_callback function callback to the fallback module configuration to notify the application of a fallback state change.

  • Added SAC_CDC_SET_TARGET_QUEUE_SIZE command to the cdc processing to be able to change the system latency at runtime. The queue memory must be allocated at the initialization.

  • Added support for 32-bit audio samples.

  • Added support for packing 32-bit audio samples into 24-bit audio samples.

  • Added support for sampling rate conversion ratio of 2.

  • Added support for sampling rate conversion ratio of 1 to disable either the multiplier or the divider.

  • Added manual fallback mode to be able to force a fallback state.

  • Added sac_sample_size_t enum to define if the sample size in bits corresponds to a SAC_WORD_SIZE_BITS or its sac_bit_depth_t.

  • Added sac_sample_format_t structure to define the format of audio samples.

  • Added support for sampling rate conversion ratio of 4.

  • Added support for scaling packed 24-bit to packed 16-bit audio samples.

  • Added cca_bad_time_sec to the sac_fallback_module_cfg_t structure to configure the number of seconds required over the CCA try count threshold before activating the fallback mode.

  • Added sac_fallback_set_cca_bad_time function to set the cca_bad_time_sec fallback configuration at runtime.

  • Added sac_fallback_get_link_margin_metrics function to get the link margin metrics.

  • Added sac_utils.c/h which contain general utility functions.

Changed

  • Changed sampling rate conversion configuration to allow the combination of a multiplier and a divider.

  • Changed the sac_compression_instance_t.bit_depth field to a sac_sample_format_t field to allow more flexibility on the uncompressed audio samples format.

  • Changed the fallback sampling divisor to 10 and moved the definition to the header file.

  • Changed cca_good_time_s to cca_good_time_sec.

  • Changed the management of the fallback flag; the Coordinator exclusively manages the fallback flag, preventing unexpected changes from Node’s fallback packets.

Fixed

  • Fixed the fallback_count statistics of the receiver.

  • Fixed an audio artifact induced when switching between sac_compression_process_discard and sac_compression_process. This will increase the processing of sac_compression_process_discard.

  • Fixed consumer queue size being 1 less than the configuration value. Free queue will be incremented by 1 instead of decrementing the consumer queue to account for consumption delay.

v0.8.0 - 2023-05-31

Release notes:

  • Error checking on API calls input parameters.

Added

  • Added error codes in sac_error_t.

  • Added sac_mute_packet processing stage used to avoid sending muted packets full of zeros.

  • Added producer_buffer_overflow_count statistic.

  • Added the possibility to increase the producer queue size to allow buffering when the audio could not be processed before the next audio packet is produced.

  • Added sac_mute_on_underflow processing stage used to mute the audio of the consumer when underflows are detected. This processing stage can be used on an audio receiving pipeline to reduce the effect of crackling sound when the wireless link starts to cut.

  • Added cca_try_count_threshold_perc to the sac_fallback_module_cfg_t structure to configure the fallback module’s CCA threshold in percentage.

  • Added link_margin_good_time_s to the sac_fallback_module_cfg_t structure to configure the number of seconds required over the link margin threshold before returning to the normal state.

  • Added cca_good_time_s to the sac_fallback_module_cfg_t structure to configure the number of seconds required under the CCA try count threshold before returning to the normal state.

  • Added sac_fallback_module_get_defaults function to initialize the sac_fallback_module_cfg_t structure with default values.

  • Added sac_fallback_gate_fallback_off_detect function to gate a processing stage on a packet where fallback is disabled.

  • Added sac_fallback_module_format_stats function to format fallback statistics as a string of characters.

  • Added sac_fallback_module_reset_stats function to reset the fallback statistics.

  • Added fallback instance NULL pointer protection.

  • Added sac_packing processing stage documentation.

  • Added error checking at initialization of processing stages.

  • Added SAC_ERR_PROCESSING_STAGE_INIT for generic error in audio processing stage initialization.

  • Added bit_depth field to the sac_compression_instance_t.

  • Added support for 18-bit sample packing and unpacking.

  • Added support for 20-bit and 24-bit samples as input for mono and stereo stream to the compression processing stage.

Changed

  • sac_pipeline_add_processing() has a new sac_error_t parameter.

  • sac_pipeline_add_extra_consumer() has a new sac_error_t parameter.

  • sac_pipeline_add_extra_producer() has a new sac_error_t parameter.

  • sac_pipeline_start() has a new sac_error_t parameter.

  • sac_pipeline_stop() has a new sac_error_t parameter.

  • Moved sac_fallback_module_cfg_t to sac_fallback_module.h.

  • Moved sac_fallback_gate_is_fallback_on to sac_fallback_gate.h.

  • Moved sac_fallback_gate_is_fallback_off to sac_fallback_gate.h.

  • Moved sac_fallback_gate_fallback_detect to sac_fallback_gate.h.

  • Moved sac_pipeline_t internal parameters to _internal sub-structure.

  • Moved sac_volume_instance_t internal parameters to _internal sub-structure.

  • Moved sac_endpoint_t internal parameters to _internal sub-structure.

  • Moved sac_fallback_state_t to sac_fallback_module.h.

  • Moved internal ADPCM state handles of the sac_compression_instance_t``structure to ``_internal sub-structure.

  • Renamed SAC_PRODUCER_QUEUE_SIZE to SAC_MIN_PRODUCER_QUEUE_SIZE.

  • Renamed txq_buffer_load_threshold to consumer_buffer_load_threshold_tenths in the sac_fallback_module_cfg_t structure.

  • Renamed FB_STATE_NORMAL to SAC_FB_STATE_NORMAL.

  • Renamed FB_STATE_WAIT_THRESHOLD to SAC_FB_STATE_WAIT_THRESHOLD.

  • Renamed FB_STATE_FALLBACK to SAC_FB_STATE_FALLBACK.

  • Renamed FB_STATE_FALLBACK_DISCONNECT to SAC_FB_STATE_FALLBACK_DISCONNECT.

  • Renamed SAC_ERR_FALLBACK_INVALID_TXQ_THRESH to SAC_ERR_FALLBACK_INIT_FAILURE.

  • Renamed sac_queue_metrics_t to sac_fallback_queue_metrics_t and moved to sac_fallback_module.h.

  • Renamed sac_link_margin_metrics_t to sac_fallback_link_margin_metrics_t and moved to sac_fallback_module.h.

  • Renamed sac_cca_metrics_t to sac_fallback_cca_metrics_t and moved to sac_fallback_module.h.

  • Renamed sac_fallback_module_t to sac_fallback_module_instance_t and moved to sac_fallback_module.c.

  • Simplified sac_compression_mode_t. It no longer accounts for the bit depth.

  • The audio pipeline initial buffering now uses queue_size - 1 as its threshold.

Removed

  • Removed txq_max_size from the sac_fallback_module_cfg_t structure.

  • Removed SAC_FALLBACK_DEFAULT_TXQ_THRESH defined from sac_fallback_module.h.

  • Removed sac_user_data processing stage.

  • Removed user_data_is_valid``flag from ``sac_header_t.

  • Removed sac_user_data related parameters from sac_pipeline setup and process.

  • Removed SAC_ERR_CDC_INIT_FAILURE to be replaced by SAC_ERR_PROCESSING_STAGE_INIT.

  • Removed all deinitializations functions from the Audio Core.

  • Removed the deinit interface from sac_processing_interface_t.

v0.7.0 - 2022-11-30

Release notes:

  • The fallback module has been optimized to work better with the Wireless Core’s clear channel assessment (CCA) feature.

  • The CDC module module/audio_cdc_module.c/h has been removed and converted to a regular processing stage processing/sac_cdc.c/h.

  • All endpoints, modules and processing stages prefix has been changed from audio_ to sac_.

  • Statistics functions have been moved from sac_api.c/h to sac_stats.c/h.

  • The Audio Core API reference section in the documentation has been enhanced.

  • The Audio Core Fallback section in the documentation has been enhanced.

  • A CDC processing stage using clock steering as compensation mechanism procesing/sac_cdc_clock_steering.c/h is now available.

Added

  • Fallback module has the new get_cca_metrics public function.

  • New cca_max_try_count member in sac_fallback_module_cfg_t.

  • New sac_cca_metrics_t type in sac_api.h.

  • New cca_metrics member in sac_fallback_module_t.

  • SAC_LINK_MARGIN_SIZE_BYTES constant in sac_api.h.

  • cdc_inflated_packets_count and cdc_deflated_packets_count counters in sac_statistics_t.

  • New API call sac_pipeline_get_cdc_inflated_packets_count().

  • New API call sac_pipeline_get_cdc_deflated_packets_count().

  • New sac_stats.c/h files.

  • New API call sac_pipeline_update_stats().

  • New API call sac_pipeline_format_stats().

  • New consumer_queue_peak_buffer_load, consumer_link_margin_min_peak, consumer_cca_fail_count_peak statistics and getters.

Changed

  • fallback_set_rx_link_margin parameter is now a uint8_t``instead of ``int16_t.

  • fallback_update_stats now has the cca_fail_count parameter.

  • In sac_link_margin_metrics_t, link_margin_accumulator is now a uint32_t instead of a int32_t and link_margin_acc_avg is now a uint8_t instead of a int16_t.

  • In sac_fallback_module_t, fallback_threshold, fallback_threshold_default and fallback_threshold_hysteresis are now a uint8_t instead of a uint16_t. Also, rx_link_margin_data_rx is now a uint8_t instead of a int16_t.

  • Replace AUDIO_ prefix to SAC_ for sac_bit_depth_t and sac_word_size_t members.

  • Rename audio_endpoint_cfg to sac_endpoint_cfg.

  • Rename sac_mixer_module_init to sac_mixer_init.

  • Rename sac_fallback_module_init to sac_fallback_init.

  • Rename fallback_* functions to sac_fallback_*.

Removed

  • Remove compression_enabled field from sac_compression_instance_t as well as SAC_COMPRESSION_ENABLE and SAC_COMPRESSION_DISABLE from sac_compression_cmd_t. Such control should be implemented by the user in the processing stage gate() function.

  • Remove packing_enabled field from sac_packing_instance_t as well as SAC_PACKING_ENABLE and SAC_PACKING_DISABLE from sac_packing_cmd_t. Such control should be implemented by the user in the processing stage gate() function.

Fixed

  • Coding style issues.

v0.6.0 - 2022-05-27

Added

  • The Audio Core now supports 20, 24 and 32-bit audio samples.

  • New processing stage that allows packing of 20 or 24-bit audio samples from 32-bit words.

  • New sinus generator endpoint that can produce pre-recorded sin waves at a frequency of 1 kHz, 2 kHz and 3 kHz for testing purposes.

  • New audio mixing module used for mixing up to 3 audio streams into a single one.

  • audio_protocol_cfg_t now has a sac_mixer_option_t in order to select if the pipeline is producing an audio stream to be mixed or if the pipeline is doing the mixing.

  • New API call sac_mixer_module_init() used to initialize the audio mixer module (if used).

  • New API call sac_endpoint_link() used to make 2 endpoints share their audio queue (for use with the audio mixing feature).

  • New API call sac_pipeline_add_extra_producer() used to add more than one audio producer in a pipeline (for use with the audio mixing feature).

  • New SAC_ERR_NULL_PTR error that happens when a pointer is NULL while it should have been initialized.

  • New SAC_ERR_MIXER_INIT_FAILURE error that happens when the mixer is not able to initialize properly due to an erroneous configuration.

  • New audio fallback module.

  • New API call sac_fallback_module_init() used to initialize the audio fallback module (if used).

  • New producer_packets_corrupted_count stat.

  • New CRC4 field in audio header used to validate the content of the audio header.

  • New gate function pointer field in the Audio Processing Interface (sac_processing_interface_t).

Changed

  • Prefix of the SPARK Audio Core (SAC) API changed from audio_ to sac_.

  • audio_protocol.c/h has been renamed to audio_cdc_module.c/h and moved to the module folder.

  • audio_protocol_cfg_t has been renamed to sac_pipeline_cfg_t.

  • Audio core now supports payload size up to 65535 bytes in its pipelines.

  • Audio payload is now aligned with 32-bit words.

  • Audio volume processing stage now has the prefix audio_ on all public functions.

  • The audio processing stage process function now returns a uint16_t payload size.

  • The bit depth field of the endpoint config structure now has a typedef enum to list all supported bit depths.

  • The payload size field of the endpoint config structure now has a uint16_t value.

  • sac_pipeline_process() now mixes audio packets when the audio mixing feature is enabled.

v0.5.0 - 2022-03-03

Added

  • Audio buffer load check inside audio_pipeline_consume().

  • A new field in audio_protocol_cfg_t has been added to turn on or off the user data feature. The audio packet trailing byte will not be appended if it is turned off.

Fixed

  • CDC not properly handling multiple consumers.

v0.4.0 - 2022-02-04

Added

  • New API call audio_processing_stage_init() that initializes a processing stage and returns a reference to it.

  • New API call audio_pipeline_setup() used to do the final setup of the pipeline before it is operational.

  • New API call audio_core_get_allocated_bytes() used to know the number of bytes used in the memory pool.

  • New AUDIO_ERR_PIPELINE_CFG_INVALID error that happens when incompatible pipeline configurations are set.

Changed

  • audio_pipeline_init() now dynamically allocated the pipeline and returns a reference to it.

  • audio_endpoint_init() now dynamically allocated the endpoint and returns a reference to it.

  • Producer endpoint audio_payload_size field needs not to account for audio packet size inflation during subsequent audio processing like in the case of upsampling or decompression. The value must always be set to the exact amount of bytes the produced audio packet is.

  • The block_size field of the src_cmsis_cfg_t type of the Sampling Rate Converter processing stage has been replace by a payload_size field and a bit_depth field.

  • A const qualifier has been added to the name field of the audio_processing_t type.

  • The max_process_count field of the audio_protocol_cfg_t has been removed. Processing stages are allocated dynamically using the chunk of RAM allocated by the application.

  • Error pointer parameter has been added to audio_endpoint_init() and removed from audio_pipeline_add_processing().

  • audio_pipeline_stop() no longer de-initializes processing stages.

Removed

  • WPS audio endpoint. Audio applications must supply their own. A working implementation is provided with the SDK.

v0.3.0 - 2021-12-13

Added

  • Support for multiple audio consumers on a single audio pipeline.

  • Constant for ADPCM overhead and producer queue size.

Changed

  • Pipeline configuration variable name from queue_avg_size to cdc_queue_avg_size.

Removed

  • Generic I2S audio endpoint. Audio applications can create their own specific audio endpoints if needed instead.

Fixed

  • Coding style.

v0.2.0 - 2021-11-09

Changed

  • Sampling rate converter processing stage filter coefficients when interpolating.

v0.1.0 - 2021-09-30

Initial release.