播放列表

[English]

播放列表是可以按顺序或按指定顺序播放的音频文件列表。

playlist/include/sdcard_scan.h 中的 sdcard_scan() 函数可扫描 microSD 卡中的音频文件,并且生成播放列表。支持指定文件深度扫描和过滤文件类型,播放列表实例可以存放于多种存储介质,以下为支持的存储介质:

扫描音频文件后,可使用 playlist_operator_handle_t 句柄调用对应的函数来实现创建、保存、打印播放列表以及获取音频序号对应的路径等功能。目前,本文中提到的大多数存储介质支持上述功能。

有关 API 的详细信息,请参阅下文。

扫描 microSD 卡

sdcard_scan() 函数可扫描指定路径下的音频文件并生成播放列表,支持指定文件深度扫描和过滤文件类型。然后,可利用回调函数将播放列表保存到指定的存储介质。

应用示例

Header File

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.

备注

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.

参数
  • 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

返回

  • ESP_OK success

  • ESP_FAIL failed

Type Definitions

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

存储播放列表

存储至 microSD 卡

播放列表可存储至 microSD 卡中,并通过 playlist_operator_handle_t 句柄调用相应函数来实现保存、显示播放列表等功能。

应用示例

Header File

Functions

esp_err_t sdcard_list_create(playlist_operator_handle_t *handle)

Create a playlist in sdcard by list id.

参数

handle[out] The playlist handle from application layer

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t sdcard_list_show(playlist_operator_handle_t handle)

Show all the URLs in sdcard playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

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

The following URLs in sdcard playlist.

参数
  • handle – Playlist handle

  • step – The offset of URL from current URL

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

The previous URLs in sdcard playlist.

参数
  • handle – Playlist handle

  • step – The offset of URL from current URL

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

bool sdcard_list_exist(playlist_operator_handle_t handle, const char *url)

Judge whether the url exists in sdcard playlist.

参数
  • handle – Playlist handle

  • url – The url to be checked

返回

  • true existence

  • false Non-existent

esp_err_t sdcard_list_reset(playlist_operator_handle_t handle)

Reset sdcard playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t sdcard_list_current(playlist_operator_handle_t handle, char **url_buff)

Get current URL in sdcard playlist.

参数
  • handle – Playlist handle

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

Choose a url by url id.

参数
  • handle – Playlist handle

  • url_id – The id of url in sdcard list

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

int sdcard_list_get_url_num(playlist_operator_handle_t handle)

Get URLs number in sdcard playlist.

参数

handle – Playlist handle

返回

  • URLs number in sdcard playlist

  • ESP_FAIL Fail to get number of urls

int sdcard_list_get_url_id(playlist_operator_handle_t handle)

Get current url id in the sdcard playlist.

参数

handle – Playlist handle

返回

  • Current url id in partition playlist

  • ESP_FAIL Fail to get url id

esp_err_t sdcard_list_destroy(playlist_operator_handle_t handle)

Destroy sdcard playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t sdcard_list_save(playlist_operator_handle_t handle, const char *url)

Save URL to sdcard playlist.

参数
  • handle – Playlist handle

  • url – URL to be saved

返回

  • ESP_OK success

  • ESP_FAIL failed

存储至 DRAM

播放列表可存储至 DRAM 中,并通过 playlist_operator_handle_t 句柄调用相应函数来实现保存、显示播放列表等功能。

Header File

Functions

esp_err_t dram_list_create(playlist_operator_handle_t *handle)

Create a playlist in dram.

参数

handle[out] The playlist handle from application layer

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t dram_list_save(playlist_operator_handle_t handle, const char *url)

Save URL to dram playlist.

参数
  • handle – Playlist handle

  • url – URL to be saved

返回

  • ESP_OK success

  • ESP_FAIL failed

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

The following URLs in dram playlist.

参数
  • handle – Playlist handle

  • step – The offset of URL from current URL

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

The previous URLs in dram playlist.

参数
  • handle – Playlist handle

  • step – The offset of URL from current URL

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

bool dram_list_exist(playlist_operator_handle_t handle, const char *url)

Judge whether the url exists in dram playlist.

参数
  • handle – Playlist handle

  • url – The url to be checked

返回

  • true existence

  • false Non-existent

esp_err_t dram_list_reset(playlist_operator_handle_t handle)

Reset dram playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t dram_list_current(playlist_operator_handle_t handle, char **url_buff)

The current URL in current playlist.

参数
  • handle – Playlist handle

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

Choose a url by url id.

参数
  • handle – Playlist handle

  • url_id – The id of url in dram list

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

int dram_list_get_url_num(playlist_operator_handle_t handle)

Get URLs number in the dram playlist.

参数

handle – Playlist handle

返回

  • URLs number in dram playlist

  • ESP_FAIL Fail to get number of urls

int dram_list_get_url_id(playlist_operator_handle_t handle)

Get current url id in the dram playlist.

参数

handle – Playlist handle

返回

  • Current url id in dram playlist

  • ESP_FAIL Fail to get url id

esp_err_t dram_list_show(playlist_operator_handle_t handle)

Show all the URLs in the dram playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t dram_list_remove_by_url(playlist_operator_handle_t handle, const char *url)

Remove corrsponding url in dram list.

参数
  • handle – Playlist handle

  • url – The url to be removed

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t dram_list_remove_by_url_id(playlist_operator_handle_t handle, uint16_t url_id)

Remove url by id.

参数
  • handle – Playlist handle

  • url_id – The url id to be removed

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t dram_list_destroy(playlist_operator_handle_t handle)

Destroy the dram playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

存储至 flash 的 NVS 分区

播放列表可存储至 flash 的 NVS 分区 中,并通过 playlist_operator_handle_t 句柄调用相应函数来实现保存、显示播放列表等功能。

Header File

Functions

esp_err_t flash_list_create(playlist_operator_handle_t *handle)

Create a playlist in nvs flash.

参数

handle[out] Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t flash_list_save(playlist_operator_handle_t handle, const char *url)

Save URL to nvs flash list.

参数
  • handle – Playlist handle

  • url – URL to be saved

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t flash_list_show(playlist_operator_handle_t handle)

Show all the URLs in nvs flash list.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

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

The following URLs in nvs flash playlist.

参数
  • handle – Playlist handle

  • step – The offset of URL from current URL

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

The previous URLs in nvs flash playlist.

参数
  • handle – Playlist handle

  • step – The offset of URL from current URL

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t flash_list_current(playlist_operator_handle_t handle, char **url_buff)

The current URL in nvs flash playlist.

参数
  • handle – Playlist handle

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

bool flash_list_exist(playlist_operator_handle_t handle, const char *url)

Judge whether the url exists in flash playlist.

参数
  • handle – Playlist handle

  • url – The url to be checked

返回

  • true existence

  • false Non-existent

esp_err_t flash_list_reset(playlist_operator_handle_t handle)

Reset flash playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

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

Choose a url by url id.

参数
  • handle – Playlist handle

  • url_id – The id of url in flash list

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

int flash_list_get_url_num(playlist_operator_handle_t handle)

Get URLs number in the flash playlist.

参数

handle – Playlist handle

返回

  • URLs number in flash playlist

  • ESP_FAIL Fail to get number of urls

int flash_list_get_url_id(playlist_operator_handle_t handle)

Get current url id in the flash playlist.

参数

handle – Playlist handle

返回

  • Curernt url id in flash playlist

  • ESP_FAIL Fail to get url id

esp_err_t flash_list_destroy(playlist_operator_handle_t handle)

Destroy the nvs flash playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

存储至 flash 的 DATA_UNDEFINED 分区

播放列表可存储至 flash 的 DATA_UNDEFINED 分区中(详情请参考 分区表),并通过 playlist_operator_handle_t 句柄调用相应函数来实现保存、显示播放列表等功能。需要先将子类型为 0x06 和 0x07 的 2 个分区添加到 flash 的分区表中。

Header File

Functions

esp_err_t partition_list_create(playlist_operator_handle_t *handle)

Create a playlist in flash partition by list id.

备注

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

参数

handle[out] The playlist handle from application layer

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t partition_list_save(playlist_operator_handle_t handle, const char *url)

Save URL to partition playlist.

参数
  • handle – Playlist handle

  • url – URL to be saved

返回

  • ESP_OK success

  • ESP_FAIL failed

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

The following URLs in partition playlist.

参数
  • handle – Playlist handle

  • step – The offset of URL from current URL

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

The previous URLs in partition playlist.

参数
  • handle – Playlist handle

  • step – The offset of URL from current URL

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

bool partition_list_exist(playlist_operator_handle_t handle, const char *url)

Judge whether the url exists in partition playlist.

参数
  • handle – Playlist handle

  • url – The url to be checked

返回

  • true existence

  • false Non-existent

esp_err_t partition_list_reset(playlist_operator_handle_t handle)

Reset partition playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t partition_list_current(playlist_operator_handle_t handle, char **url_buff)

Get current URL in the partition playlist.

参数
  • handle – Playlist handle

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

Choose a url by url id.

参数
  • handle – Playlist handle

  • url_id – The id of url in partition list

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

int partition_list_get_url_num(playlist_operator_handle_t handle)

Get URLs number in the partition playlist.

参数

handle – Playlist handle

返回

  • URLs number in partition playlist

  • ESP_FAIL Fail to get number of urls

int partition_list_get_url_id(playlist_operator_handle_t handle)

Get curernt url id in the partition playlist.

参数

handle – Playlist handle

返回

  • Current url id in partition playlist

  • ESP_FAIL Fail to get url id

esp_err_t partition_list_show(playlist_operator_handle_t handle)

Show all the URLs in the partition playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t partition_list_destroy(playlist_operator_handle_t handle)

Destroy the partition playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

播放列表管理器

播放列表管理器用于管理上述播放列表,可将多个播放列表实例添加到 playlist_handle_t 句柄。

Header File

Functions

playlist_handle_t playlist_create(void)

Create a playlist manager handle.

返回

  • 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.

备注

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

备注

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

参数
  • handle – Playlist manager handle

  • list_handle – The playlist handle to be added

  • list_id – The playlist id to be registered

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t playlist_checkout_by_id(playlist_handle_t handle, uint8_t id)

Playlist checkout by list id.

参数
  • handle – Playlist handle

  • id – Specified list id

返回

  • ESP_OK success

  • ESP_FAIL failed

int playlist_get_list_num(playlist_handle_t handle)

Get number of playlists in the handle.

参数

handle – Playlist handle

返回

  • success Number of playlists in handle

  • failed -1

playlist_type_t playlist_get_current_list_type(playlist_handle_t handle)

Get current playlist type.

参数

handle – Playlist handle

返回

  • success Type of current playlist

  • failed -1

int playlist_get_current_list_id(playlist_handle_t handle)

Get current playlist id.

参数

handle – Playlist handle

返回

  • success Current playlist id

  • failed -1

esp_err_t playlist_get_current_list_url(playlist_handle_t handle, char **url_buff)

Get current URL in current playlist.

参数
  • handle – Playlist handle

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

int playlist_get_current_list_url_num(playlist_handle_t handle)

Get number of URLs in current playlist.

参数

handle – Playlist handle

返回

Number of URLS in current playlsit

int playlist_get_current_list_url_id(playlist_handle_t handle)

Get current url id in current playlist.

参数

handle – Playlist handle

返回

Current url’s id in current playlsit

esp_err_t playlist_save(playlist_handle_t handle, const char *url)

Save a URL to the current playlist.

参数
  • handle – Playlist handle

  • url – The URL to be saved ot sdcard

返回

  • ESP_OK success

  • ESP_FAIL failed

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

Next URl in current playlist.

参数
  • handle – Playlist handle

  • step – Next steps from current position

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

Previous URL in current playlist.

参数
  • handle – Playlist handle

  • step – Previous steps from current position

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

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

Choose a url by url id.

参数
  • handle – Playlist handle

  • url_id – The id of url in current list

  • url_buff[out] A second rank pointer to get a address of URL

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t playlist_show(playlist_handle_t handle)

Show URLs in current playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t playlist_reset(playlist_handle_t handle)

Reset current playlist.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t playlist_remove_by_url(playlist_handle_t handle, const char *url)

Remove corresponding url.

参数
  • handle – Playlist handle

  • url – The url to be removed

返回

  • ESP_OK success

  • ESP_FAIL failed

esp_err_t playlist_remove_by_url_id(playlist_handle_t handle, uint16_t url_id)

Remove url by url id.

参数
  • handle – Playlist handle

  • url_id – The id of url to be removed

返回

  • ESP_OK success

  • ESP_FAIL failed

bool playlist_exist(playlist_handle_t handle, const char *url)

Judge whether the url exists in current playlist.

参数
  • handle – Playlist handle

  • url – The url to be checked

返回

  • true existence

  • false Non-existent

esp_err_t playlist_destroy(playlist_handle_t handle)

Destroy all playlists in the handle.

参数

handle – Playlist handle

返回

  • ESP_OK success

  • ESP_FAIL failed

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:

enumerator PLAYLIST_UNKNOWN

Unknown type

enumerator PLAYLIST_SDCARD

Playlist in sdcard

enumerator PLAYLIST_FLASH

Playlist in nvs

enumerator PLAYLIST_DRAM

Playlist in ram

enumerator PLAYLIST_PARTITION

Playlist in partition