Music Demo Example

Interactive audio demo showcasing the PixelRoot32 audio subsystem with instrument presets and pre-composed multi-part music. Features a UI-based interface for testing sound presets and playing layered MusicTrack arrangements.

When PIXELROOT32_ENABLE_UI_SYSTEM is on (default in PlatformDefaults.h), the demo exposes touch UI: UIButton for instrument preset selection and melody playback, UILabel for navigation hints, and UIVerticalLayout for organized button placement — see MusicDemoScene.h.

Requirements (build flags)

• PIXELROOT32_ENABLE_AUDIO — required for audio subsystem and music playback
• PIXELROOT32_ENABLE_UI_SYSTEM — required for UI widgets (buttons, labels, layouts)
• PIXELROOT32_ENABLE_TOUCH=1 — set for native in platformio.ini so touch APIs compile and mouse/touch can drive the demo

See platformio.ini for native and esp32dev.

Platforms

Environment	Display / input
native	SDL2, 240×240; touch flag enables the same code paths with simulated touch
esp32dev	ST7789 240×240 (use keyboard/GPIO per your platforms/esp32_dev.h)

Controls / interaction

• Navigate menus — use your InputManager layout to move between UI buttons (see scene update / button handling)
• Select / Play — trigger button callbacks to play instrument sounds or melodies
• Same melody again — pressing the currently playing melody button stops playback (toggle)
• Back — B stops music if playing, then returns to the previous menu level

Melody assets (src/assets/)

Melodies are generated by the PixelRoot32 Tool Suite from their .pr32music sources. Each asset is self-contained: it carries its own LIB_* InstrumentPreset definitions, beat constants (S/E/Q/H/W), and a four-part MusicTrack arrangement:

File	UI button	Role
blaster_ridge.h	Blaster Ridge	musicdemo::blaster_ridge::kTrack — fast action theme
coinleaf_grove.h	Coinleaf Grove	musicdemo::coinleaf_grove::kTrack — light adventure theme
lightworld_march.h	Lightworld March	musicdemo::lightworld_march::kTrack — heroic march
moonwell_hymn.h	Moonwell Hymn	musicdemo::moonwell_hymn::kTrack — dreamy hymn

Each .h has a companion .h.pr32music sidecar (name, BPM, patterns) used to generate it.

Each arrangement layers main lead + secondVoice (bass) + thirdVoice (harmony) + percussion, mapped by MusicPlayer to ApuCore music slots 0–3 (SFX keeps slots 4–7). The per-track LIB_* presets are tuned so loops stay full after beat-accurate gates.

Melodies (UI labels vs. engine)

UI button	BPM (see MusicDemoScene::playMelody)	Loop length (beats)	Layers (summary)
Blaster Ridge	168	32	SAW lead (LIB_SAW_EDGE/BRIGHT/RAZOR), SAW growl bass (LIB_SAW_GROWL_BASS), PULSE harmony hits (LIB_PULSE_HERO_BRASS), noise drums with clap / crash / tom / zap fills
Coinleaf Grove	152	32	PULSE lead (LIB_PULSE_BRIGHT/SPARK/THIN), TRIANGLE thump bass (LIB_TRIANGLE_THUMP), pulse harmony, noise drums with clap and open-hat accents
Lightworld March	128	32	PULSE lead (LIB_PULSE_BRIGHT), TRIANGLE thump bass, pulse hero-brass / warm-pad harmony, noise drums with crash, tom fills and open hats
Moonwell Hymn	104	32	SINE flute lead (LIB_SINE_FLUTE, bell/glass accents), TRIANGLE sub bass (LIB_TRIANGLE_SUB_BASS), sine dream/air-pad harmony, noise drums with ride, crash, soft snare and open hats

Features

• 10 engine instrument presets (one-shot tests) — Pulse Lead, Pulse Harmony, Triangle Bass, Pulse Bass, Triangle Lead, Triangle Pad, Pulse Pad, Kick, Snare, Hi-hat
• 4 four-part demo tracks — each layers lead + bass (secondVoice) + harmony (thirdVoice) + percussion, generated from tool-suite .pr32music assets with distinct BPM and texture (see table above)
• Audio Lab menu — pulse frequency sweep (Phase A), SINE / SAW chord one-shots (Phase B), and master bitcrush cycling via AudioEngine::setMasterBitcrush
• UI-based sound testing — play individual instrument sounds on demand
• Modular audio architecture — demonstrates InstrumentPreset, per-asset LIB_* preset tuning, melody sequencing, AudioEvent sweep fields, and audio scheduling

Documentation links

• Audio API
• Music player guide
• Input API
• UI API
• Core — Scene

Build

From examples/music_demo:

pio run -e native
pio run -e esp32dev

Upload (ESP32)

pio run -e esp32dev --target upload

---

Source code: https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/music_demo