Metadata-Version: 2.4
Name: DIYables-MicroPython-MiniMp3
Version: 1.0.1
Summary: MicroPython Library for Mini Mp3 Player Module, for ESP32, Raspberry Pi Pico, Arduino Nano ESP32, Arduino Giga R1 WiFi, by DIYables
Home-page: https://diyables.io
Author: DIYables
Author-email: DIYables <diyables.io@gmail.com>
License: MIT
Project-URL: Homepage, https://diyables.io/products/mini-mp3-player-module
Project-URL: Repository, https://github.com/DIYables/DIYables_MicroPython_MiniMp3
Keywords: DIYables,MiniMp3,Mini Mp3,Mini MP3 Player,MP3,MicroPython,ESP32,Raspberry Pi Pico,Arduino Nano ESP32,Arduino Giga R1 WiFi
Classifier: Programming Language :: Python :: Implementation :: MicroPython
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: license.txt
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# DIYables MicroPython Mini Mp3 Player Library

MicroPython library for the DIYables Mini Mp3 Player module (YX5200-24SS). Easy-to-use API designed for beginners. Compatible with ESP32, Raspberry Pi Pico, Arduino Nano ESP32, and Arduino Giga R1 WiFi.

![DIYables Mini Mp3 Player Module](https://diyables.io/images/products/mini-mp3-player-2.jpg)

## PRODUCT

[DIYables Mini Mp3 Player Module](https://diyables.io/products/mini-mp3-player-module)

## Tested Hardware

| Board                   | Tested |
|-------------------------|:------:|
| ESP32                   |   ✅   |
| Raspberry Pi Pico       |   ✅   |
| [DIYables ESP32 Development Board](https://diyables.io/esp32-board) |   ✅   |
| [DIYables ESP32 S3, Uno-form factor](https://diyables.io/products/esp32-s3-development-board-with-esp32-s3-wroom-1-n16r8-wifi-bluetooth-uno-compatible-form-factor-works-with-arduino-ide) |   ✅   |
| Arduino Nano ESP32              |   Not yet, expected to work   |
| Arduino Giga R1 WiFi            |   Not yet, expected to work   |
| Other MicroPython boards |   Not yet, expected to work    |

## Features
- Simple, beginner-friendly API — no complex setup needed
- No external library dependencies
- Non-blocking playback commands (play, pause, stop, volume, etc.)
- Play tracks by number, from folders, or from the special `/mp3` folder
- Volume control (0-30), 6 EQ modes
- Loop track, loop folder, loop all, shuffle
- Advertisement support (interrupt and resume)
- DAC control, sleep/wake, reset
- Status queries (current track, volume, track count, etc.)
- Optional debug output via print()
- Compatible with ESP32, Raspberry Pi Pico, Arduino Nano ESP32, and Arduino Giga R1 WiFi running MicroPython

## Tutorials
- [ESP32 MicroPython - Mini Mp3 Player Module](https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-mini-mp3-player-module)
- [Raspberry Pi Pico - Mini Mp3 Player Module](https://newbiely.com/tutorials/raspberry-pico/raspberry-pi-pico-mini-mp3-player-module)

## Installation

You can install the library via pip from PyPI:

```bash
pip install DIYables-MicroPython-MiniMp3
```

Or you can install it using Thonny IDE:
1. In Thonny, go to **Tools > Manage Packages**
2. Search for **DIYables-MicroPython-MiniMp3**
3. Click **Install**

## Wiring

### DIYables Mini Mp3 Player Pinout

| Pin | Description |
|---|---|
| VCC | Power supply (3.2V ~ 5.0V) |
| GND | Ground |
| RX | UART receive (connect to board's TX pin) |
| TX | UART transmit (connect to board's RX pin) |
| SPK_1 | Speaker+ (for direct speaker connection, max 3W) |
| SPK_2 | Speaker- (for direct speaker connection, max 3W) |
| DAC_R | Right audio output (for external amplifier) |
| DAC_L | Left audio output (for external amplifier) |
| BUSY | Low when playing, high when idle (optional) |
| IO_1 | Short press: previous track, long press: volume down |
| IO_2 | Short press: next track, long press: volume up |

### Wiring with ESP32

| Mini Mp3 Pin | ESP32 Pin | Note |
|---|---|---|
| VCC | 3.3V | |
| GND | GND | |
| RX | GPIO17 (TX) | No resistor needed (3.3V logic) |
| TX | GPIO16 (RX) | |
| SPK_1 | Speaker+ | Direct speaker connection (max 3W) |
| SPK_2 | Speaker- | Direct speaker connection (max 3W) |

### Wiring with Raspberry Pi Pico

| Mini Mp3 Pin | Pico Pin | Note |
|---|---|---|
| VCC | 3.3V | |
| GND | GND | |
| RX | GPIO4 (TX) | No resistor needed (3.3V logic) |
| TX | GPIO5 (RX) | |
| SPK_1 | Speaker+ | Direct speaker connection (max 3W) |
| SPK_2 | Speaker- | Direct speaker connection (max 3W) |

### Wiring with Arduino Nano ESP32

| Mini Mp3 Pin | Arduino Nano ESP32 Pin | Note |
|---|---|---|
| VCC | 3.3V | |
| GND | GND | |
| RX | D1 (GPIO43, TX) | No resistor needed (3.3V logic) |
| TX | D0 (GPIO44, RX) | |
| SPK_1 | Speaker+ | Direct speaker connection (max 3W) |
| SPK_2 | Speaker- | Direct speaker connection (max 3W) |

### Wiring with Arduino Giga R1 WiFi

| Mini Mp3 Pin | Arduino Giga R1 WiFi Pin | Note |
|---|---|---|
| VCC | 3.3V | |
| GND | GND | |
| RX | TX1 | No resistor needed (3.3V logic) |
| TX | RX1 | |
| SPK_1 | Speaker+ | Direct speaker connection (max 3W) |
| SPK_2 | Speaker- | Direct speaker connection (max 3W) |

> **Note:** ESP32, Raspberry Pi Pico, Arduino Nano ESP32, and Arduino Giga R1 WiFi all use 3.3V logic, so no resistor is needed on the RX line.

> **Tip:** For better audio quality, connect DAC_R and DAC_L to an external amplifier instead of using the direct speaker output.

## SD Card File Structure

> **Important:** Format your SD card as **FAT16** or **FAT32** before use.

### Track Numbering

- Track numbers start from **1** (not 0).
- The module assigns track numbers based on the **order files were copied** to the SD card, **NOT by filename**.
- To ensure correct ordering: **format the SD card first**, then copy files **one by one in order** (001.mp3 first, then 002.mp3, etc.).
- File names must start with a zero-padded number. You can add text after the number: `001-hello.mp3`, `002-goodbye.mp3`.

Root folder files (used by `play()`):
```
/001.mp3          <- play(1)
/002.mp3          <- play(2)
/003-mysong.mp3   <- play(3)
```

### Folder Numbering

- Folder numbers start from **1** (not 0).
- Folder names must be **2-digit** zero-padded numbers: `01`, `02`, ... `99`.
- Track names inside folders must be **3-digit** zero-padded numbers: `001`, `002`, ... `255`.
- Maximum: **99 folders**, **255 tracks per folder** (using `play_folder()`).

```
/01/001.mp3       <- play_folder(1, 1)
/01/002.mp3       <- play_folder(1, 2)
/02/001.mp3       <- play_folder(2, 1)
/02/002.mp3       <- play_folder(2, 2)
```

### Large Folder Mode

- For more than 255 tracks per folder, use `play_large_folder()`.
- Folder names: `01` to `15` (max **15 folders**).
- Track names must be **4-digit** zero-padded numbers: `0001` to `3000`.

```
/01/0001.mp3      <- play_large_folder(1, 1)
/01/0002.mp3      <- play_large_folder(1, 2)
/15/3000.mp3      <- play_large_folder(15, 3000)
```

### MP3 Folder

- The folder must be named `mp3` (lowercase) in the root of the SD card.
- Track names must be **4-digit** zero-padded: `0001.mp3` to `9999.mp3`.

```
/mp3/0001.mp3     <- play_from_mp3_folder(1)
/mp3/0002.mp3     <- play_from_mp3_folder(2)
```

### Advertisement Folder

- The folder must be named `advert` (lowercase) in the root.
- Track names must be **4-digit** zero-padded: `0001.mp3` to `9999.mp3`.
- Used to interrupt the current track (e.g., announcements).

```
/advert/0001.mp3  <- play_advertisement(1)
/advert/0002.mp3  <- play_advertisement(2)
```

### Summary Table

| Function | Folder Name | File Name Format | Range |
|---|---|---|---|
| `play(n)` | Root `/` | `001.mp3` - `255.mp3` | 1 - 9999 |
| `play_folder(f, t)` | `01` - `99` | `001.mp3` - `255.mp3` | folder 1-99, track 1-255 |
| `play_large_folder(f, t)` | `01` - `15` | `0001.mp3` - `3000.mp3` | folder 1-15, track 1-3000 |
| `play_from_mp3_folder(n)` | `mp3` | `0001.mp3` - `9999.mp3` | 1 - 9999 |
| `play_advertisement(n)` | `advert` | `0001.mp3` - `9999.mp3` | 1 - 9999 |

## Examples

| Example | Description |
|---|---|
| [PlayOneTrack](examples/PlayOneTrack.py) | Simplest example — play a single track |
| [LoopTrack](examples/LoopTrack.py) | Loop (repeat) a track continuously with EQ setting |
| [PlayMultipleTracks](examples/PlayMultipleTracks.py) | Play tracks one after another automatically |
| [PlayFromFolder](examples/PlayFromFolder.py) | Play tracks from numbered folders |
| [PauseResume](examples/PauseResume.py) | Toggle pause/resume with a button |
| [NextPrevButtons](examples/NextPrevButtons.py) | Next/previous track with two buttons |
| [VolumeControl](examples/VolumeControl.py) | Volume up/down with two buttons |
| [SerialControl](examples/SerialControl.py) | Control everything from the serial console (great for testing) |

## Quick Start

### For ESP32

```python
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player

uart = UART(2, baudrate=9600, tx=17, rx=16)
mp3 = MiniMp3Player(uart)
time.sleep(1)  # Wait for the module to initialize

mp3.set_volume(25)
mp3.play(1)
```

### For Raspberry Pi Pico

```python
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player

uart = UART(1, baudrate=9600, tx=4, rx=5)
mp3 = MiniMp3Player(uart)
time.sleep(1)  # Wait for the module to initialize

mp3.set_volume(25)
mp3.play(1)
```

### For Arduino Nano ESP32

```python
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player

# REPL uses native USB, so UART pins are free
uart = UART(1, baudrate=9600, tx=43, rx=44)
mp3 = MiniMp3Player(uart)
time.sleep(1)  # Wait for the module to initialize

mp3.set_volume(25)
mp3.play(1)
```

### For Arduino Giga R1 WiFi

```python
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player

uart = UART(1, baudrate=9600)
mp3 = MiniMp3Player(uart)
time.sleep(1)  # Wait for the module to initialize

mp3.set_volume(25)
mp3.play(1)
```

## API Reference

### Constructor

```python
mp3 = MiniMp3Player(uart, debug=False, timeout=100)
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `uart` | `machine.UART` | *(required)* | UART instance, already initialized at 9600 baud |
| `debug` | `bool` | `False` | Enable debug output via `print()` |
| `timeout` | `int` | `100` | Response timeout in milliseconds for status queries |

### Playback Control

| Method | Description |
|---|---|
| `play(track_num)` | Play a specific track by number (starts from 1) |
| `play_next()` | Play the next track |
| `play_previous()` | Play the previous track |
| `pause()` | Pause the currently playing track |
| `resume()` | Resume playback of a paused track |
| `stop()` | Stop playback completely |

### Folder Playback

| Method | Description |
|---|---|
| `play_folder(folder, track)` | Play a track from a numbered folder (1-99, 1-255) |
| `play_large_folder(folder, track)` | Play a track from a folder with up to 3000 tracks (1-15, 1-3000) |
| `play_from_mp3_folder(track_num)` | Play a track from the special `/mp3` folder |

### Advertisement

| Method | Description |
|---|---|
| `play_advertisement(track_num)` | Play advertisement (interrupts current track) |
| `stop_advertisement()` | Stop advertisement and resume previous track |

### Volume

| Method | Description |
|---|---|
| `set_volume(vol)` | Set volume level (0-30) |
| `volume_up()` | Increase volume by one step |
| `volume_down()` | Decrease volume by one step |

### Equalizer

| Method | Description |
|---|---|
| `set_eq(eq)` | Set EQ mode: `EQ_NORMAL`, `EQ_POP`, `EQ_ROCK`, `EQ_JAZZ`, `EQ_CLASSIC`, `EQ_BASS` |

### Repeat & Shuffle

| Method | Description |
|---|---|
| `loop_track(track_num)` | Loop a specific track continuously |
| `loop_folder(folder)` | Loop all tracks in a folder |
| `loop_all()` | Loop all tracks on the SD card |
| `stop_loop()` | Stop looping |
| `shuffle()` | Play all tracks in random order |

### DAC Control

| Method | Description |
|---|---|
| `enable_dac()` | Enable the DAC output |
| `disable_dac()` | Disable the DAC output |

### Power Management

| Method | Description |
|---|---|
| `sleep()` | Put the module into sleep mode |
| `wake_up()` | Wake the module from sleep mode |
| `reset()` | Reset the module |

### Status Queries

| Method | Return | Description |
|---|---|---|
| `is_playing()` | `bool` | `True` if a track is currently playing |
| `get_volume()` | `int` | Current volume (0-30), or -1 on error |
| `get_eq()` | `int` | Current EQ setting, or -1 on error |
| `get_track_count()` | `int` | Total tracks on the SD card, or -1 on error |
| `get_current_track()` | `int` | Current track number, or -1 on error |
| `get_folder_count()` | `int` | Number of folders, or -1 on error |
| `get_track_count_in_folder(folder)` | `int` | Tracks in a folder, or -1 on error |

### Configuration

| Method | Description |
|---|---|
| `set_timeout(ms)` | Set response timeout in milliseconds |

### Debug

| Method | Description |
|---|---|
| `print_error()` | Print the last error message from the module |

### EQ Constants

```python
import DIYables_MicroPython_MiniMp3.DIYables_MicroPython_MiniMp3 as mp3_const

mp3_const.EQ_NORMAL   # 0
mp3_const.EQ_POP      # 1
mp3_const.EQ_ROCK     # 2
mp3_const.EQ_JAZZ     # 3
mp3_const.EQ_CLASSIC  # 4
mp3_const.EQ_BASS     # 5
```

## References

* [DIYables Mini Mp3 Player Product Page](https://diyables.io/products/mini-mp3-player-module)
