Prompt Player (prompt_player)¶

1. Overview¶

This module is built on top of the audio player to play prompts corresponding to recognized command words. It integrates the lookup of prompt information from command words and provides combined playback, selective playback, and queued playback.

2. Feature Description¶

2.1. In-Command Combined Playback¶

Audio files are typically large and consume significant flash. To save flash, developers canextract common words shared by different prompts and compose the required prompt at runtime by playing multiple audio clips in sequence. For example, in the SDK’s standard “Smart fan” demo, many prompts share the prefix “Okay…”: “Okay, turn on the air conditioner”, “Okay, twenty‑five degrees”, “Okay, turn on the desk lamp”. Extract “Okay” into a separate audio file and use combined playback in the command information table. In your application, simply pass the command ID or string; the combination logic is implemented internally.

Supported APIs:

prompt_play_by_cmd_handle
prompt_play_by_cmd_id
prompt_play_by_semantic_id
prompt_play_by_cmd_string

2.1.1 Example: In-Command Combined Playback¶

Assume the audio content is as follows:

Edit the file [60000]cmd_info.xlsx under SDK\projects\sample_xxx\firmware\user_file\cmd_info\, and fill in the audio IDs for combined playback joined by plus signs (up to 16 clips).
For example, for the command word “Turn on the air conditioner”, in the column “Prompt 0 ID”, enter 4+5+6.

Sample invocation below. The playback content is “Okay, master, I have turned on the air conditioner for you”, formed by combining three audio clips:

```c // Play by command handle: the handle is obtained from the recognition result structure prompt_play_by_cmd_handle(cmd_handle, -1, default_play_done_callback,true);

// Or play by command ID: pass the command ID for “Turn on the air conditioner” prompt_play_by_cmd_id(2, -1, default_play_done_callback,true);

// Or play by semantic ID: pass the semantic ID for “Turn on the air conditioner” prompt_play_by_semantic_id(0x2BC1943, -1, default_play_done_callback,true);

// Or play by command string: pass the string “Turn on the air conditioner” prompt_play_by_cmd_string(“Turn on the air conditioner”, -1, default_play_done_callback,true); ```

2.2. Selective Playback¶

To increase variation and improve user experience, avoid having only one fixed prompt per command. For example, a wake-word response can be “Hello”, “I’m here”, or “Please speak”. When the wake word is detected, one can be selected at random for playback.
To choose prompts based on context. For example, when the user says “Increase volume”, select different prompts depending on the current volume. If already at maximum, play “Okay, at maximum volume”; otherwise play “Okay, volume increased”.

Supported APIs:

prompt_play_by_cmd_handle
prompt_play_by_cmd_id
prompt_play_by_semantic_id
prompt_play_by_cmd_string

2.2.1 Example: Selective Playback¶

Assume the audio content is as follows:

Edit the file [60000]cmd_info.xlsx under SDK\projects\sample_xxx\firmware\user_file\cmd_info. Fill in the selectable prompt audio IDs starting from the “Prompt 0 ID” column onward (up to 127 entries).

Sample invocation below. The second parameter selects which prompt to play:

// Second parameter -1 selects default prompt ID 0: plays "Okay"
 prompt_play_by_cmd_handle(cmd_handle, -1, default_play_done_callback,true);
 prompt_play_by_cmd_id(2, -1, default_play_done_callback,true);
 prompt_play_by_semantic_id(0x2BC1943, -1, default_play_done_callback,true);
 prompt_play_by_cmd_string("Turn on the air conditioner", -1, default_play_done_callback,true);

// Second parameter 0 selects prompt ID 0: plays "Okay"
 prompt_play_by_cmd_handle(cmd_handle, 0, default_play_done_callback,true);
 prompt_play_by_cmd_id(2, 0, default_play_done_callback,true);
 prompt_play_by_semantic_id(0x2BC1943, 0, default_play_done_callback,true);
 prompt_play_by_cmd_string("Turn on the air conditioner", 0, default_play_done_callback,true);

// Second parameter 1 selects prompt ID 1: plays "Master"
 prompt_play_by_cmd_handle(cmd_handle, 1, default_play_done_callback,true);
 prompt_play_by_cmd_id(2, 1, default_play_done_callback,true);
 prompt_play_by_semantic_id(0x2BC1943, 1, default_play_done_callback,true);
 prompt_play_by_cmd_string("Turn on the air conditioner", 1, default_play_done_callback,true);

// Second parameter 2 selects prompt ID 2: plays "the AC is on"
 prompt_play_by_cmd_handle(cmd_handle, 2, default_play_done_callback,true);
 prompt_play_by_cmd_id(2, 2, default_play_done_callback,true);
 prompt_play_by_semantic_id(0x2BC1943, 2, default_play_done_callback,true);
 prompt_play_by_cmd_string("Turn on the air conditioner", 2, default_play_done_callback,true);

2.3. Multi-Command Combined Playback¶

The previous sections introduced “In-Command Combined Playback” and “Selective Playback”. Using them together enables first combining then selecting, i.e., selecting among different combinations. Some applications may require more complex logic: combine different selections—in other words, select first, then combine. This module provides APIs to combine prompts from multiple command words into a single playback sequence, enabling combine → select → combine flows.

Supported APIs:

prompt_play_by_multi_cmd_id

2.3.1 Example: Multi-Command Combined Playback¶

Assume the audio content is as follows:

Suppose the target commands are “All lights on”, “Indoor lights on”, and “Outdoor lights on”.
Edit the file [60000]cmd_info.xlsx under SDK\projects\sample_xxx\firmware\user_file\cmd_info to fill in the audio IDs for playback.

Sample invocation:

prompt_play_info_t p_play_info_all[6] =
{
    // Auto mode
    {21, -1},    // Switch to auto mode 
    {27, -1},    // Middle speed
    {16, -1},    // Twenty eight degrees


    // Sleeping mode

    {29, -1},    // Switch to sleeping mode
    {26, -1},    // Low speed
    {15, -1},    // Twenty seven degrees

};

void deal_asr_msg_by_multi_cmd_id()
{
    // The 2nd parameter indicates the count: combine p_play_info_all[0]~[2] (3 command prompts)
    prompt_play_by_multi_cmd_id(p_play_info_all, 3, default_play_done_callback);
    // Switch to sleeping mode
    prompt_play_by_multi_cmd_id(&p_play_info_all[3], 1, default_play_done_callback);

    // Combine p_play_info_all[0]~[3] (4 command prompts)
    prompt_play_by_multi_cmd_id(p_play_info_all, 4, default_play_done_callback);
    // Low speed
    prompt_play_by_multi_cmd_id(&p_play_info_all[4], 1, default_play_done_callback);

    // Combine p_play_info_all[3]~[5] (3 command prompts)
    prompt_play_by_multi_cmd_id(&p_play_info_all[3], 3, default_play_done_callback);
    // Twenty seven degrees
    prompt_play_by_multi_cmd_id(&p_play_info_all[5], 1, default_play_done_callback);
}

2.4. Preemptive Playback¶

Interrupt the currently playing prompt, clear the existing playback queue, and start the new prompt immediately.

Supported APIs:

prompt_play_by_cmd_handle
prompt_play_by_cmd_id
prompt_play_by_semantic_id
prompt_play_by_cmd_string

Sample invocation below; the 4^th parameter set to true enables preemptive playback:

 // 4th parameter true: interrupt current prompt, clear queue, and start the new prompt immediately
 prompt_play_by_cmd_handle(cmd_handle, 0, default_play_done_callback,true);
 prompt_play_by_cmd_id(2, 0, default_play_done_callback,true);
 prompt_play_by_semantic_id(0x2BC1943, 0, default_play_done_callback,true);
 prompt_play_by_cmd_string("Turn on the air conditioner", 0, default_play_done_callback,true);

2.5. Queued Playback¶

In contrast to preemptive playback, queued playback appends new prompts to the end of the queue and waits for the player to play them in order. Note: the queue length in the SDK is limited. When many prompts must be queued continuously, it is recommended to combine “combined playback + queued playback”.

Supported APIs:

prompt_play_by_cmd_handle
prompt_play_by_cmd_id
prompt_play_by_semantic_id
prompt_play_by_cmd_string

Sample invocation below; the 4^th parameter set to false enables queued playback:

 // 4th parameter false: append the new prompt to the end of the queue and wait for sequential playback
 prompt_play_by_cmd_handle(cmd_handle, 0, default_play_done_callback,false);
 prompt_play_by_cmd_id(2, 0, default_play_done_callback,false);
 prompt_play_by_semantic_id(0x2BC1943, 0, default_play_done_callback,false);
 prompt_play_by_cmd_string("Turn on the air conditioner", 0, default_play_done_callback,false);

2.6. Callback Function¶

All prompt_player playback APIs are non-blocking and return immediately without waiting for the prompt to finish. However, many application logics need to know when playback completes.

Therefore, all playback APIs provide a callback. Pass a callback function pointer when calling the API; when playback finishes, the player invokes the callback to let the caller handle post-playback logic.

Supported APIs:

prompt_play_by_cmd_handle
prompt_play_by_cmd_id
prompt_play_by_semantic_id
prompt_play_by_cmd_string
prompt_play_by_multi_cmd_id

Sample invocation below; the 3^rd parameter default_play_done_callback specifies the callback invoked on completion:

 // The 3rd parameter default_play_done_callback is the callback function for the playback API
 prompt_play_by_cmd_handle(cmd_handle, 0, default_play_done_callback,true);
 prompt_play_by_cmd_id(2, 0, default_play_done_callback,true);
 prompt_play_by_semantic_id(0x2BC1943, 0, default_play_done_callback,true);
 prompt_play_by_cmd_string("Turn on the air conditioner", 0, default_play_done_callback,true);

 // Playback completion callback
 void default_play_done_callback(cmd_handle_t cmd_handle)
 {
    resume_voice_in();

    // Add post-playback handling here
 }

2.7. Playback Status¶

Query and control prompt player status and enable/disable control. Related APIs:

prompt_player_enable
prompt_is_playing
prompt_stop_play

Sample invocation:

```c // Enable prompt playback prompt_player_enable(ENABLE);

// Disable prompt playback prompt_player_enable(DISABLE);

// Check prompt playback status if(prompt_is_playing() == true) { // Playing } else { // Completed }

// Stop prompt playback prompt_stop_play();