Monday, 15 April 2019

Spectral auto-panning in MaxForLive for Ableton Live

My two recent MaxForLive audio devices have both been based around having 6 processing sections - hence the 'hex' in their names. But I realised that there was a much simpler device that uses the hex pan section, which could be used in many ways, and this blog post is devoted to it: a hex spatializer!


AUDhexSPATIAL moves parts of sounds around in the stereo field. That's all. It is quite straightforward, but don't let that fool you into thinking that you can't do much with it.

The input audio is passed through three parallel filters, and then the outputs are auto-panned across the stereo image. The three filters can be used in several ways, but the most obvious way is to use them to split the audio into three separate bands: The high-pass filter outputs the high frequencies, the low-pass filter outputs the low frequencies, and the band-pass filter outputs the middle frequencies.

Each filter output can be panned to hard left or hard right, or can be Auto-panned - controlled by a three position switch: L/Auto/R. But the frequencies of each filter are independent, so there's nothing to stop you putting the high-pass filter below the low-pass, or the band-pass anywhere from low to high.

The filters are there just to provide different blocks of frequencies to the output section where the panning happens. And the three [X] toggle switches allow you to turn the outputs on and off, so if you want to have just the high-pass filter output, then just enable that toggle switch and turn off the others. The two stereo channels are separate, so if you want different filters and pans for left and right, then that is completely possible.


After a lot of agonising, I have finally decided to use a new and consistent naming scheme for my M4L plug-ins. From now onwards, and if I update anything, then I will strive to use three prefixes:

- AUD for Audio processing devices (aka effects)
- MIDI for MIDI devices (this took ages to figure out!)
- GEN for devices that generate audio

Of course, in an imperfect world, I may not always succeed in trying to be consistent, but I will try. Please let me know if I falter!


OK, so your imagination is probably your main limitation here. If you want to have the left channel quickly auto-panning the top end of a piano sound, whilst the right channel slowly pans the bass around and both channels have two different resonant filters panning at different speeds, then that's fine.

But there's more. Try putting AUDhexSPATIAL in front of a Ping-Pong Echo, or put it in between two Ping-Pong Echoes... It is very interesting to experience just how complex a simple sequence can sound when it goes through this sort of processing.


You can't adjust the panning width directly - adding two extra rotary controls would make the centre section way too big, I reckon. (But let me know if you really want this, and I might schedule a '+' version...) You get full left-to-right panning, or else hard left or hard right. Of course, you could make a rack and use the Utility object to restrict the pan width of multiple AUDhexSPATIALs...

There are only 3 filters and three panners per channel. Making a version with more channels is not in my current plans, and my main concern would be trying to find a way to fit everything into the user interface...

Oh, and the filters are not animated - they are fixed graphics! Sorry...


Recent blog posts have included details of what is happening inside my M4L devices, and this is no exception. This time, I'm going to look at the three-position switch that has been added to the output section.

Max and MaxForLive have a lot of ways of routing numbers, messages and signals around. There are lots of objects, with names like Gate, Switch, Route, Selector, Matrix, and more. Sometimes the objects that route signals around have different names, and work slightly differently to the objects that route numbers or messages, and they can work slightly differently. It's quite a lot to get your head around, and one of these days, I'm going to try to do a guide (a bit like the one I did on squeezing controls into limited spaces!). But in the meantime, here's the first of a little mini-series where I look at a few interesting ways to route stuff.

The three-position switch does two things simultaneously: it allows you to select between hard left and hard right pan positions, or it selects the auto-pan. These are very different things, although if you look at AUDhexECHO or AUDhexFrequencyShifter then you will see that by slowing the LFO to 'stopped' then the result is fixed pan positions. But that isn't a very practical approach for a three position switch. There is also the complication that the output of the LFO that does the auto-panning is a signal (so it has the yellow-striped connections in Max), whilst the more usual way to control a panner is with numbers, so there's going to be a conversion somewhere.

First off, let's look at the context. Here's the relevant part of the Max code for the audio output of  AUDhexSPATIAL:

And here's the 'pan_mr' object expanded out (this is a cheat to make things clear - in reality, you don't see the controls that are connected to the input ports, but I have removed the ports and added the rotary control and the 3-position switch control to make it obvious how things are connected):

The main audio processing is on the left hand side. Input port 1 (the square box with '1' in it) is the audio signal that is going to be 'panned'. It goes to two signal multipliers (notice the '~' after the '*') that are driven in anti-phase using the '!- 1.' inverter shorthand that I've mentioned before. (The formula inside the object just subtracts whatever you feed into the object from 1, so it really means '1-the_number', and so it inverts the value, so if you put 0 in then you get 1 out, and if you put 1 in, then you get 0 out, and linearly for all other values...). The pan value goes from 0 to 1 to pan from left to right, and so centre is a value of 0.5.

On the far right hand side, you can see how the left and right values re stored in message boxes that are triggered every time that the switch is changed. The 'LED" object with the round circle is a useful way to convert changes into 'bangs' that also shows you what is happening when you are debugging. The '0' and '1' messages that the message boxes output when they receive a bang are converted into signals using the 'sig~' objects.    

In the middle, starting from the rotary control, there is a 'cycle~' object that does the sine-wave LFO function, followed by a bit of maths to get the output into the 0<->1 range that is required by the multipliers that do the panning. The 'scaled and offset' sine-wave is then connected to the middle input of a 'selector~' object, which is a special switch for routing signals. The other two inputs are from the signals from the message boxes. So the selector switch can output:
- a signal representing 'left'
- a signal that is an LFO sine-wave
- a signal representing 'right'

And that's how you can make a three-position switch that has fixed values on two of the settings, and an LFO signal on the other.


You can download AUDhexSPATIAL for free from

Here are the instructions for what to do with the .amxd file that you download from

(In Live 10, you can also just double-click on the .amxd file, but this puts the device in the same folder as all of the factory devices...)

Oh, yes, and sometimes last-minute fixes do get added, which is why sometimes the blog post is behind the version number of

Modular Equivalents

In terms of basic modular equivalents, then AUDhexSPATIAL requires six filters, six LFOs, six VCAs, and a mixer, plus some switching for the fixed pan positions, giving a total of about 20 ME.

Sunday, 7 April 2019

Plain text files in macOS for Nyquist plug-ins in Audacity

Sometimes interesting investigations arise completely unexpectedly! Here's a happenstance that caught me out recently...

(Yes, this screen shot shows the Audacity that I haven't updated in quite a while...)
I have written a few plug-ins for Audacity, the amazing free and open-source cross-platform audio editor software, and have never had any problems . Well, other than trying to get my head around the fascinating programming approach that it uses - an extension of the XLISP dialect of Lisp. For some reason, my brain doesn't seem to be wired to think about things the way that Lisp does, and this makes developing plug-ins quite a challenge! But I'm not used to problems with the way that the plug-ins interact with the host application (Audacity in this case)...

It happened when I was adding some functionality to an existing plug-in, the RUSS Harmonic Rejector, to cope with some unusual audio signals that I was processing. I copied across the Nyqvist text files to the appropriate 'Plug-Ins' folder on my MacBook Pro, edited the Nyqvist plug-in code, saved it, and went into Audacity to load it via the 'Effect>Add/Load Plug-Ins' menu option - and this is where things got interesting.

Here's what I saw in the dialogue box that opened:

Now those extra characters aren't there in the Nyqvist code:

;nyquist plug-in
;version 1
;type process
;name “a_RUSS_Harmonic_Filter_lp2"

Also, it turns out that in the Audacity support pages for Nyquist, there's a warning box that I hadn't paid much attention to...

Now that I read that warning again, it seems to be quite important!

But what is the warning actually saying? It says to use a plain text editor rather than a word processor, and I was using TextWrangler as my editor, and that is a plain text editor, isn't it?

It is at this point that the 'question everything, trust nothing' big red warning light starts flashing in my head, and I realise that I'm guilty of 'making assumptions'. Yep, an unquestioned, obvious assumption that you don't realise you are making until it trips you up... So I looked at the files in the Finder:

Now, the Finder is designed for 'finding' files, and it isn't particularly good at telling you much about the files themselves. There's 'Get Info...' for that, and it told me that I had two 'documents' and a document that was last saved as a 'SimpleText' document, which used to be the built-in editor for MacOS from System 7 to System 9 (I think). Unfortunately, a description like 'SimpleText' document doesn't directly indicate if it is a plain ASCII text file. ASCII, by the way, is one of the early ways of mapping numbers to keyboard characters, numbers and other functions, and so a value of 65 represents the character 'A', 49 is '1', and 10 is 'Line Feed (LF)', which is one of several characters that can indicate a new line (Carriage Return (CR) is another), and 7 is the 'Bell' character, which makes a noise (and was originally an actual physical bell!).

Anyway, I opened the Harmonic Extractor file in TextWrangler (my current but 'about-to-be-outdated' 32 bit text editor), and looked at the 'info' bar on the lower edge of the window:

Aha! This isn't a plain ASCII text file! Somewhere along the line, it has been converted to Unicode (UTF-8) encoding instead of ASCII (maybe when it was stored on Google Drive?). So what about the SimpleText document? TextWrangler said:

Now this says it is a text file, but there's an interesting 'Mac OS Roman' encoding, and it has Windows 'end of line' Carriage Return, Line Feed characters, so my tendency to use whatever text editor is around at the time is now biting me back!

Here's what the info bar should say for the 'Plain text' that the Audacity warning box was hinting at:

This is a text file, with ASCII encoding of the symbols on the keys, and with a Unix-style 'Line Feed' to indicate the end of each line. So I tried to save the Nyqvist files as Plain ASCII text files using these settings and up popped a warning that some Unicode characters could not be saved. It turns out that these were the 'smart' doubles quotes around the "title". So I took these out and replaced them with the normal less curvy double quotes and re-saved. All was well again! The plug-ins now had the correct names and were in the correct alphabetically sorted position in the menu. I also tried saving the file using the Windows 'End of Line' convention (CRLF = a Carriage Return character, followed by a Line Feed character), and that worked fine as well.


In summary:

1. You need to make very sure that your Nyquist files are 'plain ASCII text'!
2. 'Plain ASCII text' requires that your editor be set to save using the 'Western (ASCII)' encoding, and ideally to not add a hidden '.txt' extension to the end.
3. Your Nyquist files must have the '.ny' suffix (Remember that the default on macOS is to hide extensions, so use 'Get Info' to make sure that there isn't a hidden '.txt' suffix at the end of the '.ny' file.)
4. Remember that the Mac's 'Textedit' utility makes it very easy to save files as '.rtf' files, and these are NOT plain ASCII text, and just adding '.ny' at the end does not guarantee that there isn't a hidden '.txt' suffix as well...

If this was a forum, then there would be a 'SOLVED' indicator somewhere around here!

There are several things to note here. The first is that I should have thought more about how to edit a file, and especially how to save it - I'm fully guilty of this, and probably rely far too much on default settings to be appropriate to what I'm doing. The second is that Apple's 'it just works' approach sometimes works against you - in this case, setting up TextWrangler so that it saved plain ASCII text was reasonably simple, but only when you knew what was required (and even then, it is easy to end up with a hidden '.txt' extension suffix on the end of what appears to be a '.ny' file. The third is that the Audacity documentation indicated that there might be something that you should be aware of abut editing Nyqvist files, but it didn't give any explicit details, and so required more investigation. The fourth is that just adding '.ny' to the end of a filename does not make that 'extension' disappear, even if  the macOS 'Hide Extensions' default is active - but that Audacity will still accept the '.ny' as an extension even if the Mac's Finder doesn't.

What follows are some of the mitigations that can be used to try and ensure that files are created, edited and saved as plain ASCII text files, in a world where such files seem to be increasingly uncommon.


1. TextUtil

There is a utility that can be accessed via the macOS Terminal called textutil that can convert files to plain ASCII text, and remove smart quotes. Here's a template command line for use in Terminal on a file called 'rich text.rtf' that will convert it to a plain text file called 'rich text.txt':

   >textutil richtext.rtf -convert txt

Note that there's now a '.txt' extension suffix at the end of the file. Audacity is looking for '.ny' files, so you need to edit the filename...

2. Shift + Command + T in TextEdit

Also, inside TextEdit, you can use the command: 'Shift + Command + T' to change from Rich Text format to plain text. When you do this, then the 'ribbon' of buttons at the top of the window disappears and the font changes to Courier:

Notice that the double quotes are vertical in the above screen shots...

If you get a double quote that is non-vertical, then it is a smart quote, and could cause problems if you require plain ASCII text - as Audacity does for Nyqvist files:

To make it easier to see the curved 'smart' and vertical 'non-smart', then here are some screenshots with larger text:

(Notice that the 'ribbon' of buttons and the ruler vanish when you are in the 'Plain text' mode.)

To prevent any problems, then you need to turn off the 'Smart Quotes' option in the Text Edit preferences:

You also need to add 'Western ASCII' to the encodings for saving - you do this via the 'Plain Text Encoding' selector in the 'Save' dialogue box:

And then add 'Western (ASCII):

It also seems to be good to start typing in Plain text mode to avoid any smart quotes! As you can see, it isn't entirely straightforward to adjust textEdit so that it saves files as plain ASCII text! 

3. Coteditor

Despite quite a bit of searching, I didn't find a dedicated 'plain ASCII text' editor for MacOS, and unfortunately, the free and very capable generic editor that I've been using for many years, TextWrangler from Bare Bones Software, is a 32-bit applications, and so whilst it works fine in the El Capitan version of macOS that I use on this MaxBook Pro, the future is 64-bit, and so I'm going to need to change to another editor eventually. BBEdit from Bare Bones Software would be the obvious choice, but I wondered if there was an alternative simple text editor...

In my searching I found Sublime Text, BBEdit, Atom, Vim, Brackets (from Adobe), UltraEdit, Coda and Microsoft's Visual Studio Code. Most of these are serious, professional editors, and some of them have free versions (or trials), but none of them seemed to be at the simpler end of the range. However, I did find Coteditor (from that seems to be quite simple and straightforward, and it puts the save format right at the top of the main window, where even I would probably eventually notice it!   

4. Get Info

I mentioned using the Command-I 'Get Info' utility before, so here's what it shows when you look at some edited Nyqvist files:

It turns out that the 'Get Info' utility can be very useful! The 'Hide Extension' option is the default in macOS, and so even though the nyquist files have '.ny' at the end, the '1-...' test file also has a '.txt' at the end, which means that Audacity does not include it in the 'Add/remove Plug-Ins' dialogue box. The 'Name & Extension' field can be used to remove the '.txt' suffix - just click in the field and remove the '.txt', then press 'Return'.

Let's recap that:

The '1-RUSS_Harmonic_Extractor_hi2.ny' file the you see in the Finder in macOS is actually called: '1-RUSS_Harmonic_Extractor_hi2.ny.txt' (yes, with two 'extension' suffixes), because macOS hides extensions by default. The '.ny' that looks like an extension is misleading, because the '.txt' suffix that follows is the actual extension.

If you use the 'Get Info' utility to remove the '.txt' at the end of the filename, then you get a file which looks like it has a real extension of '.ny'. The 'a-RUSS_Harm_Extract_hi2.ny' file does not have '.txt' at the end, but it appears in the Finder as 'a-RUSS_Harm_Extract_hi2.ny', which means that the '.ny' isn't a real extension, because if it was, then macOS would not show it, and the file would appear as  'a-RUSS_Harm_Extract_hi2'... However, Audacity treats the 'a-RUSS_Harm_Extract_hi2.ny' file as if it had an extension of '.ny', and thus displays it in the 'Add/Remove Plug-Ins' dialogue box.   


Making sure that Nyqvist files are plain ASCII text files is very easy to get wrong, and if you do get it wrong, then your plug-in may not appear in the 'Add/Remove Plug-Ins' dialogue box, or Audacity may not display the name of the plug-in correctly. Having spent a lot of time in the integrated development environment that Max offers (for MaxForLive plug-ins, as well as Max code), then it is very interesting to see how a non-integrated development system requires more thought and organisation.

I hope that this blog post will help anyone else who experiences problems with Nyqvist files in Audacity on macOS, assuming that they can find this blog post, of course!

Buy me a coffeeBuy me a coffee