Transport-neutral, caller-owned audio capture facade. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_audio.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_audio_buffer_t
	Caller-owned writable byte buffer. More...
struct	ra8_audio_frame_t
	Immutable view of one interleaved PCM frame. More...
struct	ra8_audio_source_info_t
	Fixed output contract and storage requirement for one source. More...
struct	ra8_audio_source_t
	Caller-owned handle binding an audio source backend and its state. More...

Typedefs
typedef struct ra8_audio_source_iface	ra8_audio_source_iface_t
	Opaque source vtable implemented by concrete audio backends.
typedef void(*	ra8_audio_frame_callback_t) (void ctx, const ra8_audio_frame_t frame)
	Complete-frame callback for asynchronous audio sources.

Enumerations
enum	ra8_audio_format_t : uint8_t { k_ra8_audio_format_pcm_s16le = 0U , k_ra8_audio_format_pcm_s32le }
	PCM container layouts supported by the facade. More...

Functions
ra8_err_t	ra8_audio_frame_validate (const ra8_audio_frame_t *frame)
	Validate one PCM frame view.
ra8_err_t	ra8_audio_source_get_info (ra8_audio_source_t source, ra8_audio_source_info_t out_info)
	Query a bound source's fixed output contract.
ra8_err_t	ra8_audio_source_capture (ra8_audio_source_t source, const ra8_audio_buffer_t buffer, ra8_audio_frame_t *out_frame)
	Capture one fixed-size PCM frame into caller-owned storage.
ra8_err_t	ra8_audio_source_stream_start (ra8_audio_source_t source, const ra8_audio_buffer_t buffer, ra8_audio_frame_callback_t callback, void *ctx)
	Start asynchronous fixed-frame delivery into caller-owned scratch.
ra8_err_t	ra8_audio_source_stop (ra8_audio_source_t *source)
	Stop and release a bound source backend.

Detailed Description

Transport-neutral, caller-owned audio capture facade.

Tag: [Ring 4 / Service] {World: NS}

Audio sources capture fixed-size PCM frames into storage supplied by the caller. Concrete backends bind an opaque vtable through an _init() helper. Handles, backend state, and sample buffers are never allocated or freed by this library.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_audio.h.

Typedef Documentation

◆ ra8_audio_frame_callback_t

typedef void(* ra8_audio_frame_callback_t) (void *ctx, const ra8_audio_frame_t *frame)

Complete-frame callback for asynchronous audio sources.

Parameters

[in]	ctx	Caller context supplied to stream start.
[in]	frame	Borrowed complete PCM frame.

Precondition: frame and frame->data remain valid only during the callback.

Postcondition: The callback must copy or consume the frame before returning.

Note: The backend defines callback context; PDM invokes it from ISR context.

Since: 0.1.0

Definition at line 93 of file ra8_audio.h.

◆ ra8_audio_source_iface_t

typedef struct ra8_audio_source_iface ra8_audio_source_iface_t

Opaque source vtable implemented by concrete audio backends.

Definition at line 30 of file ra8_audio.h.

Enumeration Type Documentation

◆ ra8_audio_format_t

enum ra8_audio_format_t : uint8_t

PCM container layouts supported by the facade.

Invariant: Each value has a stable one-byte representation.

Since: 0.1.0

Enumerator
k_ra8_audio_format_pcm_s16le	Signed 16-bit little-endian PCM.
k_ra8_audio_format_pcm_s32le	Signed 32-bit little-endian PCM.

Definition at line 38 of file ra8_audio.h.

Function Documentation

◆ ra8_audio_frame_validate()

ra8_err_t ra8_audio_frame_validate ( const ra8_audio_frame_t * frame )

nodiscard

Validate one PCM frame view.

Parameters

[in] frame Candidate frame.

Returns: Error code.

Return values

k_ra8_ok	Frame metadata and byte coverage are valid.
k_ra8_err_null_ptr	frame or frame->data is nullptr.
k_ra8_err_invalid_arg	Format or scalar metadata is invalid.
k_ra8_err_invalid_size	Byte coverage does not match metadata.

Precondition: When non-NULL, frame->data is readable for frame->bytes bytes.

Postcondition: No state is modified.

Note: Thread-safe; reads only its argument.

Since: 0.1.0

Definition at line 47 of file ra8_audio.c.

References ra8_audio_frame_t::bytes, ra8_audio_frame_t::channels, ra8_audio_frame_t::data, ra8_audio_frame_t::format, internal_audio_container_bytes(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_audio_frame_t::sample_count, ra8_audio_frame_t::sample_rate_hz, and ra8_audio_frame_t::valid_bits.

Referenced by ra8_audio_source_capture(), and ra8_audio_source_memory_init().

◆ ra8_audio_source_capture()

ra8_err_t ra8_audio_source_capture	(	ra8_audio_source_t *	source,
		const ra8_audio_buffer_t *	buffer,
		ra8_audio_frame_t *	out_frame )

nodiscard

Capture one fixed-size PCM frame into caller-owned storage.

Parameters

[in,out]	source	Bound source handle.
[in]	buffer	Writable PCM storage.
[out]	out_frame	Receives a borrowed immutable frame view.

Returns: Error code.

Return values

k_ra8_ok	One complete frame captured.
k_ra8_err_null_ptr	An argument or buffer pointer was nullptr.
k_ra8_err_not_initialized	No source backend is bound.
k_ra8_err_invalid_size	Buffer cannot hold the source frame.
other	Propagated backend error.

Precondition: No other call uses source or buffer.

Postcondition: On success out_frame->data == buffer->data and validates.; On error out_frame is zeroed.

Note: Not thread-safe with respect to the same source or buffer.

Since: 0.1.0

Definition at line 190 of file ra8_audio.c.

References ra8_audio_buffer_t::capacity, ra8_audio_source_iface::capture, ra8_audio_source_t::ctx, ra8_audio_buffer_t::data, ra8_audio_frame_t::data, ra8_audio_source_info_t::frame_bytes, ra8_audio_source_iface::get_info, ra8_audio_source_t::iface, internal_audio_capture_args_valid(), internal_audio_frame_matches_info(), k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, and ra8_audio_frame_validate().

Referenced by pdm_demo_run_window().

◆ ra8_audio_source_get_info()

ra8_err_t ra8_audio_source_get_info	(	ra8_audio_source_t *	source,
		ra8_audio_source_info_t *	out_info )

nodiscard

Query a bound source's fixed output contract.

Parameters

[in,out]	source	Bound source handle.
[out]	out_info	Receives source metadata.

Returns: Error code.

Return values

k_ra8_ok	Metadata returned.
k_ra8_err_null_ptr	An argument was nullptr.
k_ra8_err_not_initialized	No source backend is bound.
other	Propagated backend error.

Precondition: out_info points to writable storage.

Postcondition: On error out_info is zeroed.

Note: Not thread-safe with respect to the same source.

Since: 0.1.0

Definition at line 85 of file ra8_audio.c.

References ra8_audio_source_t::ctx, ra8_audio_source_iface::get_info, ra8_audio_source_t::iface, k_ra8_err_not_initialized, and k_ra8_err_null_ptr.

◆ ra8_audio_source_stop()

ra8_err_t ra8_audio_source_stop ( ra8_audio_source_t * source )

nodiscard

Stop and release a bound source backend.

Parameters

[in,out] source Bound source handle.

Returns: Error code.

Return values

k_ra8_ok	Backend stopped and handle cleared.
k_ra8_err_null_ptr	source was nullptr.
k_ra8_err_not_initialized	No source backend is bound.
other	Propagated backend error; the handle remains bound for retry.

Precondition: No capture is in progress.

Postcondition: On success source is reset to an unbound state.

Note: Not thread-safe with respect to the same source.

Since: 0.1.0

Definition at line 265 of file ra8_audio.c.

References ra8_audio_source_t::ctx, ra8_audio_source_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and ra8_audio_source_iface::stop.

Referenced by c6_cam_audio_start().

◆ ra8_audio_source_stream_start()

ra8_err_t ra8_audio_source_stream_start	(	ra8_audio_source_t *	source,
		const ra8_audio_buffer_t *	buffer,
		ra8_audio_frame_callback_t	callback,
		void *	ctx )

nodiscard

Start asynchronous fixed-frame delivery into caller-owned scratch.

Parameters

[in,out]	source	Bound source handle.
[in]	buffer	Persistent writable frame storage.
[in]	callback	Complete-frame callback.
[in]	ctx	Opaque callback context; may be nullptr.

Returns: Error code.

Return values

k_ra8_ok	Streaming started.
k_ra8_err_null_ptr	Required argument or buffer pointer was nullptr.
k_ra8_err_not_initialized	Source is unbound.
k_ra8_err_not_supported	Backend has no streaming operation.
k_ra8_err_invalid_size	Buffer cannot hold one source frame.
other	Propagated backend error.

Precondition: buffer and its storage out-live the stream.

Postcondition: Complete frames are delivered until ra8_audio_source_stop.

Note: Callback execution context is backend-specific and must be respected.

Since: 0.1.0

Definition at line 228 of file ra8_audio.c.

References ra8_audio_buffer_t::capacity, ra8_audio_source_t::ctx, ra8_audio_buffer_t::data, ra8_audio_source_info_t::frame_bytes, ra8_audio_source_iface::get_info, ra8_audio_source_t::iface, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, and ra8_audio_source_iface::stream_start.

Referenced by c6_cam_audio_start().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_audio_frame_callback_t

◆ ra8_audio_source_iface_t

Enumeration Type Documentation

◆ ra8_audio_format_t

Function Documentation

◆ ra8_audio_frame_validate()

◆ ra8_audio_source_capture()

◆ ra8_audio_source_get_info()

◆ ra8_audio_source_stop()

◆ ra8_audio_source_stream_start()