# moont-live

Real-time CM-32L MIDI sink using ALSA, powered by the
[moont](https://crates.io/crates/moont) synthesizer. Appears as an ALSA
sequencer port that accepts MIDI input and renders audio to the system output.


## Build Requirements

- `alsa-lib-devel` (Fedora) or `libasound2-dev` (Debian/Ubuntu)


## Usage

    moont-live [OPTIONS] --control <ROM> --pcm <ROM>

With the `bundle-rom` feature, ROM arguments are optional:

    cargo install moont-live --features bundle-rom
    moont-live [OPTIONS]


### Options

| Flag | Description |
|------|-------------|
| `-c`, `--control ROM` | CM-32L control ROM path |
| `-p`, `--pcm ROM` | CM-32L PCM ROM path |
| `-g`, `--gm` | Enable General MIDI translation |
| `-d`, `--device DEV` | ALSA PCM device (default: `default`) |
| `-b`, `--buffer N` | Period size in frames (default: 512) |
| `-v`, `--verbose` | Log MIDI events to stderr |
| `-l`, `--list` | List MIDI ports and exit |


## Connecting MIDI Sources

After starting `moont-live`, connect a MIDI source with `aconnect`:

    # List available ports
    aconnect -l

    # Connect a source to moont
    aconnect <source_client>:<source_port> <moont_client>:<moont_port>

PipeWire and JACK users can also route MIDI using their respective tools
(e.g. `pw-link`, `qjackctl`).


## General MIDI Mode

The CM-32L uses a completely different instrument map from General MIDI.
The `--gm` flag enables a best-effort translation layer:

- Remaps GM program numbers to the closest CM-32L equivalents
- Remaps GM drum notes to CM-32L rhythm notes
- Reassigns Part 1 to MIDI channel 1 (CM-32L default is channel 2)
- Sets pitch bend range to +/-2 semitones (GM default, vs CM-32L's +/-12)

Without `--gm`, MIDI passes through unmodified, which is correct for
CM-32L-native sources (DOS games via DOSBox, ScummVM, etc).


## REPL Commands

The interactive prompt is available only with the `repl` feature:

    cargo install moont-live --features repl

This adds a prompt with runtime controls:

- `set part <1-9> [program <0-127>] [volume <0-100>]`
- `set master volume <0-100>`
- `set reverb [mode <0-3>] [time <0-7>] [level <0-7>]`
- `reset`
- `help`
- `quit`

Prompt command history is stored in `.moont-history`.


## Related Crates

| Crate | Description |
|-------|-------------|
| [moont](https://crates.io/crates/moont) | Core CM-32L synthesizer library |
| [moont-render](https://crates.io/crates/moont-render) | Render .mid files to .wav |
| [moont-web](https://crates.io/crates/moont-web) | WebAssembly wrapper with Web Audio API |


## License

moont-live is distributed under LGPL 2.1+.

> Copyright (C) 2021-2026 Geoff Hill <geoff@geoffhill.org>

This library 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](COPYING.LESSER.txt),
or (at your option) any later version.
