RetroFM Pocket

A handheld MML-era FM music player and visualizer for M5StickS3.

日本語

Why RetroFM Pocket?

The compact M5StickS3 becomes a self-contained window into Japanese retro-computer music. RetroFM Pocket recreates two landmark Yamaha FM chips in software, drives the built-in speaker in real time, and turns otherwise invisible register activity into a live spectrum and channel display.

The project plays compiled music formats associated with the MML era:

• VGM/VGZ using the YM2203 (OPN) core
• MDX using the YM2151 (OPM) core
• PDX/ADPCM samples when a matching PDX file is present

It does not currently parse raw MML source files; “MML-era” describes the music culture and workflows represented by VGM and MDX.

Features

• Real-time YM2203/OPN playback through the YMFM emulator
• YM2151/OPM MDX playback through portable_mdx
• PDX/ADPCM playback for compatible MDX tracks
• LittleFS browser for .vgm, .vgz, and .mdx files
• Japanese MDX title conversion from CP932/Shift-JIS to UTF-8
• Live track title, spectrum, volume, and FM-chip activity meters
• Two-button track and volume controls
• Deterministic, rights-cleared FM demo generated from source

Hardware

• M5Stack M5StickS3
• USB-C cable for building and flashing
• No external audio hardware is required

The PlatformIO environment uses the m5stack-stamps3 board definition because the M5StickS3 is built around the StampS3 module.

Quick Start

Requirements:

• Python 3.x
• PlatformIO CLI

Generate the included CC0 demo, copy it to LittleFS data, build, and flash:

python scripts/generate_retrofm_demo.py
copy demo\retrofm-pocket-demo.vgm data\retrofm-pocket-demo.vgm
pio run -e m5sticks3
pio run -e m5sticks3 -t upload
pio run -e m5sticks3 -t uploadfs

On PowerShell, replace copy with Copy-Item if preferred. To use your own music, place rights-cleared VGM/VGZ/MDX files and matching PDX files in data/ before uploadfs.

Controls

• BtnA, short press: next track
• BtnA, long press: volume up
• BtnB, short press: previous track
• BtnB, long press: volume down

How It Works

flowchart LR
    A["LittleFS: VGM/VGZ or MDX/PDX"] --> B{"Format loader"}
    B -->|"VGM/VGZ"| C["YM2203 / OPN via YMFM"]
    B -->|"MDX/PDX"| D["YM2151 / OPM via portable_mdx"]
    C --> E["Real-time PCM mixer"]
    D --> E
    E --> F["M5StickS3 speaker"]
    C --> G["Register activity"]
    D --> G
    E --> H["64-bin spectrum"]
    G --> I["On-device visualizer"]
    H --> I

Loading

The ESP32-S3 performs file loading, sequence interpretation, FM synthesis, ADPCM mixing, UI rendering, and audio output locally. Wi-Fi or a companion computer is not required during playback.

Project Structure

• src/: firmware sources
• src/audio/: audio output and mixing
• src/dsp/: spectrum analysis
• src/mdx/, src/opm/: MDX and YM2151 path
• src/vgm/, src/opn/: VGM and YM2203 path
• src/ui/: M5StickS3 interface
• src/encoding/: CP932/Shift-JIS title conversion
• scripts/generate_retrofm_demo.py: deterministic original-demo generator
• scripts/generate_skyfang_circuit_demo.py: YM2151/MDX arrangement-study generator
• demo/: contest demo, MDX study, and per-track provenance
• docs/contest-2026/: M5Stack contest documentation
• data/: local LittleFS payload; music files are intentionally ignored by Git

Build Verification

pio run -e m5sticks3 -j 1

Verified on 2026-08-07:

• Build: success
• RAM: 131,276 / 327,680 bytes (40.1%)
• Flash: 905,573 / 1,310,720 bytes (69.1%)

Single-job mode avoids intermittent archive races observed when building this OneDrive-hosted checkout in parallel.

Music and Licensing

• Repository code: MIT License
• Generated demo/retrofm-pocket-demo.vgm: CC0-1.0
• YMFM: BSD 3-Clause
• M5Unified and M5GFX: MIT; bundled font components retain their upstream notices
• portable_mdx: includes Apache-2.0 and original MXDRVg/X68Sound-derived terms; review upstream terms before distributing a firmware binary containing it

Music placed in data/ is not part of this repository. Do not redistribute MDX, PDX, VGM, or VGZ files unless you created them or have permission.

M5Stack Global Innovation Contest 2026

The contest story, hardware list, build narrative, media checklist, and submission copy are in docs/contest-2026.