{"id":2009,"date":"2016-02-11T16:00:51","date_gmt":"2016-02-11T16:00:51","guid":{"rendered":"https:\/\/www.reenigne.org\/blog\/?p=2009"},"modified":"2016-02-10T16:20:50","modified_gmt":"2016-02-10T16:20:50","slug":"the-mut-music-tool","status":"publish","type":"post","link":"https:\/\/www.reenigne.org\/blog\/the-mut-music-tool\/","title":{"rendered":"The MuT music tool"},"content":{"rendered":"

For 8088 MPH<\/a> I wrote a tool to convert Amiga MOD (module) files to the format required for playback with the 4.77MHz 8088 PC speaker 4 channel playback routine. The MOD file solution never felt quite ideal to me because the playback routine has some possibilities (like SID-style ring modulation) which can’t be expressed in a MOD file and there are also a lot of things you can do in a MOD that won’t really work with my player, so if I make it easy to try arbitrary MODs with the player, people are likely to try MODs that don’t come out very well and conclude that the player is rubbish.<\/p>\n

What I really wanted was to write my own tracker designed specifically for the player routines I had written (and some variants that I might want to write). But writing a whole tracker is a big project – particularly the GUI (GUIs take ages and aren’t the most interesting things to program).<\/p>\n

So I started thinking: what’s the simplest piece of software I could write that a musician could use to compose music for this player? What about a command line tool – a sort of compiler which accepts text files as input and generates binary music data in the appropriate format (or indeed various formats) as output? This isn’t entirely unprecedented – there have been various tools for processing text files into music such as Grigasoft’s “Polyphonic Music” and John Worley’s “Clockwork Pianola”.<\/p>\n

This is the design I came up with – I’m calling it “MuT” (“music tool”, pronounced “mute”) for now – it can’t seem to decide if it’s a tracker, a musical instrument or a programming language.<\/p>\n

Inside the text files we would probably want to have something similar to a more traditional tracker’s pattern grid, with different channels arranged horizontally and time going vertically. Rather than using semantically-significant spaces and newlines (which cause all sorts of trouble) I think a nice way to do it would be for the musician to lay out the grid using the “&” character to separate voices (think “C & E” means a C and an E playing at the same time) and the “|” character to indicate a new time division (think “bar is a measure of time” though the “|” interval would usually be shorter than a musical bar, obviously). So an empty grid would look something like:<\/p>\n

\r\noutput =\r\n     &     &     &     |\r\n     &     &     &     |\r\n     &     &     &     |\r\n     &     &     &     ;\r\n<\/pre>\n
The spaces could then be filled in with notes:<\/p>\n
\r\noutput = sine@(\r\n C4 & E4 & G4 & C5  |\r\n C4 & E4 & A4 & C5  |\r\n C4 & F4 & A4 & C5  |\r\n D4 & F4 & A4 & D5  |\r\n D4 & F4 & B4 & D5  |\r\n D4 & G4 & B4 & D5  |\r\n E4 & G4 & B4 & E5  |\r\n E4 & G4 & C5 & E5  );\r\n<\/pre>\n
Leaving a space blank causes the note in the same voice in the previous division to continue, so this could also be written:<\/p>\n
\r\noutput = sine@(\r\n C4 & E4 & G4 & C5  |\r\n    &    & A4 &     |\r\n    & F4 &    &     |\r\n D4 &    &    & D5  |\r\n    &    & B4 &     |\r\n    & G4 &    &     |\r\n E4 &    &    & E5  |\r\n    &    & C5 &     );\r\n<\/pre>\n
If you want to silence a voice, put a 0 in there instead of a blank:<\/p>\n
\r\noutput = sine@(\r\n C4 & E4 & G4 & C5  |\r\n 0  & 0  & A4 & 0   |\r\n    & F4 & 0  &     |\r\n D4 & 0  &    & D5  |\r\n 0  &    & B4 & 0   |\r\n    & G4 & 0  &     |\r\n E4 & 0  &    & E5  |\r\n 0  &    & C5 & 0   );\r\n<\/pre>\n
One can also put different instruments into the grid:<\/p>\n
\r\noutput =\r\n sine@C4 & square@E4 & triangle@G4 & bell@C5  |\r\n sine@C4 & square@E4 & triangle@A4 & bell@C5  |\r\n sine@C4 & square@F4 & triangle@A4 & bell@C5  |\r\n sine@D4 & square@F4 & triangle@A4 & bell@D5  |\r\n sine@D4 & square@F4 & triangle@B4 & bell@D5  |\r\n sine@D4 & square@G4 & triangle@B4 & bell@D5  |\r\n sine@E4 & square@G4 & triangle@B4 & bell@E5  |\r\n sine@E4 & square@G4 & triangle@C5 & bell@E5  ;\r\n<\/pre>\n
Instrument names are resolved per voice, and “.” is (by convention) a sort of default instrument name, so this can also be written:<\/p>\n
\r\noutput =\r\n { . = sine; } .@C4 &\r\n      { . = square; } .@E4 &\r\n           { . = triangle; } .@G4 &\r\n                      { . = bell; } .@C5  |\r\n               .@C4 & .@E4 & .@A4 & .@C5  |\r\n               .@C4 & .@F4 & .@A4 & .@C5  |\r\n               .@D4 & .@F4 & .@A4 & .@D5  |\r\n               .@D4 & .@F4 & .@B4 & .@D5  |\r\n               .@D4 & .@G4 & .@B4 & .@D5  |\r\n               .@E4 & .@G4 & .@B4 & .@E5  |\r\n               .@E4 & .@G4 & .@C5 & .@E5  ;\r\n<\/pre>\n
One can make instruments in all sorts of ways. A few simple (chiptune-esque) waveforms are built into the program, or you can load them from a file:<\/p>\n
\r\nbell = load(\"BELL.WAV\")@s\/440;\r\n<\/pre>\n
The MuT syntax is extremely flexible and rich enough to do just about any kind of audio processing, and hopefully it’s also intuitive enough that it’s not too difficult to figure out how to do just that.<\/p>\n
What follows is a more technical and in-depth explanation, so if you’re not a programmer or mathematician you might want to stop reading here.<\/p>\n
Basically most MuT objects are functions from the real numbers to the complex numbers. Both the range and domain of these functions have units (some integer power of seconds – s<\/code>) which are tracked by MuT so that it can distinguish between time-domain functions like sine@C4<\/code> and pure functions like sine<\/code>.<\/p>\n
There are various operators for acting on MuT objects:<\/p>\n
+<\/code> – pointwise addition<\/b>: output = sine@C4 + square@E4;<\/code> sounds the same as output = sine@C4 & square@E4;<\/code> but it has some different behavior in other ways – you can’t do the “empty space means continue playing the same instrument in that voice” trick if you use +<\/code> instead of &<\/code> in your grid, and you can’t use a + b<\/code> as an l-value.<\/p>\n
-<\/code> – pointwise subtraction:<\/b> same as +<\/code> but the function on the right has its phase inverted.<\/p>\n
*<\/code> – pointwise multiplication<\/b> (aka modulation). Also useful for volume envelopes.<\/p>\n
\/<\/code> and ^<\/code> – pointwise division and power<\/b> respectively. Mostly for completeness sake, though they do have some uses especially for scalars.<\/p>\n
[]<\/code> indexes into a function<\/b>, just like an array in C or Pascal. So sine[1] = 0.841...<\/code>. When you put a function instead of a scalar inside the brackets, you (naturally) get function composition. So a[b][x] = a[b[x]]<\/code>.<\/p>\n
{}<\/code> allows execution of statements during the evaluation of an expression<\/b>. This is handy for redefining instruments while inside the grid (see example above), or changing the tempo, amongst other things. The tempo (i.e. the amount of time covered by one “|” is set by the special variable division<\/code>. So if MuT sees { division \/= 2; }<\/code> inside an expression, the following grid rows will be played at twice the speed (only durations are affected, not frequencies). The scope of any changes inside {}<\/code> is the remainder of the statement in which it occurs.<\/p>\n
@<\/code> – basis scale<\/b>. This is where it gets really interesting. This is an operator only applicable to functions, not scalars (so unlike +<\/code>, -<\/code>, *<\/code>, \/<\/code> and ^<\/code> it isn’t found on calculators). Suppose you have a function f<\/code> and a scalar x<\/code>. Then (f@k)[x] = f[k*x]<\/code>. So if f<\/code> is a waveform then f@2<\/code> is the same waveform played twice as fast (and an octave higher). The @<\/code> operator also adjusts domain units if the right-hand side has a value which is not dimensionless. So, if f<\/code> has a dimensionless domain (e.g. sine<\/code>) then f@110*Hz<\/code> (or f@110\/s<\/code>) will be a normal time-indexed waveform (i.e. a sine wave with a frequency of 110Hz). As I’m sure you can see this is a very useful operator for an audio program!<\/p>\n
It gets better, though. Suppose we have a complex unit i = sqrt(-1);<\/code> and we make f@i<\/code> compute the Fourier transform of f<\/code>. Surprisingly, I discovered (after defining it that way) that the mathematics of doing so work out very neatly – time scaling and Fourier transformations are closely related, mathematically – they are both Linear Canonical Transformations<\/a>, and there’s a nice mapping from complex numbers to LCTs which gives an (efficiently computable) meaning to f@z<\/code> for any complex number z<\/code>. Using f@i<\/code> in combination with *<\/code> allows us to do convolutions and therefore any linear filters you care to describe (high-pass, low-pass, band-pass, notch, echos, resonances, you name it). Using other complex numbers on the right-hand side of @<\/code> gives us inverse Fourier transforms and fractional Fourier transforms (the musical utility of which I know not, but I’m sure inventive musicians will find some interesting uses for it).<\/p>\n
One can also use a function on the right-hand side of @<\/code>, which will result in a different basis scaling for each sample in the output – i.e. for scalar x<\/code> and functions f<\/code> and w<\/code>, (f@w)[x] = (f@(w[x]))[x]<\/code>. That’s how the first non-trivial example above works.<\/p>\n
&<\/code> – next voice operator.<\/b> This just puts moves to the next voice, as we’ve seen above. It can also be used on the left-hand side of an assignment: (a & b) = (c & d);<\/code> does the same thing as a = c; b = d;<\/code>. This is useful for grouping values together into a compound object.<\/p>\n
|<\/code> – time sequence operator.<\/b> c = a | b<\/code> yields a for division<\/code> followed by b<\/code> for division<\/code>. Functions in MuT repeat once they are complete, so if you evaluate c<\/code> in a time sequence with a sufficiently long division<\/code>, it’ll sound like a | b | a | b | ...<\/code>. Similarly you can loop a division<\/code>-long section of just one function by doing c = a | ;<\/code>.<\/p>\n
As with &<\/code>, |<\/code> can be used on the left-hand side of an assignment: (a | b) = c;<\/code> assigns the part of c<\/code> between 0<\/code> and division<\/code> to a<\/code> and the part of c<\/code> from division<\/code> to division*2<\/code> to b<\/code>. So by using just assignment, the special division<\/code> variable and the |<\/code> operator you can make whatever edits to a waveform you like.<\/p>\n
The comparison operators ==<\/code>, !=<\/code>, <<\/code>, <=<\/code>, ><\/code>, >=<\/code><\/b> work the same way as their C equivalents, yielding (in general) a function whose values are boolean (true<\/code>, false<\/code>) elements rather than numbers. These can be used with the ?:<\/code><\/b> operator to combine two functions via a predicate.<\/p>\n
The %<\/code> operator<\/b> has a couple of uses (which I might change to use different characters). On its own it gives the output from the previous voice in a voice set, which is useful for ring-modulation style effects (such as those that can be done by the SID chip and by my MOD player routine). If it comes immediately after a sequence, it yields a function which is the time-to-index mapping of that sequence. So (a|b|c)%<\/code> is a function that is 0<\/code> from 0<\/code> to division<\/code>, 1<\/code> from division<\/code> to division*2<\/code> and 2<\/code> from division*2<\/code> to division*3<\/code>. You can also change the time-to-index mapping of an l-value by assigning to this function. If the time-to-index mapping function takes a non-integral value at any point then the corresponding two elements of the sequence are mixed, so you can create fades and glissandos. Time-scaling the time-to-index mapping function will speed up or slow down the playing of that sequence without affecting the frequencies.<\/p>\n
If you combine (via multiplication or basis-scaling) two functions which don’t have the same domain units you end up with a compound object. When this compound object is basis-scaled, it’ll move the dimensions of the compound object closer and leave other elements unchanged. So you can create an instrument by combining a waveform (dimensionless domain) and a volume envelope (time domain), and when this is time-scaled the scaling will change the frequency of the waveform part without speeding up or slowing down the volume envelope.<\/p>\n
I’m contemplating a built-in function that will convert a waveform into a sequence so that it can be time-scaled without changing the pitch (or vice-versa) in the manner of a phase vocoder, but I haven’t quite got all the details ironed out yet.<\/p>\n
Arbitrary functions can be defined: e.g. major(x) = x + x@5\/4 + x@3\/2;<\/code> will turn any waveform or function into a major chord using its input as the base note. If we allow functions to be recursive, then (by the Church-Turing thesis) MuT becomes a Turing-complete programming language (for better or for worse).<\/p>\n
It’s handy to be able to have libraries of predefined functions, instruments, values (note frequencies, intervals) etc. Executing an include<\/code> statement will read in a file and insert its contents into the program at that point (much like C’s #include<\/code> directive). Conventionally, a MuT input file will start with include \"standard.mut\";<\/code> to include the predefined variables which come with the program, or include \"pc_speaker.mut\";<\/code> which does the same but also sets up special variables for the PC speaker output mode.<\/p>\n
There’s some more design documents (which are somewhat out of date but cover a few more dark corners) and the beginnings of an implementation on my github<\/a>. Being a command-line tool, it’s not terribly user-friendly but it probably wouldn’t be hard for someone more GUI-oriented than me to slap a user interface on top of it. One fairly simple user-interface for this might just be a special text editor, which plays whatever object is under the cursor whenever a particular key combination is pressed (and which highlights the parts of the MuT program which are being used to compute the currently-playing notes). An interesting enhancement would be a little knob that appears whenever the mouse hovers over a numeric value; dragging this knob changes that numeric value in real-time, changing the currently playing sound if that value is involved in it.<\/p>\n","protected":false},"excerpt":{"rendered":"
For 8088 MPH I wrote a tool to convert Amiga MOD (module) files to the format required for playback with the 4.77MHz 8088 PC speaker 4 channel playback routine. The MOD file solution never felt quite ideal to me because the playback routine has some possibilities (like SID-style ring modulation) which can’t be expressed in […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4,27,9],"tags":[],"class_list":["post-2009","post","type-post","status-publish","format-standard","hentry","category-computer","category-language","category-music"],"_links":{"self":[{"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/posts\/2009","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/comments?post=2009"}],"version-history":[{"count":11,"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/posts\/2009\/revisions"}],"predecessor-version":[{"id":2011,"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/posts\/2009\/revisions\/2011"}],"wp:attachment":[{"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/media?parent=2009"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/categories?post=2009"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.reenigne.org\/blog\/wp-json\/wp\/v2\/tags?post=2009"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}