Felucca — personal fork

Felucca on the M-VAVE FM-1

This is my personal fork of Hügelton's Felucca, multi-engine synthesizer firmware for the M-VAVE FM-1. The goal is to bring together recent features and optimizations from upstream and other forks, collect and integrate additional synthesis engines, and improve CPU efficiency, RAM use and firmware size.

This is ongoing integration and experimentation. Features are adopted as they are reviewed and tested; the fork does not automatically include every upstream or fork change.

Opt-in experimental SMK-37 Pro, Elite and MKE-P37 targets add model-specific packages and native controls. Each model's physical qualification is pending. Normal CI, PR builds and Latest Dev retain the standard FM-1 target; tagged releases also include experimental SMK assets.

Release channels: Latest Dev publishes a traceable experimental prerelease at one fixed latest-dev address, replaced after each validated PR merge; tagged releases require an explicit FM-1 test report and maintainer approval before publication. Back up first and read the recovery guide before installing development firmware.

What it offers

The standard profile combines thirteen engines with factory presets, four tracks sharing eight voices, a 64-step sequencer, songs, effects, a modulation matrix, USB/TRS MIDI and USB audio. Eight is the shared allocation pool; deadline headroom depends on the sound and USB load (measured PHYS example). The audio backport record covers PHYS decay cleanup, earlier overload recovery and their remaining FM-1 checks. The fork feature guide covers controls, defaults, compatibility limits and build identification. The upstream manual documents the shared instrument; some details may differ in this fork.

This fork incorporates upstream 1.8.0 features, including aftertouch, CLEAR ALL, step-edit undo, safer load dialogs and the FM6 AMS correction, with workflow improvements, deferred project autosave, native pixel typography, performance diagnostics and broader host/emulator regression coverage. The M8Stealth display uses native pixel lettering for both regular text and control/status badges, with stable number/unit placement (LCD typography). One native UI combines a focused parameter bank, full musical graphs and explicit editing-state feedback with readable names and stable settings lists with grouped detail pages, drawn in one rule-based look without boxes; the graph can follow the knob being turned (GRAPH). The global NORMAL/LARGE and FLAT/LINE choices are retired; physical readability and loaded-panel qualification remain pending. The diagnostic capability overview distinguishes the normal USB console and read-only host collector from opt-in assertion, crash-register, arithmetic-reproducer and screenshot builds, with their activation and evidence limits. A separate device control tool provides a guarded USB-MIDI warm restart for hardware tests, with BUSY refusal and verified boot return. It does not replace physical cold-power/recovery checks; device qualification is pending. An opt-in device-screen capture diagnostic exports firmware-rendered static HOME/menu pixels with device build provenance over USB SERIAL. Its explicit --wake option silently wakes and holds the current view for capture. It is disabled in normal builds and does not measure physical LCD colours or backlight glow. MIDI timing and DSP hardening retains external-clock phase, timestamps TRS input during rendering, and guards invalid tempo. Tessera MIDI fixes also accept fragmented USB SysEx and let local PLAY and held ARP keys work with a stopped external master. Device results qualify USB pulse-count phase with CPU2 OFF; physical TRS and CPU2 ON clock-phase checks remain pending. Five portable engines live in the pinned Felucca-Engines fork; initial standard/reduced engine build profiles are implemented. Versioned profile contracts and exact post-link resource reports expose supported recipes and their measured build allocations. Broader engine selection and startup usage modes remain planned. An opt-in ADPCM profile and source-only SDL2 desktop build are also available; both retain their upstream experimental status. The optional second-core worker is beta and off by default. Bounded FM-1 comparisons cover an idle-poll mitigation for observed BAD_JOB failures on one unit; broader unit, engine/profile and TRS qualification remains pending. After a recorded worker failure it is held off across resets until the player retries it (guide). Shared effect-control smoothing experiments are implemented, with FM-1 listening and timing qualification pending.

The opt-in MACRO/Braids profile adds a fourteenth engine with 48 oscillator models and 51 factory sounds while keeping every standard engine. WAVE, FOLD and FBFM support eight voices; the 45 added models use one voice per part. This firmware-native integration is experimental and requires FELUCCA_PROFILE=macro; the normal build and hosted demo do not include it. The current full MACRO target recipe exceeds flash capacity; see the backport build limits. The FM-1 test procedure includes reproducible projects and songs. The device results record separates user-reported model/control and held-note checks from pending persistence, transport and timing qualification under #27. Early USB rescue and explicit update-loader compatibility are implemented; the recovery guide describes OCT− entry, existing installers and the combined FM-1 checks that remain pending.

Development direction and process

Gather and review: follow upstream and related forks for useful features, engines and optimizations, preserving attribution and checking licences and compatibility. The firmware watch keeps the source registry, commit reviews and historical backfill in a queryable repository ledger. The FM Lab adoption review plans optional FM6 sound-design features, original voice content and exact optimization experiments.
Integrate engines: use the shared engine library where appropriate and build profiles to fit the FM-1's limits. Keep sound IDs, saved projects and editor behavior compatible.
Measure and optimize: compare CPU cost, RAM use and firmware size against a baseline, while preserving sound, responsive controls and audio deadlines.
Validate and document: use host tests, target builds and emulator replay, then check hardware-dependent behavior on an FM-1. Keep planned work and pending device checks explicit.

The engine collection plan describes selecting MIT, GPL and native engines in one firmware build. The GPL collection is initialized; WAVE implementation and mixed-build integration remain pending.

The modularity roadmap and capacity plan track the larger work. The performance guide explains measurements; engine extension contracts describe integration boundaries. The stored-format inventory documents the first recovery stage: a read-only raw export, with historical firmware readers retained while browser migration is pending. This README summarizes the overall direction and meaningful milestones. The changelog gives a curated overview of additions, fixes, changes and optimizations. Detailed controls and evidence belong in focused guides, issues, PRs and release notes.

For reusable optimizations, fixes, diagnostics, testing and AI workflows, start with For firmware developers. Each area links implementation and evidence, including the limits of host/target results and pending hardware checks. The AI workflow guide explains keeping task context small while retaining the required evidence and validation.

Try, install or build

Fork builds: download this fork's Releases or CI artifacts, following the download and checksum guide.
Install: use the fork's .fwsc package with the fork web installer in Chrome or Edge, or follow the command-line instructions. Raw .bin files are build material. Installation is at your own risk; M-VAVE's updater or the installer's Return to official V15 restores stock firmware (the command-line installer also takes the exact official V16). See compatible bootloaders and firmware for V16's bootloader, m-bootloader and M-VAVE's FM1 Open firmware.
Explore: try the fork browser demo or fork web editor.
Build and test: start with BUILDING.md, including engine profiles and testing a PR on hardware. For device reports, use the diagnostics guide.

git clone --recurse-submodules https://github.com/kmplngj/Felucca.git
cd Felucca
# Install the prerequisites in BUILDING.md (macOS: brew install uv), then:
uv run --locked --group build ./build.sh

The command-line PR testing helper uses the Python USB-MIDI updater with locked dependencies: uv run --locked --group midi tools/fm1_pr.py NUMBER. See its setup and usage.

The fork site follows successful full builds of main: the demo and installer use that firmware revision, and the editor comes from a pinned revision of our WebApp fork. Check the site's source revisions before testing; the live site can lag behind this checkout. See site deployment and review project compatibility before downgrading.

Development status

For now, I manage this fork's development and issues on my own, following my own priorities and wishes. This could change once the larger tasks I want to complete are done, with more room for community input and contributions.

This fork uses AI coding assistance for code, tests, documentation and maintenance. Design, sound design and direction remain mine; generative AI is not used for music, icons or artwork.

Credits and licence

Based on the work of Leo Kuroshita (@kurogedelic), Hügelton Instruments and the contributors credited in CREDITS.md. Contributions from upstream and other forks retain their attribution and licences.

Felucca is GPL-3.0-only. The Hügelton Sample Pack generator and its sounds are CC0 1.0. Bundled fonts, ported DSP and the five MIT-licensed engines in firmware/engines/ retain their own licences; see LICENSING.md and LICENSES/. M-VAVE and FM-1 are trademarks of their owners; this project is not affiliated with them.