Voice Service API

[中文]

Overview

The voice service provides two-way voice call functionality and supports common features such as AEC (Acoustic Echo Cancellation) and codec.

API Reference

Header File

Functions

voice_handle_t bk_voice_init(voice_cfg_t *cfg)

Create a voice call handle.

Parameters

cfg – [in] The voice call configuration.

Returns

The voice handle.

  • Not NULL: Success.

  • NULL: Failed.

bk_err_t bk_voice_deinit(voice_handle_t voice_handle)

Destroy a voice call handle.

Parameters

voice_handle – [in] The voice call handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_start(voice_handle_t voice_handle)

Start a voice call.

Parameters

voice_handle – [in] The voice call handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_stop(voice_handle_t voice_handle)

Stop a voice call.

Parameters

voice_handle – [in] The voice call handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

int bk_voice_read_mic_data(voice_handle_t voice_handle, char *buffer, uint32_t size)

Read microphone data.

Parameters

  • voice_handle – [in] The voice call handle.

  • buffer – [out] The buffer to store microphone data.

  • size – [in] The size of the buffer.

Returns

The actual number of bytes read.

  • Greater than 0: The number of bytes successfully read.

  • Less than or equal to 0: Failed.

int bk_voice_write_spk_data(voice_handle_t voice_handle, char *buffer, uint32_t size)

Write data to the speaker.

Parameters

  • voice_handle – [in] The voice call handle.

  • buffer – [in] The buffer containing the data to be written.

  • size – [in] The size of the data to be written.

Returns

The actual number of bytes written.

  • Greater than 0: The number of bytes successfully written.

  • Less than or equal to 0: Failed.

bk_err_t bk_voice_event_handle(voice_event_handle event_handle, voice_evt_t event, void *param, void *args)

Handle voice events.

Parameters

  • event_handle – [in] The voice event handling function.

  • event – [in] The voice event type.

  • param – [in] The event parameter.

  • args – [in] Additional parameters.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_get_status(voice_handle_t voice_handle, voice_sta_t *status)

Get the status of a voice call.

Parameters

  • voice_handle – [in] The voice call handle.

  • status – [out] The pointer to store the voice status.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

int bk_voice_get_mic_str(voice_handle_t voice_handle, voice_cfg_t *cfg)
audio_element_handle_t bk_voice_get_spk_element(voice_handle_t voice_handle)

Get the speaker element handle of the voice call.

Parameters

voice_handle – [in] The voice call handle.

Returns

The speaker element handle.

  • Not NULL: Success.

  • NULL: Failed.

void bk_voice_cal_vad_buf_size(voice_cfg_t *cfg, voice_handle_t voice_handle)
bk_err_t bk_voice_get_micstr(voice_handle_t voice_handle, audio_element_handle_t *mic_str)

Get the microphone stream handle.

Parameters

  • voice_handle – [in] The voice call handle.

  • mic_str – [out] The pointer to store the microphone stream handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_get_micstr_type(voice_handle_t voice_handle, mic_type_t *mic_type)

Get the microphone type.

Parameters

  • voice_handle – [in] The voice call handle.

  • mic_type – [out] The pointer to store the microphone type.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_get_spkstr(voice_handle_t voice_handle, audio_element_handle_t *spk_str)

Get the speaker stream handle.

Parameters

  • voice_handle – [in] The voice call handle.

  • spk_str – [out] The pointer to store the speaker stream handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_get_spkstr_type(voice_handle_t voice_handle, spk_type_t *spk_type)

Get the speaker type.

Parameters

  • voice_handle – [in] The voice call handle.

  • spk_type – [out] The pointer to store the speaker type.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_get_aec_alg(voice_handle_t voice_handle, audio_element_handle_t *aec_alg)

Get the AEC algorithm element handle.

Parameters

  • voice_handle – [in] The voice call handle.

  • aec_alg – [out] The pointer to store the AEC algorithm element handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

Header File

Functions

voice_read_handle_t bk_voice_read_init(voice_read_cfg_t *cfg)

Create a voice read handle to read mic data from voice service.

Parameters

cfg – [in] The voice read configuration.

Returns

The voice read handle.

  • Not NULL: Success.

  • NULL: Failed.

bk_err_t bk_voice_read_deinit(voice_read_handle_t voice_read_handle)

Destroy a voice read handle.

Parameters

voice_read_handle – [in] The voice read handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_read_start(voice_read_handle_t voice_read_handle)

Start a voice read.

Parameters

voice_read_handle – [in] The voice read handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_read_stop(voice_read_handle_t voice_read_handle)

Stop a voice read.

Parameters

voice_read_handle – [in] The voice read handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

Header File

Functions

voice_write_handle_t bk_voice_write_init(voice_write_cfg_t *cfg)

Create a voice write handle to write speech data to voice service.

Parameters

cfg – [in] The voice write configuration.

Returns

The voice write handle.

  • Not NULL: Success.

  • NULL: Failed.

bk_err_t bk_voice_write_deinit(voice_write_handle_t voice_write_handle)

Destroy a voice write handle.

Parameters

voice_write_handle – [in] The voice write handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_write_start(voice_write_handle_t voice_write_handle)

Start a voice write.

Parameters

voice_write_handle – [in] The voice write handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_write_stop(voice_write_handle_t voice_write_handle)

Stop a voice write.

Parameters

voice_write_handle – [in] The voice write handle.

Returns

Error code.

  • 0: Success.

  • Non-zero: Failed.

bk_err_t bk_voice_write_frame_data(voice_write_handle_t voice_write_handle, char *buffer, uint32_t len)

Write speech data to voice service.

Parameters

  • voice_write_handle – [in] The voice write handle.

  • buffer – [in] The speech data buffer.

  • len – [in] The speech data length.

Returns

The number of bytes written.

  • >= 0: Success. Note: it may return 0 if internal buffer is insufficient and data is dropped.

  • < 0 : Failed.

API Typedefs

Header File

Structures

struct audio_codec_common_t

Common audio codec configuration structure.

This structure defines common configuration parameters for audio encoders and decoders.

Public Members

uint32_t samp_rate

Audio sampling rate in Hz

uint32_t bitrate

Audio bitrate in bits per second

uint32_t frame_in_size

Input frame size in bytes

uint32_t frame_out_size

Output frame size in bytes

uint8_t bits

Number of bits per sample

uint8_t frame_in_ms

Input frame duration in milliseconds

uint8_t vbr

Variable bitrate enable flag

uint8_t channels

Number of audio channels

struct voice_cfg_t

Voice service configuration structure.

This structure defines the complete configuration for the voice service, including microphone settings, speaker settings, encoding/decoding parameters, and audio processing algorithms.

Public Members

mic_type_t mic_type

Microphone type

onboard_mic_stream_cfg_t onboard_mic_cfg

Onboard microphone configuration

onboard_dual_dmic_mic_stream_cfg_t onboard_dual_dmic_mic_cfg

Onboard dual DMIC configuration

uac_mic_stream_cfg_t uac_mic_cfg

USB audio class microphone configuration

union voice_cfg_t::[anonymous] mic_cfg

Microphone configuration union

bool aec_en

Acoustic Echo Cancellation (AEC) enable flag

aec_v3_algorithm_cfg_t aec_alg_cfg

AEC algorithm configuration

uint8_t reserve

Reserved for future use

union voice_cfg_t::[anonymous] aec_cfg

AEC configuration union

bool enc_en

Audio encoder enable flag

audio_enc_type_t enc_type

Audio encoder type

audio_codec_common_t enc_common

Common encoder configuration

g711_encoder_cfg_t g711_enc_cfg

G.711 encoder configuration

uint8_t pcm_enc_cfg

PCM encoder configuration placeholder

union voice_cfg_t::[anonymous] enc_cfg

Encoder configuration union

uint32_t read_pool_size

Size (in bytes) of pool to save encoded microphone data

uint32_t write_pool_size

Size (in bytes) of pool to save speaker data that hasn’t been decoded

bool dec_en

Audio decoder enable flag

audio_dec_type_t dec_type

Audio decoder type

audio_codec_common_t dec_common

Common decoder configuration

g711_decoder_cfg_t g711_dec_cfg

G.711 decoder configuration

uint8_t pcm_dec_cfg

PCM decoder configuration placeholder

union voice_cfg_t::[anonymous] dec_cfg

Decoder configuration union

spk_type_t spk_type

Speaker type

onboard_speaker_stream_cfg_t onboard_spk_cfg

Onboard speaker configuration

uac_speaker_stream_cfg_t uac_spk_cfg

USB audio class speaker configuration

i2s_stream_cfg_t i2s_cfg

I2S speaker configuration

union voice_cfg_t::[anonymous] spk_cfg

Speaker configuration union

voice_event_handle event_handle

Voice event handle callback function

void *args

User defined arguments for the event handle function

voice_element_init voice_enc_init

Voice encoder element init callback function, use this function to create an encoder element when enc_type=AUDIO_ENC_TYPE_USER

void *enc_args

User defined config arguments for the voice encoder init function

voice_element_init voice_dec_init

Voice decoder element init callback function, use this function to create a decoder element when dec_type=AUDIO_DEC_TYPE_USER

void *dec_args

User defined config arguments for the voice decoder init function

Macros

VOICE_BY_ONBOARD_MIC_SPK_CFG_DEFAULT()

Default voice service configuration using onboard microphone and speaker with AEC, 8000Hz sample rate and G.711a codec.

This configuration defines default settings for voice service operations using:

  • Input: Onboard microphone

  • Output: Onboard speaker

  • AEC: Enabled

  • Mic sample rate: 8000Hz

  • Speaker sample rate: 8000Hz

  • Encoder: G.711a

  • Decoder: G.711a

  • Equalizer: Disabled

DEFAULT_VOICE_BY_ONBOARD_MIC_SPK_CONFIG()
DEFAULT_VOICE_BY_ONBOARD_MIC_SPK_AEC_G711A_16000_CONFIG()

Default voice service configuration using onboard microphone and speaker with AEC, 16000Hz sample rate and G.711a codec.

This configuration defines default settings for voice service operations using:

  • Input: Onboard microphone

  • Output: Onboard speaker

  • AEC: Enabled

  • Mic sample rate: 16000Hz

  • Speaker sample rate: 16000Hz

  • Encoder: G.711a

  • Decoder: G.711a

  • Equalizer: Disabled

VOICE_BY_UAC_MIC_SPK_CFG_DEFAULT()

Default voice service configuration using UAC microphone and speaker with AEC, 8000Hz sample rate and G.711a codec.

This configuration defines default settings for voice service operations using:

  • Input: UAC microphone

  • Output: UAC speaker

  • AEC: Enabled

  • Mic sample rate: 8000Hz

  • Speaker sample rate: 8000Hz

  • Encoder: G.711a

  • Decoder: G.711a

  • Equalizer: Disabled

DEFAULT_VOICE_BY_UAC_MIC_SPK_CONFIG()
VOICE_BY_ONBOARD_DUAL_DMIC_MIC_SPK_CFG_DEFAULT()

Default voice service configuration using onboard dual DMIC and speaker with AEC, 16000Hz sample rate and G.711a codec.

This configuration defines default settings for voice service operations using:

  • Input: Onboard dual DMIC

  • Output: Onboard speaker

  • AEC: Enabled

  • Mic sample rate: 16000Hz

  • Speaker sample rate: 16000Hz

  • Encoder: G.711a

  • Decoder: G.711a

DEFAULT_VOICE_BY_ONBOARD_DUAL_DMIC_MIC_SPK_CONFIG()
DEFAULT_VOICE_BY_ONBOARD_MIC_I2S_SPK_AEC_G711A_16000_CONFIG()

Default voice service configuration using onboard microphone and speaker with AEC, 8000Hz sample rate and G.711a codec, with equalizer enabled.

This configuration defines default settings for voice service operations using:

  • Input: Onboard microphone

  • Output: Onboard speaker

  • AEC: Enabled

  • Mic sample rate: 8000Hz

  • Speaker sample rate: 8000Hz

  • Encoder: G.711a

  • Decoder: G.711a

  • Equalizer: Enabled

Default voice service configuration using onboard microphone and i2s speaker with AEC, 16000Hz sample rate and G.711a codec

This configuration defines default settings for voice service operations using:

  • Input: Onboard microphone

  • Output: I2S speaker

  • AEC: Enabled

  • Mic sample rate: 16000Hz

  • Speaker sample rate: 16000Hz

  • Encoder: G.711a

  • Decoder: G.711a

  • Equalizer: Disabled

Type Definitions

typedef bk_err_t (*voice_event_handle)(voice_evt_t evt, void *data, void *args)

Voice service event handler callback type.

This typedef defines the function pointer type for handling voice service events.

Param evt

Event type

Param data

Event data

Param args

User defined arguments

Return

bk_err_t Returns BK_OK on success, other values indicate error

typedef audio_element_handle_t (*voice_element_init)(void *args)

Voice service element init callback type.

This typedef defines the function pointer type for initializing voice service elements.

Param args

User defined arguments

Return

audio_element_handle_t Returns a handle to the initialized audio element, or NULL on failure

typedef struct voice *voice_handle_t

Voice service handle type.

This typedef defines a pointer to the voice service structure.

Enumerations

enum voice_sta_t

Generic Voice Service Types.

This file defines the common data types, enumerations, and structures used by the voice service module. These types are used to configure and control voice service operations including microphone input, speaker output, encoding, decoding, and audio processing algorithms.

Voice service status enumeration

This enumeration defines the operational states of the voice service.

Values:

enumerator VOICE_STA_NONE

Voice service is in an undefined state

enumerator VOICE_STA_IDLE

Voice service is initialized but not active

enumerator VOICE_STA_RUNNING

Voice service is actively processing audio

enumerator VOICE_STA_STOPPING

Voice service is in the process of stopping

enumerator VOICE_STA_STOPED

Voice service has been stopped

enum voice_evt_t

Voice service event enumeration.

This enumeration defines the events that can be generated by the voice service.

Values:

enumerator VOC_EVT_NONE

No event

enumerator VOC_EVT_MIC_NOT_SUPPORT

Microphone type is not supported

enumerator VOC_EVT_SPK_NOT_SUPPORT

Speaker type is not supported

enumerator VOC_EVT_ERROR_UNKNOW

Unknown error occurred

enumerator VOC_EVT_STOP

Voice service stop event

Header File

Structures

struct voice_read_cfg_t

Voice read configuration structure.

Public Members

voice_handle_t voice_handle

voice handle

uint32_t max_read_size

the max size of data read from voice handle, used in voice_read_callback

int (*voice_read_callback)(unsigned char *data, unsigned int len, void *args)

call this callback when avlid data has been read

void *args

the pravate parameter of callback

int task_stack

Task stack size

int task_core

Task running in core (0 or 1)

int task_prio

Task priority (based on freeRTOS priority)

audio_mem_type_t mem_type

memory type used, sram or psram

Macros

VOICE_READ_TASK_PRIO

Default voice read task priority.

VOICE_READ_CFG_DEFAULT()

Default voice read configuration.

This configuration defines default settings for voice read service operations using:

  • Voice handle: NULL

  • Max read size: 1920 bytes

  • Voice read callback: NULL

  • Task stack size: 2048 bytes

  • Task running in core: 0

  • Task priority: VOICE_READ_TASK_PRIO

  • Memory type: AUDIO_MEM_TYPE_PSRAM

Type Definitions

typedef struct voice_read *voice_read_handle_t

Voice Read Service Types.

This file defines the data types and structures used by the voice read service module. These types are used to configure and control voice read service operations.

Voice read handle type

Header File

Structures

struct voice_write_cfg_t

Voice write configuration structure.

Public Members

voice_handle_t voice_handle

voice handle

uint32_t start_threshold

The threshold to start writing data

uint32_t pause_threshold

The threshold to pause writing data

int task_stack

Task stack size

int task_core

Task running in core (0 or 1)

int task_prio

Task priority (based on freeRTOS priority)

audio_mem_type_t mem_type

memory type used, sram, psram or audio heap

audio_buf_type_t write_buf_type

write buffer type used, frame buffer or ring buffer

int node_size

frame buffer node size or ring buffer pool size

int node_num

frame buffer node number or 1 for ring buffer

Macros

VOICE_WRITE_TASK_PRIO

Default voice write task priority.

VOICE_WRITE_POOL_SIZE

Default voice write pool size.

VOICE_WRITE_START_THRESHOLD

Default voice write start threshold.

VOICE_WRITE_PAUSE_THRESHOLD

Default voice write pause threshold.

VOICE_WRITE_CFG_DEFAULT()

Default voice write configuration.

This configuration defines default settings for voice write service operations using:

  • Voice handle: NULL

  • Start threshold: VOICE_WRITE_START_THRESHOLD

  • Pause threshold: VOICE_WRITE_PAUSE_THRESHOLD

  • Task stack size: 2048 bytes

  • Task running in core: 0

  • Task priority: VOICE_READ_TASK_PRIO

  • Memory type: AUDIO_MEM_TYPE_PSRAM

  • Write buffer type: AUDIO_BUF_TYPE_RB

  • Node size: VOICE_WRITE_POOL_SIZE

  • Node number: 1

Type Definitions

typedef struct voice_write *voice_write_handle_t

Voice Write Service Types.

This file defines the data types and structures used by the voice write service module. These types are used to configure and control voice write service operations.

Voice write handle type