Controlling Max with Messages

Just like you can control objects by sending them messages, you can also send messages directly to the Max application. This lets you do things like:

• Get/set the value of various Max Preferences
• List all of the currently loaded Max externals
• Move the mouse cursor
• Hide/show the menu bar

To send a message directly to Max, create a message box starting with a semicolon followed by the symbol max, jitter, or dsp, to send a message directly to max itself, the Jitter engine, or the audio engine. You don't need to connect the message box to anything, simply trigger it to send the message.

Messages to max

buildcollective

Builds a collective using a patcher previously opened with openfile. The collective is named with the output filename.

checkpreempt

Sends the current Overdrive mode to a receive object

clean

Clear the dirty flag, causing Max not to show a Save Changes dialog when you close a window or quit, even if there are patchers that have been modified. This is useful in conjunction with the quit message below.

clearmaxwindow

Clear the Max Console.

closefile

Closes a patcher file previously opened with the openfile

crash

Terminate Max, generating a standard crashlog. When relaunched, The Max application will perform standard crash recovery (if crash recovery is enabled in the Max preferences).

db.exportmetadata

Write the metadata information currently stored in the database to a file. An optional argument can be used to specify a filename. If no filename is specified, the metadata is backed up to a file in your preferences folder.

db.importmetadata

Load metadata information from a previously stored file into the Max database. An optional argument can be used to specify a filename - when no argument is specified, Max will look for a backup file from a previous call to db.exportmeta in your preferences folder.

db.reset

Rebuild the internal database, used by the File Browser and others.

debug

Enable/disable sending Max's internal debugging output to the Max Console. This debug information may be of limited use for anyone who isn't debugging Max itself.

disablevirtualmididestinations

Activate to disable the creation of virtual sources by the Core MIDI driver. When set to zero (enabling virtual sources) the virtual sources are created again.

enablepathcache

Enable/disable Max's search path cache. This should only be done if you notice unusual behavior when opening files.

externaleditor

Sets the text editor used for editing text file content, such as saved coll files, text files and JavaScript code.

externs

Print all of the external objects currently loaded to the Max Console.

fileformat

Associate a filename extension with a particular four-character filetype. For example, the message max fileformat .tx TEXT associates the extension .tx with TEXT (text) files. This allows a user to send a message read george and locate a file with the name george.tx. It also ensures that files with the extension .tx will appear in a standard open file dialog where text files can be chosen.

fixwidthratio

Set the ratio of the box to the width of the text when the user chooses Fix Width from the Object menu. The default value is 1.0. A value of 1.1 would make boxes wider than they needed to be, and a value of 0.9 would make boxes narrower than they need to be.

getarch

Send the currently running Max architecture (always 'x64') to the named receive object.

getdefaultpatcherheight

Send the current default patcher height in pixels to the named receive object (See also the setdefaultpatcherheight message to Max.)

getdefaultpatcherwidth

Send the current default patcher width in pixels to the named receive object (See also the setdefaultpatcherheight message to Max.)

getenablepathcache

Report whether the path cache is enabled to the named receive object. (See also the enablepathcache message to Max.)

geteventinterval

Report the event interval to the named receive object. (See also the seteventinterval message to Max.)

getfixwidthratio

Report the current fix width ratio value to the named receive object. (See also the fixwidthratio message to Max.)

getpollthrottle

Report the current poll throttle value to the named receive object. (See also the setpollthrottle message to Max.)

getqueuethrottle

Report the current queue throttle value to the named receive object. (See also the setqueuethrottle message to Max.)

getrefreshrate

Report the current refresh rate in frames per second (fps) to the named receive object. (See also the refreshrate message to Max.)

getruntime

Send a 1 to the named receive object if the current version of Max is a runtime version, and a 0 if not.

getslop

Send the scheduler slop value to the named receive object. (See also the setslop message to Max.)

getsysqelemthrottle

Send the maximum number of patcher UI update events processed at a time to the named receive object. (See also the setsysqelemthrottle message to Max.)

getsystem

Send the name of the system (macintosh or windows) to the named receive object.

getversion

Send the Max version number as a decimal value, which needs to be converted to a hexidecimal value (e.g. Max version 7.3.4 is reported as '1844'), and output from the named receive object.

hidecursor

Hides the cursor if it is visible.

hidemenubar

Hides the menu bar.

htmlref

Look for a file called <filename>.html in the search path. If found, a web browser is opened to view the page. This opens local html files, not remote web addresses.

interval

Set the timing interval of Max's internal scheduler in milliseconds. The default value is 1. This message only affects the scheduler when Overdrive is on and scheduler in audio interrupt (available with MSP) is off. (When using scheduler in audio interrupt mode the signal vector size determines the scheduler interval.) Larger scheduler intervals can improve CPU efficiency on slower computer models at the expense of timing accuracy.

launchbrowser

Opens a web browser to view the given URL.

maxcharheightforsubpixelantialiasing

Set a threshold font size (in points) for native subpixel aliasing. Since the look of subpixel antialiasing may be undesirable when working with large fonts as compared to regular antialiasing, this attribute lets you specify a threshold font size; if a font is larger than the specified size, it will be rendered using regular rather than subpixel antialiasing.

Note that Max honors your computer's system preferences - Max won't use subpixel aliasing if you've disabled it for your system. Setting this attribute value to zero value is 0 will always use regular antialiasing, and setting a very high value will always use subpixel antialiasing (unless it is disabled in system preferences).

maxinwmenu

Enable/disable the special Status option in the Window menu bar item. This is only available when using runtime version of Max and an active custom menubar object. The Status option will allow users to see the Max Console. Defaults to 1 (enabled).

maxwindow

Displays the Max Console. If the Max Console if not currently open, the window will be displayed. If the window is currently open, it will bring it to the front.

midilist

Prints the names of all current MIDI devices in the Max Console. (See also MIDI Messages to Max, below.)

notypeinfo

(macOS only) Enable/disable saving files with traditional macOS four-character type information. By default, Max does save this information in files.

objectfile

The word objectfile, followed by two symbols that specify an object name and a file name, Create a mapping between an external object and its filename. For example, the *~ object is in a file called times~ so at startup Max executes the command max objectfile *~ times~.

openfile

The word openfile, followed by two symbols that specify an reference name and a file name or path name, attempts to open the patcher with the specified name. If successful, the patcher is associated with the reference symbol, which can be passed as argument to the buildcollective and closefile messages to Max. The openfile message is intended for batch collective building.

paths

List the current search paths in the Max Console. There is a button in the File Preferences window that does this.

preempt

Toggle Overdrive mode.

pupdate

Move the mouse cursor to a global screen position.

purgemididevices

Purge the missing MIDI device cache. Max maintains a cache of the MIDI Setup settings for known, but detached MIDI devices. Send this message to 'forget' any missing devices.

quit

Quit the Max application, equivalent to choosing Quit from the File menu. If there are unsaved changes to open files, and you haven't sent Max the clean message, Max will ask whether to save changes.

refresh

Update all Max consoles.

refreshrate

Set the rate limit, in frames per second, at which the UI for user interface objects is updated. Better visual performance can be achieved - at the cost of a slight performance decrease in Jitter, and little or no performance decrease for audio processing - by specifying a higher frame rate.

relaunchmax

Close and relaunch the Max application.

runtime

Conditionally send a message to Max if the given value matches the "runtime" status of Max. For example, the message ; max runtime 0 externs will send the externs message to Max only if the active Max application is not a runtime-only version.

sendinterval

Send the current scheduler interval to the named receive object.

sendapppath

Send the path of the Max application to the named receive object.

setdefaultpatcherheight

Set the default patcher height in pixels. Must be greater than 100.

setdefaultpatcherwidth

Set the default patcher width in pixels. Must be greater than 100.

seteventinterval

Set the time between invocations of the event-level timer (The default value is 2 milliseconds). The event-level timer handles low priority tasks like drawing user interface updates and playing movies.

setmixergbitmode

Set the state of the Enable Mixer Crossfade preference for top-level patcher mixers. A value of 0 sets the preference to Off, 1 to On, and 2 to Auto.

setmixerlatency

Set the Mixer Crossfade Latency preference for top-level patcher mixers to the specified number of milliseconds.

setmixerparallel

Enable/disable the Enable Mixer Parallel Processing preference for top-level patcher mixers.

setmixerramptime

Set the Mixer Crossfade Ramp Time preference for top-level patcher mixers to the specified number of milliseconds.

setmirrortoconsole

Enable/disable mirroring of Max Console posts to the system console (default off). The system console is available on macOS using Console.app, or on Windows using the DbgView program (free download from Microsoft).

setsleep

Set the time between calls to get the next system event, in 60ths of a second. The default value is 2.

setpollthrottle

Set the maximum number of events the scheduler executes each time it is called (The default value is 20). Setting this value lower may decrease accuracy of timing at the expense of efficiency.

setqueuethrottle

Set the maximum number of events handled at low-priority each time the low-priority queue handler is called (The default value is 2). Changing this value may affect the responsiveness of the user interface.

setslop

Set the scheduler slop value - the amount of time a scheduled event can be earlier than the current time before the time of the event is adjusted to match the current time. The default value is 25 milliseconds.

setsysqelemthrottle

Set the maximum number of patcher UI update events to process at a time. Lower values can lead to more processing power available to other low-priority Max processes, and higher values make the user interface more responsive (especially when using many bpatchers).

showcursor

Show the cursor if it is hidden.

showmenubar

Show the menu bar if it was hidden with hidemenubar

size

Print the number of symbols in the symbol table in the Max Console.

system

Conditionally send a message to Max if the Operating System condition matches. The operating system can be windows or macintosh. For example, the message ; max system windows externs will send the message externs to Max only on a Windows operating system.

useexternaleditor

Enable/disable using an external editor for text. If enabled, any situation where an external editor can be used will launch the editor. If disabled, an external editor will only be used when selected from the menu.

useslowbutcompletesearching

Enable/disable complete file searching. When enabled, it causes files not found in Max's cache of the search path to be searched in the file system. This is necessary only in extremely rare cases where the file cache does not update properly. One such case is copying a file into the search path using a version of the Mac OS prior to 10.5.5 over a network. This option may cause patcher files to be loaded more slowly. The setting defaults to off with each launch of the application, and is not stored in the user's preferences.

MIDI Configuration Messages

createoutport

Creates a new port for the specified driver. This is only possible on macOS machines. Windows is unsupported. On macOS, specifying the coremidi driver name creates a virtual output port you can use to communicate with other MIDI applications, while specifying the augraph driver name creates another port exclusively assigned to the DLS synthesizer.

deleteoutport

On macOS, deletes a port created with the createoutport message. drivername and portname should be the same as the arguments originally passed to createoutport.

driver loadbank

On macOS, loads a type 1 or 2 DLS Bank, where filename is the name of an existing DLS bank file, and portname is the name of the port that will use this bank. If portname is omitted, all DLS ports will use the bank. The folder /Library/Audio/Sounds/Banks is added to the search path when looking for a DLS bank file.

driver loadbank 0

Load the default General MIDI DLS bank

driver reverb

Enable/disable reverb. Off by default in augraph

driver latency

(midi_mme only) Set the MIDI Output Latency in milliseconds

inportinfo

Send information about MIDI input ports to the named receive objects. The information is contained in an list message with the following elements:

outportinfo

Send information about MIDI output ports to the named receive objects. The information is contained in an infolist list message. See inportinfo for a description if the infolist list elements.

createinport

(macOS only) Add a virtual MIDI input port, where portname is the name you assign to the port, and drivername should be set to coremidi. Other MIDI applications can send messages to Max using this port.

deleteinport

Deletes a port created with the createinport message. drivername and portname should be the same as the arguments originally passed to createinport.

Messages to midi

These are technically messages to Max, but specifically to MIDI configuration object owned by Max. So to send one of these messages, use a format like:

portabbrev

Set the abbreviation for a given MIDI port.

portenable

Enable/disable a given MIDI port. All ports are enabled by default.

portoffset

Similar to portabbrev, but offset is the channel offset added to identify input or output ports when a MIDI object can send to or receive from multiple ports by channel number. Must be a multiple of 16 (e.g. max midi portoffset innum PortA 16 sets the channel offset for PortA device to 16).

Messages to dsp

cpulimit

Sets a utilization limit for the CPU. Above this limit, MSP will not process audio vectors until the utilization comes back down, causing a click. If the cpu limit is set to either 0 or 100, there will be no limit checking done.

inremap

Maps a physical device input channel to a logical input channel.

iovs

Sets the I/O vector size.

open

Opens the Audio Status window.

outremap

Maps a physical device output channel to a logical output channel.

set

Turns the audio on (1) or off (0). It is equivalent to clicking on a ezadc~ or ezdac~ object.

setdriver

Sets a new audio driver based on its index into the currently generated menu of drivers created by he adstatus driver object.

If the argument is a symbol instead of an index and names a valid driver, the new driver is selected by name. An additional symbol argument may be used to specify a "subdriver" (for example, ASIO drivers use ASIO as the name of the driver and PCI-324 as a subdriver name that specifies a specific device).

sigvs

Sets the I/O signal vector size.

sr

Sets a new sampling rate in Hertz.

start

Turns the audio on.

status

Opens the Audio Status window.

stop

Turns the audio off.

takeover

Turns Scheduler in Audio Interrupt mode on (1) or off (0). It is equivalent to clicking on the Audio Interrupt checkbox in the Audio Status window. Overdrive must be on in order for this change to be reflected.

timecode

Starts (1) or stops (0) timecode reading by any audio drivers that support the feature (ASIO 2).

wclose

Closes the Audio Status window.

Messages to jitter

cursor

Toggles cursor visibility on / off.

html_ref

Launches the reference file for an object in the Max search path.

javaload

Toggles Jitter Java support on / off.

launch_browser

Launches the specified URL in the default system web browser.

menubar

Toggles menubar visibility on or off. Similar to Max's showmenubar , and hidemenubar messages.

When using in conjunction with the jit.window object's fullscreen attribute, it is recommended that the jit.window object's fsmenubar attribute is used instead of Jitter's menubar message, in order to prevent possible "pixel trash".

parallel

Toggles parallel processor support. The default is on if the machine has multiple processors (or cores), and otherwise off.

parallelthreads

Specifies the number of threads used for parallel processor support. Default is the number of processors (or cores).

parallelthresh

Specifies matrix cellcount above which parallel processors are used. Default is 10000 cells.

pollthrottle

Sets the number of scheduler events to process per scheduler tick. Equivalent to Max's setpollthrottle message.

queuethrottle

Sets the number of low priority queue events to process per low priority queue service. Equivalent to Max's setqueuethrottle message.