PocketSynth

What it is

PocketSynth turns the pink R36S (a Rockchip RK3326 retro-gaming handheld running ArkOS) into a small instrument. Plug a class-compliant USB MIDI keyboard into the OTG port and play: three instruments, ten-voice polyphony, velocity-sensitive volume, and a calm, low-stimulation display — a big note name and soft circles that drift and fade as you play.

Each instrument ships 14 samples — one WAV every six semitones from MIDI 24 to 102, generated by tools/make_samples.py (numpy additive synthesis). The engine picks the nearest sample and pitch-shifts at most ±3 semitones, so stretching stays inaudible.

Controls

The school routine

1. Connect the keyboard first, then power on. Hot-plugging USB while the console runs on battery browns out the power rail and the device shuts off instantly.
2. If you must replug mid-session, put the charger in the DC port first (the top USB-C). With wall power attached, hot-plugging is safe. The bottom port marked OTG is the data port.
3. Launch PocketSynth from the Ports menu. The corner status reads waiting for keyboard → keyboard connected within a couple of seconds.
4. Press A once for the test note — your two-second sound check.

How it works

The obvious path — Godot's built-in MIDI API — is a dead end on this hardware, so notes take a scenic route:

• Korg microKEY2class-compliant USB MIDI, bus-powered (<100 mA)
• USB-C OTG porthost mode is on by default in ArkOS's device tree
• kernel: snd-usb-audiobuilt into the ArkOS kernel; the keyboard appears as /dev/snd/midiC1D0
• midi_bridge.shbash + od read the raw MIDI bytes and forward them as UDP datagrams to 127.0.0.1:9000
• MidiInput.gdnon-blocking PacketPeerUDP; parses note-on/off, running status, velocity
• Sampler.gd10 AudioStreamPlayer voices, nearest-sample + pitch_scale, velocity → volume
• rockchiprk817the internal speaker — pinned explicitly by the launcher (see below)

Why the bridge exists

Two verified engine limitations force the detour. The FRT runtime (the ARM build of Godot 3.5 that PortMaster ships for these handhelds) compiles out the ALSA MIDI driver entirely — OS.get_connected_midi_inputs() returns empty forever. And Godot 3 refuses to open character devices: its file layer stat-checks every path and rejects anything that isn't a regular file, so reading /dev/snd/midiC1D0 directly is impossible. A 40-line bash script and one UDP socket solve both.

This is the moment it first worked — the diagnostic build showing the kernel had seen the keyboard all along:

The audio hijack, explained

The strangest bug of the build: the keyboard worked, the app worked, and the speaker stayed silent while the volume kept "resetting to 0%."

Because USB MIDI is a subclass of USB Audio, the microKEY2 registers as a sound card. ArkOS ships USB-DAC auto-switching with no check for whether the new card can actually play audio: a udev rule tags any USB sound card, and a hidden root script (polling every second) rewrites the system-wide audio default to point at it. Result: the entire OS tries to play sound through a keyboard with no speakers.

Two fixes, both in the repo:

• PocketSynth.sh (always active) — the launcher finds the first non-USB sound card, points SDL straight at it via AUDIODEV, and restores its mixer. The hijacker can rewrite configs all it wants; the synth never consults them.
• FixKorgAudio.sh (optional, run once from the Ports menu) — installs a udev rule exempting Korg devices (vendor 0944) from the auto-switch, so games and menus also keep their sound while the keyboard is plugged in.

One-day build log

• Morning. "Could we make a music device if I plug a MIDI keyboard into the R36S?" First test: keyboard undetected — and unplugging it powers the console off (battery brownout; wall charger fixes it).
• Research. Four parallel deep-dives verify the real story: the OTG port and kernel support MIDI out of the box; the Godot runtime doesn't, at all. The bridge architecture is chosen: rawmidi → UDP → GDScript.
• Proof. A diagnostic build puts lsusb-style evidence on the device screen (its only debug channel — no SSH, and file logs never survive). The photo above: notes streaming, velocities intact.
• Instrument. 42 samples synthesized on the Mac, the sampler engine and calm UI written, an adversarial review catching two real bugs (stuck notes on unplug; a dead panic button) before they cost an SD-card round trip.
• Silence, then sound. The USB-DAC hijack diagnosed and pinned. Launcher fix deployed. IT WORKED.

Build & deploy runbook

1. Open the project in Godot 3.5.2 — never Godot 4, which silently converts and breaks it.
2. Project → Export → Linux/X11 → Export PCK/Zip → save as deploy/ports/pocketsynth/game.pck.
3. Copy deploy/ports/* onto the SD card's ports/ folder. Delete the card's old pocketsynth/ first — cp -R nests into an existing directory and the device will silently boot the stale build. Then sync before ejecting.

ports/
├── PocketSynth.sh          launcher: audio pin + bridge + FRT
├── FixKorgAudio.sh         optional one-time system fix
└── pocketsynth/
    ├── game.pck            the exported Godot app (~6 MB)
    ├── frt_3.5.2.squashfs  PortMaster Godot runtime
    ├── midi_bridge.sh      rawmidi → UDP bridge
    └── godot.gptk          button → key mapping

Troubleshooting