Skip to content

API Reference

Jump to bottom Edit New page
Michael Miller edited this page May 19, 2020 · 22 revisions

Constructors

DFMiniMp3<SERIAL_METHOD, NOTIFICATION_METHOD>(T_SERIAL_METHOD& serial)

This will define the object with the given serial method and notification method.

SERIAL_METHOD - the class type of the serial hardware support, usually either HardwareSerial or SoftwareSerial.
NOTIFICATION_METHOD - the class type of the notification handler, you must provide this. Please read Implementing a notification method for more details.

serial - the instance of the serial hardware support that matches the provided SERIAL_METHOD.

Methods

void begin()

This will initialize the DFMiniMp3 and prepare it for use. Call this within the sketches setup().

void loop()

This will service the DFMiniMp3, listening for responses from the hardware. Call this often within the sketches loop().

DfMp3_PlaySources getPlaySources()

This will return the active play sources. This method is not supported with all the generally compatible chips. It will work with the YXS200-24SS chip. It will not work with the MH2024K-24SS chip.
The return value is a bit field value with any of the following possible fields set.
DfMp3_PlaySources_Usb -
DfMp3_PlaySources_Sd -
DfMp3_PlaySources_Pc -
DfMp3_PlaySources_Flash -

void playGlobalTrack(uint16_t track)

This will play the given global track.
track - the global track number. A global track number is the number of the file as enumerated from all folders on the SD card. It has no relationship to the file name. You can use the getTotalTrackCount() to obtain the number of tracks enumerated.

void playMp3FolderTrack(uint16_t track)

This will play the track from within the mp3 folder.
An example filename would be sd:/mp3/0013_ThisIsMyFavoriteSong.mp3, and calling playMp3FolderTrack(13) would play it.
track - the track number as listed in the filename. The filename must start with a four digit, zero padded number and any characters that follow will be ignored.

void playFolderTrack(uint8_t folder, uint8_t track)

This will play the track from within the specific numbered folder.
An example filename would be sd:/02/013_ThisIsMyFavoriteSong.mp3, and calling playFolderTrack(2, 13) would play it.
folder - the folder number as listed in the folder name. The foldername must be a three digit on some chips and two digits on newer chips, zero padded number.
track - the track number as listed in the track filename. The filename must start with a three digit, zero padded number and any characters that follow will be ignored.

void playFolderTrack16(uint8_t folder, uint16_t track)

This will play the track from within the specific numbered folder.
An example filename would be sd:/08/2013_ThisIsMyFavoriteSong.mp3, and calling playFolderTrack16(8, 2013) would play it.
folder - the folder number as listed in the folder name. The foldername must be a two digit, zero padded number.
track - the track number as listed in the track filename. The filename must start with a four digit, zero padded number and any characters that follow will be ignored.

void playRandomTrackFromAll()

This will play a random track from all tracks on the SD card. This will include all tracks from all folders including the advertisement folder.

void nextTrack()

This will cause the current track to stop and the next track to start playing immediately.

void prevTrack()

This will cause the current track to stop and the previous track to start playing immediately.

uint16_t getCurrentTrack(DfMp3_PlaySource source)

This will return the current playing track from the given source. source - One of the following values:
DfMp3_PlaySource_Usb -
DfMp3_PlaySource_Sd - (the default)
DfMp3_PlaySource_Aux -
DfMp3_PlaySource_Sleep -
DfMp3_PlaySource_Flash -

void setVolume(uint8_t volume)

This will set the playback volume.
volume - (0-30) the volume level to set.

uint8_t getVolume()

This will return the current volume.

void increaseVolume()

This will increase the volume by 1.

void decreaseVolume()

This will decrease the volume by 1.

void loopGlobalTrack(uint16_t globalTrack)

This will start playing the given globalTrack and have it loop continuously. When the song finishes, it will restart at the beginning. globalTrack - the global track number. A global track number is the number of the file as enumerated from all folders on the SD card. It has no relationship to the file name. You can use the getTotalTrackCount() to obtain the number of tracks enumerated.

void loopFolder(uint8_t folder)

This will start playing the tracks within the given folder and have it loop continuously playing all songs within the folder.
folder - (0-99) the folder number in the root represented as two digits zero padded.

DfMp3_PlaybackMode getPlaybackMode()

Retrieve the current playback mode.
DfMp3_PlaybackMode_Repeat -
DfMp3_PlaybackMode_FolderRepeat -
DfMp3_PlaybackMode_SingleRepeat -
DfMp3_PlaybackMode_Random -

void setRepeatPlayCurrentTrack(bool repeat)

Set the mode to repeat play any file that is playing. If set, the mp3 will loop continuously. If not set, it will play once and then stop.

void setRepeatPlayAllInRoot(bool repeat)

Set the mode to repeat play all files that are the root of the media. If set, it will loop continuously. If not set, it will play once and then stop.

void setEq(DfMp3_Eq eq)

Set the equalizer mode.
eq One of the equalizer modes.
DfMp3_Eq_Normal -
DfMp3_Eq_Pop -
DfMp3_Eq_Rock -
DfMp3_Eq_Jazz -
DfMp3_Eq_Classic -
DfMp3_Eq_Bass -

DfMp3_Eq getEq()

Get the current equalizer mode.
returns one of these values.
DfMp3_Eq_Normal -
DfMp3_Eq_Pop -
DfMp3_Eq_Rock -
DfMp3_Eq_Jazz -
DfMp3_Eq_Classic -
DfMp3_Eq_Bass -

void setPlaybackSource(DfMp3_PlaySource source)

Sets the playback source. Generally avoid calling this unless you know what you are doing.
source - One of the following values:
DfMp3_PlaySource_Usb -
DfMp3_PlaySource_Sd - the most common value
DfMp3_PlaySource_Aux -
DfMp3_PlaySource_Sleep -
DfMp3_PlaySource_Flash -

void sleep()

Cause the Mp3 module to go into a very low power mode. This is useful for battery operated devices when long periods of no sound will be needed.
Note:
There are two confirmed ways to wake up a module. Try any of the two and see which works best for your particular hardware:

  • Calling reset(), although this is a slow process and may cause click noises in the audio output
  • Calling setPlaybackSource(DfMp3_PlaySource_Sd)

void reset()

Reset the hardware module. Calling this method will make the module not available for about one second and may cause noise in the audio output.

void start()

This will resume playing the current track where it was paused at.

void pause()

This will pause the current playing track.

void stop()

This will stop the current playing track.

uint16_t getStatus()

This will return the current status. The exact meaning of the status isn't well documented.

uint16_t getFolderTrackCount(uint16_t folder)

This will return the count of tracks in the given folder
folder - the folder number to enumerate files within.

uint16_t getTotalTrackCount(DfMp3_PlaySource source)

This will return the count of tracks in all folders, including advertisements.
source - the media source to enumerate. One of the following values.
DfMp3_PlaySource_Usb - through the USB interface if present
DfMp3_PlaySource_Sd - on the SD card, the most common source
DfMp3_PlaySource_Flash - on the flash memory soldered on the board if present

uint16_t getTotalFolderCount()

This will return the count of folders in the root of the media.

void playAdvertisement(uint16_t track)

This will pause the current playing track, then play the given advertisement track, and when the advertisement track is finished, it will resume the original track where it was interrupted.
An example filename would be sd:/advert/0042_BuyHitchHikersGuideFromAmazon.mp3, and calling playAdvertisement(42) would play it.
track - the track number as listed in the filename. The filename must start with a four digit, zero padded number and any characters that follow will be ignored.

void stopAdvertisement()

This will stop the current playing advertisement and resume the original interrupted track.

void disableDac()

This will disable the onboard DAC.
NOTE: This method does seem to work across most chips used on these modules, but it is not documented for all of them and may not work consistently.

void enableDac()

This will enable the onboard DAC.
NOTE: This method does seem to work across some chips used on these modules, but it is not documented for all of them and has been demonstrated to not work consistently.

bool isOnline()

Will return if some media play source is online and ready to play.

Add a custom footer
Add a custom sidebar
Clone this wiki locally