ASR Service API

[中文]

Overview

The ASR service provides a complete automatic speech recognition processing framework, supporting the Wanson ASR engine, and offering flexible integration methods. This service supports audio data collection, processing, recognition, and other functions, while also featuring AEC and resampling capabilities.

API Reference

  1. bk_asr_create

Create an ASR service handle.

asr_handle_t bk_asr_create(asr_cfg_t *cfg);

  • Parameters:

    • cfg: ASR configuration parameters, including sample rate, AEC configuration, etc.

  • Return Value:

    • Non-NULL: Success, returns ASR handle

    • NULL: Failure, usually due to invalid parameters or memory allocation failure

  1. bk_asr_init

Initialize the ASR service (ASR does not directly use the microphone, but receives audio data from other audio services as input).

bk_err_t bk_asr_init(asr_cfg_t *cfg, asr_handle_t asr_handle);

  • Parameters:

    • cfg: ASR configuration parameters

    • asr_handle: ASR handle, created by bk_asr_create

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  1. bk_asr_init_with_mic

Initialize the ASR service with a microphone (ASR service can run independently, not relying on other audio services).

bk_err_t bk_asr_init_with_mic(asr_cfg_t *cfg, asr_handle_t asr_handle);

  • Parameters:

    • cfg: ASR configuration parameters

    • asr_handle: ASR handle, created by bk_asr_create

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  1. bk_asr_deinit

Deinitialize the ASR service.

bk_err_t bk_asr_deinit(asr_handle_t asr_handle);

  • Parameters:

    • asr_handle: ASR handle

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  1. bk_asr_start

Start the ASR service.

bk_err_t bk_asr_start(asr_handle_t asr_handle);

  • Parameters:

    • asr_handle: ASR handle

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  1. bk_asr_stop

Stop the ASR service.

bk_err_t bk_asr_stop(asr_handle_t asr_handle);

  • Parameters:

    • asr_handle: ASR handle

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  1. bk_aud_asr_read_mic_data

Read microphone data.

int bk_aud_asr_read_mic_data(asr_handle_t asr_handle, char *buffer, uint32_t size);

  • Parameters:

    • asr_handle: ASR handle

    • buffer: Buffer for storing microphone data

    • size: Buffer size

  • Return Value:

    • Greater than 0: Number of bytes successfully read

    • Less than or equal to 0: Failure

  1. bk_aud_asr_init

Initialize the audio ASR service.

bk_err_t bk_aud_asr_init(aud_asr_cfg_t *cfg);

  • Parameters:

    • cfg: Audio ASR configuration parameters

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  1. bk_aud_asr_deinit

Deinitialize the audio ASR service.

bk_err_t bk_aud_asr_deinit(aud_asr_handle_t aud_asr_handle);

  • Parameters:

    • aud_asr_handle: Audio ASR handle

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  1. bk_aud_asr_start

Start the audio ASR service.

bk_err_t bk_aud_asr_start(aud_asr_handle_t aud_asr_handle);

  • Parameters:

    • aud_asr_handle: Audio ASR handle

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  1. bk_aud_asr_stop

Stop the audio ASR service.

bk_err_t bk_aud_asr_stop(aud_asr_handle_t aud_asr_handle);

  • Parameters:

    • aud_asr_handle: Audio ASR handle

  • Return Value:

    • 0: Success

    • Non-zero: Failure

ASR Engine Interface Function Description

Core function interfaces for interacting with Wanson ASR engine, detailed as follows:

  1. ASR Initialization Interface

int bk_wanson_asr_common_init(void);

  • Function: Initialize the Wanson ASR engine

  • Return Value:

    • 0: Success

    • Non-zero: Failure

    • Description: This function must be called to initialize the engine before using the ASR service

  1. ASR Deinitialization Interface

void bk_wanson_asr_common_deinit(void);

  • Function: Deinitialize the Wanson ASR engine and release resources

    • Description: This function should be called to release resources when the ASR service is no longer used

  1. ASR Recognition Interface

int bk_wanson_asr_recog(void *read_buf, uint32_t read_size, void *p1, void *p2);

  • Function: Process audio data and perform speech recognition

  • Parameters:

    • read_buf: Audio data buffer

    • read_size: Audio data size

    • p1/p2: Additional parameters

  • Return Value:

    • 0: Success

    • Non-zero: Failure

  • Note: This function processes the input audio data, and recognition results are returned through callback functions

Note

  1. These interface functions must be initialized externally by user code before starting the ASR service that used by bk_asr_start.

  2. The implementation of these interface functions will be passed to the ASR service through function pointers in the aud_asr_cfg_t structure.

  3. If users need to use a custom ASR engine but still want to use the ASR processing flow provided by the SDK, they need to:

  • Replace the corresponding ASR library and related files

  • Implement corresponding callback functions according to the above function interface format, including result processing callbacks

Data Structures

  1. asr_cfg_t

ASR configuration structure.

typedef struct
{
   mic_type_t mic_type;                             /* Microphone type */
   union
   {
      onboard_mic_stream_cfg_t    onboard_mic_cfg; /* Onboard microphone configuration */
      uac_mic_stream_cfg_t        uac_mic_cfg;     /* UAC microphone configuration */
   } mic_cfg;
   uint32_t read_pool_size;                        /* Read pool size */
   bool asr_en;
   bool asr_rsp_en;
   bool aec_en;                                   /* AEC function enable flag */
   uint32_t asr_sample_rate;
   union
   {
      rsp_algorithm_cfg_t rsp_alg_cfg;            /* Resampling algorithm configuration */
      uint32_t reserved;
   }rsp_cfg;
   union
   {
      aec_v3_algorithm_cfg_t aec_alg_cfg;        /* AEC algorithm configuration */
      uint32_t reserved2;
   }aec_cfg;
   asr_event_handle event_handle;                /* ASR event handling callback function */
   void * args;                                  /* User-defined parameters */
}  asr_cfg_t;

  1. aud_asr_cfg_t

Audio ASR configuration structure.

typedef struct {
    asr_handle_t asr_handle;                            /* ASR handle */
    void *args;                                         /* Private parameters for callback */
    int task_stack;                                     /* Task stack size */
    int task_core;                                      /* Task running core (0 or 1) */
    int task_prio;                                      /* Task priority */
    audio_mem_type_t mem_type;                          /* Memory type used */
    uint32_t max_read_size;                             /* Maximum data size read from ASR handle */
    void (*aud_asr_result_handle)(uint32_t param);      /* ASR result processing callback (user-defined) */
    int (*aud_asr_init)(void);                          /* ASR initialization callback */
    int (*aud_asr_recog)(void *read_buf, uint32_t read_size, void *p1, void *p2); /* ASR recognition callback */
    void (*aud_asr_deinit)(void);                       /* ASR deinitialization callback */
} aud_asr_cfg_t;

  1. struct asr

ASR service structure.

struct asr
{
   audio_element_handle_t  mic_str;            /* MIC element */
   mic_type_t              mic_type;           /* Onboard or UAC microphone */
   bool                    asr_en;             /* ASR enable flag */
   bool                    asr_rsp_en;         /* Whether ASR source needs resampling */
   bool                    aec_en;             /* AEC enable flag */
   audio_pipeline_handle_t asr_pipeline;       /* ASR audio pipeline */
   audio_element_handle_t  asr_raw_read;       /* Raw audio read element */
   audio_element_handle_t  asr_rsp;            /* ASR resampling element */
   audio_element_handle_t  aec_alg;            /* AEC algorithm handle */
   audio_port_handle_t     aec_alg_ref_rb;     /* AEC reference ring buffer */
   audio_port_handle_t     asr_in_rb;          /* ASR input ring buffer */
   audio_event_iface_handle_t asr_evt;         /* Audio event interface */

   asr_sta_t             status;               /* ASR handle status */
   asr_event_handle      event_handle;         /* ASR event handling callback */
   void *                args;                 /* Event handling function parameters */

   beken_thread_t          listener_task_hdl;  /* Listener task handle */
   beken_queue_t           listener_msg_que;   /* Listener message queue */
   beken_semaphore_t       listener_sem;       /* Listener semaphore */
   bool                    listener_is_running; /* Listener running status */
};

Note

  1. All fields in the ASR service structure are for internal use and do not need to be directly accessed by users.

  2. The status and event handling callback functions of the ASR service are managed internally by the SDK and do not need to be manually called by users.

  3. If the mic input source of the ASR service depends on other audio service components, then mic_str needs to be obtained from the source service component. You can refer to the asr_service_example project.

  1. asr_sta_t

ASR status enumeration.

typedef enum {
    ASR_STA_NONE = 0,      /* Initial state */
    ASR_STA_IDLE,          /* Idle state */
    ASR_STA_RUNNING,       /* Running state */
    ASR_STA_STOPPING,      /* Stopping state */
    ASR_STA_STOPED         /* Stopped state */
} asr_sta_t;

  1. asr_evt_t

ASR event enumeration.

typedef enum {
    ASR_EVT_START = 0,         /* Start event */
    ASR_EVT_STOP,              /* Stop event */
    ASR_EVT_MIC_NOT_SUPPORT,   /* Microphone not supported event */
    ASR_EVT_ERROR_UNKNOW       /* Unknown error event */
} asr_evt_t;

  1. asr_event_handle

ASR event handling callback function type.

typedef bk_err_t (*asr_event_handle)(asr_evt_t event, void *param, void *args);