Skip to content
ericdahl-devPublic

About

Original analog-style polysynth firmware for the M-VAVE FM-1

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

173 Commits

Folders and files

Repository files navigation

fm1-8p

An original firmware for the M-VAVE FM-1 that turns it into a polyphonic analog-style synth, inspired by mid-80s two-oscillator polysynths with a chorus. It is not affiliated with or endorsed by Roland or M-VAVE.

Status

On the desktop, the fixed-point engine plays band-limited voices of two oscillators each (saw, pulse, square or noise, with octave, fine tune, pulse width and a mix between them), a resonant 24 dB lowpass (with key tracking and its own envelope), a 4-position highpass (with a bass-boost position, the JX-8P's HPF 0) and an ADSR amp envelope, up to 8 at once (6 by default), with voice stealing, the sustain pedal, pitch bend, a unison mode, an LFO routed to pitch and pulse width with a delay, and velocity, rendered from a MIDI file to a WAV.

Build and run

Linux or macOS, with a C compiler (gcc or clang) and GNU make. No other dependencies. On macOS, the Xcode command line tools (xcode-select --install) give clang and make. CI builds and tests on both: build-test (gcc) and build-test (clang) on Ubuntu, build-test (macos-latest, clang) on macOS.

make                 # builds build/fm1-8p-render and build/fm1-8p-bench
make check           # runs the tests and the float-free engine check
make bench           # times the engine per voice count (see Benchmark)
make bench-full      # the same on the full patch, every modulation on
make render-demo     # renders examples/demo.mid to build/demo.wav

./build/fm1-8p-render -r 44100 -v 6 -s amp_attack_ms=200 -s amp_release_ms=800 \
    -s chorus_mode=1 song.mid song.wav
./build/fm1-8p-render -s filter_cutoff_cents=6000 -s filter_resonance_permille=700 \
    -s filter_env_amount_cents=3600 song.mid song.wav

chorus_mode is 0 (off, the default), 1 (slow), 2 (deep) or 3 (fast); the modes are described in docs/fixed-point.md.

Run ./build/fm1-8p-render with no arguments to list every option and parameter.

The render tool plays one MIDI channel (-c, by default the channel of the first note on) with 6 voices by default (-v). Each voice is mixed at 1.44/(2 x voices), PG-8X's level (#102); past -2.85 dBFS a soft clip bends the output short of full scale, so it never wraps. The mixing makes a single note quieter with more voices: -18.4 dBFS with 6, -2.9 dBFS with -v 1 or in unison (-s voice_mode=1, where one note takes every voice). After each render the tool prints the voice count, channel and that level.

The no-sound gate

A change that should not change the sound, such as a speed-up, a refactor or a smaller binary, must pass the gate:

make gate BASE=origin/main              # HEAD is the commit checked out
make gate BASE=a254bee HEAD=my-branch   # either one may also be a source directory

It builds the renderer on both commits, renders every gate clip on each, and fails if any WAV differs by a single byte. It prints the clips that differ, then how many clips reach each engine function. That count comes from a second --coverage build of HEAD and gcov; the device build is untouched. A function reached by fewer than 2 clips is flagged, so a change can't pass on a path that only one clip plays. The count is per function, not per branch inside one. GATE_COVERAGE=0 skips it.

The clips are listed in tools/gate_cases.py and play MIDI that tools/gate_midi.py writes:

  • every DCO-1 × DCO-2 wave with X-MOD, SYNC 1 and SYNC 2 at three level pairs
  • FM cross-mod and two noises
  • pulse-width modulation
  • the controllers: sustain pedal, mod wheel, pitch bend, all notes off and all sound off
  • each highpass step
  • the filter and its envelope, including inverted and from envelope 2
  • unison
  • the 32 JX-8P factory tones, each tree on its own converter

Nothing in it is PG-8X material. A tree's renders are kept in build/gate by a hash of its sources, so the next run against the same BASE renders only HEAD.

With the FM-1 build inputs (FM1_REF, a folder holding fm1-dock, the JieLi toolchain, the AC79 SDK, fm1-dock's venv and fm1-live; or tools/fm1-build.sh's own variables), it also prints the CPU rows in fm1-emu's strict timing: 8 voices, U and F, with code bytes, for step F plain, with sync, the ring and both. Each runs as built and with 3 KB of padding ahead of the engine, which moves every function, so a gain that is only alignment shows. The device reads about 1.08 times the emulator. Without those inputs it says the rows were skipped.

make check-gate tests the gate itself. For each covered path, a one-line change in a copy of the tree must fail the gate. It renders for a few minutes, so it is not part of make check.

Benchmark

build/fm1-8p-bench [-b BLOCKS] [-r RUNS] [-w WORKLOAD] (-h for help) times the engine on the FM-1 CPU test's workload (firmware/cpu_test.c): the same held chord at 1 to 8 voices, 44 100 Hz, 256-frame blocks. For each run and voice count it renders one block untimed (the notes start there), then times BLOCKS blocks one by one (default 2000) and keeps the median block. The table gives the median of the RUNS runs (default 5).

-w picks the workload: default (what runs without -w), full, or all; it can be repeated (-w default -w full is -w all). Each one prints its own table, under ## default patch or ## full patch. make bench runs the default workload and make bench-full the full one:

workload what plays
default the default patch, as in the CPU test's steps 1 to 8. With every modulation depth at 0 the LFO costs nothing here
full the CPU test's step F patch on the same chord: osc1 pulse and osc2 saw mixed half and half, 30 cents of vibrato, 25 % pulse-width modulation, amp velocity at 100 % with a different velocity per note, a resonant lowpass (cutoff 10500 cents, resonance 700, its envelope sweeping it up 3600 cents into the top of its range) with the first highpass step, and the deep chorus; at every count up to 8, where step F plays 4 voices

The columns:

column meaning
ns / block time for one 256-frame block
ns / frame ns / block divided by 256: compare with the FM-1's 22 676 ns per frame
ns / voice-frame ns / frame divided by the voice count
spread (slowest run - fastest run) / median, in %

The clock is CLOCK_MONOTONIC on Linux and CLOCK_UPTIME_RAW on macOS (whose CLOCK_MONOTONIC ticks in microseconds, too coarse for a 1-2 µs block). The first line of the output gives the clock's smallest step. If a voice count's blocks read as 0 ns, the bench says "timer too coarse" and exits with 1.

Repeatability, measured on a ThinkPad T480s (i5-8350U, Linux, other jobs running): over three runs of the default workload, each voice count's ns / block stayed within 0.2 %. The spread column is the warning light: a run that something else interrupted shows up there (one run in five often reads 10-90 % slow on a busy machine), while the median ignores it. Compare numbers from the same machine only, and rerun when the spread is above a few percent. The FM-1's own numbers come from fm1-emu or the device (FM-1 CPU-test firmware below); the desktop numbers are for spotting changes in cost between commits.

The engine uses only integer math. Its number formats, the sample rate and block size rules, and how the float-free check works are in docs/fixed-point.md. How notes get voices (the stealing rule), the sustain pedal, pitch bend, unison mode (-s voice_mode=1 -s unison_detune_cents=20) and the output gain staging are in docs/voices.md. The LFO (waveforms, rate, delay and fade-in, depths, routing to pitch and pulse width) and the velocity curve are in docs/modulation.md, for example -s lfo_pitch_cents=20 -s lfo_delay_ms=300 -s amp_velocity_pct=70.

FM-1 firmware: the synth

firmware/fm1_8p/ is the playable synth, the fm1-dock module FM1-8P: the FM-1's keys (with their velocity; OCT- and OCT+ move the octave, each key lights while held) and MIDI (note on and off, sustain CC 64, pitch bend; any channel, from whatever fm1-dock takes in: USB, Bluetooth or the jack) play the engine on 4 voices (PLAY_VOICES in firmware/play.h). It boots on SOUNDTRACK, tone 17 of the JX-8P's 32 factory tones, which are all in firmware/patches.c (converted by tools/jx8p.py; the source and the mapping are in docs/patches.md). The screen shows the name, the patch, the voice count and the last note played. The key and MIDI mapping is plain C (firmware/play.[ch]), tested on the desktop by make test.

ENV opens page 4A, VCF (docs/ui/interaction.md), drawn in docs/ui/visual.md's Night Panel theme: KNOB1-4 set CUTOFF, RESO, ENV and KEY, and a tap of EDIT or HOME goes back to the PLAY screen. The keys play on every page. PRESETS steps through the 32 factory patches (P1 .. P32) on any page, showing the number and name; with unsaved edits the first turn warns EDITED: TURN AGAIN TO DISCARD and a turn the same way while the warning shows (1.5 s) discards them and loads. What the knobs and PRESETS do, how values read, the meter, the filter curve and what to redraw are plain C in firmware/ui.[ch], also tested by make test; the module draws what it says.

FM-1 CPU-test firmware

firmware/fm1_8p_cpu/ runs the unchanged engine on the FM-1 as an fm1-dock module and measures it: it holds a chord and steps from 1 to 8 voices, 5 s each, then runs the unison burst (row U: 8 voices in unison, 8 note-ons and a detune change in every block), then the full patch (row F: a 4-voice chord, the device's polyphony, with the filter, both oscillators, vibrato, pulse-width modulation, amp velocity and the chorus), showing the worst render time per step on screen (as % of a 256-frame block, 5.8 ms; the block that starts a step, engine init and note on, isn't timed) and logging each step a sweep held in full (tools/dock.py logs in fm1-dock; the burst logs as count 9, the full patch as 10). KNOB1 picks a step by hand, 1 to 8, U, then F (it stops there; a hand-picked U keeps bursting), and stops the sweep; PLAY sweeps again from 1. To run it on an FM-1, follow docs/device-test.md.

Linux x86-64 (macOS through fm1-dock's Docker fallback, untested), with curl, git, tar, xz and Python 3 with Pillow:

tools/fm1-build.sh fetch     # fm1-dock, JieLi toolchain, AC79 SDK files into build/fm1-deps
tools/fm1-build.sh build     # build/fm1/fm1_8p.dock and fm1-8p.fwsc (the synth),
                             # build/fm1/fm1_8p_cpu.dock and fm1-8p-cpu.fwsc (the CPU test)
tools/fm1-build.sh canaries  # each firmware/canary module must fail fm1-dock's safety checks
tools/fm1-build.sh emu       # the CPU test in fm1-emu, strict timing: build/fm1/emu-report.md
tools/fm1-build.sh emu-play  # FM1-8P plays keys and MIDI in fm1-emu; fails on an overrun

Every input is pinned in firmware/pins.env and checked before a build:

input pin
fm1-dock (GPL-3.0-only) commit 9e6e08e, fetched, not vendored
JieLi Linux toolchain, clang 4.0.1 for pi32v2 tarball sha256 and directory jieli-linux-toolchains-20260730.1 (the download URL always serves the latest)
JieLi AC79 SDK AC79NN_SDK_V1.2.1_2023-12-13 commit d179b448; the 3 files the package needs, each by sha256
fm1-emu (MIT) release v0.4.0, sha256
Pillow 13.0.0

To use inputs you already have, set JIELI_TOOLCHAIN, AC79_SDK, FM1_DOCK, PYTHON or FM1_LIVE. They are checked the same way, and fetch never changes them: a mismatch stops the build. FM1_LIVE must be the pinned fm1-live build unless FM1_EMU_UNPINNED=1, which the report then notes.

The module lists no engine files: the build fills in every engine/*.c, so a new engine file needs no firmware edit.

Known risk: JieLi's toolchain URL always serves their latest tarball. When they publish a new one, fetch stops with "JieLi published a new toolchain" (CI too, once its cache is gone). Review the new one, then update JIELI_TOOLCHAIN_SHA256 and JIELI_TOOLCHAIN_DIR in firmware/pins.env. We don't mirror the tarball: its license for redistribution is unknown.

  • The .dock goes onto an FM-1 that runs fm1-dock, over USB, without flashing (tools/dock.py deploy in fm1-dock).
  • The .fwsc is a solo firmware package, identity FM-1_948, with fm1-dock's safety checks and rescue modes (OCT- at power-on: USB rescue; OCT+: safe start). Keep the stock firmware for recovery.

CI builds both on every push (job fm1-firmware, artifact fm1-8p-cpu) and runs the emulator step as a report in the job summary; it becomes a gate once the emulator is calibrated against the device (#13).

Layout

  • engine/ - the synth engine: plain C99, fixed point, no hardware or OS code, no dynamic allocation. Public interface: engine/fm1_8p.h.
  • host/ - the desktop render tool: Standard MIDI File reader, WAV writer.
  • firmware/ - the FM-1 modules: the synth, play.[ch] (plain C, tested on the desktop) and fm1_8p/ (the fm1-dock module); the CPU test, cpu_test.[ch] and fm1_8p_cpu/; canary/ (modules the build must reject), pins.env.
  • tests/ - tests, run with a small single-header runner (tests/tinytest.h).
  • tools/ - the float-free check, the FM-1 build (fm1-build.sh) and the scripts that generate the pitch table and examples/demo.mid.

Plan

  1. Synth engine in plain C (engine/), with no hardware code: two oscillators per voice (saw, pulse, square, noise, sync, cross-mod), a 24 dB resonant lowpass, a stepped highpass, two envelopes, an LFO and a stereo chorus.
  2. Desktop build (host/): renders the engine to WAV or plays it live on Linux and macOS, for listening tests against reference recordings.
  3. CPU spike on the device: one voice with filter and chorus on the FM-1 to measure load and decide the voice count: 4 voices, final (Eric, 2026-11-15; the measurements are in docs/device-test.md).
  4. FM-1 firmware (fw/): built on JieLi's Linux toolchain and AC79 SDK, the same way as fm1-dock, released through zvenson/fm1-build for The Firmware Hub.

Hardware notes

  • The FM-1 runs on a JieLi AC791N (pi32v2 CPU). Expect fixed-point DSP.
  • Keep the stock M-VAVE V15 firmware ("PC Firmware" at m-vave.com/download) for recovery.

License

GPL-3.0. See LICENSE.

About

Original analog-style polysynth firmware for the M-VAVE FM-1

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages