-
-
Notifications
You must be signed in to change notification settings - Fork 33
API Reference
The constructor will require the declaration of several template arguments that specialize the class to the sketch writer's needs. Some of these class types are provided and some are required by the user to provide.
DFMiniMp3<T_SERIAL_METHOD, T_NOTIFICATION_METHOD, T_CHIP_VARIANT, C_ACK_TIMEOUT>(T_SERIAL_METHOD& serial)
T_SERIAL_METHOD - the class type of the serial hardware support, usually either HardwareSerial or SoftwareSerial.
T_NOTIFICATION_METHOD - the class type of the notification handler, you must provide this. Please read Implementing a notification method for more details. The examples also demonstrate simple implementations.
T_CHIP_VARIANT - (optional) the class type of the chip variant you have, usually either Mp3ChipOriginal or Mp3ChipMH2024K16SS. The default is Mp3ChipOriginal. In the rare case you have a chip that doesn't support ACK feature, then you use Mp3ChipIncongruousNoAck.
C_ACK_TIMEOUT - (optional) the value in milliseconds to use for serial timeout when waiting for an ACK from the chip. The default is 900 ms.
serial - the instance of the serial support that matches the provided T_SERIAL_METHOD.
The following example uses the hardware serial instance Serial1 with the user provided callback class named Mp3Callbacks.
DFMiniMp3<HardwareSerial, Mp3Callbacks> mp3(Serial1);
The following example uses the software serial instance SoftSerial with the user provided callback class named Mp3Callbacks specialized for the MH2024K16SS chip.
DFMiniMp3<SoftwareSerial, Mp3Callbacks, Mp3ChipMH2024K16SS> mp3(SoftSerial);
The following example sets the ACK timeout to 1600 ms if your chip requires a longer serial timeout.
DFMiniMp3<SoftwareSerial, Mp3Callbacks, Mp3ChipMH2024K16SS, 1600> mp3(SoftSerial);
This will initialize the DFMiniMp3 and prepare it for use. Call this within the sketches setup().
baud - (defaults to 9600) the baud rate the module communicates at. It is rare you will need to provide this.
This alternative begin will initialize the DFMiniMp3 and prepare it for use in the case that pins can be set for the serial device when its begin() is called. Call this within the sketches setup().
rxPin - the receive pin for the serial.
txPin - the transmit pin for the serial.
baud - (defaults to 9600) the baud rate the module communicates at. It is rare you will need to provide this.
This changes the number retries used when the module has communications problems. The default is 3 and this should not need to be called.
This will service the DFMiniMp3, listening for responses from the hardware. Call this often within the sketches loop().
DEPRECATED - the return communication is the same as the play source online notification, and thus will cause issues.
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 -
This will return current software/firmware version used within the MP3 module.
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.
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.
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.
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.
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.
This will cause the current track to stop and the next track to start playing immediately.
This will cause the current track to stop and the previous track to start playing immediately.
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 -
This will set the playback volume.
volume - (0-30) the volume level to set.
This will return the current volume.
This will increase the volume by 1.
This will decrease the volume by 1.
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.
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.
Retrieve the current playback mode. It will be one of the following.
DfMp3_PlaybackMode_Repeat -
DfMp3_PlaybackMode_FolderRepeat -
DfMp3_PlaybackMode_SingleRepeat -
DfMp3_PlaybackMode_Random -
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.
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.
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 -
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 -
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 -
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)
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.
During software development it is a good practice to call this right after begin() to put the MP3 Module into a known state. In a final product, there is an assumption that the uC and the MP3 Module will be powered on together and thus will start in a known state; so it can be removed then.
This will resume playing the current track where it was paused at. Some modules have required calling this before anything is played.
This will pause the current playing track.
This will stop the current playing track.
This will return the current status.
struct DfMp3_Status {
DfMp3_StatusSource source;
DfMp3_StatusState state;
};
source - one of the following
DfMp3_StatusSource_General - some modules don't provide specific sources so they will return this
DfMp3_StatusSource_Usb -
DfMp3_StatusSource_Sd -
DfMp3_StatusSource_Sleep - some modules the source will also return this state
state - one of the following
DfMp3_StatusState_Idle -
DfMp3_StatusState_Playing -
DfMp3_StatusState_Paused -
DfMp3_StatusState_Sleep -
DfMp3_StatusState_Shuffling - switching tracks to continue playing
This will return the count of tracks in the given folder
folder - the folder number to enumerate files within.
NOTE: If the count returned doesn't match your expectations, please read this discussion where one chip returns the last accessed folder and ignores the passed in folder id.
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
This will return the count of folders in the root of the media.
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.
This will stop the current playing advertisement and resume the original interrupted track.
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.
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.
Will return true if some media play source is online and ready to play.