Developer Guide on Audio Player¶

1. Overview¶

SDK built-in components The lightweight audio player is a very important component. CI130X is a voice recognition chip, and voice broadcast is an indispensable part of voice interaction. The component is lightweight, easy to use, and extensible. The playback component can support decoder registration extensions. Users can register audio decoders, such as MP3, ACC, and FLAC. After completing the registration of related decoders, they can use the universal player interface for audio playback. Player data source acquisition has supported spiflash, sd card, http network download and extended writing interface. If you use spiflash, sd card, http network download, you can directly use the relevant api interface to directly start the playback. While using the data write interface, you can freely call the write function to write data into the buffer, and you can complete the playback task without caring about decoding and hardware playback.

Figure 1-1 Player structure

2. Instructions for use¶

2.1. Code structure¶

Source File	illustrate
audio_play_api.c audio_play_api.h	Player interface function
audio_play_decoder.c audio_play_decoder.h	decoder interface
audio_play_device.c audio_play_device.h	sound card hardware
audio_play_os_port.c audio_play_os_port.h	os abstraction layer
audio_play_process.c audio_play_process.h	The player schedules the main task
get_play_data.c get_play_data.h	Audio data source acquisition

2.2. Decoder registration¶

The player provides the audio playing format, which requires the decoder. The decoder structure is defined in audio_play_decoder, when the system is initialized, the corresponding decoder of the audio format needs to be registered to the player component through registe_decoder_ops function.

registe_decoder_ops(&prompt_decoder);  // Register prompt decoder
registe_decoder_ops(&mp3_decoder);     // Register MP3 decoder
registe_decoder_ops(&aac_decoder);     // Register aac decoder
registe_decoder_ops(&ms_wav_decoder);  // Register ms_Wav decoder
registe_decoder_ops(&flac_decoder);    // Register flac decoder

Prompt

Relevant audio playback formats need to be provided by the decoder. Here, only the registered ops interface is provided.

2.3. Preset Data Source Playback API¶

2.3.1. Play audio¶

play_audio function provides the function of playing audio files from SD cards and network urls. Examples are as follows:

//Play from the file system/test128.mp3. 0 represents the start offset of play. "mp3" is a standard mp3 file with a decoder type and ID3V2 header. You can fill in NULL. The player can automatically identify the file type. NULL is the callback function registration when play is completed
play_audio("/", "test128.mp3", 0, "mp3",NULL);
//Playback is from the network 192.168.31.1/test128.mp3, the second parameter is filled with NULL, "mp3" is the decoder type, 0 represents the start offset of playback, and NULL is the callback function registration when playback is completed
play_audio("192.168.31.1/test128.mp3", NULL, 0, "mp3",NULL);

2.3.2. Play voice command words¶

play_prompt function provides the function of playing adpcm broadcast words from the splash. The use example is as follows:

//0x4000 is the audio address of adpcm broadcast words in flash, 1 is the number of audio played, and NULL is the callback when playing is completed
play_prompt(0x4000,1,NULL);

Prompt

Please use cmd to obtain the address of the broadcast speech audio in flash_The player interface in info is basically used for internal playback.

2.4. Use of External User defined Data Source¶

audio_play_api also provides a set of outside_* interfaces. The purpose of the interface is to create an external data stream. By writing the original audio data to the data stream, the player can play through the player’s decoder.

Interface name	Function description
play_with_outside	Request to play external data
outside_init_stream	To create an external data stream service, you need to pass the data stream descriptor and data end descriptor
outside_destroy_stream	Destroy the data stream
set_curr_outside_handle	Set the data stream descriptor used by the current player
outside_send_end_sem	End signal of sending data
outside_write_stream	Write data to the data stream
outside_clear_stream	Clean up the data stream

In this set of interfaces, the outside_init_stream function can create an external data stream service. By using set_curr_outside_handle to set the data stream used by the current player, data can be written to the stream via the outside_write_stream function. At this point, calling the playback interface will cause the player to automatically retrieve audio data from the stream for decoding and playback. When the data ends, use the outside_send_end_sem function to send a signal, ensuring that the playback end callback function terminates properly after all data has finished playing. When using the external data stream method, player interfaces such as start, pause, and querying progress can also be utilized. As shown in the figure:

Start the playback process:

Figure 2-1 Start the playback process

Users actively pause/stop playing:

Figure 2-2 User Actively Pauses/Stops Playback

The user actively continues to play:

Figure 2-3 Users actively continue playing

The end of user audio data sends the end of data signal to stop:

Figure 2-4 End of user audio data, send data end signal and stop

Note

The data management of this group of interfaces requires users to manage themselves, and the player will not be responsible for the data progress information.