CYD_MP3Player_LVGL

CYD MP3 Music Player

1. Feature

• GUI by LVGL
• Internal DAC and onboard amplifier can directly drive a speaker connected to CYD
• Can manage approximately 3,000 music files ¹
• Can display the cover photo for each album
• "Playlist" to display music titles, artist names, and album names
• "Album List" to manage the albums you want to play
• Heart-shaped "Favorites" button to play only selected files
• Power saving mode to turn off the LCD after a set time, and a sleep timer to shut down the device

2. Screens

Screen transition

• Screen: Main
  Controls the playback of audio files included in the playlist.

• Screen: Playlist
  A list of audio file titles, artists, and album names.

• Screen: Album List
  Manages a list of albums that contain music files recorded on a single CD. Albums with a check mark will be included in the playlist.

  In addition to the default list "All", you can create some new lists.

• Screen: Setting
  The number of music files that can be included in a playlist is limited to approximately 600+α (α ≦ 25).

  By creating and switching between several subfolders (called "Partition" in this application) on the SD card, you can manage a total of over 3000 files.

  You can also set the time until the backlight turns off and the sleep timer.

3. Software Requirements

3.1. Arduino IDE

Name	Version
Arduino IDE	2.3.4 and up

3.2. Platform board package

Name	Version
esp32 by Espressif Systems	2.0.17 2

Select ESP32 Dev Module as a board.

3.3. Libraries

Name	Version
LVGL by kisvegabor	9.2.2 and up
LovyanGFX by lovyan03	1.2.7
SdFat by Bill Greiman	2.3.0
ArduinoJson by Benoit Blanchon	7.4.2

3.4. Library configuration

• LVGL
  After installing LVGL, configure lv_conf.h by referring to the official document "Configure LVGL". Some samples of lv_conf.h for this application are provided in the assets/lv_conf/. For details, see assets/lv_conf/README.md.

• SdFat
  To handle long filenames and multibyte characters, uncomment the definition of the symbol USE_UTF8_LONG_NAMES in libraries/SdFat/src/SdFatConfig.h under your sketchbook folder.

3.5. Custom Fonts

In addition to LVGL's fonts, this application embeds several national alphabets and symbols of 12px and 14px, as well as Japanese Kanji Level 1 and Level 2.

To create custom fonts, refer to assets/fonts/README.md and use LVGL Font Converter to create/download the font data, save them to src/, and modify ui.h.

4. Edit and Compile / Upload

4.1. Edit config.h

Open config.h in the Arduino IDE and follow the comments to modify the default settings as desired.

4.2. Compile / Upload

Set the following two items from the "Tools" menu in the Arduino IDE.

Item	Selection
Partition Scheme	"Huge App (3MB No OTA/1MB SPIFFS)"
Upload Speed	"460800" (Mac), "921600" (Win)

5. How To Use

This application is designed to take albums ripped from CDs and save them directly to your SD card. In addition to .mp3, the .m4a and .wav audio file formats are supported.

Note for Mac users: If a large number of dot files are created on the SD card, it will take a long time to search for audio files. In order to avoid this, use the Terminal app to navigate to the directory containing the audio files (e.g. NO NAME/MP3/) and execute the following command to delete them.

% cd /Volumes/NO\ NAME/MP3/
% find . -name ".???*" -print -exec /bin/rm -rf {} \;

5.1. About "Partition"

Due to the SRAM capacity of MCU, if you plan to store a large number of albums, it is recommended that you create subfolders (up to 5) and limit the number of albums to arround 50 titles and the number of music files to arround 600+α, in each subfolder.

In this application, such subfolder is named as "Partition" and can be selected in the "Setting" screen.

5.2. Shuffle Mode

"Shuffle" works as bellow:

• (1) continues to randomly select and add albums to the playlist until the total number of music files exceeds 600+α
• (2) and finally randomly sorts the playlist again.

However, due to the "600+α" limitation for music files, when "Shuffle" is OFF, the behavior will differ depending on whether you select an individual partition or "All".

When you select an individual partition, albums will be added to the playlist in ascending order, but when you select "All", only (1) will be performed.

5.3. Album List

Pressing the "Keyboard" button under the dropdown will create an empty list, so enter a list name, close the keyboard, select the album you want to add, and finally press the "Save" button.

The "Keyboard" button is also used to edit an existing list.

5.4. Album Cover Photo

The "Main Screen" displays one of the 10 default images randomly. Besides the default image, you can put an album cover photo named @photo.jpg to your album folder.

Due to memory capacity limitations of the MCU, this @photo.jpg must be 96x96 and its size must be 6KB or less.

To generate the @photo.jpg image, use something like GIMP and it's good to set the compression rate to around 50-75%.

5.5. Backlight / Sleep Timer

The "Backlight" setting not only turns off the LCD illumination but also stops the clock to the LCD, reducing power consumption by approximately 40%.

The "Sleep Timer" will put the MCU into deep sleep mode after the set time has elapsed. To recover from this state, press the reset button or cycle the power.

5.6. Auto Saving

Some UI-related parameters (e.g. "Shuffle", "Favorite", "Partition", etc.) are automatically saved to the SD card between songs or when you pause playback, and are restored when you power cycle the device.

6. Known Issues

• The Arduino IDE may freeze or reset during compilation with ESP32 core 2.0.17 (probably due to the issue IDE Crash on Failed Compile #2691).

  • In case it freezes, try killing all IDE-related processes and restarting the IDE.
  • In case it resets, try quitting and restarting the IDE.

  You can kill all the IDE related processes by the following command in the Terminal APP on Mac.

  ps -axc｜grep -i arduino｜awk '{print $1}'｜xargs -I@ kill -9 @

• Due to the exception handling for the new operator differs between the C++ Standard Template Library (STL) and SdFat, the following warning will be out during compilation, but this is not a problem for practical use.

  /Users/xxxx/Documents/Arduino/libraries/SdFat/src/FsLib/FsNew.h:44:48: warning: optimization attribute on 'void* operator new(size_t, newalign_t*)' follows definition but the attribute doesn't match [-Wattributes]
  void* operator new(size_t size, newalign_t* ptr);
                                                  ^
  /Users/xxxx/Library/Arduino15/packages/esp32/tools/xtensa-esp32-elf-gcc/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/include/c++/8.4.0/new:168:14: note: previous definition of 'void* operator new(std::size_t, void*)' was here
  inline void* operator new(std::size_t, void* __p) _GLIBCXX_USE_NOEXCEPT
               ^~~~~~~~

• When using the built-in DAC and amplifier, there will be a "click" sound when powering up and when pausing/resume playback.

• The UI screen is designed for a 240x320 resolution only and is not responsive.

• It has been observed that @photo.jpg does not display depending on the tool that generates/compresses JPEG images. If the album cover photo is not displayed, please recreate it using GIMP or similar.

• The elapsed playing time is an estimate by the I2S audio library and may differ from the actual playing time. Please consider it as just a UI effect.

• "Bluetooth" icon at the top left on "Main" screen is not supported yet 😅

7. Credits

Thanks to the ESP32 I2S audio library in hexeguitar/ESP32_TFT_PIO (MIT license). This application includes a customized version of the CYD_Audio library.

Also thanks to the high quality photos under the license by Unsplash.

• Annie Spratt
• Kailun Zhang
• David Becker
• Doncoombez
• Dzo
• Esra Afşar
• Grigorii Shcheglov
• Pranav Nav
• Rohit Choudhari
• Vincent Tint

8. Have Fun!

If you find any issues or have suggestions, please report in Issues or Discussions 🥰

---

Footnotes

1. Estimated number of audio files that can be stored on a 32GB microSD card. ↩

2. In version 3.x, the I2S driver for the internal DAC is deprecated and does not work properly. ↩