Microphone

Microphone driver interface. More...

Modules
	nRF5 PDM microphone
	Microphone implementation for the nRF5 PDM peripheral.
	QEMU microphone
	Microphone implementation for QEMU, delivering silence on a timer.
	SF32LB52 PDM microphone
	Microphone implementation for the SF32LB52 PDM peripheral.

Macros
#define	MIC_SAMPLE_RATE   (16000)
	Sample rate of the captured audio, in Hz.
#define	MIC_DEFAULT_VOLUME   (-1)
	Volume value meaning the driver default; not used by the drivers.

Typedefs
typedef const struct MicDevice	MicDevice
	Microphone device, defined by the driver implementation.
typedef void(*	MicDataHandlerCB) (int16_t *samples, size_t sample_count, void *context)
	Handler for a full buffer of captured audio.
typedef void(*	MicDataReadyCB) (void *context)
	Notification that a frame is ready for mic_poll().

Functions
void	mic_init (MicDevice *this)
	Initialize the microphone driver.
void	mic_set_volume (MicDevice *this, uint16_t volume)
	Set the capture gain.
bool	mic_start (MicDevice *this, MicDataHandlerCB data_handler, void *context, int16_t *audio_buffer, size_t audio_buffer_len)
	Start capturing.
bool	mic_start_polling (MicDevice *this, MicDataHandlerCB data_handler, void *context, int16_t *audio_buffer, size_t audio_buffer_len, MicDataReadyCB ready)
	Start capturing with realtime dispatch.
void	mic_poll (MicDevice *this)
	Deliver the pending frames to the data handler.
bool	mic_get_frame_time (MicDevice *this, uint32_t *sample_time)
	Get the capture time of the frame being delivered.
void	mic_stop (MicDevice *this)
	Stop capturing.
bool	mic_is_running (MicDevice *this)
	Check whether the microphone is running.
uint32_t	mic_get_channels (MicDevice *this)
	Get the number of audio channels.

Detailed Description

Microphone driver interface.

The driver captures 16-bit PCM at MIC_SAMPLE_RATE into a caller-provided buffer and hands each full buffer to a data handler. The per-implementation MicDevice definitions live in the microphone driver subgroups.

static int16_t s_frame[320];
 
static void prv_frame(int16_t *samples, size_t sample_count, void *context) {
  encode(samples, sample_count);
}
 
mic_init(MIC);
mic_start(MIC, prv_frame, NULL, s_frame, ARRAY_LENGTH(s_frame));
...
mic_stop(MIC);

Macro Definition Documentation

MIC_DEFAULT_VOLUME

#define MIC_DEFAULT_VOLUME   (-1)

Volume value meaning the driver default; not used by the drivers.

MIC_SAMPLE_RATE

#define MIC_SAMPLE_RATE   (16000)

Sample rate of the captured audio, in Hz.

Typedef Documentation

MicDataHandlerCB

typedef void(* MicDataHandlerCB) (int16_t *samples, size_t sample_count, void *context)

Handler for a full buffer of captured audio.

Runs on the system task, or on the consumer's task from mic_poll() in polling mode.

Parameters

samples	Captured samples, the buffer passed when starting.
sample_count	Number of 16-bit samples in samples.
context	User context passed when starting.

MicDataReadyCB

typedef void(* MicDataReadyCB) (void *context)

Notification that a frame is ready for mic_poll().

Runs from the DMA ISR; it must only wake the consumer.

Parameters

context

User context passed to mic_start_polling().

MicDevice

typedef const struct MicDevice MicDevice

Microphone device, defined by the driver implementation.

Function Documentation

mic_get_channels()

uint32_t mic_get_channels

(

MicDevice *

this

)

Get the number of audio channels.

Parameters

this	Microphone device.

Returns

1 for mono, 2 for stereo; 1 if the device does not specify it.

mic_get_frame_time()

bool mic_get_frame_time	(	MicDevice *	this,
		uint32_t *	sample_time
	)

Get the capture time of the frame being delivered.

Only valid inside the data handler.

Parameters

	this	Microphone device.
[out]	sample_time	Time of the first sample of the frame, on a wrapping MIC_SAMPLE_RATE clock derived from uptime and re-anchored whenever it drifts more than 8 ms from it.

Returns

True if sample_time was set, false outside the data handler.

mic_init()

void mic_init

(

MicDevice *

this

)

Initialize the microphone driver.

Called once at boot.

Parameters

this	Microphone device.

mic_is_running()

bool mic_is_running

(

MicDevice *

this

)

Check whether the microphone is running.

Parameters

this	Microphone device.

Returns

True if capturing.

mic_poll()

void mic_poll

(

MicDevice *

this

)

Deliver the pending frames to the data handler.

Only for capture started with mic_start_polling().

Parameters

this	Microphone device.

mic_set_volume()

void mic_set_volume	(	MicDevice *	this,
		uint16_t	volume
	)

Set the capture gain.

Must be called after mic_init() and while the microphone is stopped; ignored while running.

Parameters

this	Microphone device.
volume	Gain; the range is driver specific (0-100 on SF32LB52, 0-1024 on nRF5).

mic_start()

bool mic_start	(	MicDevice *	this,
		MicDataHandlerCB	data_handler,
		void *	context,
		int16_t *	audio_buffer,
		size_t	audio_buffer_len
	)

Start capturing.

data_handler is called each time audio_buffer has been filled.

Parameters

this	Microphone device.
data_handler	Handler for each full buffer.
context	User context passed to data_handler.
audio_buffer	Buffer the driver fills, owned by the caller until mic_stop() returns.
audio_buffer_len	Capacity of audio_buffer, in 16-bit samples.

Returns

True if capture started, false if it was already running or could not start.

mic_start_polling()

bool mic_start_polling	(	MicDevice *	this,
		MicDataHandlerCB	data_handler,
		void *	context,
		int16_t *	audio_buffer,
		size_t	audio_buffer_len,
		MicDataReadyCB	ready
	)

Start capturing with realtime dispatch.

Provided by drivers that select MIC_POLLING. Instead of calling data_handler on the system task, the driver calls ready and the consumer calls mic_poll() from its own task to receive the frames.

Parameters

this	Microphone device.
data_handler	Handler for each full buffer, called from mic_poll().
context	User context passed to data_handler and ready.
audio_buffer	Buffer the driver fills, owned by the caller until mic_stop() returns.
audio_buffer_len	Capacity of audio_buffer, in 16-bit samples.
ready	Called when frames are ready.

Returns

False, without starting capture, if the device is busy.

mic_stop()

void mic_stop

(

MicDevice *

this

)

Stop capturing.

Samples in a partially filled buffer are dropped. Once this returns, no more handlers run and the buffer is no longer written.

Parameters

this	Microphone device.