Playlist¶

A playlist is a list of audio files that can be played back either sequentially or in a specified order.

The sdcard_scan() function in the playlist/include/sdcard_scan.h scans the audio files in a microSD card and generate a playlist of files. You can specify file depth and filter out file types when scanning. The playlist instances can be saved to a variety of storage media. The following are the supported storage media:

Saving to MicroSD Card
Saving to DRAM
Saving to NVS Partition in Flash
Saving to DATA_UNDEFINED Partition in Flash

After scanning the audio files, you can use the playlist_operator_handle_t handle to call the corresponding functions to create, save, print playlists, and obtain the path corresponding to the audio ID. Currently, most of the storage media mentioned in this document support the above functions.

See the description below for the API details.

Scanning MicroSD Card¶

The sdcard_scan() function can scan audio files in a specified path and generate playlists. It supports the scanning of files at a specified depth and filtering of file types. Then, the playlist can be saved to the specified storage medium using a callback function.

Application Example¶

Header File¶

playlist/include/sdcard_scan.h

Functions¶

esp_err_t sdcard_scan(sdcard_scan_cb_t cb, const char *path, int depth, const char *file_extension[], int filter_num, void *user_data)¶

Scan files in SD card and use callback function to save files that meet filtering conditions.

Note

example sdcard_scan(callback, “/sdcard”, 5, const char *[]{“mp3”, “aac”}, 2, user_data); Scan 5 levels folder in sdcard and save mp3 files and aac files.

Return

ESP_OK success
ESP_FAIL failed

Parameters

cb: The callback function
path: The path to be scanned
depth: The depth of file scanning // .e.g. if you only want to save files in “/test” , depth = 0. // if you want to save files in “/test/scan_test/”, depth = 1
file_extension: File extension of files that are supposed to be saved // .e.g. const char *[]{“mp3”, “aac”}
filter_num: Number of filters
user_data: The data to be used by callback function

Type Definitions¶

typedef void (*sdcard_scan_cb_t)(void *user_data, char *url)¶

Saving Playlist¶

Saving to MicroSD Card¶

The playlist can be stored in the microSD card. Functions, such as those to save and display the playlist, can be called through the playlist_operator_handle_t handle.

Application Example¶

Header File¶

playlist/include/sdcard_list.h

Functions¶

esp_err_t sdcard_list_create(playlist_operator_handle_t *handle)¶

Create a playlist in sdcard by list id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

[out] handle: The playlist handle from application layer

esp_err_t sdcard_list_show(playlist_operator_handle_t handle)¶

Show all the URLs in sdcard playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t sdcard_list_next(playlist_operator_handle_t handle, int step, char **url_buff)¶

The following URLs in sdcard playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: The offset of URL from current URL
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t sdcard_list_prev(playlist_operator_handle_t handle, int step, char **url_buff)¶

The previous URLs in sdcard playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: The offset of URL from current URL
[out] url_buff: A second rank pointer to get a address of URL

bool sdcard_list_exist(playlist_operator_handle_t handle, const char *url)¶

Judge whether the url exists in sdcard playlist.

Return

true existence
false Non-existent

Parameters

handle: Playlist handle
url: The url to be checked

esp_err_t sdcard_list_reset(playlist_operator_handle_t handle)¶

Reset sdcard playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t sdcard_list_current(playlist_operator_handle_t handle, char **url_buff)¶

Get current URL in sdcard playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t sdcard_list_choose(playlist_operator_handle_t handle, int url_id, char **url_buff)¶

Choose a url by url id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url_id: The id of url in sdcard list
[out] url_buff: A second rank pointer to get a address of URL

int sdcard_list_get_url_num(playlist_operator_handle_t handle)¶

Get URLs number in sdcard playlist.

Return

URLs number in sdcard playlist
ESP_FAIL Fail to get number of urls

Parameters

handle: Playlist handle

int sdcard_list_get_url_id(playlist_operator_handle_t handle)¶

Get current url id in the sdcard playlist.

Return

Current url id in partition playlist
ESP_FAIL Fail to get url id

Parameters

handle: Playlist handle

esp_err_t sdcard_list_destroy(playlist_operator_handle_t handle)¶

Destroy sdcard playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t sdcard_list_save(playlist_operator_handle_t handle, const char *url)¶

Save URL to sdcard playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url: URL to be saved

Saving to DRAM¶

The playlist can be stored in DRAM. Functions, such as those to save and display the playlist, can be called through the playlist_operator_handle_t handle.

Header File¶

playlist/include/dram_list.h

Functions¶

esp_err_t dram_list_create(playlist_operator_handle_t *handle)¶

Create a playlist in dram.

Return

ESP_OK success
ESP_FAIL failed

Parameters

[out] handle: The playlist handle from application layer

esp_err_t dram_list_save(playlist_operator_handle_t handle, const char *url)¶

Save URL to dram playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url: URL to be saved

esp_err_t dram_list_next(playlist_operator_handle_t handle, int step, char **url_buff)¶

The following URLs in dram playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: The offset of URL from current URL
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t dram_list_prev(playlist_operator_handle_t handle, int step, char **url_buff)¶

The previous URLs in dram playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: The offset of URL from current URL
[out] url_buff: A second rank pointer to get a address of URL

bool dram_list_exist(playlist_operator_handle_t handle, const char *url)¶

Judge whether the url exists in dram playlist.

Return

true existence
false Non-existent

Parameters

handle: Playlist handle
url: The url to be checked

esp_err_t dram_list_reset(playlist_operator_handle_t handle)¶

Reset dram playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t dram_list_current(playlist_operator_handle_t handle, char **url_buff)¶

The current URL in current playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t dram_list_choose(playlist_operator_handle_t handle, int url_id, char **url_buff)¶

Choose a url by url id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url_id: The id of url in dram list
[out] url_buff: A second rank pointer to get a address of URL

int dram_list_get_url_num(playlist_operator_handle_t handle)¶

Get URLs number in the dram playlist.

Return

URLs number in dram playlist
ESP_FAIL Fail to get number of urls

Parameters

handle: Playlist handle

int dram_list_get_url_id(playlist_operator_handle_t handle)¶

Get current url id in the dram playlist.

Return

Current url id in dram playlist
ESP_FAIL Fail to get url id

Parameters

handle: Playlist handle

esp_err_t dram_list_show(playlist_operator_handle_t handle)¶

Show all the URLs in the dram playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t dram_list_remove_by_url(playlist_operator_handle_t handle, const char *url)¶

Remove corrsponding url in dram list.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url: The url to be removed

esp_err_t dram_list_remove_by_url_id(playlist_operator_handle_t handle, uint16_t url_id)¶

Remove url by id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url_id: The url id to be removed

esp_err_t dram_list_destroy(playlist_operator_handle_t handle)¶

Destroy the dram playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

Saving to NVS Partition in Flash¶

The playlist can be stored in the NVS partition in flash. Functions, such as those to save and display the playlist, can be called through the playlist_operator_handle_t handle.

Header File¶

playlist/include/flash_list.h

Functions¶

esp_err_t flash_list_create(playlist_operator_handle_t *handle)¶

Create a playlist in nvs flash.

Return

ESP_OK success
ESP_FAIL failed

Parameters

[out] handle: Playlist handle

esp_err_t flash_list_save(playlist_operator_handle_t handle, const char *url)¶

Save URL to nvs flash list.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url: URL to be saved

esp_err_t flash_list_show(playlist_operator_handle_t handle)¶

Show all the URLs in nvs flash list.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t flash_list_next(playlist_operator_handle_t handle, int step, char **url_buff)¶

The following URLs in nvs flash playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: The offset of URL from current URL
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t flash_list_prev(playlist_operator_handle_t handle, int step, char **url_buff)¶

The previous URLs in nvs flash playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: The offset of URL from current URL
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t flash_list_current(playlist_operator_handle_t handle, char **url_buff)¶

The current URL in nvs flash playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
[out] url_buff: A second rank pointer to get a address of URL

bool flash_list_exist(playlist_operator_handle_t handle, const char *url)¶

Judge whether the url exists in flash playlist.

Return

true existence
false Non-existent

Parameters

handle: Playlist handle
url: The url to be checked

esp_err_t flash_list_reset(playlist_operator_handle_t handle)¶

Reset flash playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t flash_list_choose(playlist_operator_handle_t handle, int url_id, char **url_buff)¶

Choose a url by url id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url_id: The id of url in flash list
[out] url_buff: A second rank pointer to get a address of URL

int flash_list_get_url_num(playlist_operator_handle_t handle)¶

Get URLs number in the flash playlist.

Return

URLs number in flash playlist
ESP_FAIL Fail to get number of urls

Parameters

handle: Playlist handle

int flash_list_get_url_id(playlist_operator_handle_t handle)¶

Get current url id in the flash playlist.

Return

Curernt url id in flash playlist
ESP_FAIL Fail to get url id

Parameters

handle: Playlist handle

esp_err_t flash_list_destroy(playlist_operator_handle_t handle)¶

Destroy the nvs flash playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

Saving to `DATA_UNDEFINED` Partition in Flash¶

The playlist can be stored in the DATA_UNDEFINED partition (see Partition Tables for details) in flash. Functions, such as those to save and display the playlist, can be called through the playlist_operator_handle_t handle. Please add the two partitions whose subtypes are 0x06 and 0x07 to the flash partition table first.

Header File¶

playlist/include/partition_list.h

Functions¶

esp_err_t partition_list_create(playlist_operator_handle_t *handle)¶

Create a playlist in flash partition by list id.

Note

Please add 2 partitions to partition table whose subtype are 0x06 and 0x07 first

Return

ESP_OK success
ESP_FAIL failed

Parameters

[out] handle: The playlist handle from application layer

esp_err_t partition_list_save(playlist_operator_handle_t handle, const char *url)¶

Save URL to partition playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url: URL to be saved

esp_err_t partition_list_next(playlist_operator_handle_t handle, int step, char **url_buff)¶

The following URLs in partition playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: The offset of URL from current URL
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t partition_list_prev(playlist_operator_handle_t handle, int step, char **url_buff)¶

The previous URLs in partition playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: The offset of URL from current URL
[out] url_buff: A second rank pointer to get a address of URL

bool partition_list_exist(playlist_operator_handle_t handle, const char *url)¶

Judge whether the url exists in partition playlist.

Return

true existence
false Non-existent

Parameters

handle: Playlist handle
url: The url to be checked

esp_err_t partition_list_reset(playlist_operator_handle_t handle)¶

Reset partition playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t partition_list_current(playlist_operator_handle_t handle, char **url_buff)¶

Get current URL in the partition playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t partition_list_choose(playlist_operator_handle_t handle, int url_id, char **url_buff)¶

Choose a url by url id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url_id: The id of url in partition list
[out] url_buff: A second rank pointer to get a address of URL

int partition_list_get_url_num(playlist_operator_handle_t handle)¶

Get URLs number in the partition playlist.

Return

URLs number in partition playlist
ESP_FAIL Fail to get number of urls

Parameters

handle: Playlist handle

int partition_list_get_url_id(playlist_operator_handle_t handle)¶

Get curernt url id in the partition playlist.

Return

Current url id in partition playlist
ESP_FAIL Fail to get url id

Parameters

handle: Playlist handle

esp_err_t partition_list_show(playlist_operator_handle_t handle)¶

Show all the URLs in the partition playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t partition_list_destroy(playlist_operator_handle_t handle)¶

Destroy the partition playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

Playlist Manager¶

Playlist Manager manages the above playlists and can add multiple playlist instances to the playlist_handle_t handle.

Header File¶

playlist/include/playlist.h

Functions¶

playlist_handle_t playlist_create(void)¶

Create a playlist manager handle.

Return

playlist handle success
NULL failed

esp_err_t playlist_add(playlist_handle_t handle, playlist_operator_handle_t list_handle, uint8_t list_id)¶

Create a playlist manager and add playlist handle to it.

Note

The partition playlist can only be added once, or it will be overwrited by the newest partiiton playlist

Note

Different lists must use different IDs, because even if they are in different handles, list_id is the only indicator that distinguishes them.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist manager handle
list_handle: The playlist handle to be added
list_id: The playlist id to be registered

esp_err_t playlist_checkout_by_id(playlist_handle_t handle, uint8_t id)¶

Playlist checkout by list id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
id: Specified list id

int playlist_get_list_num(playlist_handle_t handle)¶

Get number of playlists in the handle.

Return

success Number of playlists in handle
failed -1

Parameters

handle: Playlist handle

playlist_type_t playlist_get_current_list_type(playlist_handle_t handle)¶

Get current playlist type.

Return

success Type of current playlist
failed -1

Parameters

handle: Playlist handle

int playlist_get_current_list_id(playlist_handle_t handle)¶

Get current playlist id.

Return

success Current playlist id
failed -1

Parameters

handle: Playlist handle

esp_err_t playlist_get_current_list_url(playlist_handle_t handle, char **url_buff)¶

Get current URL in current playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
[out] url_buff: A second rank pointer to get a address of URL

int playlist_get_current_list_url_num(playlist_handle_t handle)¶

Get number of URLs in current playlist.

Return

Number of URLS in current playlsit

Parameters

handle: Playlist handle

int playlist_get_current_list_url_id(playlist_handle_t handle)¶

Get current url id in current playlist.

Return

Current url’s id in current playlsit

Parameters

handle: Playlist handle

esp_err_t playlist_save(playlist_handle_t handle, const char *url)¶

Save a URL to the current playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url: The URL to be saved ot sdcard

esp_err_t playlist_next(playlist_handle_t handle, int step, char **url_buff)¶

Next URl in current playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: Next steps from current position
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t playlist_prev(playlist_handle_t handle, int step, char **url_buff)¶

Previous URL in current playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
step: Previous steps from current position
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t playlist_choose(playlist_handle_t handle, int url_id, char **url_buff)¶

Choose a url by url id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url_id: The id of url in current list
[out] url_buff: A second rank pointer to get a address of URL

esp_err_t playlist_show(playlist_handle_t handle)¶

Show URLs in current playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t playlist_reset(playlist_handle_t handle)¶

Reset current playlist.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

esp_err_t playlist_remove_by_url(playlist_handle_t handle, const char *url)¶

Remove corresponding url.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url: The url to be removed

esp_err_t playlist_remove_by_url_id(playlist_handle_t handle, uint16_t url_id)¶

Remove url by url id.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle
url_id: The id of url to be removed

bool playlist_exist(playlist_handle_t handle, const char *url)¶

Judge whether the url exists in current playlist.

Return

true existence
false Non-existent

Parameters

handle: Playlist handle
url: The url to be checked

esp_err_t playlist_destroy(playlist_handle_t handle)¶

Destroy all playlists in the handle.

Return

ESP_OK success
ESP_FAIL failed

Parameters

handle: Playlist handle

Structures¶

struct playlist_operation_t¶

All types of Playlists’ operation.

Public Members

esp_err_t (*show)(void *playlist)¶: Show all the URLs in playlist

esp_err_t (*save)(void *playlist, const char *url)¶: Save URLs to playlist

esp_err_t (*next)(void *playlist, int step, char **url_buff)¶: Get next URL in playlist

esp_err_t (*prev)(void *playlist, int step, char **url_buff)¶: Get previous URL in playlist

esp_err_t (*reset)(void *playlist)¶: Reset the playlist

esp_err_t (*choose)(void *playlist, int url_id, char **url_buff)¶: Get url by url id

esp_err_t (*current)(void *playlist, char **url_buff)¶: Get current URL in playlist

esp_err_t (*destroy)(void *playlist)¶: Destroy playlist

bool (*exist)(void *playlist, const char *url)¶: Judge whether the url exists

int (*get_url_num)(void *playlist)¶: Get number of URLS in current playlist

int (*get_url_id)(void *playlist)¶: Get current url id in playlist

playlist_type_t type¶: Type of playlist

esp_err_t (*remove_by_url)(void *playlist, const char *url)¶: Remove the corresponding url

esp_err_t (*remove_by_id)(void *playlist, uint16_t url_id)¶: Remove url by id

struct playlist_operator_t¶

Information of playlist manager node.

Public Members

void *playlist¶: Specific playlist’s pointer

esp_err_t (*get_operation)(playlist_operation_t *operation)¶: Function pointer to get playlists’ handle

Type Definitions¶

typedef playlist_operator_t *playlist_operator_handle_t¶

typedef struct playlist_handle *playlist_handle_t¶

Enumerations¶

enum playlist_type_t¶

Type of playlist.

Values:

PLAYLIST_UNKNOWN = -1¶: Unknown type

PLAYLIST_SDCARD¶: Playlist in sdcard

PLAYLIST_FLASH¶: Playlist in nvs

PLAYLIST_DRAM¶: Playlist in ram

PLAYLIST_PARTITION¶: Playlist in partition

Provide feedback about this document

Playlist¶

Scanning MicroSD Card¶

Application Example¶

Header File¶

Functions¶

Type Definitions¶

Saving Playlist¶

Saving to MicroSD Card¶

Application Example¶

Header File¶

Functions¶

Saving to DRAM¶

Header File¶

Functions¶

Saving to NVS Partition in Flash¶

Header File¶

Functions¶

Saving to DATA_UNDEFINED Partition in Flash¶

Header File¶

Functions¶

Playlist Manager¶

Header File¶

Functions¶

Structures¶

Type Definitions¶

Enumerations¶

Saving to `DATA_UNDEFINED` Partition in Flash¶