Prompt Tones

Overview

Prompt tones refer to the device playing local preset audio files or playing specific audio files in certain states based on agreements with the cloud, to meet interaction and information reminder requirements for various scenarios.

Prompt tones are divided into two categories:

• Local prompt tones: Play local preset audio files directly, which is convenient and fast.
• Cloud prompt tones: Request specific states from the cloud, with responses provided by AI. Cloud prompt tones can maintain consistency with the role’s voice and offer a better interactive experience, but they have a certain latency.

Local prompt tones

Directory structure

The code for local prompt tones is located in the src/wukong/assets/ directory:

assets/
├── scripts/
│   └── gen_media_src.py    # MP3 to C file generation script
├── media_src.h             # Media resource master header file
├── media_src_zh.h          # Chinese prompt tone declarations
├── media_src_zh.c          # Chinese prompt tone data
├── media_src_en.h          # English prompt tone declarations
├── media_src_en.c          # English prompt tone data
└── README.md               # This document

MP3 file naming rules

The script categorizes MP3 files into two groups, Chinese and English, based on their filename suffixes.

MP3 file requirements for local prompt tones

• Voice timbre: It is recommended to generate the voice timbre by using the voice of the product’s AI role.
• Format: Standard MP3, 16 kHz sampling rate, 16-bit bit depth, and mono channel.
• Bitrate: 32 kbps is recommended to reduce firmware size.
• Duration: Prompt tones should ideally be controlled within 1–3 seconds.
• File size: Excessively large files will significantly increase flash memory usage, requiring a trade-off.

How to generate C files

1. Prepare MP3 files. Place all MP3 files into the same directory. For example, scripts/mp3/ or another MP3 directory in your project.

2. Run the generation script.

   # Run from the assets/scripts directory
   cd src/wukong/assets/scripts
   python gen_media_src.py <path to mp3 files>
   

   Example: If the MP3 files are in the scripts/mp3 directory:

   python gen_media_src.py ./mp3
   # Alternatively, use an absolute path
   python gen_media_src.py /path/to/your/mp3_folder
   

3. Generate the result. The script will perform the following operations:

   • Traverse all *.mp3 files in the specified directory.
   • Classify them according to the zh/en suffix.
   • Generate the following files in the assets/ directory:
     • media_src_zh.h/media_src_zh.c (Chinese)
     • media_src_en.h/media_src_en.c (English)
     • media_src.h (Master header file that includes the above)

Variable naming rules

• File name:dingdong_zh.mp3 → C array name: media_src_dingdong_zh
• File name: wakeup_en.mp3 → C array name:media_src_wakeup_en
• Hyphens (-) in file names will be replaced with underscores (_).

Example

Play a prompt tone directly

In wukong_audio_player.c, prompt tones are played using wukong_audio_play_data().

#include "media_src.h"

// Play dingdong_zh prompt tone
audio_data = (CONST CHAR_T*)media_src_dingdong_zh;
audio_size = sizeof(media_src_dingdong_zh);
wukong_audio_play_data(AI_AUDIO_CODEC_MP3, audio_data, audio_size);

Play prompt tones uniformly by type

In the switch (type) block of wukong_audio_player_alert(), select different prompt tones based on the TY_AI_TOY_ALERT_TYPE_E type.

1. Place a new file in the MP3 directory (ending with _zh.mp3 or _en.mp3).
2. Run gen_media_src.py to regenerate the C files.
3. Add the corresponding case in the switch (type) block.

Example: Add a Chinese prompt tone for network configuration:

case AI_TOY_ALERT_TYPE_NETWORK_CFG:
    audio_data = (CONST CHAR_T*)media_src_network_config_zh;
    audio_size = sizeof(media_src_network_config_zh);
    break;

Cloud prompt tones

In addition to local MP3 files, the Wukong AI supports cloud prompt tones: speech generated by cloud TTS (Text-to-Speech) is sent to the device for playback. This allows dynamic changes to the text content and voice timbre without requiring a firmware reflash.

Enable cloud prompt tones

Configure in include/tuya_device_cfg.h:

#define ENABLE_CLOUD_ALERT 1   /* Enable cloud prompt tones. The default value of 0 indicates it is disabled. */

Process of cloud prompt tones

wukong_audio_player_alert(type)
        │
        ├─ ENABLE_CLOUD_ALERT==1 and type supports cloud
        │       │
        │       └─► wukong_ai_agent_cloud_alert(type)
        │               │
        │               ├─ Success → Send command to cloud → Cloud TTS stream → Play back in the device
        │               └─ Failure → Fallback to local MP3
        │
        └─ Other cases → Play local media_src_xxx directly

Prompt tone priority

When ENABLE_CLOUD_ALERT == 1, prompt tones of the following types will request the cloud first. If successful, the cloud TTS is played. On failure or if unsupported, it falls back to the local MP3 files.

The following types are local only and do not use the cloud (in case the device is offline or the cloud is unsupported):

• AI_TOY_ALERT_TYPE_POWER_ON: Power-on announcement
• AI_TOY_ALERT_TYPE_BATTERY_LOW: Low battery
• AI_TOY_ALERT_TYPE_PLEASE_AGAIN: Please repeat
• AI_TOY_ALERT_TYPE_NOT_ACTIVE: Not paired
• AI_TOY_ALERT_TYPE_NETWORK_CFG: Pairing in progress
• AI_TOY_ALERT_TYPE_NETWORK_FAIL: Network connection failed
• AI_TOY_ALERT_TYPE_NETWORK_DISCONNECT: Network disconnected

How-to

The application layer can directly call wukong_ai_agent_cloud_alert() to request a cloud prompt tone (requires #include "wukong_ai_agent.h" first).

#include "wukong_ai_agent.h"

/* Request the "Network Connected" cloud prompt tone */
wukong_ai_agent_cloud_alert(AT_NETWORK_CONNECTED);

/* Request the "Wake-up" cloud prompt tone */
wukong_ai_agent_cloud_alert(AT_WAKEUP);

Recommendations

• Single role: Prioritize using local prompt tones for consistent voice timbre and fast response.
• Multiple role switching: Prioritize using cloud prompt tones for easier remote updates of text and voice timbre.
• Offline/pairing scenarios: Local MP3 files must be used to ensure playback even without a network connection.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.