ferrosintesis

A General MIDI synthesizer in pure Rust with zero third-party dependencies. Give it a .mid file, get stereo audio — no SoundFont required: the instruments are physical and spectral models (Karplus-Strong strings, modal partial banks, lip-valve brass, a cathedral pipe organ), and their attacks are reinforced by an embedded bank of public-domain recorded transients. cargo add ferrosintesis is the entire setup.

Most GM synthesis crates are SoundFont players: excellent if you have a good .sf2, but you must bring one. ferrosintesis is for the other case — a MIDI file in hand and nothing else on disk. It was built to render a catalog of generative albums and voiced with corresponding care; it plays any GM file faithfully.

Quick start

cargo add ferrosintesis

use ferrosintesis::offline::{self, Normalization, Options};
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let song = offline::load(Path::new("input.mid"))?;
    println!("{}: {:.1} s, {} events", song.title(), song.seconds(), song.events_len());

    // `Options` has private fields: build it from Default with the with_* builders.
    let opt = Options::default().with_reverb(0.25);

    // Bounded-memory render, -18 LUFS loudness normalization, -1 dBTP limit,
    // deterministic dither, and atomic WAV publication.
    let stats = offline::render_to_wav(
        &song,
        &opt,
        Path::new("output.wav"),
        Normalization::loudness(-18.0, -1.0),
    )?;
    eprintln!("{} voices, peak {:.3}", stats.voices_spawned, stats.peak);
    Ok(())
}

offline::parse(&bytes) is load for in-memory data. For progress, offline::render_to_wav_with_progress takes a FnMut(Progress) callback — rendered seconds, total seconds, active voices, and a fraction() helper. Song exposes title(), seconds(), initial_bpm(), events_len() and markers_len(). Errors are MidiError, a plain enum implementing std::error::Error.

The audio contract

offline::render_to_wav is the normal file path. It streams float audio to scratch beside the output, measures loudness while rendering, applies exact disk-backed normalization and true-peak limiting, then incrementally writes and atomically publishes the WAV. Audio working memory does not grow with track duration.

offline::render remains the lower-level alternative. It returns (Vec<f32>, Stats): interleaved stereo — left, right, left, right — at opt.sample_rate(), un-normalized. normalize_loudness, normalize_to_i16, and write_wav preserve the buffer-first building blocks for callers that need them. The measurement primitives — integrated_lufs, true_peak_dbtp, limit_true_peak — are public if you want your own gain staging.

Options

The fields are private: build with Options::default() plus the with_* methods, and read them back with the matching accessors (opt.sample_rate(), opt.echo(), …). That is what lets a later release add or rename a knob without breaking you.

Feature flags

embedded-samples (default) compiles twenty-five first-party asset crates into the binary: 1156 recorded WAVs -- attack transients, sustain loops, whole-voice instruments and the sampled drum kit -- embedding ~111 MiB of PCM. The synth uses them the way the Roland D-50 did — LA synthesis: play a real onset, crossfade into the modeled body — because the ear judges an instrument mostly by its first hundred milliseconds, and onsets (hammer strikes, bow bites, breath chiff, brass articulation) are what synthesis fakes worst.

The instrument models

The kalimba's lamella bank lives under GM 108, grouped with the Modal chromatic-percussion row above (not a gap in the table: 108 was previously missing from an earlier draft of this doc, now covered). If your material leans on GM 120–127 sound effects, all eight are now voiced: 120 fret noise plays a sampled finger-slide bank by default (modeled squeak under --no-samples), and 121–127 are dedicated modeled voices per the SFX row above.

Controllers

The rule throughout: an unauthored controller is inert. A channel that never sends one renders exactly as if the feature did not exist.

GM 0 piano recordings (CC0 bank select)

Bank-select MSB picks which recording voices GM 0 Acoustic Grand. Bank 0 is what a channel that never sends CC0 hears. Each recording carries its own onset calibration, so a slot's number never changes how its bank was baked.

Bank 0 became our own Yamaha B1 upright on 2026.07.26; the previous line-up shifted down one slot intact, so the VSCO upright that used to be the default is now bank 1. A CC0 value past the end plays the model alone. This table is checked against the code by gm0_cc0_table_in_the_readme_matches_the_source, so it cannot drift from the shipped routing the way the crate docs once did.

Score-authored amp (driven guitars 29/30)

A file can shape the driven-guitar amp and cabinet per channel, so two channels can be two different rigs. Address the six knobs by NRPN — MSB (CC99) = 0x30, LSB (CC98) = the index below, value on Data Entry MSB (CC6):

Every value is a signed offset from the shipped voicing, with 64 = as-shipped, so the offset composes with whatever GM29/GM30 already sound like. The base voicing differs by program (29 overdrive vs 30 distortion) and by bank (the CC0 alt bank is a lead amp), so the same NRPN value lands on four different starting points — the offset is relative to each. The shipped base for each is:

Notes: the parameters are inert on any channel not playing GM29/30; changing a knob mid-note is click-free (smoothed); and a channel that authors no amp NRPN renders exactly as the program voicing does. The values are channel state — they survive Program Change, CC0 and CC121, and reset only on GM System On.

The driven-guitar shaper runs at 4× oversampling. That is what makes these ranges possible: the tanh stages generate harmonics above the internal Nyquist which fold back into the audible band, and at 2× that fold-back consumed the whole alias budget with Drive alone at maximum, forcing every knob to stay narrow. 4× buys about 10 dB of margin for roughly 0.5 % of a CPU core per driven channel.

Realtime

ferrosintesis::live wraps the same engine for realtime use: RealtimeSynth::new(RealtimeOptions::default()), feed raw MIDI bytes with write_byte, and sum stereo blocks into your output buffer with render_add(frames, &mut out). It is the secondary surface — the crate is offline-first — but it is the same voices and the same mix.

Performance

Render in release. A release build (LTO) renders a dense, fully-orchestrated track at roughly 5x realtime on a current desktop — a four-minute piece in about fifty seconds — and sparser material considerably faster. Debug builds are dramatically slower and are not worth timing.

Sample provenance and licensing

The code is licensed MIT OR Apache-2.0. The embedded PCM is not: it comes from twenty-five first-party asset crates, and while most of them are CC0 1.0 and need no credit, ten are not. The asset crates contain nothing but that PCM and include_bytes!; the per-crate inventory, provenance and regeneration tooling live under tools/ferrosintesis-samples/, which is the authority on what each bank contains.

If you distribute a binary

A build with default features embeds all twenty-five banks. You must reproduce the notices of the ten attribution-bearing banks below. Each ships the exact required text in its own crate's NOTICE file — concatenating those ten files satisfies every licence here. The remaining fifteen banks are CC0 and require nothing.

This table is not maintained by hand. licensing.rs derives the attribution-bearing set from the embedded-samples feature list and each bank's own license field, and fails the build if a bank is missing here or ships without a packaged NOTICE — so a new CC-BY bank cannot land silently uncredited, which is exactly how five of these ten came to be omitted before (MM-BUG-KILN-00060). It caught the B1 upright the same way back when that first-party bank still declared MIT OR Apache-2.0: "we own it" is not an exemption the derivation recognises — correctly, since a downstream distributor has no way to know that. The B1 was re-dedicated CC0 1.0 on 2026.07.25 and so has left this table entirely. That is the point: it is the declared license field that moves a bank in or out here, never who happens to own it.

The CC0 banks

The remaining fifteen need no attribution: our own Yamaha B1 acoustic upright (the GM 0 default recording since 2026.07.26 — Arthur's instrument, performance and recording, dedicated to the public domain), the VSCO 2 Community Edition orchestral library (violin, flutes, brass, reeds, string sections), the FreePats Spanish classical guitar bank, our own recordings of an Eastman E1D steel-string acoustic (the GM 25 default bank in two articulations, picked and fingerstyle — first-party and CC0-dedicated, so there is no upstream to pin), the Discord SFZ GM Bank's Martin HD28 steel-string acoustic (which held that default slot until 2026.07.23 and is now the GM 25 CC0=2 alternate), the Versilian Community Sample Library (harpsichord, concert harp, timpani, Baroque recorders, ocarina — in ferrosintesis-samples-orchestral2), the VCSL Steinway and Kawai grands, sfzinstruments/ganjo, and the Freesound recording "Blown Bottle Two" (349867, by Terry93D) that is the whole GM 76 blown-bottle voice (ferrosintesis-samples-bottle). The generator pins every source — VSCO and VCSL to exact commits, FreePats and the Martin to SHA-256-verified archives, ganjo and MTG.SoloSax to commits, the MuseScore soundfont to a commit + SHA-256, and the Freesound bottle to a committed SHA-256-verified source.

MSRV and dependencies

Rust 1.87. The dependency closure is this crate plus its first-party sample-asset crates — no third-party code, no build scripts, and #![forbid(unsafe_code)] throughout.

Design

The long version — how each instrument model works, what the LA-synthesis layer is and why onsets matter most, the mix architecture bus by bus — is DESIGN.md.