Re-SiON

A small player for SiON MML music. Give it MML text and it renders stereo audio. It has no dependencies and is no_std, so the same code runs as a Rust crate, as WebAssembly in the browser, and as a C library.

Based on SiON by keim (MIT), while referencing GDSiON by Yuri Sizov (MIT) for correctness. See the license.

Quick start

Every interface works the same way: create a song from MML, then ask it for audio a block at a time until it says it has finished.

Rust

[dependencies]
sion = { path = "../sion" }
use sion::{Song, RATE};

let mut song = Song::new("t120 %5@0 l8 cdefgab<c;");
let mut buf = vec![0f32; 2 * 1024]; // 1024 frames
while song.render(&mut buf) {
    // buf holds 1024 stereo frames at RATE Hz: send them to your audio output.
}

JavaScript (browser, Node, Deno)

Copy sion.wasm and sion.js next to your page.

import { Sion } from "./sion.js";

const sion = await Sion.load(fetch("sion.wasm"));
const song = sion.song("t120 %5@0 l8 cdefgab<c;");
const buf = new Float32Array(2 * 1024);
while (song.render(buf)) {
  // play buf (interleaved stereo, sion.rate Hz)
}
song.free(); // songs live in wasm memory: free them when done

C / C++

Link against libsion.so (Linux) or sion.dll (Windows) and include sion.h.

#include <string.h>
#include "sion.h"

const char *mml = "t120 %5@0 l8 cdefgab<c;";
SionSong *song = sion_song_new(mml, strlen(mml));
float buf[2 * 1024];
while (sion_song_render(song, buf, 1024)) {
    /* play buf (interleaved stereo, sion_rate() Hz) */
}
sion_song_free(song);

How playback works

Rendering. Each render call fills the buffer and moves playback forward by that many frames. Any buffer size works. Samples are clamped to -1..1.

Declicking. A key-on, volume change or pan change can make a track's output jump in the middle of a wave: a waveform restarting from its first frame, or a hard pan flip. As in trackers, such a jump is smoothed over: the output picks up where it would have been without the change, and the difference fades out over about a millisecond. On a key-on, or when the volume comes up from silence, only the old level fades out, so attacks stay sharp. Everything else is exactly SiON's output, and so is any track that no such change touches.

Ending. render returns false once every track has ended and the output has been silent for half a second, so release tails are not cut off. A song with a $ loop point never ends: stop it yourself.

Length. length measures one pass through the MML, in frames, without rendering any audio. One pass ends when every track has either finished or jumped back to its $ once. It is capped at one hour. Release tails are not included.

Looping. For a song with $, loop_start gives the frame playback returns to after length frames. Use both to show a loop region or to seek within a looping song.

Seeking. skip(frames) moves forward without producing output. It jumps from event to event instead of synthesizing every sample, so it is fast even for long songs. The result is close to, but not exactly, what continuous playback gives: echoes from before the last quarter second are missing, and vibrato phases drift. With declicking on, the jump is crossfaded over about 6 ms (256 frames): the audio that would have played next fades out as the audio after the skip fades in, so nothing pops. A new song, with nothing played yet, just fades in. A player that renders ahead into a buffer and drops it on a seek should fade that buffer out itself from the frame playing, and call forget_rendered() before skipping, because the song is then past what was heard. To seek backwards, create a new song and skip from the start.

Following along. notes() gives, per track, the byte offset in the MML text of the note playing now (-1 for a rest or an ended track). Use it to highlight the playing notes in an editor. It needs the spans feature (always on in the WebAssembly build).

PCM samples. Modules %7 and %10 play recorded samples. Embed them in the MML with #PCMB, or set them from code with set_sample, which replaces any #PCMB of the same number. #PCMWAVE, #PCMVOICE and #SAMPLER build instruments and drum kits out of them (see Sample instruments and drum kits).

Rust API

Everything is on sion::Song. The crate is not on crates.io, so add it as a path or git dependency.

ItemDescription
RATE: f32Output sample rate: 44100.0.
Song::new(mml: &str) -> SongParse MML. Never fails: anything it does not understand is ignored.
Song::from_bytes(mml: &[u8]) -> SongSame, from bytes. Only the ASCII in the MML matters.
song.render(out: &mut [f32]) -> boolFill out with interleaved stereo. false once the song has finished.
song.skip(frames: u64) -> boolMove ahead without output (see Seeking). false once finished.
song.forget_rendered()Next skip fades in from silence instead of crossfading (see Seeking).
song.position() -> u64Frames rendered or skipped so far.
song.notes() -> impl Iterator<Item = i32>Per track, the byte offset of the playing note, or -1. Needs the spans feature.
song.set_sample(n: usize, s: Sample)Set PCM sample n (0..255) for %7 / %10.
Song::length(mml: &str) -> u64Frames in one pass through the MML, without rendering.
Song::loop_start(mml: &str) -> Option<u64>Frame a $ loop returns to after length. None if the song ends.
Song::length_bytes, Song::loop_start_byteslength and loop_start for MML as bytes.

Sample describes one PCM sample:

FieldDescription
data: Vec<f32>Mono samples in -1..1.
rate: f32Sample rate it was recorded at, in Hz.
key: i32MIDI note that plays it at its original pitch (60 = middle C).
lp: Option<usize>Frame to loop back to after the end, or None to play once.
bidi: boolLoop back and forth instead of jumping back.
use sion::{Sample, Song};

let mut song = Song::new("%7@0 o5 l4 c e g;");
song.set_sample(0, Sample { data: my_wave, rate: 22050.0, key: 60, lp: None, bidi: false });

JavaScript API

sion.js wraps sion.wasm. It has no dependencies and works in browsers, Node and Deno.

Sion

MemberDescription
await Sion.load(source)Load the module. source: a fetch response, bytes, or a WebAssembly.Module.
sion.rateOutput sample rate (44100).
sion.song(mml)Parse MML text into a Song.
sion.length(mml)Frames in one pass through the MML, without rendering.
sion.loopStart(mml)Frame a $ loop returns to after length. -1 if the song ends.

Song

MemberDescription
song.render(buf)Fill a Float32Array with interleaved stereo. false once the song has finished.
song.skip(frames)Move ahead without output. false once finished.
song.forgetRendered()Next skip fades in from silence instead of crossfading.
song.positionFrames rendered or skipped so far.
song.notes()Array with, per track, the UTF-8 byte offset of the playing note, or -1.
song.setSample(n, data, rate, key, loopStart, bidi)Set PCM sample n (0..255). data: mono floats in -1..1. Optional: key (60), loopStart (-1 = no loop), bidi (false).
song.free()Release the song's memory. Do not use the song afterwards.

notes() offsets count UTF-8 bytes, not JS string characters. They only differ if the MML contains non-ASCII text, such as comments in Japanese.

To play in real time, render inside an AudioWorklet. The web player's worklet.js and player.js show one way to do it.

C API

Declared in sion.h. All functions are safe to call with a NULL song or MML pointer.

FunctionDescription
uint32_t sion_rate(void)Output sample rate (44100).
SionSong *sion_song_new(const char *mml, size_t len)Parse len bytes of MML. The text need not end in NUL.
void sion_song_free(SionSong *song)Free a song.
int32_t sion_song_render(SionSong *song, float *out, size_t frames)Fill out with 2 * frames floats. 1 while playing, 0 once finished.
int32_t sion_song_skip(SionSong *song, uint64_t frames)Move ahead without output. 1 while playing, 0 once finished.
void sion_song_forget_rendered(SionSong *song)Next skip fades in from silence instead of crossfading.
uint64_t sion_song_position(const SionSong *song)Frames rendered or skipped so far.
uint64_t sion_length(const char *mml, size_t len)Frames in one pass through the MML.
int64_t sion_loop_start(const char *mml, size_t len)Frame a $ loop returns to after sion_length. -1 if the song ends.
void sion_song_set_sample(song, n, data, frames, rate, key, loop_start, bidi)Set PCM sample n (0..255) from frames mono floats. Negative loop_start = no loop. Nonzero bidi = back-and-forth loop. See sion.h for the argument types.

A song is not thread-safe: use each SionSong from one thread at a time. Separate songs are independent.

Building

The crate builds on stable Rust. The release scripts need nightly with rust-src, which they use to make the outputs small.

CommandOutput
cargo build --releaseThe Rust library.
cargo testRuns the tests in tests/.
./build-wasm.shtarget/wasm32-unknown-unknown/wasm/sion.wasm. Runs wasm-opt too if Binaryen is installed.
./build-ffi.sh [TARGET]target/TARGET/ffi/libsion.so, or sion.dll + libsion.dll.a for a Windows target.

Cargo features:

FeatureDescription
spansTrack which note in the MML each track is playing (Song::notes). Slightly slower parsing.
smallNightly only. For size-optimized builds: keeps the per-sample code optimized for speed.
wasmThe WebAssembly exports. Used by build-wasm.sh; not for use as a dependency.
ffiThe C exports. Used by build-ffi.sh; not for use as a dependency.

MML support

This section is a summary. For each command's full meaning and parameters, see the SiON MML reference manual.

Structure

Notes and timing

CommandMeaning
c d e f g a bNotes. Add + or # for sharp and - for flat, then an optional length: c+8, e-4..
rRest.
4, 8., 16.. (after a note)Length: a note value, with optional dots.
^Tie: adds a length to the previous note (c4^16).
&Slur: the next note changes pitch without re-attacking.
&&Hold the note into the next one, which re-attacks.
*Glide: bend from this note to the next over this note's length.
lDefault note length (l8).
o, <, >Octave (o5 is the default), up one, down one.
tTempo in BPM (t120).
qGate: the share of each note that sounds, in eighths (q6, default 6).
@qGate in absolute time: shorten notes, delay key-on.
[ ... | ... ]nRepeat n times (default 2). The part after | is skipped on the last time.
$Loop point: when the track ends, it jumps back here forever.
kt, !@nsTranspose in semitones.
kDetune, in 1/64 semitones. Fractions are allowed (k-12.375).
!@krDetune relative to the current value.
poPortamento: slide between slurred notes over n frames.

Volume and panning

CommandMeaning
vVolume, 0..16 (default 16).
(, )Volume up / down by one step.
xExpression (a second volume), 0..128.
%v, %xVolume curve used by v and x.
@vVolume 0..128, then up to 7 effect send levels (@v64,32 sends half to #EFFECT1).
pPan, 0 (left) to 8 (right); 4 is the center.
@pFine pan, -64 (left) to 64 (right).
@maskIgnore later commands of some kinds (bits: 1 volume, 2 pan, 4 gate, 8 tone, 16 envelope, 32 modulation, 64 slur).

Sound modules

%n picks the sound source for the track, and @n picks a tone within it.

ModuleSound
%0PSG: square wave and noise.
%1NES APU: pulse waves, triangle, noise.
%2Noise.
%3Yamaha MA-3 waveforms.
%4Custom wavetables from #WAV, #WAVB or #WAVCOLOR.
%5All built-in waveforms (%5@0 is a sine wave).
%6FM voice defined with #@, #OPM@, #OPN@, #OPL@, #OPX@, #MA@ or #AL@.
%7PCM sample: %7@n plays #PCMB n, or instrument n if #PCMWAVE / #PCMVOICE define one.
%8Pulse wave with adjustable duty.
%9Ramp wave.
%10Sampler: each key plays its own sample at its own rate (a drum kit). %10@n picks bank n (0..3) of #SAMPLER keys; without any, key n plays #PCMB n.
%11Plucked string (Karplus–Strong).
%12Game Boy.
%13Konami VRC6.
%14Commodore SID.

Tone shaping

CommandMeaning
@Tone number, then optional envelope: @tone,ar,dr,sr,rr,sl,tl,….
sRelease rate, then an optional pitch sweep during release.
@rrRelease rate of the carriers.
@al, @fbFM algorithm (operator count, connection) and feedback.
iSelect which FM operator the next operator commands change.
@tl, @ml, @dt, @fx, @ph, @se, @erPer-operator total level, multiple, detune, fixed pitch, start phase, SSG envelope, envelope reset.
@ph on %7 / %10Start frame (fractions and negative values allowed), then optionally how many frames to play.
@f, %fResonant filter with its own envelope; %f picks low-pass (0), band-pass (1) or high-pass (2).
@lfoLFO speed and waveform for mp / ma.
mp, maVibrato (pitch) and tremolo (amplitude) depth, optionally fading in.
@clockScale the FM operators' clock, in percent.
@fpsEnvelope table speed for this track, in steps per second.
@i, @o, @rPipes: route one track's output into another as FM input or ring modulation.

Envelope tables

Define a table with #TABLEn{...}, then apply it per step to a note:

CommandApplies the table to
naAmplitude.
ntNote (in semitones).
npPitch (in 1/64 semitones).
nfFilter cutoff.
@@Tone number.

Prefix with _ (_na) for the release part of the note. na values set the expression (x, 0..128) itself; !na adds them to the track's x. A table can also be written inline: na{0,8,16}. Table syntax supports (a,b)n interpolation, [...]n repeats, a | loop point and a *scale+offset suffix.

As in SiON, a table's first value applies at the key-on (or key-off, for _ tables) and each next one an envelope frame later (#FPS, @fps: 735 samples at the default 60), and values are read as (int)(v + 0.5), so a negative value comes out one higher (-10 plays as -9; write -11 for -10).

Definitions (# statements)

StatementMeaning
#A=...;Macro: A in a track is replaced by the text. A(3) plays it transposed. Also #A+=, #ABC= and #A-C=.
#MACRO{dynamic};Expand macros where they are used rather than where they are defined.
#@n{...} and chip formatsFM voice n: #@, #OPM@, #OPN@, #OPL@, #OPX@, #MA@, #AL@. Text after } runs when the voice is selected.
#TABLEn{...}Envelope table n (0..254).
#WAVn{...}Wavetable n for %4, as values -128..127.
#WAVBn{...}Wavetable n as hex bytes.
#WAVCOLORn{hex}Wavetable n from a wave color: hex digits, lowest first, set the levels (0-f) of harmonics 1, 2, 3, 4, 5, 6 and 8; an 8th digit picks the base wave (%5@n, sine by default). Also #WAVC.
#PCMBn{data}rate,key,loop,flags,levelPCM sample n: see below.
#PCMWAVEn{sample,note,from,to,,start,end,loop}Instrument n for %7: keys from..to play #PCMB sample. See below.
#PCMVOICEn{...}commandsEnvelope, key scaling and commands for instrument n. See below.
#SAMPLERn{sample,hold,pan,,start,end,loop}%10 drum kit key: see below.
#EFFECTn{...}Effect chain: see below.
#FM{...}Wire the following tracks into one FM sound (#FM{B3(A)}: A modulates B).
#SIGN{...}Key signature: D, F#m, Bb… or a list like c+ f+.
#TMODE{unit=n \| timerb=n \| fps=n}How t values are read.
#VMODE{n88 \| mdx \| psg \| %v.. \| %x..}Volume curves, matching other MML dialects.
#QUANT{n}Steps for q (default 8).
#FPS{n}Envelope table speed for all tracks (default 60).
#REVSwap the direction of < > and ( ). #REV{oct} or #REV{vol} swaps only one.
#FBMODE{chip}Chip-style FM feedback.
#ENDStop reading here.

Sample instruments and drum kits

#PCMB holds the audio. These three statements say how to play it, and refer to a #PCMB by its number, so one sample can be used by several instruments without being stored again. They can come before or after the #PCMBs they use. Arguments can be left out (#PCMWAVE0{3,,0,59}): each one has a default.

#PCMWAVEn{sample,note,from,to,channels,start,end,loop} gives %7 instrument n (0..255) a sample for a range of keys. Several of them with different ranges make one instrument play different samples on different keys (a multisample), and switching between them needs no @n:

ArgumentMeaning (default)
sampleThe #PCMB number.
noteThe note at which the sample plays at its #PCMB rate (the #PCMB's key). Fractions are allowed.
from, toThe keys that play it (0, 127). to -1 means just from. Keys outside every range are silent.
channelsIgnored: samples are mono.
start, endThe first frame, and the frame to stop before, counted in the #PCMB (all of it).
loopThe frame to loop from, counted in the #PCMB (the #PCMB's own loop). -1: no loop. Below -1, such as -500: loop the last 500 frames.

#PCMVOICEn{volume note,volume range,volume amount,pan note,pan range,pan width,ar,dr,sr,rr,sl}commands sets how instrument n plays:

A #PCMVOICE without a #PCMWAVE plays #PCMB n on every key.

#SAMPLERn{sample,hold,pan,channels,start,end,loop} makes key n % 128 of %10 bank n / 128 play a sample, at its own rate, whatever the pitch. hold 1 plays the sample to its end after key-off (0). pan (-64..64) is added to the track's pan (0). channels, start, end and loop are as for #PCMWAVE. In a bank that has any #SAMPLER, keys without one are silent.

#PCMB0{...}22050,48;  #PCMB1{...}22050,72;   // a low and a high recording of the same instrument
#PCMWAVE0{0,,0,59};   #PCMWAVE0{1,,60,127};  // instrument 0: sample 0 below o5c, sample 1 from there
#PCMVOICE0{,,,,,,63,0,0,40,0};               // with a slower release
#PCMB2{...}; #PCMB3{...};
#SAMPLER36{2}; #SAMPLER38{3,1};              // kit: kick on o3c, snare on o3d (playing on through key-off)
%7@0 l8 o4 cegb<ceg;
%10 l8 o3 cdcd;

Effects

#EFFECT0 is the master chain, which everything passes through. #EFFECT1 to #EFFECT7 are send effects, fed by @v send levels. Units run in order. After }, @v, p and @p set the effect's return level and pan.

#EFFECT0{ eq 100,100,120 };
#EFFECT1{ reverb 70,40,80,100 } @v64;
%5@0 @v100,40 l8 cdefgab<c;
UnitParameters (defaults)
delaytime ms (250), feedback % (25), cross 0/1 (0), wet % (100)
reverbdelay 1 % (70), delay 2 % (40), feedback % (80), wet % (100)
chorusdelay ms (20), feedback % (20), rate Hz (4), depth (20), wet % (50), invert (1)
autopanrate Hz (1), width % (100)
distpre-gain dB (-60), post-gain dB (18), low-pass Hz (2400), slope (1)
wswave shaper: amount % (50), output % (100)
compthreshold % (70), window ms (50), attack ms (20), release ms (20), max gain dB (6), mix % (50)
dsdown-sampler: rate shift (0), bits (16), channels (2)
speakerhardness % (20)
stereoinvert (0), width % (140), rotation % (0)
eqlow %, mid %, high % (100 each), low/mid split Hz (880), mid/high split Hz (5000)
lf hf bf nf pf af lb hblow-pass, high-pass, band-pass, notch, peak, all-pass, low shelf, high shelf: frequency Hz, bandwidth (1), gain dB (6)
nlf nhflow/high-pass swept by tables: cutoff table, resonance table, steps per second (20)
voweloutput % (100), then six formant frequency/gain pairs

Differences from SiON

Additions:

#SAMPLER, #PCMWAVE and #PCMVOICE use SiON's names and arguments, with one difference: where SiON expects the name of a sound, they take a #PCMB number. In SiON these statements hold no audio. The braces name a sound that the program running SiON loaded and registered under that name. An MML file can't carry the sound, so a song that uses them only plays inside that program. Here the audio is in the file, in #PCMB, and these statements point at it, so the whole song is one MML file. (In SiON, registering sounds under the names 0, 1, … would make the same text work.) The rest differs only in small ways:

Playback differs in one way: jumps from key-ons and volume and pan changes are smoothed over (see Declicking).

Not supported: event triggers (%t, %e), which are skipped.