sac_api.h

SPARK Audio Core Application Programming Interface.

Copyright: Copyright (C) 2026 SPARK Microsystems International Inc. All rights reserved.
License: This source code is proprietary and subject to the SPARK Microsystems Software EULA found in this package in file EULA.txt.
Author: SPARK FW Team.

Defines

SAC_MAX_CHANNEL_COUNT 2: Maximum of audio channels supported in audio core.

SAC_NO_ARG 0: Placeholder to be used in a sac_processing_ctrl function call when no arguments are required.

SAC_NODE_PAYLOAD_SIZE_OFFSET 0: Position of the audio payload in the audio packet.

SAC_NODE_PAYLOAD_SIZE_VAR_SIZE sizeof(uint16_t): Size of the audio payload variable.

SAC_PACKET_HEADER_OFFSET (SAC_NODE_PAYLOAD_SIZE_OFFSET + SAC_NODE_PAYLOAD_SIZE_VAR_SIZE): Position of the audio header in the audio packet.

SAC_PACKET_DATA_OFFSET (SAC_PACKET_HEADER_OFFSET + sizeof(sac_header_t)): Position of the packet data in the audio packet.

SAC_MIN_PRODUCER_QUEUE_SIZE 1: Minimum queue size necessary for a producer audio endpoint. Note: More memory will be allocated for processing purposes.

SAC_BYTE_SIZE_BITS 8: Number of bits required to store a byte.

SAC_WORD_SIZE_BYTE 4: Number of bytes required to store an audio sample aligned to a CPU word.

SAC_WORD_SIZE_BITS ((SAC_WORD_SIZE_BYTE) * (SAC_BYTE_SIZE_BITS)): Number of bits required to store an audio sample aligned to a CPU word.

sac_node_get_payload_size(node) (*((uint16_t *)(queue_get_data_ptr((node), SAC_NODE_PAYLOAD_SIZE_OFFSET)))): Get the audio payload size in the audio packet.

sac_node_set_payload_size(node, payload_size) ((*((uint16_t *)(queue_get_data_ptr((node), SAC_NODE_PAYLOAD_SIZE_OFFSET)))) = (payload_size)): Set the audio payload size in the audio packet.

sac_node_get_header(node) ((sac_header_t *)(queue_get_data_ptr((node), SAC_PACKET_HEADER_OFFSET))): Get a pointer to the audio header in the audio packet.

sac_node_get_data(node) ((uint8_t *)(queue_get_data_ptr((node), SAC_PACKET_DATA_OFFSET))): Get a pointer to the packet data in the audio packet.

sac_align_data_size(current_size, type_to_align) (sizeof(type_to_align) - ((current_size) % sizeof(type_to_align))): Return an array size aligned on a specific type.

Typedefs

typedef struct sac_pipeline sac_pipeline_t

Audio pipeline structure forward declaration.

Audio Core Pipeline.

typedef struct sac_processing sac_processing_t

Audio processing instance forward declaration.

Audio Core Processing.

typedef struct sac_cfg sac_cfg_t: Audio Core Configuration.

typedef enum sac_bit_depth sac_bit_depth_t: Audio Core bit depth of an audio sample.

typedef enum sac_sample_encoding sac_sample_encoding_t: Audio Core sample encoding attributes.

typedef struct sac_sample_format sac_sample_format_t: Audio sample format.

typedef struct sac_header sac_header_t: Audio Core Header.

typedef struct sac_processing_interface sac_processing_interface_t: Processing Interface.

typedef struct sac_endpoint_interface sac_endpoint_interface_t: Endpoint Interface.

typedef struct sac_mixer_option sac_mixer_option_t: Add Audio Core Mixer’s specific options when using pipelines to mix packets.

typedef struct sac_endpoint_cfg sac_endpoint_cfg_t: Audio Core Endpoint Configuration.

typedef struct sac_endpoint sac_endpoint_t: Audio Core Endpoint.

typedef struct sac_pipeline_cfg sac_pipeline_cfg_t: Audio Core Pipeline Configuration.

typedef struct sac_statistics sac_statistics_t: Audio Core Statistics.

Enums

enum sac_bit_depth

Audio Core bit depth of an audio sample.

Values:

enumerator SAC_16BITS = 16: 16-bit PCM samples.

enumerator SAC_18BITS = 18: 18-bit PCM samples.

enumerator SAC_20BITS = 20: 20-bit PCM samples.

enumerator SAC_24BITS = 24: 24-bit PCM samples.

enumerator SAC_32BITS = 32: 32-bit PCM samples.

enum sac_sample_encoding

Audio Core sample encoding attributes.

Values:

enumerator SAC_SAMPLE_UNPACKED: The audio samples are encoded in a word with a size of SAC_WORD_SIZE_BITS. The valid bits of the sample are right aligned (LSB aligned) in the word.

enumerator SAC_SAMPLE_PACKED: The audio samples are encoded with a size corresponding to the bit depth.

Functions

void sac_init(sac_cfg_t cfg, sac_status_t *status)

Initialize the Audio Core.

Parameters:

cfg – [in] Audio Core configuration.
status – [out] Status code.

void sac_mixer_init(sac_mixer_module_cfg_t cfg, sac_status_t *status)

Initialize the SAC Mixer Module.

Note

Only call this initialization when the Mixer Module is needed.

Parameters:

cfg – [in] Configuration of the SAC Mixer Module.
status – [out] Status code.

sac_pipeline_t *sac_pipeline_init(const char *name, sac_endpoint_t *producer, sac_pipeline_cfg_t cfg, sac_endpoint_t *consumer, sac_status_t *status)

Initialize a SAC pipeline.

Parameters:

name – [in] Name of the pipeline.
producer – [in] Producer endpoint.
cfg – [in] Pipeline configuration.
consumer – [in] Consumer endpoint.
status – [out] Status code.

Returns:

Reference to the initialized SAC pipeline.

sac_endpoint_t *sac_endpoint_init(void *instance, const char *name, sac_endpoint_interface_t iface, sac_endpoint_cfg_t cfg, sac_status_t *status)

Initialize an Audio Core endpoint.

Parameters:

instance – [in] Endpoint instance.
name – [in] Name of the endpoint.
iface – [in] Interface of the endpoint.
cfg – [in] Endpoint configuration.
status – [out] Status code.

Returns:

Reference to the initialized endpoint.

void sac_endpoint_link(sac_endpoint_t *consumer, sac_endpoint_t *producer, sac_status_t *status)

Link the queue of a consumer endpoint with a producer endpoint.

pipeline1 = sac_pipeline_init("", PROD1, cfg, CONS1, &status);
// Create 2 consumers for the first pipeline.
sac_pipeline_add_extra_consumer(pipeline1, CONS2, &status);
sac_setup(pipeline1);

pipeline2 = sac_pipeline_init("", PROD2, cfg, CONS3, &status);
// Link the first pipeline consumer to this pipeline's producer.
sac_endpoint_link(CONS1, PROD2, &status);
sac_setup(pipeline2);

pipeline3 = sac_pipeline_init("", PROD3, cfg, CONS4, &status);
// Link the second pipeline consumer to this pipeline's producer.
sac_endpoint_link(CONS2, PROD3, &status);
sac_setup(pipeline3);

Note

This can be used to share processes between two pipelines:

Note

(PROD1) -> [pipeline1] -> (CONS1) ->- (PROD2) -> [pipeline2] -> (CONS3) | (CONS2) ->- (PROD3) -> [pipeline3] -> (CONS4)

Note

- (name) represents an Endpoint.

[name] represents a pipeline.
-> represents the connection between endpoint and pipelines.
->- represents the links made by ‘sac_endpoint_link’ between endpoints.
| represents the link made by ‘sac_pipeline_add_extra_consumer’ between endpoints.

Note

Code example:

Parameters:

consumer – [in] Consumer endpoint instance to be linked.
producer – [in] Producer endpoint instance to be linked.
status – [out] Status code.

sac_processing_t *sac_processing_stage_init(void *instance, const char *name, sac_processing_interface_t iface, sac_status_t *status)

Initialize an Audio Core processing stage.

Parameters:

instance – [in] Processing stage instance.
name – [in] Name of the processing stage.
iface – [in] Interface of the processing stage.
status – [out] Status code.

Returns:

Reference to the initialized processing stage.

void sac_pipeline_add_processing(sac_pipeline_t *pipeline, sac_processing_t *process, sac_status_t *status)

Add a processing stage to the pipeline.

Parameters:

pipeline – [in] Pipeline instance.
process – [in] Pointer to processing structure.
status – [out] Status code.

void sac_pipeline_add_extra_consumer(sac_pipeline_t *pipeline, sac_endpoint_t *next_consumer, sac_status_t *status)

Add an extra consumer endpoint to the pipeline.

Parameters:

pipeline – [in] Pipeline instance.
next_consumer – [in] Extra consumer endpoint.
status – [out] Status code.

void sac_pipeline_add_extra_producer(sac_pipeline_t *pipeline, sac_endpoint_t *next_producer, sac_status_t *status)

Add an extra producer endpoint to the pipeline.

Note

This feature is used for Audio Mixing.

Parameters:

pipeline – [in] Pipeline instance.
next_producer – [in] Extra producer endpoint.
status – [out] Status code.

void sac_add_producer(sac_endpoint_t *main_producer, sac_endpoint_t *next_producer, sac_status_t *status)

Add an extra producer to the producer list.

Note

This feature can be used to map a producer to multiple pipelines by chaining producers of all pipelines.

Parameters:

main_producer – [in] Main producer of the list.
next_producer – [in] Extra producer endpoint.
status – [out] Status code.

void sac_pipeline_add_input_pipeline(sac_pipeline_t *pipeline, sac_pipeline_t *input_pipeline, sac_status_t *status)

Add an input pipeline to a pipeline doing audio mixing.

Parameters:

pipeline – [in] Pipeline instance.
input_pipeline – [in] Input pipeline instance.
status – [out] Status code.

void sac_pipeline_setup(sac_pipeline_t *pipeline, sac_status_t *status)

Setup the Audio Core pipeline.

Note

This makes the pipeline ready to use. It must be called last, after every other initialization functions.

Parameters:

pipeline – [in] Pipeline instance.
status – [out] Status code.

void sac_pipeline_start(sac_pipeline_t *pipeline, sac_status_t *status)

Start the Audio Core pipeline.

Parameters:

pipeline – [in] Pipeline instance.
status – [out] Status code.

void sac_pipeline_stop(sac_pipeline_t *pipeline, sac_status_t *status)

Stop the Audio Core pipeline.

Parameters:

pipeline – [in] Pipeline instance.
status – [out] Status code.

uint32_t sac_processing_ctrl(sac_processing_t *sac_processing, sac_pipeline_t *pipeline, uint8_t cmd, uint32_t arg, sac_status_t *status)

Execute process specific control.

Parameters:

sac_processing – SAC processing structure.
pipeline – [in] Pipeline instance.
cmd – [in] Command specific to the processing stage.
arg – [in] Argument specific to the processing stage.
status – [out] Status code.

Returns:

A value specific to the control function.

void sac_pipeline_process(sac_pipeline_t *pipeline, sac_status_t *status)

Execute the Audio Core processing stages.

Parameters:

pipeline – [in] Pipeline instance.
status – [out] Status code.

void sac_pipeline_produce(sac_pipeline_t *pipeline, sac_status_t *status)

Execute the produce endpoint.

Parameters:

pipeline – [in] Pipeline instance.
status – [out] Status code.

void sac_pipeline_consume(sac_pipeline_t *pipeline, sac_status_t *status)

Execute the consumer endpoint(s).

Parameters:

pipeline – [in] Pipeline instance.
status – [out] Status code.

uint32_t sac_get_allocated_bytes(sac_status_t *status)

Get the number of bytes allocated in the memory pool.

Parameters:: status – [out] Status code.
Returns:: Number of bytes allocated in the memory pool.

uint16_t sac_node_memcpy(queue_node_t *dest_node, uint8_t *data, uint16_t size, sac_status_t *status)

Copy data into a node.

Parameters:

dest_node – [in] Node to copy data to.
data – [in] Data to copy.
size – [in] Size of the data to copy.
status – [out] Status code.

Returns:

Number of bytes copied into the node.

uint16_t sac_node_data_memcpy(queue_node_t *dest_node, uint8_t *data, uint16_t size, sac_status_t *status)

Copy data into a node’s data payload section.

Parameters:

dest_node – [in] Node to copy data to.
data – [in] Data payload to copy.
size – [in] Size of the data payload to copy.
status – [out] Status code.

Returns:

Number of bytes copied into the node’s data payload section.

void sac_set_extra_queue_size(sac_endpoint_t *endpoint, uint8_t extra_queue_size, sac_status_t *status)

Set endpoint internal queue extra.

Note

This may be used by multiple processes. Each process defines the number of additional nodes it requires, and the sum of them is used to initialize the endpoint queue size. This approach allows for more nodes to be allocated while maintaining the user-specified size configuration.

Parameters:

endpoint – [in] Endpoint instance.
extra_queue_size – [in] Extra queue size required.
status – [out] Status code.

struct sac_cfg

#include <sac_api.h>

Audio Core Configuration.

Public Members

uint8_t *memory_pool: Memory pool instance from which memory allocation is done.

size_t memory_pool_size: Memory pool size in bytes.

struct sac_sample_format

#include <sac_api.h>

Audio sample format.

Public Members

sac_bit_depth_t bit_depth: Bit resolution of an audio sample.

sac_sample_encoding_t sample_encoding: Audio sample encoding attribute.

struct sac_header

#include <sac_api.h>

Audio Core Header.

Public Members

uint8_t tx_queue_level_high: For clock drift compensation. Used by the recorder to notify the player that its TX audio buffer is filling up.

uint8_t fallback: Indicates the fallback mode of a packet.

uint8_t crc4: CRC4 of the header.

uint8_t payload_size: Size of the payload (audio samples) expressed in bytes.

struct sac_processing_interface

#include <sac_api.h>

Processing Interface.

Public Members

void (*init)(void *instance, const char *name, sac_pipeline_t *pipeline, mem_pool_t *mem_pool, sac_status_t *status): Function the audio core uses to execute any processing stage initialization sequence.

uint32_t (*ctrl)(void *instance, sac_pipeline_t *pipeline, uint8_t cmd, uint32_t args, sac_status_t *status): Function the audio application uses to interact with the processing stage.

uint16_t (*process)(void *instance, sac_pipeline_t *pipeline, sac_header_t *header, uint8_t *data_in, uint16_t size, uint8_t *data_out, sac_status_t *status): Function the audio core uses to do processing on audio samples.

bool (*gate)(sac_processing_t *process, sac_pipeline_t *pipeline, sac_header_t *header, uint8_t *data_in, uint16_t size, sac_status_t *status): Function called by process_samples prior to process to determine if process will be executed or not.

struct sac_processing

#include <sac_api.h>

Audio Core Processing.

Public Members

void *instance: Pointer to the processing stage’s specific instance.

const char *name: Character string describing the processing stage.

sac_processing_interface_t iface: Interface the processing stage must comply to.

struct sac_processing *next_process: Pointer to the next processing state.

struct sac_endpoint_interface

#include <sac_api.h>

Endpoint Interface.

Public Members

uint16_t (*action)(void *instance, uint8_t *samples, uint16_t size): Function the audio core uses to send or receive audio samples depending if the endpoint produces or consumes.

void (*start)(void *instance): Function the audio core uses to execute any endpoint startup sequence.

void (*stop)(void *instance): Function the audio core uses to stop any endpoint operations.

struct sac_mixer_option

#include <sac_api.h>

Add Audio Core Mixer’s specific options when using pipelines to mix packets.

Public Members

bool input_mixer_pipeline: True if it is the input pipeline of the mixing stage.

bool output_mixer_pipeline: True if it is the output pipeline of the mixing stage.

struct sac_endpoint_cfg

#include <sac_api.h>

Audio Core Endpoint Configuration.

Public Members

bool use_encapsulation: True if the endpoint produces or consumes audio packets (SAC header + audio payload), False for only audio payloads (audio samples).

bool delayed_action: True if the endpoint requires a complete cycle to produce or consume data. False if the endpoint produces or consumes instantly.

uint8_t channel_count: 1 if the endpoint produces or consumes mono audio payloads and 2 for interleaved stereo.

uint16_t audio_payload_size: Size in bytes of the audio payload.

uint8_t queue_size: Size in number of audio packets the endpoint’s queue can contain.

struct sac_endpoint

#include <sac_api.h>

Audio Core Endpoint.

Public Members

void *instance: Pointer to endpoint’s specific instance.

const char *name: Character string describing the endpoint.

sac_endpoint_interface_t iface: Interface the endpoint must comply to.

sac_endpoint_cfg_t cfg: SAC endpoint configuration.

struct sac_endpoint *next_endpoint: Pointer to the next endpoint.

queue_t *queue: Internal: queue the endpoint will use to store or retrieve audio packets.

queue_t *free_queue: Internal: Pointer to the free queue the endpoint will retrieve free nodes from.

queue_node_t *current_node: Internal: pointer to the queue node the endpoint is working with at the moment.

bool buffering_complete: Internal: Whether or not the initial audio buffering has been completed.

uint8_t extra_queue_size: Internal: Extra queue size requested by processes if required.

uint8_t num_endpoints: Total number of endpoints, stored in the first endpoint of the pipeline.

struct sac_endpoint::[anonymous] _internal

struct sac_pipeline_cfg

#include <sac_api.h>

Audio Core Pipeline Configuration.

Public Members

bool do_initial_buffering: Wait for the consumer queue (TX audio buffer) to be full before starting to consume.

sac_mixer_option_t mixer_option: Configure the pipeline with mixer’s specific options.

uint16_t max_payload_size: Max payload size supported in the pipeline. (Defaults to the maximum payload size between the producer and the consumer).

struct sac_statistics

#include <sac_api.h>

Audio Core Statistics.

Public Members

uint32_t producer_buffer_load: Number of audio packets currently in the producer queue.

uint16_t producer_buffer_size: Maximum number of audio packets the producer queue can hold.

uint32_t producer_buffer_overflow_count: Number of times the producer queue has overflowed.

uint32_t producer_packets_corrupted_count: Number of corrupted packets received from the coord.

uint32_t consumer_buffer_load: Number of audio packets currently in the consumer queue.

uint16_t consumer_buffer_size: Maximum number of audio packets the consumer queue can hold.

uint32_t consumer_buffer_overflow_count: Number of times the consumer queue has overflowed.

uint32_t consumer_buffer_underflow_count: Number of times the consumer queue has underflowed.

uint32_t consumer_queue_peak_buffer_load: Consumer queue peak load.

struct sac_pipeline

#include <sac_api.h>

Audio Core Pipeline.

Public Members

const char *name: Name of the pipeline.

sac_pipeline_t *input_pipeline[MAX_NB_OF_INPUTS]: Pipeline inputting audio samples when doing audio mixing.

sac_endpoint_t *producer: Pointer to the SAC endpoint that will produce audio samples to this SAC pipeline.

sac_processing_t *process: List of processing stages that will sequentially be produced samples before they are consumed.

sac_endpoint_t *consumer: Pointer to the SAC endpoint that will consume audio samples from this SAC pipeline.

sac_pipeline_cfg_t cfg: SAC pipeline configuration.

sac_statistics_t _statistics: SAC pipeline statistics.

uint8_t buffering_threshold: Internal: The number of audio packets to buffer before considering the initial buffering complete.

uint32_t samples_buffered_size: Internal: Size in bytes of samples produced but not yet consumed.

queue_t *processing_queue: Internal: Queue used for processing the pipeline.

uint32_t current_sample_count: Internal: Number of samples produced.

uint32_t pending_packets: Internal: Used to track pending packets in the accumulator to be added to the CDC target queue length.

struct sac_pipeline::[anonymous] _internal