NOTES on the Cheap Yellow Display Bluetooth MP3 Music Player -- VERSION 2.X

!!! PLEASE READ THIS ALL THE WAY THROUGH !!!

The only hardware required is a Cheap, Yellow Diplay Module (ESP32-2432S028) and an SD card
to hold the MP3 music files.

NOTE: make sure you power your CYD with a USB power module that can put out at least 2.5 AMPs or you may face dropouts when listening to your music.

Features of this program include:
=================================

1. Playback of MP3 audio files stored on the SD card. ONLY MP3 FILES ARE SUPPORTED!
2. Bluetooth connectivity
3. Touch screen control
4. Provides an FTP server allowing files to be uploaded/downloaded to/from the SD
   card using an FTP client like Filezilla
5. Sequential, random and shuffle song playing modes of operation
6. While playing songs, the display will turns off. The display will turn back
   on when a new song starts playing or when the screen is touched.
   Note, the resistive touch screen is not very responsive at times
   so you may have to touch a button multiple times.

Required Libraries
==================

Music player version 2.X requires multiple libraries to be installed:

  First off three libraries written by Phil Schatzmann are needed

  They are:
    1. ESP32-A2DP
    2. arduino-audio-tools
    3. arduino-libhelix

  Please use the ones in the Resources directory otherwise problem can occur.

libhelix Note
=============

## Parameters

The decoder needs to allocate a buffer to store a frame and the decoded data. The following default values have been defined in ConfigHelix.h: 

```
#define MP3_MAX_OUTPUT_SIZE 1024 * 5
#define MP3_MAX_FRAME_SIZE 1024 * 2 
#define AAC_MAX_OUTPUT_SIZE 1024 * 8 
#define AAC_MAX_FRAME_SIZE 2100 
```

These values are working with standard bitrates, but in some exceptional cases (with extreme (220kbs) or insane (320kbs) bitrates) you might need to increase these values e.g. to
```
#define MP3_MAX_OUTPUT_SIZE 1024 * 10
#define MP3_MAX_FRAME_SIZE 3200
```

Alternatively you can set the values in your sketch by calling the following methods:
```
setMaxPCMSize(int size)
setMaxFrameSize(int size)
```

In addition, these libraries which are downloaded and installed within the Arduino IDE:
    1. MultiButton - Martin Poelstra V: 1.3.0
    2. SdFat - Bill Greiman V: 2.3.0
 
Arduino IDE 2.3.5 Configuration
===============================

From the IDE's Tools menu, select:
    Board: ESP32 Dev Module
    Partition Scheme: Huge APP
    Upload Speed: 460800


SD card layout
==============

This program expects the MP3 music files stored on the SD card to have a specific arrangement.
At the root level of the SD card should be a directory for each of the artists. Under the artists directory is a subdirectory for each of the artist's Albums/CDs. A subdirectory under the Albums/CD directory contains the songs on the artist's Album/CD.

/Artist1
  /Album/CD1
    /Songs

  /Album/CD2
    /Songs
     
/Artist2
  /Album/CD1
    /Songs

  /Album/CD2
    /Songs
.
.
.

/ArtistN
  /Album/CD1
    /Songs

  /Album/CD2
    /Songs

Though I don't know what the limits are, this music player can support a lot of artists, albums and songs. I've used this software with my 500 CD music collection without issue. Famous last words (;>)


To configure this program for operation you need to edit the Secrets.h file with your credentials before you compile and upload the program to your CYD. See the file for details.

Operation
=========

At power up you will be shown a welcome screen showing the program name and version. After that, you will be presented with the Operations screen with the following options:
Bluetooth, Sequential Play, Random Play, Shuffle and Remote Access.

The on screen buttons include "-", "Back", "+" and "Sel". Use the - and + buttons to move between on screen selections. Touch Sel to select the highlighted operation. Screens nest as you navagate through the artist, albums/CD and song selections. Use the Back button to move back out the screen hierarchy.  

First select Bluetooth to pair with your playback device. The music player will pair with the Bluetooth device with the strongest signal (probably the closest device). After pairing you will be brought back to the Operations screen.

Select Sequential Play if you want to play the songs in a song directory one after another in order. Select Random Play if you want the program to skip around in a song directory. After mode selection you will be presented with a list of Artists. Once you select an artist you will be presented with a list of the albums/CD for the artist. After selecting the album/CD, you will see the songs on the artist's album/CD you selected. Once you select a song it will start playing.

Selecting Shuffle from the Operation screen will randomly pick songs from the collection of artists, albums/CDs and song that are available on the device.

Select Remote Access in preparation for using FTP to update the content of the SD card. Shortly after Remote Access selection (assuming you have configured your credentials correctly) you will be shown the IP address on the network for connection by an FTP client. If you run Filezilla, select Site Manager from the File menu and specify the IP address and FTP username and password specified in the Secrets.h file. If all is well you will see the contents of the SD card and you can add or delete artists, albums/CDs and/or songs. Clicking any button on the screen after the the FTP opeations are completed will cause the music player to reboot. This is intentional. 

Once a song is playing you can touch the Sel button to configure aspects of song playback. From this screen you can change the volume up and down and can configure looping which will play the selected song over and over until you turn looping off. The Sel button returns you to normal song playback.

Have fun with your new music player.

