moont/

lib.rs

// Copyright (C) 2021-2026 Geoff Hill <geoff@geoffhill.org>
// Copyright (C) 2003-2026 Dean Beeler, Jerome Fisher, Sergey V. Mikayev
//
// This program is free software: you can redistribute it and/or modify it
// under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 2.1 of the License, or (at
// your option) any later version. Read COPYING.LESSER.txt for details.

//! Roland CM-32L synthesizer emulator.
//!
//! Renders 32kHz stereo PCM audio from MIDI input. Based on
//! [Munt](https://github.com/munt/munt/), with no external dependencies.
//!
//! The CM-32L is in the [MT-32 family](https://en.wikipedia.org/wiki/Roland_MT-32)
//! of synthesizers. This hardware predates
//! [General MIDI](https://en.wikipedia.org/wiki/General_MIDI), but
//! [many early 1990s PC games][vogons] directly support these synths.
//!
//! [vogons]: https://www.vogonswiki.com/index.php/List_of_MT-32-compatible_computer_games
//!
//! # Quick start
//!
//! ```no_run
//! use moont::{CM32L, Frame, Rom, Synth};
//!
//! let control = std::fs::read("CM32L_CONTROL.ROM").unwrap();
//! let pcm = std::fs::read("CM32L_PCM.ROM").unwrap();
//! let rom = Rom::new(&control, &pcm).expect("invalid ROM");
//! let mut synth = CM32L::new(rom);
//!
//! // Note On: channel 1, middle C, max velocity.
//! synth.play_msg(0x7f3c91);
//!
//! // Render 1 second of audio at 32 kHz.
//! let mut buf = vec![Frame(0, 0); 32000];
//! synth.render(&mut buf);
//!
//! // Note Off.
//! synth.play_msg(0x3c81);
//! ```
//!
//! # Loading ROMs
//!
//! The CM-32L ROMs are not distributed with this crate. Load them at
//! runtime with [`Rom::new`]:
//!
//! ```no_run
//! # use moont::Rom;
//! let control = std::fs::read("CM32L_CONTROL.ROM").unwrap();
//! let pcm = std::fs::read("CM32L_PCM.ROM").unwrap();
//! let rom = Rom::new(&control, &pcm).expect("invalid ROM");
//! ```
//!
//! With the **`bundle-rom`** feature, ROMs are parsed at compile time and
//! embedded in the binary, enabling `Rom::bundled()`:
//!
//! ```ignore
//! let rom = Rom::bundled();
//! ```
//!
//! # General MIDI translation
//!
//! The CM-32L uses its own instrument map. When the input is General MIDI,
//! use [`GmSynth`] to translate program changes, drum notes, and bank
//! selects into CM-32L equivalents:
//!
//! ```no_run
//! use moont::{GmSynth, Rom, Synth};
//!
//! let control = std::fs::read("CM32L_CONTROL.ROM").unwrap();
//! let pcm = std::fs::read("CM32L_PCM.ROM").unwrap();
//! let mut synth = GmSynth::new(Rom::new(&control, &pcm).unwrap());
//! synth.play_msg(0x7f3c91);
//! ```
//!
//! # Type-safe MIDI messages
//!
//! The [`midi::Message`] type provides validated message construction as
//! an alternative to raw `u32` values:
//!
//! ```
//! use moont::midi::Message;
//!
//! let msg = Message::note_on(60, 100, 0).unwrap();
//! let packed: u32 = msg.try_into().unwrap();
//! ```
//!
//! # Features
//!
//! | Feature | Description |
//! |---------|-------------|
//! | **`bundle-rom`** | Embed pre-parsed ROMs in the binary (enables `Rom::bundled()`) |
//! | **`tracing`** | Emit [`tracing`](https://docs.rs/tracing) spans and events |
//!
//! # Related crates
//!
//! | Crate | Description |
//! |-------|-------------|
//! | [`moont-render`](https://docs.rs/moont-render) | Render .mid files to .wav |
//! | [`moont-live`](https://docs.rs/moont-live) | Real-time ALSA MIDI sink |
//! | [`moont-web`](https://docs.rs/moont-web) | WebAssembly wrapper with Web Audio API |

#[cfg(feature = "tracing")]
macro_rules! trace {
    ($($arg:tt)*) => { ::tracing::trace!($($arg)*) };
}
#[cfg(not(feature = "tracing"))]
macro_rules! trace {
    ($($arg:tt)*) => {};
}

#[cfg(feature = "tracing")]
macro_rules! debug {
    ($($arg:tt)*) => { ::tracing::debug!($($arg)*) };
}
#[cfg(not(feature = "tracing"))]
macro_rules! debug {
    ($($arg:tt)*) => {};
}

#[cfg(feature = "tracing")]
macro_rules! info {
    ($($arg:tt)*) => { ::tracing::info!($($arg)*) };
}
#[cfg(not(feature = "tracing"))]
macro_rules! info {
    ($($arg:tt)*) => {};
}

#[cfg(feature = "tracing")]
macro_rules! warn {
    ($($arg:tt)*) => { ::tracing::warn!($($arg)*) };
}
#[cfg(not(feature = "tracing"))]
macro_rules! warn {
    ($($arg:tt)*) => {};
}

#[cfg(feature = "tracing")]
macro_rules! debug_span {
    ($($arg:tt)*) => { ::tracing::debug_span!($($arg)*).entered() };
}
#[cfg(not(feature = "tracing"))]
macro_rules! debug_span {
    ($($arg:tt)*) => {
        ()
    };
}

mod dispatch;
mod element;
pub mod gm;
mod lpf;
pub mod midi;
mod midiqueue;
pub mod param;
mod pcm;
mod ramp;
mod render;
mod reverb;
pub mod rom;
pub mod smf;
mod synth;
mod sysex;
mod tables;
mod tva;
mod tvf;
mod tvp;

#[cfg(feature = "bundle-rom")]
mod bundle;

pub use gm::GmSynth;
pub use rom::Rom;

/// Audio frames (stereo samples) per second.
pub const SAMPLE_RATE: u32 = 32000;

#[cfg(feature = "bundle-rom")]
impl Rom {
    /// Returns the bundled ROM (pre-parsed at compile time).
    ///
    /// Each call returns a new [`Rom`] containing references to the
    /// embedded ROM data. This is a cheap operation (two pointers).
    ///
    /// Requires the **`bundle-rom`** feature and CM-32L ROM files at
    /// `testdata/rom/` during compilation.
    pub const fn bundled() -> Rom {
        bundle::bundled_rom()
    }
}

use element::{PartArena, PartialArena, PolyArena};
use lpf::CoarseLpf;
use midiqueue::MidiQueue;
use reverb::Reverb;
use sysex::MemState;

/// Stereo PCM audio frame of two (left, right) 16-bit little-endian samples.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Hash)]
#[repr(C)]
pub struct Frame(pub i16, pub i16);

/// Interface for MIDI synthesizers.
///
/// MIDI messages must be added in time-ascending order, otherwise they will
/// be ignored during rendering.
pub trait Synth {
    /// Returns the number of frames rendered so far.
    fn current_time(&self) -> u32;

    /// Enqueues one MIDI message at a specific frame.
    ///
    /// A MIDI baud rate transfer delay is added to `time` before
    /// enqueuing: 24 frames for 3-byte messages, 16 frames for
    /// 2-byte messages (program change and channel pressure).
    fn play_msg_at(&mut self, msg: u32, time: u32) -> bool;

    /// Enqueues one MIDI message starting from the current frame.
    ///
    /// Equivalent to `play_msg_at(msg, current_time())`. The message
    /// is processed after the MIDI baud rate transfer delay (16 or
    /// 24 frames), not at the current frame itself.
    fn play_msg(&mut self, msg: u32) -> bool {
        self.play_msg_at(msg, self.current_time())
    }

    /// Enqueues one MIDI System Exclusive message at a specific frame.
    ///
    /// No transfer delay is added; the message is processed at
    /// exactly the given frame.
    fn play_sysex_at(&mut self, sysex: &[u8], time: u32) -> bool;

    /// Enqueues one MIDI System Exclusive message at the current frame.
    ///
    /// Equivalent to `play_sysex_at(sysex, current_time())`. The
    /// message is processed immediately at the current frame.
    fn play_sysex(&mut self, sysex: &[u8]) -> bool {
        self.play_sysex_at(sysex, self.current_time())
    }

    /// Renders audio samples into a slice of frames.
    ///
    /// The output slice is filled with stereo audio frames. Each [`Frame`]
    /// is comprised of two 16-bit, native-endian, signed PCM audio samples.
    ///
    /// The internal clock is advanced by the number of frames rendered.
    fn render(&mut self, out: &mut [Frame]);
}

/// CM-32L synthesizer state.
#[derive(Debug)]
pub struct CM32L {
    time: u32,
    rom: Rom,
    mem: Box<MemState>,
    midi_queue: MidiQueue,
    parts: PartArena,
    free_polys: PolyArena,
    free_partials: PartialArena,
    reverb: Reverb,
    lpf_left: CoarseLpf,
    lpf_right: CoarseLpf,
    last_midi_timestamp: u32,
    chantable: [[u8; 9]; 16],
    aborting_part_ix: usize,
    master_tune_pitch_delta: i32,
}

impl CM32L {
    /// Creates a new synthesizer instance.
    ///
    /// Use the bundled ROM or load ROMs at runtime:
    /// - `CM32L::new(Rom::bundled())` - uses bundled ROM
    /// - `CM32L::new(Rom::new(ctrl, pcm)?)` - for dynamically loaded ROMs
    pub fn new(rom: Rom) -> CM32L {
        let reverb = Reverb::new();
        let mem = MemState::new(&rom);
        let master_volume = mem.master_volume;
        let parts = PartArena::new(master_volume, &rom);
        let free_partials = PartialArena::new(&rom.meta().reserve_settings);
        let mut chantable = [[0xFF; 9]; 16];
        dispatch::rebuild_chantable(&mut chantable, &mem.raw_system);
        CM32L {
            time: 0,
            rom,
            mem,
            midi_queue: MidiQueue::new(),
            parts,
            free_polys: PolyArena::new(),
            free_partials,
            reverb,
            lpf_left: CoarseLpf::new(),
            lpf_right: CoarseLpf::new(),
            last_midi_timestamp: 0,
            chantable,
            aborting_part_ix: 0,
            master_tune_pitch_delta: 0,
        }
    }
}