gmuwe 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# What changes, version by version
+
+## 0.1.0
+
+The first release on its own. Until now the engine was a part of `groggo`, the library for point-and-click adventures, where it was built against five scores and a battery of listening probes; `groggo/gmuwe` keeps re-exporting it.
+
+- **`MusicEngine`**: plays a `.mid` file through the synthesizer, changes piece on the bar, the beat or a marker the composer wrote, resumes a piece where it left off, fades, renders a score offline into an `AudioBuffer`, and tells where it is: `position()` and `onBeat()` with the audio-clock instant each beat falls on.
+- **`FmSynth`**: a two-operator FM synthesizer with a bank covering the 128 General MIDI programs, the GM2/GS drum kits, per-channel reverb, chorus, pan, rotary and drive, a tempo-locked delay, a limiter on the output and a polyphony reserve that keeps a full chord from clipping. Any instrument can be replaced by a sampled one.
+- **`MidiInput`**: the General MIDI message set played live, from a keyboard or your own code, with the same laws as a score.
+- **`parseMidi`** and the musical-time helpers: ticks, seconds, bars and beats, the next boundary of a grid.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Communication Box
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# gMUWE
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+*A music engine for the browser: an FM synthesizer with a General MIDI bank, a sequencer that plays `.mid` files and knows where the bar is, and a live MIDI input. No dependencies, about 40 KB gzipped.*
+
+```sh
+npm install gmuwe
+```
+
+## A note in three lines
+
+```js
+import { MidiInput } from 'gmuwe';
+
+const input = new MidiInput({ context: new AudioContext() });
+input.programChange(0, 73); // a flute on channel 1
+input.noteOn(0, 60, 100); // middle C, now
+input.noteOff(0, 60, input.ctx.currentTime + 0.5); // released half a second later
+```
+
+A MIDI keyboard takes two more:
+
+```js
+const midi = await navigator.requestMIDIAccess();
+for (const port of midi.inputs.values()) port.onmidimessage = (e) => input.message(e.data);
+```
+
+## A score in two
+
+```js
+import { MusicEngine } from 'gmuwe';
+
+const music = new MusicEngine({ context: new AudioContext(), fetchFile: (file) => fetch(file).then((r) => r.arrayBuffer()) });
+await music.play('theme.mid');
+```
+
+The score is a standard MIDI file, written with any notation program. The engine reads its programs, its controllers, its tempo map, its time signatures and its markers, and from then on the music is something a program can talk to:
+
+```js
+await music.play('battle.mid', { quantize: 'bar' }); // the change falls on the next bar line
+await music.play('ending.mid', { quantize: 'marker', marker: 'coda' }); // or where the composer put a mark
+music.onMarker((name, when) => { /* the scene waits for the music */ });
+music.onBeat((beat, when) => { /* a light pulses on the beat, at `when` on the audio clock */ });
+music.position(); // { bar, beat, tick, seconds, bpm }
+const buffer = await music.render('theme.mid'); // the score played once, offline, as an AudioBuffer
+```
+
+A piece resumed is resumed where it was left; a piece stopped on a marker stops on the marker; the loop returns to the tick you say. The browser starts no sound without a gesture of the user: create the `AudioContext` inside a click.
+
+## What is inside
+
+- **A two-operator FM synthesizer**, in the style of the sound cards of the Nineties, with a bank that covers the 128 General MIDI programs and the GM2/GS drum kits. Reverb, chorus, pan, a rotary speaker and a drive per channel, a delay locked to the tempo, a limiter on the output, and a polyphony reserve that keeps a full chord from clipping instead of letting it.
+- **Sampled instruments in place of synthesized ones**, declared per program, with zones, loops and envelopes, played by the same sequencer under the same laws.
+- **A sequencer** that schedules on the audio clock with a lookahead, follows the tempo map and the time signatures, applies the sustain pedal, the pitch wheel and the volume and expression curves inside a held note, and reports beats and markers with the instant they fall on.
+- **A live input** that plays a note exactly as the same note in a score: the pedal holds it, the wheel bends it, the controllers shape it.
+
+## Where to read more
+
+The engine was born inside [Groggo](https://groggo.dev-box.it), a library for point-and-click adventures, and the chapter [Sound and music](https://groggo.dev-box.it/en/14-sound-and-music.html) of its guide is the engine's manual: the General MIDI table, the effects, the drum kits, the sample bank, the markers and the live input. Whoever installs Groggo reaches the engine as `groggo/gmuwe`.
+
+MIT. gMUWE is a project of [Communication Box](https://communicationbox.it).