espressif/adf_examples - 0.2.5 - Example music_player • ESP Component Registry

# SD Card Music Player - [中文版本](./README_CN.md) - Regular Example: ⭐⭐ ## Example Brief This example demonstrates an SD card music player with a touch-screen UI. It scans local music files on a microSD card, shows the player screen, song information, and playback controls on the display, and plays music through the board audio output device. ### Typical Use Cases - Local music player with touch screen - SD card audio scanning and list playback - On-screen player UI synchronized with playback state ### Runtime Flow 1. `esp_board_manager` initializes SD card, audio DAC, LCD, and touch 2. `esp_media_db` scans `/sdcard` for `.mp3`, `.aac`, and `.wav` files (scan depth is 1) 3. `esp_playlist` imports scan results and manages repeat modes (one / all / shuffle) 4. `esp_audio_simple_player` decodes asynchronously; PCM is written directly to the codec with `esp_codec_dev_write()` 5. `esp_lvgl_adapter` runs the LVGL task and shows a dark player page ### File Structure ``` music_player/ ├── assets/ Place font.ttf here to embed it into the assets partition ├── main/ │ ├── app_main.c Application entry │ ├── music_player_config.h Default volume, font path, and related macros │ ├── music_player_board.c/h Board peripheral init │ ├── music_player_display.c/h LVGL adapter and display registration │ ├── music_player_playback.c/h Playlist and simple player control │ ├── music_player_ui.c/h Player UI and touch controls │ └── idf_component.yml ├── partitions.csv ├── sdkconfig.defaults ├── sdkconfig.defaults.esp32p4 ├── sdkconfig.defaults.esp32s3 ├── sdkconfig.defaults.esp32s31 ├── pytest_music_player.py ├── README.md └── README_CN.md ``` ## Environment Setup ### Hardware Requirements - microSD card (FAT filesystem) - Speaker or headphones connected to the board audio output - LCD and touch input devices ### Supported IDF Branch This example supports IDF release/v5.4 (>= v5.4.3) and release/v5.5 (>= v5.5.2). ### Software Requirements - Copy `.mp3`, `.aac`, or `.wav` test files into the `/sdcard` mount point (UTF-8 filenames supported) - To use FreeType for Chinese rendering, place `font.ttf` under `assets/` before build; it is embedded into the Flash assets partition (ensure redistribution is allowed). Without it, the built-in CJK font is used ## Build and Flash ### Build Preparation Make sure ESP-IDF is configured before building this example. If it is already set up, enter the project directory directly. Otherwise, run the following scripts in the ESP-IDF root directory. See the [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/) for the target chip you use. ``` ./install.sh . ./export.sh ``` Quick steps: - Enter the example directory: ``` cd adf_examples/player/music_player ``` This example uses [ESP Board Manager](https://github.com/espressif/esp-board-manager). The [`esp-bmgr-assist`](https://pypi.org/project/esp-bmgr-assist/) helper tool is recommended as the default entry point. - Install the helper in the activated ESP-IDF Python environment (once per environment): ```bash pip install esp-bmgr-assist pip install --upgrade esp-bmgr-assist # run this command when an update is requested ``` - List the currently visible boards: ```bash idf.py bmgr -l ``` Example output: ```text ℹ️ Board Components: espressif/esp_boards: [1] esp32_c3_lyra [2] esp32_lyrat_4_3 [3] esp32_lyrat_mini_1_1 [4] esp32_p4_eye [5] esp32_p4_function_ev_board [6] esp32_s31_function_coreboard_1 [7] esp32_s31_korvo_1 [8] esp32_s3_box_3 [9] esp32_s3_box_lite [10] esp32_s3_korvo_2_3 [11] esp32_s3_lcd_ev_board [12] esp_vocat_1_0 [13] esp_vocat_1_2 ``` The example output above is based on the board list and ordering from `esp_boards` 0.5.2. Different `esp_boards` versions or custom board dependencies may change the list and indexes. Use the actual output of `idf.py bmgr -l` when selecting a board. - Select a board: ```bash idf.py bmgr -b <board_index|board_name> ``` For example, to select `esp32_p4_function_ev_board`: ```bash idf.py bmgr -b 5 # or idf.py bmgr -b esp32_p4_function_ev_board ``` On first invocation of `idf.py bmgr`, the component is downloaded automatically based on the `espressif/esp_board_manager` dependency declared in `main/idf_component.yml`. > [!NOTE] > To switch to a different board supported by `esp_board_manager`, repeat the same steps with the new board name or index. > For a custom board, see [Creating a Board Guide](https://docs.espressif.com/projects/esp-board-manager/en/latest/create-board/index.html). > For more information, see the [ESP Board Manager getting started guide](https://github.com/espressif/esp-board-manager/blob/main/esp_board_manager/README.md). ### Project Configuration Default behavior is defined in `main/music_player_config.h` and `sdkconfig.defaults`; extra menuconfig is usually unnecessary. Common tunables: - `MUSIC_PLAYER_DEFAULT_VOLUME`: default playback volume (currently 70) - `MUSIC_PLAYER_FONT_PATH` / `MUSIC_PLAYER_FONT_SIZE`: FreeType font path and size (default `F:font.ttf`, 28) - `MUSIC_PLAYER_SCAN_DEPTH`: media DB scan depth (currently 1, scanning `/sdcard`) For FreeType, built-in CJK font, and other LVGL options, use `idf.py menuconfig` under `Component config` → `ESP LVGL Adapter` and `LVGL configuration`. ### Build and Flash - Build the example ``` idf.py build ``` - Flash and monitor (replace PORT with your serial port): ``` idf.py -p PORT flash monitor ``` - Press `Ctrl-]` to exit the monitor ## How to Use the Example ### Features and Usage 1. Copy music files into the `/sdcard` mount point or one of its first-level subdirectories (see `scan dir: /sdcard` in the log below) 2. After boot, the example scans the folder; if tracks are found it plays the first one, otherwise the UI shows no music available 3. Use the bottom touch control bar: - Playlist / previous / play or pause / next / volume − / volume + / loop mode - Loop mode button cycles one-track repeat, list repeat, and shuffle 4. The top area shows the current song title (ellipsis mode, Chinese supported), repeat mode, and volume 5. The progress bar and time labels show playback progress 6. When the current track finishes, the next track starts automatically according to the selected mode ### Log Output The following is a continuous on-target log from ESP32-P4 Function EV, including step logs `[ 1 ]` through `[ 5 ]`, `Scanned N tracks`, and `Play file:` lines. LCD, touch, and codec initialization logs vary with the selected board configuration. ```text I (1229) main_task: Calling app_main() I (1229) MUSIC_PLAYER: [ 1 ] Initialize board peripherals I (1229) PERIPH_LDO: LDO initialize success W (1229) ldo: The voltage value 0 is out of the recommended range [500, 2700] I (1229) DEV_FS_FAT_SUB_SDMMC: slot_config: cd=-1, wp=-1, clk=0, cmd=0, d0=0, d1=0, d2=0, d3=0, d4=0, d5=0, d6=0, d7=0, width=4, flags=0x1 Name: SC32G Type: SDHC Speed: 40.00 MHz (limit: 40.00 MHz) Size: 30436MB CSD: ver=2, sector_size=512, capacity=62333952 read_bl_len=9 SSR: bus_width=4 I (1276) DEV_FS_FAT: Filesystem mounted, base path: /sdcard I (1276) BOARD_MANAGER: Device fs_sdcard initialized I (1277) BOARD_DEVICE: Device handle fs_sdcard found, Handle: 0x4ffbb43c TO: 0x4ffbb43c I (1278) PERIPH_I2S: I2S[0] STD, TX, ws: 10, bclk: 12, dout: 9, din: 11 I (1278) PERIPH_I2S: I2S[0] initialize success: 0x4800822c I (1278) DEV_AUDIO_CODEC: DAC is ENABLED I (1278) PERIPH_GPIO: Initialize success, pin: 53, set the default level: 0 I (1279) PERIPH_I2C: I2C master bus initialized successfully I (1284) ES8311: Work in Slave mode I (1287) DEV_AUDIO_CODEC: Successfully initialized codec: audio_dac I (1287) DEV_AUDIO_CODEC: Create esp_codec_dev success, dev:0x4ffbc284, chip:es8311 I (1287) BOARD_MANAGER: Device audio_dac initialized I (1287) BOARD_DEVICE: Device handle audio_dac found, Handle: 0x4ffbb854 TO: 0x4ffbb854 I (1288) I2S_IF: No paired data, current mode: playback I (1288) I2S_IF: STD: TX, data_bit: 16, slot_bit: 16, ws_width: 16, slot_mode: STEREO, slot_mask: 0x3 I (1289) I2S_IF: STD: TX, sample_rate_hz: 48000, mclk_multiple: 256, clk_src: 0 I (1303) Adev_Codec: Open codec device OK I (1303) MUSIC_PLAYER_BOARD: SD card mounted at /sdcard, scan dir: /sdcard I (1304) MUSIC_PLAYER: [ 2 ] Initialize display and LVGL music UI I (1304) DEV_DISPLAY_LCD: Initializing LCD display: display_lcd, chip: ek79007, sub_type: dsi I (1304) DEV_DISPLAY_LCD_SUB_DSI: Initializing DSI LCD display: display_lcd, chip: ek79007 I (1304) BOARD_PERIPH: Reuse periph: ldo_mipi, ref_count=2 I (1306) PERIPH_DSI: MIPI DSI bus initialize success I (1306) ek79007: version: 1.0.4 E (1467) lcd_panel: esp_lcd_panel_swap_xy(50): swap_xy is not supported by this panel W (1467) DEV_DISPLAY_LCD: Failed to swap LCD panel XY: ESP_ERR_NOT_SUPPORTED E (1467) lcd_panel: esp_lcd_panel_disp_on_off(71): disp_on_off is not supported by this panel I (1467) DEV_DISPLAY_LCD: Successfully initialized LCD display: display_lcd (sub_type: dsi), panel: 0x4ffbd65c, io: 0x4ffbd610 I (1468) BOARD_MANAGER: Device display_lcd initialized I (1468) BOARD_PERIPH: Reuse periph: i2c_master, ref_count=2 I (1468) GT911: I2C address initialization procedure skipped - using default GT9xx setup I (1470) GT911: TouchPad_ID:0x39,0x31,0x31 I (1470) GT911: TouchPad_Config_Version:89 I (1470) DEV_LCD_TOUCH_SUB_I2C: Successfully initialized LCD touch: lcd_touch, addr: 0xba, touch:0x48134cd4, io:0x4ffbdab8 I (1470) DEV_LCD_TOUCH: Successfully initialized LCD touch: lcd_touch, chip: gt911, sub_type: i2c I (1471) BOARD_MANAGER: Device lcd_touch initialized I (1471) BOARD_DEVICE: Device handle display_lcd found, Handle: 0x4ffbbe14 TO: 0x4ffbbe14 I (1471) BOARD_DEVICE: Device display_lcd config found: 0x40232fe0 (size: 124) I (1471) BOARD_DEVICE: Device handle lcd_touch found, Handle: 0x4ffbda30 TO: 0x4ffbda30 I (1472) esp_lvgl:adapter: LVGL adapter initialized successfully I (1474) esp_lvgl:bridge_v9: Initializing hardware resources I (1474) esp_lvgl:bridge_v9: Hardware resources initialized successfully W (1475) esp_lvgl:touch: LV_USE_GESTURE_RECOGNITION is disabled; only single-point pointer events are available I (1475) esp_lvgl:touch: Touch input device registered successfully (IRQ mode: disabled) I (1476) mmap_assets: MMAP Assets [assets] mounted successfully. (Lib: v2.0.0, Bin: v1.0.0) I (1476) lv_fs: Drive 'F' successfully created, version: 1.0.1 I (1476) esp_lvgl:adapter: File system mounted successfully I (1476) MUSIC_PLAYER_DISPLAY: LVGL assets FS mounted as F: I (1476) MUSIC_PLAYER_DISPLAY: Display initialized: 1024x600 (dsi) I (1536) MUSIC_PLAYER_UI: Use FreeType font: F:font.ttf I (1540) esp_lvgl:adapter: LVGL task started successfully I (1540) MUSIC_PLAYER: [ 3 ] Scan SD card playlist from /sdcard I (1878) MUSIC_PLAYER_PLAYBACK: Scanned 365 tracks under /sdcard I (1890) MUSIC_PLAYER: [ 4 ] Start playback controller I (1891) ASP_POOL: Dest rate:48000 I (1891) ASP_POOL: Dest channels:2 I (1891) ASP_POOL: Dest bits:16 I (1892) MUSIC_PLAYER: [ 5 ] Music player ready I (1892) MUSIC_PLAYER_PLAYBACK: Play file: /sdcard/test_1.mp3 E (1892) ESP_GMF_PIPELINE: esp_gmf_pipeline.c:536 (esp_gmf_pipeline_stop): Got NULL Pointer I (1892) AUD_SIMP_PLAYER: Use the tag of io from pool, in_str:io_file I (1893) ESP_GMF_FILE: Open, dir:1, uri:/sdcard/test_1.mp3 I (1896) ESP_GMF_FILE: File size: 4784128 byte, file position: 0 I (1897) ESP_ES_PARSER: The version of es_parser is v1.0.1 W (1898) ESP_GMF_ASMP_DEC: Not enough memory for out, need:4608, old: 1024, new: 4608 I (7892) : ┌───────────────────┬──────────┬─────────────┬─────────┬──────────┬───────────┬────────────┬───────┐ I (7893) : │ Task │ Core ID │ Run Time │ CPU │ Priority │ Stack HWM │ State │ Stack │ I (7893) : ├───────────────────┼──────────┼─────────────┼─────────┼──────────┼───────────┼────────────┼───────┤ I (7894) : │ lvgl │ 0 │ 408646 │ 20.43% │ 6 │ 4056 │ Suspended │ Extr │ I (7895) : │ IDLE0 │ 0 │ 304097 │ 15.20% │ 0 │ 1228 │ Ready │ Intr │ I (7895) : │ TSK_0x4ff5bd14 │ 0 │ 271071 │ 13.55% │ 10 │ 3840 │ Blocked │ Intr │ I (7896) : │ esp_timer │ 0 │ 15753 │ 0.79% │ 22 │ 3764 │ Suspended │ Intr │ I (7896) : │ main │ 0 │ 460 │ 0.02% │ 1 │ 1428 │ Running │ Intr │ I (7897) : │ ipc0 │ 0 │ 0 │ 0.00% │ 24 │ 708 │ Suspended │ Intr │ I (7897) : ├───────────────────┼──────────┼─────────────┼─────────┼──────────┼───────────┼────────────┼───────┤ I (7898) : │ IDLE1 │ 1 │ 482368 │ 24.12% │ 0 │ 1220 │ Ready │ Intr │ I (7898) : │ ipc1 │ 1 │ 0 │ 0.00% │ 24 │ 716 │ Suspended │ Intr │ I (7908) : │ music_ctrl │ 1 │ 0 │ 0.00% │ 5 │ 3640 │ Blocked │ Intr │ I (7909) : ├───────────────────┼──────────┼─────────────┼─────────┼──────────┼───────────┼────────────┼───────┤ I (7910) : │ swdraw │ 7fffffff │ 518961 │ 25.95% │ 3 │ 14348 │ Ready │ Intr │ I (7910) : │ Tmr Svc │ 7fffffff │ 0 │ 0.00% │ 1 │ 1724 │ Blocked │ Intr │ I (7911) : └───────────────────┴──────────┴─────────────┴─────────┴──────────┴───────────┴────────────┴───────┘ ``` ## Troubleshooting ### Music Files Not Found If scan fails or you see `No music found`, verify that the microSD card is mounted and `/sdcard` contains `.mp3`, `.aac`, or `.wav` files. ### Playback Failure If you see `Failed to run player` or `Failed to open on read`, check file integrity, supported format, and SD card connection. ### Chinese Text Rendering Issues If the assets partition does not contain `font.ttf`, the example falls back to the built-in CJK font. For better Chinese rendering, place `font.ttf` in `assets/` and rebuild before flashing. ## References - [ESP Audio Simple Player](https://components.espressif.com/components/espressif/esp_audio_simple_player) - [ESP Board Manager](https://github.com/espressif/esp-board-manager) - [ESP LVGL Adapter](https://components.espressif.com/components/espressif/esp_lvgl_adapter) ## Technical Support - Forum: [esp32.com](https://esp32.com/viewforum.php?f=20) - Issues: [GitHub issue](https://github.com/espressif/esp-adf/issues) We will get back to you as soon as possible.