Gregory Taylor

I’d like to start this series of tutorials with a confession: I work slowly.

Knowing that about me probably explains a lot of things, from the rate at which the tutorials I write appear to the rate at which I release recordings, all the way to how long my current MSP performance rig has been around (hint: it’s measured in years). That doesn’t mean that nothing has changed, of course — merely that I’m one of those slow preparation/fast execution people. When I’m experimenting with implementing new algorithms, I’ll set something up, turn it on, and let it run for a looooong time, listening and tweaking along the way. Similarly, the arrival of new software features — even features in Max — don’t send me down the rabbit hole right away; I tend to try to work my way through them at my leisure, a little bit at a time, until I figure out what the little bits are doing and then imagine where they might fit the way I work and think about things or until I notice something unexpected and start the (slow) process of integrating that into my practice.

The arrival of Max’s MC features has been a game-changer for a lot of Max users, who wept with joy at the ability to use things like the deviate message to retune enormous banks of sine waves or patch large and complex audio processes without the previous "subway-map-from-Hades" riot of patchcord connections. 

But while the world has filled with new swarms and clouds, there are still people out where who’ve found it a bit daunting, or wondered how they’d begin to make sense of it. (Witness all the beginner videos out there, in case you doubt me.) I’d like to begin a small set of tutorials in a different way – to chart my own path into using some of Max’s MC features, one small piece at a time. If you’re familiar with the tutorials I’ve written, you’re going to recognize the raw materials pretty quickly – they’re things I’ve created earlier (and, occasionally, modified just a bit for these tutorials for reasons that will become apparent). While it’s possible that my way of working doesn’t match your own, I hope that the through-line of investigation remains clear, and that you can find something useful and (I hope) inspiring. Let’s get started.

Longtime Cycling ’74 website readers probably know one thing about me for certain: I love low frequency oscillators (LFOs), and I’ve got the tutorial series out there to prove it. While the LFO’s service in audio as a modulation source is ubiquitous and great, I personally tend to approach them as a slightly more general source for generating and organizing variety. I use them to rescue myself from situation in which abandoning some part of my Max patching to randomness seems or feels wrong because, well, I’m not random.

So you’d be right in imagining that the first time I saw a video tutorial about using the deviate message to retune a huge bank of sine waves, I started wondering about going low instead of going high.

As you know from my LFO tutorial series, I started by creating a simple LFO patch, and then began to investigate what I could do by creating multiple instances of that patch and then modifying them individually and summing/averaging the results to create more complex control structures. When Gen came along and I’d decided to embracing using it, I realized that porting my LFOs to gen~ was really a pretty easy task, and that gen~ allowed me to realize a good deal of efficiency by “ganging” those multiple summer/averaged LFO networks into a single gen~ object.

So I figured that that’s where I’d start: take a gen~ LFO patch and move it into the MC world and see what I could do with MC’s features that would match up with my working methods.

It's not hard to figure out that one of the great features of MC involves the ability to create a wrapper around multiple Max objects that lets you address each instance individually — especially useful when you use some specialized MC features to set and modify those individual instances from a single source. So I decided to take a version of my standard gen~-based LFO and to create a special version of it for use in the MC world (You'll find this patch - single_channelLFO.maxpat -  in the folder of patches I've included):

If you're familiar with my basic gen~ LFO, there aren't a lot of surprises for this as a starting point. The main difference is that I've converted the contents of the gen~ object so that each of the parameters is now a signal input rather than the message-based Gen param operator approach I often use. Here's the contents of the basic_MC_LFO.gendsp file I've saved as a separate .gendsp patch and loaded into the gen~ object using the @gen <filename> attribute:

I have made a few revisions to the gen~ LFO here. First, I'm using the @default attributes for the in operators to set up my gen~ patcher so that I've got a standard set of starting parameter values for my LFO:

The frequency of the phasor operator (@default 1 Hz.) that drives everything else

I've added the ability to set the phase of the individual phasor operator (@default 0.) with a floating-point number value between 0. and 1.0. Not sure why I didn't add this feature before, but I figured that individual phase controls might prove useful (and they will... trust me).

Each phasor operator uses a rate operator (@default 1.0) to scale the phasor operator's output for nice long rates of change

A duty cycle setting (default 50%) for square-wave output

A waveform select option via the selector operator.

The output from the phasor operator (adjusted for phase and output-scaled as needed) is used to generate six different output waveforms. The triangle operator does most of the heavy lifting here, using argument settings to output positive and negative-going ramps or triangle waveforms, with the cycle operator (which uses the @index phase attribute to transform the phasor operator's ramp output to a sine wave and a latch operator-driven noise source (triggered by the end of the master phasor's 0. - 1.0 cycle) that produces random outputs.

I also decided to add an output that indicated the point at which the phase-adjusted and output-scaled phasor wrapped to 0. as a second output. I've found over time that I use that feature a lot - usually adding a little MSP patching to generate bang messages from the spike.

Moving this patch into the MC world requires nothing more than loading the MC_LFO.gendsp file into the MC version of the MSP gen~ object (mc.gen~) and specifying the number of instances we want to work with using the @chans attribute. In the interests of clarity (and my own predilection for quartets), I'm going to create a patch with 4 different LFOs: mc.gen~ @gen MC_LFO.gendsp @chans 4.

That now means that each individual inlet in the mc.gen~ object now addresses 4 independent inputs, so I'm going to need to add a way to address each of the four instances. It's MC to the rescue once again by means of the mc.sig~ @chans 4 object. In practice, you'll find that a good deal of the work you do in MC involves substituting the MSP objects you already work with with their MC variants. In some cases, some Max UI objects will automatically adjust to the number of output channels they receive. The scope~ object is just such an example of that — connecting scope~ objects to the waveform and trigger outputs automatically convert to multichannel displays (you can click on the dots at the bottom of the display to see which instance you're viewing. They all look the same, at the moment because they're all set to the same default values).

There are a number of ways to send data to the mc.sig~ objects, but I'm going to go with a really simple method, adding an mc.input 4 object to each of the five mc.sig~ @chans 4 objects. After that, providing control for each parameter of each instance of the LFO is just a matter of adding some number boxes to the patch. Here's the result (the multichannel_LFO1.maxpat patcher file_:

Using MC to created a multichannel version of the basic LFO has the additional advantage of simplifying the internals of a any patch that outputs multiple instances of something - you just don't need the mass of internal param and setparam operator-based logic you'd usually rely on (e.g. needing parameters like phase1, phase2, and so on). Even though I am working with 4 independent instances of my LFO, I didn't have to modify the internals of my basic_MC_LFO.gendsp patch at all.

Once I had that hooked up, I started experimenting with changing input values. Setting different phasor operator rates immediately produced changes to the multichannel displays, so I could see that was happening and could select each instance's display separately.

Finally, summing and averaging these multiple LFO outputs to produce exotic and interesting waveforms involves nothing more than adding an mc.mixdown~ 1 object and multiplying the result by .25 to scale the output into the standard -1.0 - 1.0 output range. In the case of the trigger outputs, we don't need to scale at all - one mc.mixdown~ 1 object does the trick. And, as long as I've got four separate triggers based on the phase-adjusted and scaled phasor operators, I might as well pull them out to use separately. How do I unpacke 'em? Yep, that's right - an mc.unpack~ 4 object. You can see the results in the multichannel_MIDI.maxpat file.

After I got my patch to the point where I could access all the parameters, I thought I'd check some of the interesting ways to interact with MC objects that were available to me. I'd certainly seen and heard about the deviate message, but was wondering about what else there might be. It was time to click on the magnifying glass in my patcher window to fire up Max's in-app search. Sure enough, I found what I was looking for in the Generating a Range of Values for All Wrapper Instances section of the MC documentation. The idea of distributing parameters across a specified range was much more compelling to me than deviation, so I thought I'd go with that. 

I'd found what I was looking for but um... I wasn't quite sure that I understood it. So I went for my usual Plan B when consulting documentation: Create a Max patch that lets you explore the thing you're having trouble making sense of, and play with it until you do. Since I was dealing with numbers distributed over a range. I created the spreading.maxpat patch in the distribution to do just that. I could input specific values in the range of 0. - 1.0 or scroll the integer number box, and watch how several variations of the spread messages behaved, and - most importantly, seem them next to one another (Sometimes, a value didn't do anything and, once I got the hang of it, I could easily see why). Here's the patch in action:

There were two features of this work that surprised me a little. First, I think I would prefer to use different varieties of the spread message for different functions. Here are some examples:

For phase offsets, I want the lower bound clamped to zero (no phase adjustment) and to keep the fourth value below 1.0, since that's really the same thing as a phase of zero). 


I'd like to do my range setting by specifying the upper and lower bound when it comes to multipliers for my phasor operators


Duty cycles for square waves should never use zero or one for values. 

I'll use different flavors of the spread message for each situation — choose the tool that fits the task.

The second insight is something I'll save for later. It knocked my work completely sideways and sent me right down the rabbit hole. But more on that later....

For phase offsets, I want the lower bound clamped to zero (no phase adjustment) and to keep the fourth value below 1.0, since that's really the same thing as a phase of zero).   

I'd like to do my range setting by specifying the upper and lower bound when it comes to multipliers for my phasor operators  

I'll use different flavors of the spread message for each situation — choose the tool that fits the task.The second insight is something I'll save for later. It knocked my work completely sideways and sent me right down the rabbit hole. But more on that later....

Hey - I think I've won the prize for going the longest in an MC tutorial without making any noise! But that's okay with me - I'm trying to get things sorted out in terms of UI/parameter control and figuring out the spread messages.. It's time to hook up something to make a little noise. I think I'll use this as the basis for a step sequencer (those are also close to my heart, as you may have noticed or read). Here's how it'll work:

I've got four independent LFO waveforms, each of which has its own trigger output, as well. I'm going to sum and average all four waveforms to created the waveform to sample to derive MIDI note numbers.  

I've got four independent trigger outputs, as well. I'm going to create a way to use one or more of them to serve as the latch for waveform sampling. I'd like to be able to arbitrarily apply any trigger (or group of them) to the latching/sampling, and to create a four-output version for my MC step sequencer.t  

I think I'd like to be able to add some sync to my individual LFO outputs, while I'm at it. That might require a little thought, but it's a feature I want.

There are a lot of places I could go with this basic design from there - grab the individual waveforms and use them to drive filters, use the summed exotic audio output for pitch for an oscillator, and so on. But I'm going to keep it simple: 

I'll add some very simple sample/hold-based parameter acquisition to get me the component parts for a MIDI note message (pitch/velocity/duration),  

Take my MIDI message patching and multiply that by four (one voice in honor of each of the LFOs) to get a four-voice patch  

I'm going to borrow a little scale-mapping patching from a random grid sequencer Max for Live device I wrote a tutorial on a while back to add some scale/modal rectitude to the proceedings.

And I do need to add that synchronization to the patch while I'm at it.

As things stand, I've got some really interesting summed waveform action -  the output of the mc.mixdown~ 1 and *~ .25 object pair. I've also got four independent triggers (one for each phase-adjusted and scaled phasor operator in the MC_LFO.gendsp patch. The nice feature of my exceptionally busy summed waveform is that all I have to do to get very different MIDI message results is to sample the waveform at the slower rates of the phasor operators - as the triggers cluster or overlap, I'll be grabbing the same note or one nearby. Widely spaced phasor speeds will sample from the same material at wide intervals. And, should I desire it, the results can be made periodic by judicious sets of parameters for rate, phase, and multiplier (especially in situations where I'm using the same waveform in all four sets of LFOs. After some trial and error, this patch falls well  into the kind of patching I generally enjoy — something whose adjustable variety implies pattern and intention rather than randomness (and your personal mileage may vary here, but on the bright side, this can be coaxed into staggering randomness with only a little effort).

Assembling the MIDI note messages is handled by the ez-map patcher. Each instance of the subpatcher grabs its input from some combination of three of the four audio outlets from the mc.unpack~ 4 object and from the summed waveform to sample. Here's a look at what's under the hood:

It's a straight-ahead piece of work: three sah~ MSP objects take the summed waveform as input and grab the triggers sent into inlets 2, 3, and 4. Each spike grabs a sample of the summed waveform and scales it for use as a MIDI note number (I'm using a narrow range of notes 24 to 48 and then transposing and scale-mapping that value later on. The audio-rate result is then converted to even data with a snapshot~ 20 object and a change object that filters out repeating triggers.

You'll notice there are two additional objects for the first sample-and-hold patching: I decided as I developed the patch that I found total chromaticism kind of boring, so I thought I might do some scale mapping to use different scales and modes (and my own non-western tunings, although I really don't need anything special to do that, since the tuning tables are done via lookup in another MSP patch).

A while back, I wrote a tutorial that used noise surfaces in Jitter to generate synth controls. In that tutorial, I included some patching to make scale mapping a little easier (you'll find it used in my book Step by Step, as well). It's perfect for this patch, so I've taken the liberty of borrowing it and using it here.

Those two extra objects are all I need to use the patching I've cut from the noise tutorial patch - all it does is to increment a lookup table index (the table object in Max counts from one instead of the more usual zero), and use that index to lookup a numerical offset to the pitches we've sampled stored in a table object.

Note: If you're interested in working through the scale mapper patch, I'd suggest firing up and checking out Noise Tutorial 1: Riding Tandem With The Random. You'll find the scale mapping stuff described in the section Scale mapping for fun and profit.

The rest of the MIDI patching is a question of collecting and routing the three outputs from the ez-map subpatcher. I added some octave offsets to add variety to the four voice, and decided that I liked using the buddy object to synchronize the different pitch, velocity, and duration outlets (I don't really need it, but decided that I liked the results when working with extreme ranges. Like I said, I patch and then tweak and listen a bunch).

The only other thing I needed was some reset logic. That involved adding a new inlet to the basic_MC_LFO.gendsp patcher that connected the right inlet of the only phasor operator in our patch (I love how easy loading multiple instances of gen~ patches using mc.gen~ - it makes keeping track of things so much simpler). I renamed the patch MC_LFO.gendsp because that's the version I'll be using from here on out, and loaded that new version into the mc.gen~ object. Sending a non-zero value to all four instances is done by using an mc.target 0 object (zero meaning "send the input to all instances") and another mc.sig~ @chans 4 object to the main patch. Presto - reset!

Here's what it looks like with everything in place in the multichannel_format.maxpat file. I added some pattr objects/a preset object/a pattrstorage bit of preset prep, and the easy-peasy output mapping. It sounds pretty good for a bunch of MC LFOs, I think.

That's it for now. Next time out, I'm going to show you what it was during this patchfest that was the mysterious "other thing" that caught my attention. The resulting journey down the rabbit hole will be the starting point for the next excursion. Stay tuned....

Learn More: See all the articles in this series 

image1.png

The arrival of Max’s MC features has been a game-changer for a lot of Max users. This short series of MC tutorials will chart my own path into MC, learning what it did that would fit with my workflow. It borrows from earlier work of mine, and I hope that the through-line of investigation remains clear and that you can find something useful and (I hope) inspiring.

an-mc-journey-part-1

An MC Journey, Part 1

Jeremy

In this series, we're going to do a deep dive into designing a MIDI-based editor for a hardware synthesizer: the KORG minilogue xd. We'll be using Max, and especially the js object, to accomplish this.

Don't worry if you're not a Max expert, most of the work we'll be doing isn't going to be in Max at all! And the Max objects we do use will be a good introduction or refresher for how to work with MIDI data, and how to build simple patchers in Max.

Although we're going to be looking at a lot of (simple) JavaScript code, this series won't be a tutorial in JavaScript programming. I'll explain the code as we go along, but I won't be explaining basic language features. If you're familiar with any text-based programming language, JavaScript will probably look familiar enough to you to follow along. And if you're inexperienced with text-based programming, JavaScript is a great language to get started with!

Finally, do you need to own a KORG minilogue xd? Well, sort of. If you want to actually use the scripts we'll develop to control some hardware, then yes (and if you have a KORG prologue (the big brother of the minilogue), the two synthesizer engines are similar enough that you can probably quickly adapt these scripts for your hardware). But even if you don't have access to this specific hardware, the concepts we'll be investigating are applicable to any MIDI-capable instrument (even plug-ins!), and could be worth your time.

Even in Max's earliest versions in the 80s, one primary function was remote control of external hardware using the then-new Musical Instrument Digital Interface (MIDI) protocol. As Max has grown, MIDI support has remained and, over time, been extended and improved. Over the past several years, we've made a bunch of improvements to Max's MIDI functionality, adding support for MIDI Polyphonic Expression (MPE), (Non-)Registered Parameter Numbers (RPNs and NRPNs), 14-bit continuous controllers, to name some highlights.

Although music hardware has changed significantly in that last nearly 40 years, MIDI has remained and remained relevant. Most music production gear (of the non-control-voltage variety) produced today supports MIDI, either via the old-fashioned DIN-5 cables, or via USB, or even via minijack cables. The actual MIDI protocol hasn't changed much since the music industry accepted version 1.0 in 1983, although there have been extensions like General MIDI, MIDI Time Code and MIDI Machine Control, and more recently, MPE, which permits high-resolution control of individual notes (for many parameters which were historically global).

MIDI 2.0 was ratified only this year, and we expect MIDI 2.0 hardware and software implementations to start appearing before too long.

Why do I need an editor for my synthesizer?

You don't, of course. Most well-designed instruments work perfectly fine without being attached to a computer editor, and allow access to all of their features via buttons, knobs and a display. That was true of the venerable Yamaha DX7 in 1983, and remains true for a parameter behemoth like Dave Smith Instruments Prophet 12 or the Novation Peak. But an external editor offers a few advantages:

Most obviously, if you're working at the computer, sometimes it's comfortable to stay at the computer. If your synths are across the room, being able to tweak some values without standing up can be a time- and focus-saver.

You can see all of the parameters at once.

You can more easily save and restore the state of the synth (if you don't want to store to the internal memory of your synthesizer), which, depending on what you're up to, may make your work more portable.

I chose the KORG for a simple reason: I have one, and I hadn't built an editor for it yet. But that argument aside, the minilogue xd is a (relatively) affordable, compact and feature-rich synthesizer which happens to sound fantastic, and can be found in a lot of home studios for those reasons. Most importantly, it has excellent MIDI support and documentation.

A quick technical excursion: the KORG minilogue xd is a 3-oscillator hybrid synthesizer. The first 2 oscillators are VCOs (voltage-controlled oscillators), fully analog (and they will go out of tune to prove it). The third oscillator is digital, and, in addition to generating noise and digitally-generated basic waveforms, it can load user programs to become, for instance, a wavetable oscillator, an FM or additive oscillator or whatever any number of third-party developers have come up with.

The rest of the signal flow, including the filter, is analog, up until the effects section, which is again DSP-based. Like the digital oscillator, you can load external modulation, delay and reverb effects to complement the generous built-in set.

To further rationalize my choice: in my opinion, the minilogue xd falls into the Goldilocks zone of size, cost and parameters. It's got enough parameters to make it interesting to control, but not so many that we can't fit all the control elements into a single Max patcher window. 

OK, with all that as prologue (get it?), let's get to work!

Let's make a quick and dirty continuous controller generator in JavaScript. This isn't nearly as nice or useful as our final version will be, but it's a good way to get our feet wet and ensure that everything is working properly. The idea is simply to route a parameter name from Max to generate a valid continuous controller message for the associated parameter.

Let's start with the script. Here it is in its entirely:

var cctls = [
    { name: "VCO 1 PITCH", cc: 34 },
    { name: "VCO 1 LEVEL", cc: 39 }
];

function getRandomInt(min, max) {
    return Math.floor(Math.random() * (max - min + 1)) + min;
}
getRandomInt.local = 1;

This is a little more verbose than necessary because it adds some randomization in case you don't provide a value argument, but as you can see, it's pretty concise. At the top, after we set up the 'js' object's outlet, we define an Array named 'cctls', which contains two Objects representing CC parameters of the minilogue xd. In JavaScript, Array objects are indicated by square brackets ( [  ] ), and Objects are indicated by curly braces ( {  } ), so we've made an Array of Objects. Each Object can have named properties, similar to a dictionary in Max.

For the time being, we're keeping track of a name (property 'name') and a CC# (property 'cc'). We use the name to look up a parameter when a message is received from Max, and we use the the CC# to modify the associated parameter on the instrument. In the anything() function, we search for a parameter based on the message's name. If we find a match, we send a value -- either the value sent in from Max, or a randomly generated value if there was no argument -- as a message from the 'js' object's outlet, formatted for the 'ctlout' object in Max.

Look how neat and clean that is! For comparison purposes, here's a good-faith effort to make the same patcher without using the 'js' object. 

That's not so bad, but it should be clear that once we're managing more than a few parameters, maintaining this logic is going to get tedious, especially if the parameters have different ranges. Encapsulating this kind of functionality inside the 'js' object is a great way to clean up your Max patchers.

Give it a try (the patcher and the script are in the archive attached to this article). If your minilogue xd isn't responding, ensure that you haven't disabled "MIDI Rx CC" in the Global section of the Edit Mode (it's behind the 5th illuminated button when you're in Global Edit mode).

I have a little more to say before we push ahead. You might be wondering: why are we doing this in JavaScript at all? Isn't Max capable of doing everything we need to do? Sort of. We could build this in Max, but the patcher would be huge and difficult to debug, read and maintain. Here, for instance, are the guts of a (small part of a) Yamaha DX7 editor I built in Max before I knew better: 

Any good programmer has the essential virtue of laziness, and building our editor in JavaScript is going to help us avoid doing a ton of repetitive and error-prone routing of data to and from our editor's interface (more on that later!).

Which brings us to modeling. Our goal, as in our first example, is to use JavaScript to manage the communication between our patcher and our instrument. As above, we'll create a table containing all of the parameters in a synth voice patch, with properties for the name and CC (or NRPN) index. Eventually, we'll be adding information about the parameter's range, a current value, maybe a default value. That is, we're going to create a model of the voice, its properties and its state using JavaScript.

When we change a parameter value from Max, we'll update the model and then send the change to the instrument. And when we change a parameter value at the instrument, we'll update the model and then send the change back into Max (to keep a user interface in sync with the state of the instrument, for instance).

For the geeks: this type of programming is called Model-View-Controller programming. I described the Model above, and the View is just the user interface (yes, our editor will have a user interface). The Controller is the part which handles communication between Max (or the minilogue xd) and the Model, and it will also live in JavaScript.

Until recently, implementing this type of programming structure in Max was somewhat difficult, but there have been some recent additions to the 'js' object which make this much easier (and which we'll discuss in Part 2 of this series).

The first thing we need to do is take a look at the MIDI implementation of our synth. At the time of this writing, it's at version 1.01 (2020.2.10) and available on KORG's support website (it's also included in the download accompanying this series). Here's an excerpt from the "Recognized Receive Data" table in that document: 

This table describes the channel messages to which the minilogue xd will react. Let's find one of the parameters we mapped in the first example: VCO 1 PITCH is described on line 396 in the document, and in the screenshot above. 

What do we know about this parameter? We know its name ("VCO 1 PITCH"), we know that it's a CC message (the status byte is 0xBn, which is the hexadecimal indicator for a continuous controller message [the 'n' is the channel, so 0xB0 means CC on MIDI channel 0]). We know that it's CC 0x22 (decimal 34), and its value is apparently from 0-127 (the full range of a 7-bit CC parameter [that's from 0 to 27 - 1, if you're curious where those numbers come from]). We can modify our script above to add properties for min and max, for instance:

var cctls = [
    { name: "VCO 1 PITCH", cc: 34, min: 0, max: 127 },
    .    
    .    
    .    
];

On the right hand side of the documentation page, there are a bunch of footnotes. These add some additional information about the parameters, for instance if they have an extended range or some kind of enumerated value. In this case, we care about footnotes 5-2 and 5-4.

Note 5-2 is critical, but we already checked and confirmed it above: 

*5-2 : This message is recognized when the "MIDI Rx CC" is set to "On" 

*5-4 : When a 10 bit value is received the lower 3 bits are first expected via a CC #63(0x3f) message.

That's important! This parameter is actually a 10-bit value, which means that its range is from 0-1023 (that's 210 - 1). If you edit the parameter on the instrument, you can confirm that -- the values available for pitch are much more granular than 128 steps. Let's modify our model:

var cctls = [
     { name: "VCO 1 PITCH", cc: 34, min: 0, max: 127 },
     .
     .
     .
];

If you're familiar with MIDI, you know that continuous controller messages are restricted to the 7-bit value range of 0-127. According to Note 5-4, in order to use the full 10-bit range of this parameter, we need to send the lower three bits to a different CC (CC#63) first, and then pass the upper seven bits to the "real" CC (34). How do we do that in JavaScript? Like this:

if (param.max > 127) {
    var bit3 = val & 7;
    var bit7 = val >> 3;
    outlet(0, bit3, 63);
    outlet(0, bit7, param.cc);
}
else {
    outlet(0, val, param.cc);
}

In the above, we first get the 3 lower bits by ANDing (&) the value with 7 (written as a binary number, 7 is 111, so '& 7' gives us only the parts of the value contained in the 3 lower bits). Then we shift the upper 7 bits over by 3 bits (>> 3), deleting the lower 3 bits since we don't need them anymore (they are stored in 'bit3'). That gives us a 7-bit number (10 - 3 = 7) which we store in 'bit7'. Finally, we output 'bit3' to CC#63, and 'bit7' to the parameter's CC, as described above. Got it?

Just in case that wasn't clear, here's some ASCII art:

abcdefghij                 // 10-bit value
abcdefghij & 7  = hij      // lower 3 bits
abcdefghij >> 3 = abcdefg  // upper 7 bits

As I mentioned above, MIDI continuous controller messages are limited to values from 0-127. And there are only 128 CC numbers (also from 0-127, and even then, some of them are reserved for special duties). That would mean that MIDI instruments can only support a bit fewer than 128 parameters with the fairly coarse resolution of 128 steps. And although many MIDI instruments manage with those restrictions, MIDI provides another, more flexible mechanism for parameters called (Non-)Registered Parameter Numbers. 

The RPNs are, as the name implies, registered for specific tasks and aren't used very often. The NRPNs, though, are increasingly popular for instruments with lots of parameters, or those with high-resolution parameter values, or both. Manufacturers like Elektron, Dave Smith Instruments/Sequential, Novation and others use NRPNs generously for their instrument lines. 

There are 16384 NRPN parameters (14 bits worth), each of which can transmit a 14-bit value (0-16383). And, in case you were wondering, recent versions of Max have special objects for handling NRPNs, 'nrpnin' and 'nrpnout'.

Most of the critical parameters of the minilogue xd are implemented as CCs, but there are several which use NRPNS. You can find them in Table 3 of the MIDI implementation document. For instance, the Multi Engine's Shape parameter can be controlled this way. So let's extend our minimal model to accommodate them. This:

var nrpns = [
    { name: "MULTI SHAPE NOISE", nrpn: 0x14, min: 0, max: 1023 },
    { name: "MULTI SHAPE VPM", nrpn: 0x15, min: 0, max: 1023 }
];

We could just add the NRPNs to our original list of parameters, but since I know something about the future of this project, I've decided to keep them separate. This will allow us to perform special processing for NRPN parameters which isn't necessary for CC parameters and vice versa. More on that in the next installment.

Our processing code has gotten a little longer, but it's still simple:

The function getParamForName() searches both Arrays (CC and NRPN) and returns a parameter Object if found. Assuming that one is found, we determine which outlet, and which parameter number we want to use, depending on whether we're working with an NRPN or not. We can determine that by checking whether the parameter has an 'nrpn' property. We'll use outlet 0 (the leftmost outlet) for NRPN messages, and outlet 1 for CC messages.

The KORG NRPN implementation is a little unusual (the more you use MIDI, the more you'll discover that "unusual" implementations are not that unusual). It uses low-resolution NRPNs (a 7-bit value) in combination with our old friend CC#63 for transmitting 7-, 8-, 10- and 14-bit values. The footnotes to Table 3 in the MIDI Implementation document describe how to AND and bitshift the values to make this work.

For the moment, we're only modeling 10-bit values, and we can use the same code we wrote for 10-bit CC parameters. The 3 lower bits go to CC#63, the 7 higher bits to the NRPNs index using the low-resolution NRPN syntax.

Our patcher hasn't gotten much bigger, and that mostly because of the extra parameter messages: 

One quick remark: the parameters I've chosen to illustrate NRPNs are particularly interesting because they are going to cause us some problems moving forward! When you turn the Shape knob on the instrument panel and observe the output using something like Midi Monitor (https://www.snoize.com/MIDIMonitor/) on macOS or MIDI-OX on Windows, you'll see that the minilogue xd sends CC#54, not one of these NRPNs.

However, when sending a complete voice patch to the minilogue xd, we need to know the individual values of Shape for the Noise, VPM and User sections of the Multi Engine oscillator. So we'll need to figure out how to update the state of the Shape parameter(s) properly when receiving the CC parameter change from the instrument. We'll encounter this problem more acutely and Part 2, and finally solve it in Part 3 (hint: it involves MIDI System Exclusive messages).

Take this version for a spin, and then we'll start wrapping up.

The last thing we want to do is listen to the instrument and update our model when changes arrive. For the moment, we're just going to post a message to the Max window -- after all, we don't have a real UI/View yet.

I mentioned above that the KORG NRPN implementation is a little unusual. If you look in the example patcher (minilogueTheFourth.maxpat), you'll see a little 'js fixKorgNrpn.js' object between the 'midiin' and 'nrpnin' objects. This little script "standardizes" the non-standard messages KORG is sending so that the 'nrpnin' object can parse them. In Max 8.1.9 and newer, there's a new @permissive mode to 'nrpnin' to permit this non-standard input.

Because of the problem described above with the transmission of the Shape parameter(s), I've added an NRPN parameter for the Voice Mode so that we can verify reception of NRPN parameters, too:

var nrpns = [
    { name: "VOICE MODE TYPE", nrpn: 0x10, min: 0, max: 4, 
        enum: [ "ARP LATCH", "ARP", "CHORD", "UNISON", "POLY" ] },
    ...
];

The Voice Mode Type parameter is a little different than the parameters we've seen so far. It's an enumeration (the values are provided in Note 3-5 of the MIDI Implementation document). We can use the enumerated values to map values to a string for display, as you'll see below.

Here are the updated portions of our script:

The function incoming() is used to process messages sent from the instrument. 

The first thing it does is check for a message on CC#63. As we've seen, this special CC# is used for transmitting the low bits of a value greater than 127. If a CC#63 message comes, we cache the value in the global variable lastLowBits and return immediately. 

If any other message arrives, the script attempts to resolve the CC# or NRPN# to a parameter via getParamForIndex() (we send NRPN messages into the left inlet and CC messages into the right inlet, so that the script can easily tell the difference). getParamForIndex() does approximately the same work as getParamForName() did, but it matches the type and index of the message, rather than the name. We need to know whether the parameter is a CC or NRPN because the indices aren't necessarily unique -- you could have both a CC#16 and an NRPN#16 -- so we need to tell getParamForIndex() where to look.

If the parameter is found, we check for a valid value in lastLowBits (>= 0) and combine it with the value passed to incoming(). We first shift the value 3 bits to the left and then OR the low bits in. Some more ASCII art to illustrate that process, in case you're new to bitwise operations.

       hij  // lastLowBits
   abcdefg  // current value
   abcdefg << 3     = abcdefg000  // value << 3
abcdefg000 | hij = abcdefghij  // value | lastLowBits

Because we know that all values > 127 are 10-bit values at the moment, this is straightforward. When we extend the Model to include 8- and 14-bit parameters, this function will get more complicated. Also note that we're storing the received value as a property of the parameter ('value'). We don't need it quite yet, but we will in the next installments of this series.

Finally, we post all of the information to the Max window (with an enumerated name, if available). At the very, very end, we invalidate the lastLowBits and are prepared to receive new messages.

If you try this out, you'll see that changing the OSC 1 Pitch or Level, or the Voice Mode on the minilogue xd will now cause the script to respond by posting the new value to the Max window.

Let's call it a day. We've covered a lot of ground in this first article, and hopefully you've got a better understanding of how JavaScript can be used to handle the modeling of the parameter space of an instrument. Our Model is still pretty simple, but as we saw above with enumerated parameters, extending the Model is straightforward. We've still got some work to do, though -- we're about halfway toward having something working and about a third of the way toward having something I'd consider pretty good.

Linked to this article, you'll find all of the versions of the patcher and associated code we worked on. Additionally, there's a somewhat more complex version of this project in which all parameters (both CC and NRPN) have been modeled, including the non-10-bit NRPNs and enumerated parameters. 

minilogue_1_illustration.png

In this tutorial series, I’m going to do a deep dive into designing a MIDI-based editor for a hardware synthesizer: the KORG minilogue xd. We'll be using Max, and especially the 'js' object, to accomplish this. If you're not a Max expert, don’t worry - most of the work we'll be doing isn't going to be in Max at all, and the Max objects we do use will be a good introduction or refresher for how to work with MIDI data and how to build simple patchers in Max.

building-a-synthesizer-editor-with-javascript-part-1

Building a Synthesizer Editor with JavaScript, Part 1

Timothy Place

Here’s the first in a series on using the FFT in Max. Spend 26 minutes building two spectral effects processing patchers including a version of the classic Forbidden Planet example.

Download the patches used in this tutorial.

All the tutorials in this series: Part 1, Part 2, Part 3, Part 4, Part 5, Part 6, Part 7.

Build two spectral effects processing patchers including a version of the classic Forbidden Planet example. Get the patches: https://cycling74.com/2017/01/17/advanced-max-ffts-part-1/

Advanced Max: FFTs, Part 1

advanced-max-ffts-part-1

Darwin Grosse

Max 7 includes a new set of tools developed by Matthew Davidson for his work as a Berklee School of Music instructor. The idea is to have a set of objects that would be as easy to use as the Vizzie modules, but would mirror some of the functionality of a Eurorack modular synthesizer. The result is BEAP: the Berklee Electro Acoustic Pedagogy - a fancy way of saying “A Modular Synthesizer in Max!”

We are going to highlight individual BEAP modules over the next few months, but we should start off with a basic patch: our first BEAP synthesizer. Follow a step-by-step demo of the creation of a simple synth, and use it to explore the BEAP system on your own.

Max 7 includes the BEAP modules, developed by Matthew Davidson for his work as a Berklee School of Music. 
Learn more about the video tutorial series here: 
https://cycling74.com/2015/09/15/a-few-minutes-with-beap-tutorial-series

A Few Minutes with BEAP: Create a Simple Synthesizer (Part 1)

a-few-minutes-with-beap-tutorial-series

A Few Minutes with BEAP, Part 1

There has been a lot of wonderful activity in the Gen domain, and we would like even more people to experience the differences between Max and Gen programming. I originally created a set of three videos developed in Max 6 for the curious absolute beginner. Using Max 7, I developed a series of text-based "Getting Started" tutorials. (These replace the first Max 6 video which was no longer useful.) The text and video tutorials introduce the gen~ environment, explain a bit of the differences between working in the Max vs. gen~ environment, and include a few simple programs to get you started. Check them out below! 

Note to Ableton Live 9/10 Suite users: Access to Gen requires a full Max license. Get details on crossgrading!

gen~ for Beginners, Part 1: A Place to Start

gen~ for Beginners, Part 2: Similarities and Differences

gen~ for Beginners, Part 3: Counting, and a World without bang Messages

gen~ for Beginners, Part 4: Working with buffers (and data)  

gen~ for Beginners, Part 5: The Codebox Operator 

gen~ for Beginners, Part 6: Thinking Inside the Codebox 

gen~ for Beginners, Part 7: Creating Reusable Tools 

If you're ready to do even more in Gen, follow our Gen Patch-a-Day series.


This set of tutorials will get you started using the gen~ object in Max.  For more in this series: 
https://cycling74.com/tutorials/gen-video-tutorial-series

gen~ for Beginners: Working with Abstractions

gen~ for Beginners: Debugging and Signal-Rate Processing

image8.png

There has been a lot of wonderful activity in the Gen domain. In this series, I will introduce the gen~ environment, explain a bit of the differences between working in the Max vs. gen~ environment, and include a few simple programs to get you started.

gen-video-tutorial-series

gen~ Tutorial Series for Beginners

Isabel Kaspriskie

The recent changes to the mtr object allow us to now access internal data in the form of a “dump dictionary,” a powerful feature that we can harness easily with scripting tools. This tutorial series will focus on using mtr with JavaScript. 

In Part 1 of this series, we will introduce a JavaScript library called mtr-accessor which helps morph a dump dictionary into an easy-to-use format. We’ll show you: 

The structure and contents of the mtr data

How to do a basic operation like printing mtr contents to the Max console 

This tutorial assumes you have reviewed the JavaScript Tutorial 1: Basic JavaScript introduction to using JavaScript with Max.

Make sure to save these files in the same folder your Max patch will be saved, or in a location shared with all of your Max patches.

Now create a new empty file called “mtr-to-console.js” and save it in the same folder as “mtr-accessor.js”. This script will be where we write all of our code to access the shared library and send output to Max. It’s the JS to MTR connection!

Okay, let’s open up our script, “mtr-to-console.js” and add the following setup lines:

autowatch = 1; // Reload the script any time we save new changes
inlets = 1; // One inlet to the js object
outlets = 1; // One outlet from the js object

var mtr = require(“mtr-accessor”);
var myMtr;

The first var statement shows how “mtr-to-console.js” will use the contents of our shared library using the require statement. The second line sets up a global variable (myMtr) where our formatted mtr data will be stored.

Finally, let’s write the function that will fill up the myMtr variable with our easy-to-handle format!

function dictionary(v) {
    var d = new Dict(v);
    myMtr = new mtr.Mtr(d, 'dict');
}

What we’ve done here is take a dump dictionary in from the js object’s inlet and created a Dict object. To create an easy-to-handle object, we passing the Dict we just made into constructor for the mtr.Mtr() JavaScript object. Notice that the second argument to the constructor is ’dict’. The purpose of this will become clearer in later parts of this tutorial series, but for now just know that this tells the library the type of data being send it comes from a Max Dict object.

The following diagram gives a general idea of what data is stored in a mtr.Mtr object:

tracks: This holds “track” arrays which in turn hold event info, like event type and event value. Each event type is either a number or an array, making it much easier to handle all of the different possible kinds of inputs from Max!

trackInfo: For each track, there is metadata info like track length, whether the track loops, and what speed to playback at.

topLevel: This holds any miscellaneous top-level mtr data, like the type of dictionary input that is parsed.

isValidInput: This is true if the data was parsed with a supported type, otherwise it is false. isValidInput will be true in our current example because we passed in a supported type (‘dict’) as the second argument to the constructor of mtr.Mtr().

Now that we have an overview of what’s available to us in myMtr, let’s access it! We’re going to step through the data in myMtr and print it to the Max console.

First, add the following helper function for printing a single line to the bottom of your “mtr-to-console.js” file:

function postln(v) {
    post(v + '\n');
}

Now, back in the dictionary() function, after the line you created myMtr, we can iterate through the data with the following code:

for (var n = 0; n < myMtr.tracks.length; n++) {
    var z = myMtr.tracks[n].length;
    postln("");
    postln("Track " + n);
    postln(" Length: " + myMtr.trackInfo[n].length);
    postln(" Loop: " + myMtr.trackInfo[n].loop);
    postln(" Trackspeed: " + myMtr.trackInfo[n].trackspeed);
    postln("  Event Count: " + z);
    
    // the first and last event info (if available)
    if (z > 0) {
        postln(" First @ " + myMtr.tracks[n][0].accum.toFixed(2) + " ms");
        postln(" Last @ " + myMtr.tracks[n][z-1].accum.toFixed(2) + " ms");
    }
}

Once you save the changes you’ve just made to the script, you can feed dump dictionary output into the inlet of your js object and see the data in your Max console window! 

Now that we’ve shown the power of the mtr-accessor library, part 2 of this tutorial series will demonstrate using the jsui object as a visualizer for our mtr data. Stay tuned!

Learn More: See all the articles in this series  

Search Results