Ever since Cycling 74 introduced the idea of packages in Max 6.1, I’ve been pretty excited. Previously, there wasn’t a great way to distribute and install tools, objects, externals, media. And if you wanted to use anyone else’s tools, you had to wade through the murky collection of application directories and dump in single files–an unfailing way to ensure that you’d have to re-install these tools after a Max/MSP update.

With packages, Cycling 74 got rid of the mess. Tool creation, installation, and for me, distribution is clear and simple. Even if I’m developing my own set of abstractions for nobody’s computer but my own, packages provide a platform for a confident working-practice with long-term benefits. This post is meant to outline the pros of Max packages by walking through a working example of how one can set up her/his own Max package.

While I have created several Max packages since 2014, the post will outline my latest Max package, Korg Nano.  It’s a basic example, two objects that comprise a software implementation of the Korg nanoKontrol USB controller, certainly enough to get one started.

Installation
After downloading the Korg Nano package, unzip the file and place the unzipped folder directly into the ‘packages’ directory.  For Mac users, the folder is Applications > Max 6.1 > packages.  Or, you can read a short article by Cycling 74 on packages for installation.

What It Is
In short, packages provide global access. Autocompletion, media in global search paths, extras in the top Extras dropdown menu, option clicking helpfiles, it’s all there. What the Korg Nano package provides is a software listener for the 151 controls on the Korg nanoKontrol USB controller. The package is meant to be a plug ‘n play solution for this hardware device (and I use it for prototyping all the time).

After installation of Korg Nano in the Max packages directory (make sure you restart Max), navigate to the folder.  You will see four folders inside (docs, help, media, patchers) and a README file. Each folder has a unique purpose, and there are many more one can add (extras, javascript, clippings, templates, etc). If you’re curious, there is an “about packages.txt” file in the packages directory that outlines the finer points of Max packages. For now, we’ll unpack these four folders (docs, help, media, patchers).

The patchers folder is where you throw your abstractions and objects (not externals), including any additional bpatchers that you may have used to create your objects. Of course, if your package depends upon third-party objects, you can place them here (and within any named subfolder). For Korg Nano, there are two main objects, korgnano and korgnano.inputmenu.  korgnano is built from several bpatchers, which one will see listed in a subfolder (“patchers > korg_nanoKontrol”).

The media folder allows one to place images, audio, and video. This folder becomes global (after restarting Max), so you can also use packages as a way to manage media instead of worrying about “filepath” when you move from computer to computer. Since Korg Nano is a software implementation of the USB hardware controller, I used image buttons that simulate the look and feel of the hardware controller. Placing images in the media folder ensures they will be found, regardless of what computer I am using.

The help folder is exactly what one would expect. Help files ending with the extension .maxhelp.  While help files are useful (e.g. option-click an object to access its help file), Max packages allows one to provide some serious help to the help files. This helpful power boost comes by way of the docs folder.

The docs folder contains reference files that enable hover tooltips, documentation window text, uniform descriptions, and fancy descriptive break downs and object links from within the reference window. To understand what is happening in the help file screenshot above, let’s dig into the docs folder.  Navigate to the “korgnano-0.0.1 > docs > refpages > korgnano > korgnano.inputmenu.maxref.xml” file.  This xml file contains all the descriptions that get pulled for the help file. While this file contains confusing html/xml style tags, one need only look to two examples to see their power.

The first example comes from the first two xml tags <digest> and <description>.  These two description tags show up in the Autocomplete menu, the documentation window, the reference window (outside any help file), and the help file’s title object (actually, a jsui object that uses an application Max script “helpdetails.js” to parse these xml tags and display them for clean documentation).

The second example of documentation power comes from the <seealsolist> tag near the bottom of the .xml file.  One only needs to place additional object names here (e.g. “<seealso name=’korgnano’/>”) and links automatically appear in the reference documentation window, linking to your objects’ help files. This is handy here, as I want to link the korgnano object and the korgnano.inputmenu object together since these objects are symbiotic. The korgnano object grabs data from your Korg hardware controller and then sends the controller data direct to korgnano.inputmenu objects.

Docs, Help, Media, Patchers. That’s it.  A Max package that enables software listening for the Korg nanoKontrol, neatly bundled for distribution. Clear documentation files to help anyone navigate the tools, even me! when I revisit my tool a few months down the line. However, I do not need to distribute to reap the benefits.  Clippings, templates, patchers, or even externals that I use often in my own work have a place within a Max package, easily searchable and documented so I have a working practice that is efficient and scalable. For anyone working in Max, packages offer a clean way to keep your sh** together.

Reference
Korg Nano Max package

Notes
Packages also work with Max 7. While my example was built using Max 6.1, there is no reason why it shouldn’t work in Max 7. Email me if you have issues.

Speaking of issues… if you’re having trouble with autocomplete, try creating a message object in a Max window with the text “; max db.reset”.  This will refresh Max’s preferences, but may take 60 seconds+ to reload. Here’s the original forum post where I found this fix.